ARM-software · athoelke · Sep 3, 2024 · Apr 4, 2024 · Apr 5, 2024
@@ -10,9 +10,9 @@ Key identifiers are integral values that act as permanent names for persistent k
 
 :code:`PSA_KEY_ID_NULL = 0`
     Reserved as an invalid key identifier.
-:code:`PSA_KEY_ID_USER_MIN – PSA_KEY_ID_USER_MAX`
+:code:`PSA_KEY_ID_USER_MIN - PSA_KEY_ID_USER_MAX`
     Applications can freely choose persistent key identifiers in this range.
-:code:`PSA_KEY_ID_VENDOR_MIN – PSA_KEY_ID_VENDOR_MAX`
+:code:`PSA_KEY_ID_VENDOR_MIN - PSA_KEY_ID_VENDOR_MAX`
     Implementations can define additional persistent key identifiers in this range, and must allocate any volatile key identifiers from this range.
 
 Key identifiers outside these ranges are reserved for future use.

@@ -121,12 +121,12 @@ Lifetime encodings
 
                 Implementations should support this value if they support persistent keys at all. Applications should use this value if they have no specific needs that are only met by implementation-specific features.
 
-        *   -   ``2 – 127``
+        *   -   ``2 - 127``
             -   Persistent key with a PSA Certified API-specified lifetime.
 
                 The |API| does not define the meaning of these values, but another PSA Certified API may do so.
 
-        *   -   ``128 – 254``
+        *   -   ``128 - 254``
             -   Persistent key with a vendor-specified lifetime.
 
                 No PSA Certified API will define the meaning of these values, so implementations may choose the meaning freely. As a guideline, higher persistence levels should cause a key to survive more management events than lower levels.
@@ -171,12 +171,12 @@ Lifetime encodings
 
                 Implementations should support this value if there is a secure element attached to the operating environment. As a guideline, secure elements may provide higher resistance against side channel and physical attacks than the primary local storage, but may have restrictions on supported key types, sizes, policies and operations and may have different performance characteristics.
 
-        *   -   ``2 – 0x7fffff``
+        *   -   ``2 - 0x7fffff``
             -   Other locations defined by a PSA specification.
 
                 The |API| does not currently assign any meaning to these locations, but future versions of this specification or other PSA Certified APIs may do so.
 
-        *   -   ``0x800000 – 0xffffff``
+        *   -   ``0x800000 - 0xffffff``
             -   Vendor-defined locations.
 
                 No PSA Certified API will assign a meaning to locations in this range.

@@ -21,11 +21,11 @@ Key type encoding
 
     :code:`PSA_KEY_TYPE_NONE == 0`
         Reserved as an invalid key type.
-    :code:`0x0001 – 0x7fff`
+    :code:`0x0001 - 0x7fff`
         Specification-defined key types.
         Key types defined by this standard always have bit 15 clear.
         Unallocated key type values in this range are reserved for future use.
-    :code:`0x8000 – 0xffff`
+    :code:`0x8000 - 0xffff`
         Implementation-defined key types.
         Implementations that define additional key types must use an encoding with bit 15 set.
         The related support macros will be easier to write if these key encodings also respect the bitwise structure used by standard encodings.
@@ -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.
-    :code:`0x01 – 0x7f`
+        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.
+    :code:`0x80 - 0xff`
+        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.
-    :code:`0x01 – 0x7f`
+        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.
+    :code:`0x80 - 0xff`
+        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 */

@@ -41,11 +41,11 @@ Algorithm encoding
 
     :code:`0x00000000`
         Reserved as an invalid algorithm identifier.
-    :code:`0x00000001 – 0x7fffffff`
+    :code:`0x00000001 - 0x7fffffff`
         Specification-defined algorithm identifiers.
         Algorithm identifiers defined by this standard always have bit 31 clear.
         Unallocated algorithm identifier values in this range are reserved for future use.
-    :code:`0x80000000 – 0xffffffff`
+    :code:`0x80000000 - 0xffffffff`
         Implementation-defined algorithm identifiers.
         Implementations that define additional algorithms must use an encoding with bit 31 set.
         The related support macros will be easier to write if these algorithm identifier encodings also respect the bitwise structure used by standard encodings.

@@ -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.
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -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
     }
-}
+}
@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
@@ -1,2 +1,2 @@
-SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license