Rename key-wrap algorithms to be agnostic of the block cipher

Author: athoelke

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

@@ -58,8 +58,6 @@ typedef struct psa_custom_key_parameters_t {
     /* specification-defined value */
 #define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \
     /* specification-defined value */
-#define PSA_ALG_AES_KW ((psa_algorithm_t)0x0B400100)
-#define PSA_ALG_AES_KWP ((psa_algorithm_t)0x0BC00200)
 #define PSA_ALG_AES_MMO_ZIGBEE ((psa_algorithm_t)0x02000007)
 #define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x020000ff)
 #define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
@@ -144,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)

doc/crypto/api/keys/types.rst

@@ -322,9 +322,9 @@ 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)
-            *   `PSA_ALG_AES_KW`
-            *   `PSA_ALG_AES_KWP`
 
     .. subsection:: Key format
 
@@ -371,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
@@ -465,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
@@ -502,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`

doc/crypto/api/ops/key-wrapping.rst

@@ -38,48 +38,54 @@ When using one of these key-wrapping algorithms, the key attributes are managed
 Key-wrapping algorithms
 -----------------------
 
-.. macro:: PSA_ALG_AES_KW
+.. macro:: PSA_ALG_KW
     :definition: ((psa_algorithm_t)0x0B400100)
 
     .. summary::
-        The AES-KW key-wrapping algorithm.
+        A key-wrapping algorithm based on the NIST Key Wrap (KW) mode of a block cipher.
 
-    .. todo::
-        Decide if we should support any 128-bit block-cipher, as described in SP800-38F.
-        If so, the name of this algorithm would need to change.
-        For example, to ``PSA_ALG_SP800_38_KEY_WRAP``?
+        .. versionadded:: 1.4
 
-    This is the NIST Key Wrap algorithm, using an AES key-encryption key, as defined in :cite-title:`SP800-38F`.
-    The algorithm is also defined in :rfc-title:`3394`.
+    KW is defined for block ciphers that have a 128-bit block size.
+    The underlying block cipher is determined by the key type.
 
-    Keys to be wrapped must have a length equal to a multiple of the 'semi-block' size for AES.
+    Keys to be wrapped must have a length equal to a multiple of the 'semi-block' size for the block cipher.
     That is, a multiple of 8 bytes.
 
-    To wrap keys that are not a multiple of the AES semi-block size, `PSA_ALG_AES_KWP` can be used.
+    To wrap keys that are not a multiple of the semi-block size, `PSA_ALG_KWP` can be used.
+
+    This is the NIST Key Wrap algorithm, using any block-cipher that operates on 128-bit blocks, as defined in :cite-title:`SP800-38F`.
+    A definition of AES-KW is also found in :rfc-title:`3394`.
 
     .. subsection:: Compatible key types
 
         | `PSA_KEY_TYPE_AES`
+        | `PSA_KEY_TYPE_ARIA`
+        | `PSA_KEY_TYPE_CAMELLIA`
+        | `PSA_KEY_TYPE_SM4`
 
-.. macro:: PSA_ALG_AES_KWP
+.. macro:: PSA_ALG_KWP
     :definition: ((psa_algorithm_t)0x0BC00200)
 
     .. summary::
-        The AES-KWP key-wrapping algorithm with padding.
+        A key-wrapping algorithm based on the NIST Key Wrap with Padding (KWP) mode of a block cipher.
 
-    .. todo::
-        Decide if we should support any 128-bit block-cipher, as described in SP800-38F.
-        If so, the name of this algorithm would need to change.
-        For example, to ``PSA_ALG_SP800_38_KEY_WRAP_WITH_PADDING``?
+        .. versionadded:: 1.4
 
-    This is the NIST Key Wrap with Padding algorithm, using an AES key-encryption key, as defined in :cite-title:`SP800-38F`.
-    The algorithm is also defined in :rfc-title:`5649`.
+    KWP is defined for block ciphers that have a 128-bit block size.
+    The underlying block cipher is determined by the key type.
 
     This algorithm can wrap a key of any length.
 
+    This is the NIST Key Wrap with Padding algorithm, using any block-cipher that operates on 128-bit blocks, as defined in :cite-title:`SP800-38F`.
+    A definition of AES-KWP is also found in :rfc-title:`5649`.
+
     .. subsection:: Compatible key types
 
         | `PSA_KEY_TYPE_AES`
+        | `PSA_KEY_TYPE_ARIA`
+        | `PSA_KEY_TYPE_CAMELLIA`
+        | `PSA_KEY_TYPE_SM4`
 
 Key wrapping functions
 ----------------------
@@ -89,6 +95,8 @@ Key wrapping functions
     .. summary::
         Unwrap and import a key using a specified wrapping key.
 
+        .. versionadded:: 1.4
+
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
 
@@ -200,6 +208,8 @@ Key wrapping functions
     .. summary::
         Wrap and export a key using a specified wrapping key.
 
+        .. versionadded:: 1.4
+
     .. param:: psa_key_id_t wrapping_key
         Identifier of the key to use for the wrapping operation.
         It must permit the usage `PSA_KEY_USAGE_WRAP`.
@@ -280,6 +290,8 @@ Support macros
     .. summary::
         Sufficient output buffer size for `psa_wrap_key()`.
 
+        .. versionadded:: 1.4
+
     .. param:: wrap_key_type
        A supported key-wrapping key type.
     .. param:: alg
@@ -300,6 +312,8 @@ Support macros
     .. summary::
         Sufficient buffer size for wrapping any asymmetric key pair.
 
+        .. versionadded:: 1.4
+
     This value must be a sufficient buffer size when calling `psa_wrap_key()` to export any asymmetric key pair that is supported by the implementation, regardless of the exact key type and key size.
 
     See also `PSA_WRAP_KEY_OUTPUT_SIZE()`.

doc/crypto/appendix/encodings.rst

@@ -299,8 +299,8 @@ The defined values for S, B, and WRAP-TYPE are shown in :numref:`table-key-wrap-
     :widths: auto
 
     Key-wrapping algorithm, S, B,  WRAP-TYPE, Algorithm identifier, Algorithm value
-    AES-KW, 0, 1, ``0x01``, `PSA_ALG_AES_KW`, ``0x0B400100``
-    AES-KWP, 1, 1, ``0x02``, `PSA_ALG_AES_KWP`, ``0x0BC00200``
+    AES-KW, 0, 1, ``0x01``, `PSA_ALG_KW`, ``0x0B400100``
+    AES-KWP, 1, 1, ``0x02``, `PSA_ALG_KWP`, ``0x0BC00200``
 
 .. _kdf-encoding:
 

doc/crypto/appendix/history.rst

@@ -21,6 +21,8 @@ Changes to the API
 *   Added `psa_check_key_usage()` to query a key's capabilities.
 *   Add support for extendable-output functions (XOF).
     See :secref:`xof`.
+*   Added support for key wrapping using key-wrapping algorithms.
+    See :secref:`key-wrapping`.
 
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -71,8 +73,6 @@ Changes to the API
 
     -   Added `PSA_ALG_ECIES_SEC1` as a key-encapsulation algorithm that implements the key agreement steps of ECIES.
 
-*   Added support for key wrapping using key-wrapping algorithms. See :secref:`key-wrapping`.
-
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~