Replace "generator" with "key derivation"

docs/getting_started.md

@@ -335,7 +335,7 @@ Deriving a new AES-CTR 128-bit encryption key into a given key slot using HKDF w
 1. Set up the generator using the `psa_key_derivation` function providing a key slot containing a key that can be used for key derivation and a salt and label (Note: salt and label are optional).
 1. Initiate a key policy to for the derived key by calling `psa_key_policy_set_usage()` with `PSA_KEY_USAGE_ENCRYPT` parameter and the algorithm `PSA_ALG_CTR`.
 1. Set the key policy to the derived key slot.
-1. Import a key from generator into the desired key slot using (`psa_generate_derived_key`).
+1. Import a key from generator into the desired key slot using (`psa_key_derivation_output_key`).
 1. Clean up generator.
 
 At this point the derived key slot holds a new 128-bit AES-CTR encryption key derived from the key, salt and label provided:
@@ -358,7 +358,7 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
 
     psa_algorithm_t alg = PSA_ALG_HKDF(PSA_ALG_SHA_256);
     psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
-    psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
+    psa_key_derivation_operation_t generator = PSA_KEY_DERIVATION_OPERATION_INIT;
     size_t derived_bits = 128;
     size_t capacity = PSA_BITS_TO_BYTES(derived_bits);
 
@@ -378,10 +378,10 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
 
     psa_set_key_policy(derived_key, &policy);
 
-    psa_generate_derived_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
+    psa_key_derivation_output_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
 
     /* Clean up generator and key */
-    psa_generator_abort(&generator);
+    psa_key_derivation_abort(&generator);
     /* as part of clean up you may want to clean up the keys used by calling:
      * psa_destroy_key( base_key ); or psa_destroy_key( derived_key ); */
     mbedtls_psa_crypto_free();

include/psa/crypto_extra.h

@@ -157,9 +157,10 @@ psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
  * - For HKDF (#PSA_ALG_HKDF), \p salt is the salt used in the "extract" step
  *   and \p label is the info string used in the "expand" step.
  *
- * \param[in,out] generator       The generator object to set up. It must have
- *                                been initialized as per the documentation for
- *                                #psa_crypto_generator_t and not yet in use.
+ * \param[in,out] operation       The key derivation object to set up. It must
+ *                                have been initialized as per the documentation
+ *                                for #psa_key_derivation_operation_t and not
+ *                                yet be in use.
  * \param handle                  Handle to the secret key.
  * \param alg                     The key derivation algorithm to compute
  *                                (\c PSA_ALG_XXX value such that
@@ -169,7 +170,7 @@ psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
  * \param[in] label               Label to use.
  * \param label_length            Size of the \p label buffer in bytes.
  * \param capacity                The maximum number of bytes that the
- *                                generator will be able to provide.
+ *                                operation will be able to provide.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -190,7 +191,7 @@ psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_key_derivation(psa_crypto_generator_t *generator,
+psa_status_t psa_key_derivation(psa_key_derivation_operation_t *operation,
                                 psa_key_handle_t handle,
                                 psa_algorithm_t alg,
                                 const uint8_t *salt,
@@ -433,7 +434,7 @@ psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
 psa_status_t psa_generate_derived_key_to_handle(psa_key_handle_t handle,
                                       psa_key_type_t type,
                                       size_t bits,
-                                      psa_crypto_generator_t *generator);
+                                      psa_key_derivation_operation_t *operation);
 
 psa_status_t psa_generate_random_key_to_handle(psa_key_handle_t handle,
                               psa_key_type_t type,

include/psa/crypto_struct.h

@@ -188,14 +188,14 @@ typedef struct
     uint8_t block_number;
     unsigned int state : 2;
     unsigned int info_set : 1;
-} psa_hkdf_generator_t;
+} psa_hkdf_key_derivation_t;
 #endif /* MBEDTLS_MD_C */
 
 #if defined(MBEDTLS_MD_C)
-typedef struct psa_tls12_prf_generator_s
+typedef struct psa_tls12_prf_key_derivation_s
 {
     /* The TLS 1.2 PRF uses the key for each HMAC iteration,
-     * hence we must store it for the lifetime of the generator.
+     * hence we must store it for the lifetime of the operation.
      * This is different from HKDF, where the key is only used
      * in the extraction phase, but not during expansion. */
     unsigned char *key;
@@ -219,10 +219,10 @@ typedef struct psa_tls12_prf_generator_s
     /* The 1-based number of the block. */
     uint8_t block_number;
 
-} psa_tls12_prf_generator_t;
+} psa_tls12_prf_key_derivation_t;
 #endif /* MBEDTLS_MD_C */
 
-struct psa_crypto_generator_s
+struct psa_key_derivation_s
 {
     psa_algorithm_t alg;
     size_t capacity;
@@ -234,16 +234,16 @@ struct psa_crypto_generator_s
             size_t size;
         } buffer;
 #if defined(MBEDTLS_MD_C)
-        psa_hkdf_generator_t hkdf;
-        psa_tls12_prf_generator_t tls12_prf;
+        psa_hkdf_key_derivation_t hkdf;
+        psa_tls12_prf_key_derivation_t tls12_prf;
 #endif
     } ctx;
 };
 
