Documentation: point to key_custom instead of key_ext
Replace references to the deprecated functions `psa_generate_key_ext()` and
`psa_key_derivation_output_key_ext()` by their replacements
Implement `psa_generate_key_custom()` and
`psa_key_derivation_output_key_custom()`.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/psa-transition.md b/docs/psa-transition.md
index bbb7da2..dea14fe 100644
--- a/docs/psa-transition.md
+++ b/docs/psa-transition.md
@@ -779,7 +779,7 @@
The easiest way to create a key pair object is by randomly generating it with [`psa_generate_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga1985eae417dfbccedf50d5fff54ea8c5). Compared with the low-level functions from the legacy API (`mbedtls_rsa_gen_key`, `mbedtls_ecp_gen_privkey`, `mbedtls_ecp_gen_keypair`, `mbedtls_ecp_gen_keypair_base`, `mbedtls_ecdsa_genkey`), this directly creates an object that can be used with high-level APIs, but removes some of the flexibility. Note that if you want to export the generated private key, you must pass the flag [`PSA_KEY_USAGE_EXPORT`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__policy/#group__policy_1ga7dddccdd1303176e87a4d20c87b589ed) to [`psa_set_key_usage_flags`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__attributes/#group__attributes_1ga42a65b3c4522ce9b67ea5ea7720e17de); exporting the public key with [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) is always permitted.
-For RSA keys, `psa_generate_key` uses 65537 as the public exponent. You can use [`psa_generate_key_ext`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#group__random_1ga6776360ae8046a4456a5f990f997da58) to select a different public exponent. As of Mbed TLS 3.6.0, selecting a different public exponent is only supported with the built-in RSA implementation, not with PSA drivers.
+For RSA keys, `psa_generate_key` uses 65537 as the public exponent. You can use [`psa_generate_key_custom`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__random/#ga0415617443afe42a712027bbb8ad89f0) to select a different public exponent. As of Mbed TLS 3.6.1, selecting a different public exponent is only supported with the built-in RSA implementation, not with PSA drivers.
To create a key object from existing material, use [`psa_import_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga0336ea76bf30587ab204a8296462327b). This function has the same basic goal as the PK parse functions (`mbedtls_pk_parse_key`, `mbedtls_pk_parse_public_key`, `mbedtls_pk_parse_subpubkey`), but only supports a single format that just contains the number(s) that make up the key, with very little metadata. The table below summarizes the PSA import/export format for key pairs and public keys; see the documentation of [`psa_export_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1ga668e35be8d2852ad3feeef74ac6f75bf) and [`psa_export_public_key`](https://mbed-tls.readthedocs.io/projects/api/en/development/api/group/group__import__export/#group__import__export_1gaf22ae73312217aaede2ea02cdebb6062) for more details.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 9dbd014..006da9b 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -119,8 +119,8 @@
* value in the structure.
* The persistent key will be written to storage when the attribute
* structure is passed to a key creation function such as
- * psa_import_key(), psa_generate_key(), psa_generate_key_ext(),
- * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext()
+ * psa_import_key(), psa_generate_key(), psa_generate_key_custom(),
+ * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom()
* or psa_copy_key().
*
* This function may be declared as `static` (i.e. without external
@@ -164,8 +164,8 @@
* value in the structure.
* The persistent key will be written to storage when the attribute
* structure is passed to a key creation function such as
- * psa_import_key(), psa_generate_key(), psa_generate_key_ext(),
- * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext()
+ * psa_import_key(), psa_generate_key(), psa_generate_key_custom(),
+ * psa_key_derivation_output_key(), psa_key_derivation_output_key_custom()
* or psa_copy_key().
*
* This function may be declared as `static` (i.e. without external
@@ -3234,7 +3234,7 @@
* of or after providing inputs. For some algorithms, this step is mandatory
* because the output depends on the maximum capacity.
* -# To derive a key, call psa_key_derivation_output_key() or
- * psa_key_derivation_output_key_ext().
+ * psa_key_derivation_output_key_custom().
* To derive a byte string for a different purpose, call
* psa_key_derivation_output_bytes().
* Successive calls to these functions use successive output bytes
@@ -3457,7 +3457,7 @@
* \note Once all inputs steps are completed, the operations will allow:
* - psa_key_derivation_output_bytes() if each input was either a direct input
* or a key with #PSA_KEY_USAGE_DERIVE set;
- * - psa_key_derivation_output_key() or psa_key_derivation_output_key_ext()
+ * - psa_key_derivation_output_key() or psa_key_derivation_output_key_custom()
* if the input for step
* #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD
* was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was
@@ -3707,9 +3707,9 @@
* on the derived key based on the attributes and strength of the secret key.
*
* \note This function is equivalent to calling
- * psa_key_derivation_output_key_ext()
- * with the production parameters #PSA_KEY_PRODUCTION_PARAMETERS_INIT
- * and `params_data_length == 0` (i.e. `params->data` is empty).
+ * psa_key_derivation_output_key_custom()
+ * with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT
+ * and `custom_data_length == 0` (i.e. `custom_data` is empty).
*
* \param[in] attributes The attributes for the new key.
* If the key type to be created is
@@ -3782,7 +3782,7 @@
* operation.
* \param[in,out] operation The key derivation operation object to read from.
* \param[in] custom Customization parameters for the key generation.
- * When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT
+ * When this is #PSA_CUSTOM_KEY_PARAMETERS_INIT
* with \p custom_data_length = 0,
* this function is equivalent to
* psa_key_derivation_output_key().
@@ -4002,7 +4002,7 @@
* operation. The value of this key was likely
* computed by a previous call to
* psa_key_derivation_output_key() or
- * psa_key_derivation_output_key_ext().
+ * psa_key_derivation_output_key_custom().
*
* \retval #PSA_SUCCESS \emptydescription
* \retval #PSA_ERROR_INVALID_SIGNATURE
@@ -4170,9 +4170,9 @@
* between 2^{n-1} and 2^n where n is the bit size specified in the
* attributes.
*
- * \note This function is equivalent to calling psa_generate_key_ext()
- * with the production parameters #PSA_KEY_PRODUCTION_PARAMETERS_INIT
- * and `params_data_length == 0` (i.e. `params->data` is empty).
+ * \note This function is equivalent to calling psa_generate_key_custom()
+ * with the custom production parameters #PSA_CUSTOM_KEY_PARAMETERS_INIT
+ * and `custom_data_length == 0` (i.e. `custom_data` is empty).
*
* \param[in] attributes The attributes for the new key.
* \param[out] key On success, an identifier for the newly created
@@ -4221,7 +4221,7 @@
*
* \param[in] attributes The attributes for the new key.
* \param[in] custom Customization parameters for the key generation.
- * When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT
+ * When this is #PSA_CUSTOM_KEY_PARAMETERS_INIT
* with \p custom_data_length = 0,
* this function is equivalent to
* psa_generate_key().