Rework the encoding of asymmetric key types

This provides more flexibility to allocate additional asymmetric key types for PAKE and PQC algorithms.

Allocate the top bit of the FAMILY field to the ASYM-TYPE field. This makes FAMILY 6 bits and ASYM-TYPE 5.

The top bit of FAMILY was previously for IMPDEF families, but support for IMPDEF key types is already provided via bit 15 in the type. So it was not used in any specification defined family values.

Defined ASYM-TYPE 0 to be a category of non-parameterized asymmetric keys, including RSA.

* Updated the ECC family and DH family definitions. Also added clarification about the inclusion of the parity bit.
* Updated all relevant sections of the encoding appendix, including the bit field graphics and ASYM-TYPE values in the tables.
* Updated the example macros in the appendix to mask FAMILY and ASYM-TYPE fields correctly.

doc/crypto/api/keys/types.rst

@@ -756,12 +756,21 @@ The curve type affects the key format, the key derivation procedure, and the alg
     The range of elliptic curve family identifier values is divided as follows:
 
     :code:`0x00`
-        Reserved. Not allocated to an ECC family.
+        Reserved.
+        Not allocated to an ECC family.
     :code:`0x01 - 0x7f`
         ECC family identifiers defined by this standard.
         Unallocated values in this range are reserved for future use.
     :code:`0x80 - 0xff`
-        Implementations that define additional families must use an encoding in this range.
+        Invalid.
+        Values in this range must not be used.
+
+    The least significant bit of a elliptic curve family identifier is a parity bit for the whole key type.
+    See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types.
+
+    .. admonition:: Implementation note
+
+        To provide other elliptic curve families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type.
 
 .. macro:: PSA_KEY_TYPE_ECC_KEY_PAIR
     :definition: /* specification-defined value */
@@ -1173,12 +1182,21 @@ Diffie Hellman keys
     The range of Diffie-Hellman group family identifier values is divided as follows:
 
     :code:`0x00`
-        Reserved. Not allocated to a DH group family.
+        Reserved.
+        Not allocated to a DH group family.
     :code:`0x01 - 0x7f`
         DH group family identifiers defined by this standard.
         Unallocated values in this range are reserved for future use.
     :code:`0x80 - 0xff`
-        Implementations that define additional families must use an encoding in this range.
+        Invalid.
+        Values in this range must not be used.
+
+    The least significant bit of a Diffie-Hellman group family identifier is a parity bit for the whole key type.
+    See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types.
+
+    .. admonition:: Implementation note
+
+        To provide other Diffie-Hellman group families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type.
 
 .. macro:: PSA_KEY_TYPE_DH_KEY_PAIR
     :definition: /* specification-defined value */

doc/crypto/appendix/encodings.rst

@@ -558,55 +558,57 @@ PAIR is either 0 for a public key, or 3 for a key pair.
 
 The defined values for ASYM-TYPE are shown in :numref:`table-asymmetric-type`.
 
+The defined values for FAMILY depend on the ASYM-TYPE value. See the details for each asymmetric key sub-type.
+
 .. csv-table:: Asymmetric key sub-type values
     :name: table-asymmetric-type
     :header-rows: 1
     :align: left
     :widths: auto
 
     Asymmetric key type, ASYM-TYPE, Details
-    RSA, 0, See :secref:`rsa-key-encoding`
-    Elliptic Curve, 1, See :secref:`ecc-key-encoding`
-    Diffie-Hellman, 2, See :secref:`dh-key-encoding`
-    SPAKE2+, 4, See :secref:`spakep2-key-encoding`
+    Non-parameterized, 0, See :secref:`simple-asymmetric-key-encoding`
+    Elliptic Curve, 2, See :secref:`ecc-key-encoding`
+    Diffie-Hellman, 4, See :secref:`dh-key-encoding`
+    SPAKE2+, 8, See :secref:`spakep2-key-encoding`
 
-.. _rsa-key-encoding:
+.. _simple-asymmetric-key-encoding:
 
-RSA key encoding
-^^^^^^^^^^^^^^^^
+Non-parameterized asymmetric key encoding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The key type for RSA keys defined in this specification are encoded as shown in :numref:`fig-rsa-key-fields`.
+The key type for non-parameterized asymmetric keys defined in this specification are encoded as shown in :numref:`fig-np-key-fields`.
 
-.. figure:: ../figure/encoding/rsa_key.*
-    :name: fig-rsa-key-fields
+.. figure:: ../figure/encoding/np_key.*
+    :name: fig-np-key-fields
 
-    RSA key encoding
+    Non-parameterized asymmetric keys encoding
 
 PAIR is either 0 for a public key, or 3 for a key pair.
 
-The defined values for RSA keys are shown in :numref:`table-rsa-type`.
+The defined values for NP-FAMILY and P are shown in :numref:`table-np-type`.
 
-.. csv-table:: RSA key values
-    :name: table-rsa-type
+.. csv-table:: Non-parameterized asymmetric key family values
+    :name: table-np-type
     :header-rows: 1
     :align: left
     :widths: auto
 
