Document new functions psa_generate_key_ext, psa_key_derivation_output_key_ext
Document proposed additions to the PSA API: psa_generate_key_ext(),
psa_key_derivation_output_key_ext(). For psa_generate_key_ext(), document
the one use case we intend to implement immediately, which is generating an
RSA key with a custom public exponent.
Subsequent commits will implement the documented functionality.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index fe10ee0..d6ad969 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -119,8 +119,9 @@
* 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_key_derivation_output_key() or psa_copy_key().
+ * psa_import_key(), psa_generate_key(), psa_generate_key_ext(),
+ * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext()
+ * or psa_copy_key().
*
* This function may be declared as `static` (i.e. without external
* linkage). This function may be provided as a function-like macro,
@@ -163,8 +164,9 @@
* 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_key_derivation_output_key() or psa_copy_key().
+ * psa_import_key(), psa_generate_key(), psa_generate_key_ext(),
+ * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext()
+ * or psa_copy_key().
*
* This function may be declared as `static` (i.e. without external
* linkage). This function may be provided as a function-like macro,
@@ -3226,7 +3228,8 @@
* psa_key_derivation_set_capacity(). You may do this before, in the middle
* 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().
+ * -# To derive a key, call psa_key_derivation_output_key() or
+ * psa_key_derivation_output_key_ext().
* To derive a byte string for a different purpose, call
* psa_key_derivation_output_bytes().
* Successive calls to these functions use successive output bytes
@@ -3449,7 +3452,8 @@
* \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() if the input for step
+ * - psa_key_derivation_output_key() or psa_key_derivation_output_key_ext()
+ * 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
* either a direct input or a key with #PSA_KEY_USAGE_DERIVE set;
@@ -3697,6 +3701,12 @@
* Future versions of this specification may include additional restrictions
* 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 method #PSA_KEY_GENERATION_METHOD_INIT and
+ * `method_length == sizeof(psa_key_generation_method_t)`
+ * (i.e. `method->flags == 0` and `method->data` is empty).
+ *
* \param[in] attributes The attributes for the new key.
* If the key type to be created is
* #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in
@@ -3750,6 +3760,83 @@
psa_key_derivation_operation_t *operation,
mbedtls_svc_key_id_t *key);
+/** Derive a key from an ongoing key derivation operation with a custom method.
+ *
+ * See the description of psa_key_derivation_out_key() for the operation of
+ * this function with the default method.
+ * Mbed TLS currently does not currently support any non-default methods.
+ *
+ * \note This function is experimental and may change in future minor
+ * versions of Mbed TLS.
+ *
+ * \param[in] attributes The attributes for the new key.
+ * If the key type to be created is
+ * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in
+ * the policy must be the same as in the current
+ * operation.
+ * \param[in,out] operation The key derivation operation object to read from.
+ * \param[in] method Customization parameters for the key generation.
+ * When this is #PSA_KEY_GENERATION_METHOD_INIT
+ * with \p method_length =
+ * `sizeof(psa_key_generation_method_t)`,
+ * this function is equivalent to
+ * psa_key_derivation_output_key().
+ * Mbed TLS currently only supports the default
+ * method, i.e. #PSA_KEY_GENERATION_METHOD_INIT,
+ * for all key types.
+ * \param method_length Length of \p method in bytes.
+ * This must be
+ * `sizeof(psa_key_generation_method_t) + n`
+ * where `n` is the size of `method->data` in bytes.
+ * \param[out] key On success, an identifier for the newly created
+ * key. For persistent keys, this is the key
+ * identifier defined in \p attributes.
+ * \c 0 on failure.
+ *
+ * \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_INSUFFICIENT_DATA
+ * There was not enough data to create the desired key.
+ * Note that in this case, no output is written to the output buffer.
+ * The operation's capacity is set to 0, thus subsequent calls to
+ * this function will not succeed, even with a smaller output buffer.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * The key type or key size is not supported, either by the
+ * implementation in general or in this particular location.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * The provided key attributes are not valid for the operation.
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * The #PSA_KEY_DERIVATION_INPUT_SECRET or
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a
+ * key; or one of the inputs was a key whose policy didn't allow
+ * #PSA_KEY_USAGE_DERIVE.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
+ * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
+ * \retval #PSA_ERROR_DATA_INVALID \emptydescription
+ * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
+ * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active and completed
+ * all required input steps), or the library has not been previously
+ * initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_key_derivation_output_key_ext(
+ const psa_key_attributes_t *attributes,
+ psa_key_derivation_operation_t *operation,
+ const psa_key_generation_method_t *method,
+ size_t method_length,
+ mbedtls_svc_key_id_t *key);
+
/** Compare output data from a key derivation operation to an expected value.
*
* This function calculates output bytes from a key derivation algorithm and
@@ -3835,7 +3922,8 @@
* and the permitted algorithm must match the
* operation. The value of this key was likely
* computed by a previous call to
- * psa_key_derivation_output_key().
+ * psa_key_derivation_output_key() or
+ * psa_key_derivation_output_key_ext().
*
* \retval #PSA_SUCCESS \emptydescription
* \retval #PSA_ERROR_INVALID_SIGNATURE
@@ -4003,6 +4091,11 @@
* 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 method #PSA_KEY_GENERATION_METHOD_INIT and
+ * `method_length == sizeof(psa_key_generation_method_t)`
+ * (i.e. `method->flags == 0` and `method->data` is empty).
+ *
* \param[in] attributes The attributes for the new key.
* \param[out] key On success, an identifier for the newly created
* key. For persistent keys, this is the key
@@ -4035,6 +4128,63 @@
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
mbedtls_svc_key_id_t *key);
+/**
+ * \brief Generate a key or key pair using a custom method.
+ *
+ * See the description of psa_generate_key() for the operation of this
+ * function with the default method. In addition, this function supports
+ * the following non-default methods, described in more detail in the
+ * documentation of ::psa_key_generation_method_t:
+ *
+ * - RSA keys: generation with a custom public exponent.
+ *
+ * \note This function is experimental and may change in future minor
+ * versions of Mbed TLS.
+ *
+ * \param[in] attributes The attributes for the new key.
+ * \param[in] method Customization parameters for the key generation.
+ * When this is #PSA_KEY_GENERATION_METHOD_INIT
+ * with \p method_length =
+ * `sizeof(psa_key_generation_method_t)`,
+ * this function is equivalent to
+ * psa_key_derivation_output_key().
+ * \param method_length Length of \p method in bytes.
+ * This must be
+ * `sizeof(psa_key_generation_method_t) + n`
+ * where `n` is the size of `method->data` in bytes.
+ * \param[out] key On success, an identifier for the newly created
+ * key. For persistent keys, this is the key
+ * identifier defined in \p attributes.
+ * \c 0 on failure.
+ *
+ * \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 \emptydescription
+ * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
+ * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
+ * \retval #PSA_ERROR_DATA_INVALID \emptydescription
+ * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
+ * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes,
+ const psa_key_generation_method_t *method,
+ size_t method_length,
+ mbedtls_svc_key_id_t *key);
+
/**@}*/
/** \defgroup interruptible_hash Interruptible sign/verify hash
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index 34d072b..b5e942e 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -223,6 +223,29 @@
return v;
}
+struct psa_key_generation_method_s {
+ /* Future versions may add other fields in this structure. */
+ uint32_t flags;
+ uint8_t data[];
+};
+
+/** The default method for key generation or key derivation.
+ *
+ * Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext()
+ * with `method=PSA_KEY_GENERATION_METHOD_INIT` and
+ * `method_length=sizeof(psa_key_generation_method_t)` is equivalent to
+ * calling psa_generate_key() or psa_key_derivation_output_key()
+ * respectively.
+ */
+#define PSA_KEY_GENERATION_METHOD_INIT { 0 }
+
+static inline struct psa_key_generation_method_s psa_key_generation_method_init(
+ void)
+{
+ const struct psa_key_generation_method_s v = PSA_KEY_GENERATION_METHOD_INIT;
+ return v;
+}
+
struct psa_key_policy_s {
psa_key_usage_t MBEDTLS_PRIVATE(usage);
psa_algorithm_t MBEDTLS_PRIVATE(alg);
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index e2ebd8a..35a3bdb 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -455,6 +455,30 @@
*/
typedef uint16_t psa_key_derivation_step_t;
+/** \brief Custom method for key generation or key derivation.
+ *
+ * This is a structure type with at least the following fields:
+ *
+ * - \c flags: an unsigned integer type. 0 for the default method.
+ * - \c data: a flexible array of bytes.
+ *
+ * The interpretation of this structure depend on the type of the
+ * created key.
+ *
+ * - #PSA_KEY_TYPE_RSA_KEY_PAIR:
+ * - \c flags: must be 0.
+ * - \c data: the public exponent, in little-endian order.
+ * This must be an odd integer and must not be 1.
+ * Implementations must support 65535, should support 3 and may
+ * support other values.
+ * When not using a driver, Mbed TLS supports values up to \c INT_MAX.
+ * If this is empty or if the custom method is omitted altogether,
+ * the default value 65537 is used.
+ * - Other key types: reserved for future use. \c flags must be 0.
+ *
+ */
+typedef struct psa_key_generation_method_s psa_key_generation_method_t;
+
/**@}*/
#endif /* PSA_CRYPTO_TYPES_H */