Merge pull request #224 from athoelke/crypto-key-wrap-v2

Add support for key wrapping (v2)

Author: athoelke

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

@@ -110,6 +110,7 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \
     /* specification-defined value */
 #define PSA_ALG_IS_KEY_ENCAPSULATION(alg) /* specification-defined value */
+#define PSA_ALG_IS_KEY_WRAP(alg) /* specification-defined value */
 #define PSA_ALG_IS_MAC(alg) /* specification-defined value */
 #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */
 #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */
@@ -141,6 +142,8 @@ typedef struct psa_custom_key_parameters_t {
     /* specification-defined value */
 #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) /* specification-defined value */
 #define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) /* specification-defined value */
+#define PSA_ALG_KW ((psa_algorithm_t)0x0B400100)
+#define PSA_ALG_KWP ((psa_algorithm_t)0x0BC00200)
 #define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)
 #define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002)
 #define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003)
@@ -340,9 +343,11 @@ typedef struct psa_custom_key_parameters_t {
 #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)
 #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000)
 #define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400)
+#define PSA_KEY_USAGE_UNWRAP ((psa_key_usage_t)0x00020000)
 #define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000)
 #define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000)
 #define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800)
+#define PSA_KEY_USAGE_WRAP ((psa_key_usage_t)0x00010000)
 #define PSA_MAC_LENGTH(key_type, key_bits, alg) \
     /* implementation-defined value */
 #define PSA_MAC_MAX_SIZE /* implementation-defined value */
@@ -385,6 +390,9 @@ typedef struct psa_custom_key_parameters_t {
     /* implementation-defined value */
 #define PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE 32
 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */
+#define PSA_WRAP_KEY_OUTPUT_SIZE(wrap_key_type, alg, key_type, key_bits) \
+    /* implementation-defined value */
+#define PSA_WRAP_KEY_PAIR_MAX_SIZE /* implementation-defined value */
 #define PSA_XOF_OPERATION_INIT /* implementation-defined value */
 psa_status_t psa_aead_abort(psa_aead_operation_t * operation);
 psa_status_t psa_aead_decrypt(psa_key_id_t key,
@@ -744,6 +752,12 @@ psa_status_t psa_sign_message(psa_key_id_t key,
                               uint8_t * signature,
                               size_t signature_size,
                               size_t * signature_length);
+psa_status_t psa_unwrap_key(const psa_key_attributes_t * attributes,
+                            psa_key_id_t wrapping_key,
+                            psa_algorithm_t alg,
+                            const uint8_t * data,
+                            size_t data_length,
+                            psa_key_id_t * key);
 psa_status_t psa_verify_hash(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t * hash,
@@ -756,6 +770,12 @@ psa_status_t psa_verify_message(psa_key_id_t key,
                                 size_t input_length,
                                 const uint8_t * signature,
                                 size_t signature_length);
+psa_status_t psa_wrap_key(psa_key_id_t wrapping_key,
+                          psa_algorithm_t alg,
+                          psa_key_id_t key,
+                          uint8_t * data,
+                          size_t data_size,
+                          size_t * data_length);
 psa_status_t psa_xof_abort(psa_xof_operation_t * operation);
 psa_xof_operation_t psa_xof_operation_init(void);
 psa_status_t psa_xof_output(psa_xof_operation_t * operation,

doc/crypto/api/keys/policy.rst

@@ -101,6 +101,8 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
     -   `PSA_KEY_USAGE_VERIFY_HASH`
     -   `PSA_KEY_USAGE_DERIVE`
     -   `PSA_KEY_USAGE_VERIFY_DERIVATION`
+    -   `PSA_KEY_USAGE_WRAP`
+    -   `PSA_KEY_USAGE_UNWRAP`
 
     The flag `PSA_KEY_USAGE_DERIVE_PUBLIC` is used in the function `psa_check_key_usage()` to query if a key can be used for the public role in the specified algorithm.
 
@@ -293,6 +295,27 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
         The key must have the `PSA_KEY_USAGE_DERIVE` permission.
     *   `PSA_ALG_HKDF` is invalid, as there is no such role in single-key derivation algorithms.
 
+.. macro:: PSA_KEY_USAGE_WRAP
+    :definition: ((psa_key_usage_t)0x00010000)
+
+    .. summary::
+        Permission to wrap another key with the key.
+
+    This flag is required to use the key in a key-wrapping operation.
+    The flag must be present on keys used with the following APIs:
+
+    *   `psa_wrap_key()`
+
+.. macro:: PSA_KEY_USAGE_UNWRAP
+    :definition: ((psa_key_usage_t)0x00020000)
+
+    .. summary::
+        Permission to unwrap another key with the key.
+
+    This flag is required to use the key in a key-unwrapping operation.
+    The flag must be present on keys used with the following APIs:
+
+    *   `psa_unwrap_key()`
 
 .. function:: psa_set_key_usage_flags
 

doc/crypto/api/keys/types.rst

@@ -322,6 +322,8 @@ Symmetric keys
             *   `PSA_ALG_ECB_NO_PADDING`
             *   `PSA_ALG_CCM`
             *   `PSA_ALG_GCM`
+            *   `PSA_ALG_KW`
+            *   `PSA_ALG_KWP`
             *   `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input)
 
     .. subsection:: Key format
@@ -369,6 +371,8 @@ Symmetric keys
             *   `PSA_ALG_ECB_NO_PADDING`
             *   `PSA_ALG_CCM`
             *   `PSA_ALG_GCM`
+            *   `PSA_ALG_KW`
+            *   `PSA_ALG_KWP`
             *   `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input)
 
     .. subsection:: Key format
@@ -463,6 +467,8 @@ Symmetric keys
             *   `PSA_ALG_ECB_NO_PADDING`
             *   `PSA_ALG_CCM`
             *   `PSA_ALG_GCM`
+            *   `PSA_ALG_KW`
+            *   `PSA_ALG_KWP`
             *   `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input)
 
     .. subsection:: Key format
@@ -500,6 +506,8 @@ Symmetric keys
             *   `PSA_ALG_ECB_NO_PADDING`
             *   `PSA_ALG_CCM`
             *   `PSA_ALG_GCM`
+            *   `PSA_ALG_KW`
+            *   `PSA_ALG_KWP`
             *   `PSA_ALG_SP800_108_COUNTER_CMAC` (secret input)
 
     .. subsection:: Key format

doc/crypto/api/ops/algorithms.rst

@@ -20,6 +20,7 @@ The specific algorithm identifiers are described alongside the cryptographic ope
 *   :secref:`mac-algorithms`
 *   :secref:`cipher-algorithms`
 *   :secref:`aead-algorithms`
+*   :secref:`key-wrapping-algorithms`
 *   :secref:`key-derivation-algorithms`
 *   :secref:`sign`
 *   :secref:`asymmetric-encryption-algorithms`
@@ -141,6 +142,20 @@ Algorithm categories
 
     See :secref:`aead-algorithms` for a list of defined AEAD algorithms.
 
+.. macro:: PSA_ALG_IS_KEY_WRAP
+    :definition: /* specification-defined value */
+
+    .. summary::
+        Whether the specified algorithm is a key wrapping algorithm.
+
+    .. param:: alg
+        An algorithm identifier: a value of type `psa_algorithm_t`.
+
+    .. return::
+        ``1`` if ``alg`` is a key-wrapping algorithm, ``0`` otherwise. This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier.
+
+    See :secref:`key-wrapping-algorithms` for a list of defined key-wrapping algorithms.
+
 .. macro:: PSA_ALG_IS_KEY_DERIVATION
     :definition: /* specification-defined value */
 

doc/crypto/api/ops/index.rst

@@ -15,6 +15,7 @@ Cryptographic operation reference
     mac
     cipher
     aead
+    key-wrapping
     key-derivation
     signature
     pk-encryption