Add extended key creation functions for non-default production methods

doc/crypto/api.db/psa/crypto.h

@@ -24,6 +24,9 @@ typedef uint32_t psa_pake_primitive_t;
 typedef uint8_t psa_pake_primitive_type_t;
 typedef uint8_t psa_pake_role_t;
 typedef uint8_t psa_pake_step_t;
+typedef struct psa_custom_key_parameters_t {
+    uint32_t flags;
+} psa_custom_key_parameters_t;
 #define PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) \
     /* implementation-defined value */
 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \
@@ -206,6 +209,7 @@ typedef uint8_t psa_pake_step_t;
     /* implementation-defined value */
 #define PSA_CRYPTO_API_VERSION_MAJOR 1
 #define PSA_CRYPTO_API_VERSION_MINOR 3
+#define PSA_CUSTOM_KEY_PARAMETERS_INIT { 0 }
 #define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03)
 #define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30)
 #define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t) 0x33)
@@ -505,6 +509,11 @@ psa_status_t psa_export_public_key(psa_key_id_t key,
                                    size_t * data_length);
 psa_status_t psa_generate_key(const psa_key_attributes_t * attributes,
                               psa_key_id_t * key);
+psa_status_t psa_generate_key_custom(const psa_key_attributes_t *attributes,
+                                     const psa_custom_key_parameters_t *custom,
+                                     const uint8_t *custom_data,
+                                     size_t custom_data_length,
+                                     mbedtls_svc_key_id_t *key);
 psa_status_t psa_generate_random(uint8_t * output,
                                  size_t output_size);
 psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t * attributes);
@@ -585,6 +594,12 @@ psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t * op
 psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t * attributes,
                                            psa_key_derivation_operation_t * operation,
                                            psa_key_id_t * key);
+psa_status_t psa_key_derivation_output_key_custom(const psa_key_attributes_t *attributes,
+                                                  psa_key_derivation_operation_t *operation,
+                                                  const psa_custom_key_parameters_t *custom,
+                                                  const uint8_t *custom_data,
+                                                  size_t custom_data_length,
+                                                  mbedtls_svc_key_id_t *key);
 psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t * operation,
                                              size_t capacity);
 psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t * operation,

doc/crypto/api/keys/attributes.rst

@@ -111,8 +111,8 @@ Managing key attributes
     #.  If the key is persistent, call `psa_set_key_id()`. Also call `psa_set_key_lifetime()` to place the key in a non-default location.
     #.  Set the key policy with `psa_set_key_usage_flags()` and `psa_set_key_algorithm()`.
     #.  Set the key type with `psa_set_key_type()`. Skip this step if copying an existing key with `psa_copy_key()`.
-    #.  When generating a random key with `psa_generate_key()` or deriving a key with `psa_key_derivation_output_key()`, set the desired key size with `psa_set_key_bits()`.
-    #.  Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.
+    #.  When generating a random key with `psa_generate_key()` or `psa_generate_key_custom()`, or deriving a key with `psa_key_derivation_output_key()` or `psa_key_derivation_output_key_custom()`, set the desired key size with `psa_set_key_bits()`.
+    #.  Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.
     #.  Optionally call `psa_reset_key_attributes()`, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself.
 
     A typical sequence to query a key's attributes is as follows:

doc/crypto/api/keys/ids.rst

@@ -92,7 +92,7 @@ Attribute accessors
 
     If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to `PSA_KEY_LIFETIME_PERSISTENT`.
 
-    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`.
+    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`.
 
     .. admonition:: Implementation note
 

doc/crypto/api/keys/lifetimes.rst

@@ -273,7 +273,7 @@ Attribute accessors
 
     To make a key persistent, give it a persistent key identifier by using `psa_set_key_id()`. By default, a key that has a persistent identifier is stored in the default storage area identifier by `PSA_KEY_LIFETIME_PERSISTENT`. Call this function to choose a storage area, or to explicitly declare the key as volatile.
 
-    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`.
+    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_generate_key_custom()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_agreement()`, `psa_pake_get_shared_key()`, or `psa_copy_key()`.
 
     .. admonition:: Implementation note
 

doc/crypto/api/keys/management.rst

@@ -15,8 +15,8 @@ Key creation
 New keys can be created in the following ways:
 
 *   `psa_import_key()` creates a key from a data buffer provided by the application.