-    RSA key type, Key type, Key type value
-    Public key, `PSA_KEY_TYPE_RSA_PUBLIC_KEY`, ``0x4001``
-    Key pair, `PSA_KEY_TYPE_RSA_KEY_PAIR`, ``0x7001``
+    Key family, Public/pair, PAIR, NP-FAMILY, P, Key type, Key value
+    RSA, Public key, 0, 0, 1, `PSA_KEY_TYPE_RSA_PUBLIC_KEY`, ``0x4001``
+    , Key pair, 3, 0, 1, `PSA_KEY_TYPE_RSA_KEY_PAIR`, ``0x7001``
 
 .. _ecc-key-encoding:
 
-Elliptic Curve key encoding
+Elliptic curve key encoding
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The key type for Elliptic Curve keys defined in this specification are encoded as shown in :numref:`fig-ecc-key-fields`.
+The key type for elliptic curve keys defined in this specification are encoded as shown in :numref:`fig-ecc-key-fields`.
 
 .. figure:: ../figure/encoding/ecc_key.*
     :name: fig-ecc-key-fields
 
-    Elliptic Curve key encoding
+    Elliptic curve key encoding
 
 PAIR is either 0 for a public key, or 3 for a key pair.
 
@@ -630,7 +632,7 @@ The defined values for ECC-FAMILY and P are shown in :numref:`table-ecc-type`.
     Montgomery, 0x20, 1, `PSA_ECC_FAMILY_MONTGOMERY`, ``0x4141``, ``0x7141``
     Twisted Edwards, 0x21, 0, `PSA_ECC_FAMILY_TWISTED_EDWARDS`, ``0x4142``, ``0x7142``
 
-a.  The key type value is constructed from the Elliptic Curve family using either :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` as required.
+a.  The elliptic curve family values defined in the API also include the parity bit. The key type value is constructed from the elliptic curve family using either :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` as required.
 
 .. _dh-key-encoding:
 
@@ -657,12 +659,12 @@ The defined values for DH-FAMILY and P are shown in :numref:`table-dh-type`.
     DH key group, DH-FAMILY, P, DH group :sup:`a`, Public key value, Key pair value
     RFC7919, 0x01, 1, `PSA_DH_FAMILY_RFC7919`, ``0x4203``, ``0x7203``
 
-a.  The key type value is constructed from the Diffie Hellman family using either :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_DH_KEY_PAIR(family)` as required.
+a.  The Diffie Hellman family values defined in the API also include the parity bit. The key type value is constructed from the Diffie Hellman family using either :code:`PSA_KEY_TYPE_DH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_DH_KEY_PAIR(family)` as required.
 
 .. _spakep2-key-encoding:
 
 SPAKE2+ key encoding
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 The key type for SPAKE2+ keys defined in this specification are encoded as shown in :numref:`fig-spake2p-key-fields`.
 
@@ -685,4 +687,5 @@ The defined values for ECC-FAMILY and P are shown in :numref:`table-spake2p-type
     SECP R1, 0x09, 0, :code:`PSA_ECC_FAMILY_SECP_R1`, ``0x4412``, ``0x7412``
     Twisted Edwards, 0x21, 0, :code:`PSA_ECC_FAMILY_TWISTED_EDWARDS`, ``0x4442``, ``0x7442``
 
-a.  The key type value is constructed from the Elliptic Curve family using either :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(family)` as required.
+a.  The elliptic curve family values defined in the API also include the parity bit.
+    The key type value is constructed from the elliptic curve family using either :code:`PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(family)` as required.

doc/crypto/appendix/history.rst

@@ -24,6 +24,15 @@ Changes to the API
 *   Add extended key generation and derivation functions, `psa_generate_key_custom()` and `psa_key_derivation_output_key_custom()`, that accept additional parameters to control the key creation process.
 *   Define a key production parameter to select a non-default exponent for RSA key generation.
 
+*   Reworked the allocation of bits in the encoding of asymmetric keys, to increase the scope for additional asymmetric key types:
+
+    -   Bit 7 was previously an unused indicator for :sc:`implementation defined` family values, and is now allocated to the ASYM-TYPE.
+    -   ASYM-TYPE 0 is now a category for non-parameterized asymmetric keys, of which RSA is one specific type.
+
+    This has no effect on any currently allocated key type values, but affects the correct implementation of macros used to manipulate asymmetric key types.
+
+    See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`.
+
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/crypto/appendix/specdef_values.rst

@@ -246,6 +246,8 @@ Algorithm macros
     #define PSA_PAKE_PRIMITIVE_GET_TYPE(pake_primitive) \
         ((psa_pake_primitive_type_t)((pake_primitive >> 24) & 0xFF))
 
+.. _appendix-specdef-key-values:
+
 Key type macros
 ~~~~~~~~~~~~~~~
 