-#define PSA_CRYPTO_GENERATOR_INIT {0, 0, {{0, 0}}}
-static inline struct psa_crypto_generator_s psa_crypto_generator_init( void )
+#define PSA_KEY_DERIVATION_OPERATION_INIT {0, 0, {{0, 0}}}
+static inline struct psa_key_derivation_s psa_key_derivation_operation_init( void )
 {
-    const struct psa_crypto_generator_s v = PSA_CRYPTO_GENERATOR_INIT;
+    const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT;
     return( v );
 }
 

include/psa/crypto_values.h

@@ -1216,12 +1216,12 @@
  * For example, `PSA_ALG_HKDF(PSA_ALG_SHA256)` is HKDF using HMAC-SHA-256.
  *
  * This key derivation algorithm uses the following inputs:
- * - #PSA_KDF_STEP_SALT is the salt used in the "extract" step.
+ * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step.
  *   It is optional; if omitted, the derivation uses an empty salt.
- * - #PSA_KDF_STEP_SECRET is the secret key used in the "extract" step.
- * - #PSA_KDF_STEP_INFO is the info string used in the "expand" step.
- * You must pass #PSA_KDF_STEP_SALT before #PSA_KDF_STEP_SECRET.
- * You may pass #PSA_KDF_STEP_INFO at any time after steup and before
+ * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step.
+ * - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step.
+ * You must pass #PSA_KEY_DERIVATION_INPUT_SALT before #PSA_KEY_DERIVATION_INPUT_SECRET.
+ * You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before
  * starting to generate output.
  *
  * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
@@ -1590,25 +1590,25 @@
  *
  * This must be a key of type #PSA_KEY_TYPE_DERIVE.
  */
-#define PSA_KDF_STEP_SECRET              ((psa_key_derivation_step_t)0x0101)
+#define PSA_KEY_DERIVATION_INPUT_SECRET     ((psa_key_derivation_step_t)0x0101)
 
 /** A label for key derivation.
  *
  * This must be a direct input.
  */
-#define PSA_KDF_STEP_LABEL               ((psa_key_derivation_step_t)0x0201)
+#define PSA_KEY_DERIVATION_INPUT_LABEL      ((psa_key_derivation_step_t)0x0201)
 
 /** A salt for key derivation.
  *
  * This must be a direct input.
  */
-#define PSA_KDF_STEP_SALT                ((psa_key_derivation_step_t)0x0202)
+#define PSA_KEY_DERIVATION_INPUT_SALT       ((psa_key_derivation_step_t)0x0202)
 
 /** An information string for key derivation.
  *
  * This must be a direct input.
  */
-#define PSA_KDF_STEP_INFO                ((psa_key_derivation_step_t)0x0203)
+#define PSA_KEY_DERIVATION_INPUT_INFO       ((psa_key_derivation_step_t)0x0203)
 
 /**@}*/