-*   `psa_generate_key()` creates a key from randomly generated data.
-*   `psa_key_derivation_output_key()` creates a key from data generated by a pseudorandom derivation process. See :secref:`kdf`.
+*   `psa_generate_key()` and `psa_generate_key_custom()` create a key from randomly generated data.
+*   `psa_key_derivation_output_key()` and `psa_key_derivation_output_key_custom()` create a key from data generated by a pseudorandom derivation process. See :secref:`kdf`.
 *   `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`.
 *   `psa_pake_get_shared_key()` creates a key from the shared secret result of a password-authenticated key exchange. See :secref:`pake`.
 *   `psa_copy_key()` duplicates an existing key with a different lifetime or with a more restrictive usage policy.
@@ -114,6 +114,50 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. note::
         The |API| does not support asymmetric private key objects outside of a key pair. To import a private key, the ``attributes`` must specify the corresponding key pair type. Depending on the key type, either the import format contains the public key data or the implementation will reconstruct the public key from the private key as needed.
 
+.. struct:: psa_custom_key_parameters_t
+    :type:
+
+    .. summary::
+        Custom production parameters for key generation or key derivation.
+
+    .. field:: uint32_t flags
+        Flags to control the key production process.
+        ``0`` for the default production parameters.
+
+    .. note::
+
+        Future versions of the specification, and implementations, may add other fields in this structure.
+
+    The interpretation of this structure depends on the type of the key. :numref:`tab-custom-key-parameters` shows the custom production parameters for each type of key. See the key type definitions for details of the valid parameter values.
+
+    .. list-table:: Custom key parameters
+        :name: tab-custom-key-parameters
+        :widths: 1 4
+        :header-rows: 1
+
+        *   -   Key type
+            -   Custom key parameters
+
+        *   -   RSA
+
+            -   Use the production parameters to select an exponent value that is different from the default value of ``65537``.
+
+                See `PSA_KEY_TYPE_RSA_KEY_PAIR`.
+
+        *   -   Other key types
+            -   Reserved for future use.
+
+                ``flags`` must be ``0``.
+
+.. macro:: PSA_CUSTOM_KEY_PARAMETERS_INIT
+    :definition: { 0 }
+
+    .. summary::
+        The default production parameters for key generation or key derivation.
+
+    Calling `psa_generate_key_custom()` or `psa_key_derivation_output_key_custom()` with :code:`custom == PSA_CUSTOM_KEY_PARAMETERS_INIT` and ``custom_data_length == 0`` is equivalent to calling `psa_generate_key()` or `psa_key_derivation_output_key()`
+    respectively.
+
 .. function:: psa_generate_key
 
     .. summary::
@@ -142,7 +186,9 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
             The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier.
 
     .. param:: psa_key_id_t * key
-        On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure.
+        On success, an identifier for the newly created key.
+        For persistent keys, this is the key identifier defined in ``attributes``.
+        `PSA_KEY_ID_NULL` on failure.
 
     .. return:: psa_status_t
     .. retval:: PSA_SUCCESS
@@ -179,9 +225,95 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
 
     Implementations must reject an attempt to generate a key of size ``0``.
 