@@ -255,43 +257,43 @@ Key type macros
         (1u << (((type) >> 8) & 7))
 
     #define PSA_KEY_TYPE_DH_GET_FAMILY(type) \
-        ((psa_dh_family_t) ((type) & 0x00ff))
+        ((psa_dh_family_t) ((type) & 0x007f))
 
     #define PSA_KEY_TYPE_DH_KEY_PAIR(group) \
-        ((psa_key_type_t) (0x7200 | (group)))
+        ((psa_key_type_t) (0x7200 | ((group) & 0x007f)))
 
     #define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \
-        ((psa_key_type_t) (0x4200 | (group)))
+        ((psa_key_type_t) (0x4200 | ((group) & 0x007f)))
 
     #define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \
-        ((psa_ecc_family_t) ((type) & 0x00ff))
+        ((psa_ecc_family_t) ((type) & 0x007f))
 
     #define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \
-        ((psa_key_type_t) (0x7100 | (curve)))
+        ((psa_key_type_t) (0x7100 | ((curve) & 0x007f)))
 
     #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \
-        ((psa_key_type_t) (0x4100 | (curve)))
+        ((psa_key_type_t) (0x4100 | ((curve) & 0x007f)))
 
     #define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
         (((type) & 0x4000) == 0x4000)
 
     #define PSA_KEY_TYPE_IS_DH(type) \
-        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4200)
+        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4200)
 
     #define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \
-        (((type) & 0xff00) == 0x7200)
+        (((type) & 0xff80) == 0x7200)
 
     #define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \
-        (((type) & 0xff00) == 0x4200)
+        (((type) & 0xff80) == 0x4200)
 
     #define PSA_KEY_TYPE_IS_ECC(type) \
-        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4100)
+        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4100)
 
     #define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \
-        (((type) & 0xff00) == 0x7100)
+        (((type) & 0xff80) == 0x7100)
 
     #define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \
-        (((type) & 0xff00) == 0x4100)
+        (((type) & 0xff80) == 0x4100)
 
     #define PSA_KEY_TYPE_IS_KEY_PAIR(type) \
         (((type) & 0x7000) == 0x7000)
@@ -303,13 +305,13 @@ Key type macros
         (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001)
 
     #define PSA_KEY_TYPE_IS_SPAKE2P(type) \
-        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4400)
+        ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4400)
 
     #define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \
-        (((type) & 0xff00) == 0x7400)
+        (((type) & 0xff80) == 0x7400)
 
     #define PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY(type) \
-        (((type) & 0xff00) == 0x4400)
+        (((type) & 0xff80) == 0x4400)
 
     #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \
         (((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000)
@@ -321,13 +323,13 @@ Key type macros
         ((psa_key_type_t) ((type) & ~0x3000))
 
     #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \
-        ((psa_ecc_family_t) ((type) & 0x00ff))
+        ((psa_ecc_family_t) ((type) & 0x007f))
 
     #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) \
-        ((psa_key_type_t) (0x7400 | (curve)))
+        ((psa_key_type_t) (0x7400 | ((curve) & 0x007f)))
 
     #define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \
-        ((psa_key_type_t) (0x4400 | (curve)))
+        ((psa_key_type_t) (0x4400 | ((curve) & 0x007f)))
 
 Hash suspend state macros
 ~~~~~~~~~~~~~~~~~~~~~~~~~

doc/crypto/figure/encoding/asymmetric_key.json

@@ -1,8 +1,8 @@
 {
     "reg": [
         { "name": "P", "bits": 1 },
-        { "name": "FAMILY", "bits": 7 },
-        { "name": "ASYM-TYPE", "bits": 4 },
+        { "name": "FAMILY", "bits": 6 },
+        { "name": "ASYM-TYPE", "bits": 5 },
         { "name": "PAIR", "bits": 2 },
         { "name": "1", "bits": 1 },
         { "name": "0", "bits": 1 }
@@ -15,4 +15,4 @@
         "vspace": 52,
         "hspace": 300
     }
-}
+}

doc/crypto/figure/encoding/asymmetric_key.json.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <[email protected]>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/crypto/figure/encoding/asymmetric_key.pdf.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <[email protected]>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/crypto/figure/encoding/asymmetric_key.svg.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <[email protected]>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/crypto/figure/encoding/dh_key.json

@@ -1,8 +1,8 @@
 {
     "reg": [
         { "name": "P", "bits": 1 },
-        { "name": "DH-FAMILY", "bits": 7 },
-        { "name": "2", "bits": 4 },
+        { "name": "DH-FAMILY", "bits": 6 },
+        { "name": "4", "bits": 5 },
         { "name": "PAIR", "bits": 2 },
         { "name": "1", "bits": 1 },
         { "name": "0", "bits": 1 }
@@ -15,4 +15,4 @@
         "vspace": 52,
         "hspace": 300
     }
-}
+}

doc/crypto/figure/encoding/dh_key.json.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <[email protected]>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

doc/crypto/figure/encoding/dh_key.pdf.license

@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <[email protected]>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <[email protected]>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license