-    The following type-specific considerations apply:
+    The key type definitions in :secref:`key-types` provide specific details relating to generation of the key.
+
+    .. note::
+
+        This function is equivalent to calling `psa_generate_key_custom()` with the production parameters `PSA_CUSTOM_KEY_PARAMETERS_INIT` and ``custom_data_length == 0`` (``custom_data`` is ignored).
+
+.. function:: psa_generate_key_custom
+
+    .. summary::
+        Generate a key or key pair using custom production parameters.
+
+    .. param:: const psa_key_attributes_t * attributes
+        The attributes for the new key.
+
+        The following attributes are required for all keys:
+
+        *   The key type. It must not be an asymmetric public key.
+        *   The key size. It must be a valid size for the key type.
+
+        The following attributes must be set for keys used in cryptographic operations:
+
+        *   The key permitted-algorithm policy, see :secref:`permitted-algorithms`.
+        *   The key usage flags, see :secref:`key-usage-flags`.
+
+        The following attributes must be set for keys that do not use the default volatile lifetime:
+
+        *   The key lifetime, see :secref:`key-lifetimes`.
+        *   The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`.
+
+        .. note::
+            This is an input parameter: it is not updated with the final key attributes.
+            The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier.
+
+    .. param:: const psa_custom_key_parameters_t *custom
+        Customized production parameters for the key generation.
+
+        When this is `PSA_CUSTOM_KEY_PARAMETERS_INIT` with ``custom_data_length == 0``, this function is equivalent to `psa_generate_key()`.
+    .. param:: const uint8_t *custom_data
+        A buffer containing additional variable-sized production parameters.
+    .. param:: size_t custom_data_length
+        Length of ``custom_data`` in bytes.
+    .. param:: mbedtls_svc_key_id_t *key
+        On success, an identifier for the newly created key.
+        For persistent keys, this is the key identifier defined in ``attributes``.
+        `PSA_KEY_ID_NULL` on failure.
+
+    .. return:: psa_status_t
+    .. retval:: PSA_SUCCESS
+        Success.
+        If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
+    .. retval:: PSA_ERROR_ALREADY_EXISTS
+        This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
+    .. retval:: PSA_ERROR_NOT_SUPPORTED
+        The following conditions can result in this error:
+
+        *   The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.
+        *   The production parameters are not supported by the implementation.
+    .. retval:: PSA_ERROR_INVALID_ARGUMENT
+        The following conditions can result in this error:
+
+        *   The key type is invalid, or is an asymmetric public key type.
+        *   The key size is not valid for the key type.
+        *   The key lifetime is invalid.
+        *   The key identifier is not valid for the key lifetime.
+        *   The key usage flags include invalid values.
+        *   The key's permitted-usage algorithm is invalid.
+        *   The key attributes, as a whole, are invalid.
+        *   The production parameters are invalid.
+    .. retval:: PSA_ERROR_NOT_PERMITTED
+        The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
+    .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY
+    .. retval:: PSA_ERROR_INSUFFICIENT_ENTROPY
+    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
+    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
+    .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE
+    .. retval:: PSA_ERROR_STORAGE_FAILURE
+    .. retval:: PSA_ERROR_DATA_CORRUPT
+    .. retval:: PSA_ERROR_DATA_INVALID
+    .. retval:: PSA_ERROR_BAD_STATE
+        The library requires initializing by a call to `psa_crypto_init()`.
+
+    Use this function to provide explicit production parameters when generating a key.
+    See the description of `psa_generate_key()` for the operation of this function with the default production parameters.
+
+    The key is generated randomly. Its location, policy, type and size are taken from ``attributes``.
+
+    Implementations must reject an attempt to generate a key of size ``0``.
 
-    *   For RSA keys (`PSA_KEY_TYPE_RSA_KEY_PAIR`), the public exponent is 65537. The modulus is a product of two probabilistic primes between :math:`2^{n-1}` and :math:`2^n` where :math:`n` is the bit size specified in the attributes.
+    See the documentation of `psa_custom_key_parameters_t` for a list of non-default production parameters. See the key type definitions in :secref:`key-types` for details of the custom production parameters used for key generation.
 
 .. function:: psa_copy_key
 

doc/crypto/api/keys/policy.rst

@@ -236,7 +236,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
     *   `psa_key_derivation_key_agreement()`
     *   `psa_raw_key_agreement()`
 
-    If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key derivation operation, then it permits calling `psa_key_derivation_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()` at the end of the operation.
+    If this flag is present on all keys used in calls to `psa_key_derivation_input_key()` for a key derivation operation, then it permits calling `psa_key_derivation_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_output_key_custom()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()` at the end of the operation.
 
 .. macro:: PSA_KEY_USAGE_VERIFY_DERIVATION
     :definition: ((psa_key_usage_t)0x00008000)

doc/crypto/api/keys/types.rst

@@ -643,6 +643,23 @@ RSA keys
 
         See `PSA_KEY_TYPE_RSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`.
 
+    .. subsection:: Key generation
+
+        A call to `psa_generate_key()` will generate an RSA key-pair with the default public exponent of ``65537``. The modulus :math:`n=pq` is a product of two probabilistic primes :math:`p\ \text{and}\ q`, where :math:`2^{r-1} \le n < 2^r` and :math:`r` is the bit size specified in the attributes.
+
+        The exponent can be explicitly specified in non-default production parameters in a call to `psa_generate_key_custom()`. Use the following custom production parameters:
+
+        *   The production parameters structure, ``custom``, must have ``flags`` set to zero.
+
+        *   If ``custom_data_length == 0``, the default exponent value ``65537`` is used.
+
+        *   The additional production parameter buffer ``custom_data`` is the public exponent, in little-endian byte order.
+
+            The exponent must be an odd integer greater than ``1``.
+            An implementation must support an exponent of ``65537``, and is recommended to support an exponent of ``3``, and can support other values.
+
+            The maximum supported exponent value is :scterm:`implementation defined`.
+
     .. subsection:: Key derivation
 
         The method used by `psa_key_derivation_output_key()` to derive an RSA key-pair is :term:`implementation defined`.