diff --git a/doc/crypto/overview/intro.rst b/doc/crypto/overview/intro.rst index 7c2306c1..18904036 100644 --- a/doc/crypto/overview/intro.rst +++ b/doc/crypto/overview/intro.rst @@ -26,6 +26,12 @@ This document includes: * General considerations for implementers of this specification, and for applications that use the interface defined in this specification. See :secref:`implementation-considerations` and :secref:`usage-considerations`. * A detailed definition of the API. See :secref:`library-management`, :secref:`key-management`, and :secref:`crypto-operations`. +:cite-title:`PSA-PQC` is a companion document for version 1.3 of this specification. +`[PSA-PQC]` defines an API for :term:`Post-Quantum Cryptography` (PQC) algorithms. +The PQC API is a proposal at BETA status. +The API defined by `[PSA-PQC]` is provided in a separate specification to reflect the different status of this API, and indicate that a future version can include incompatible changes to the PQC API. +When the PQC API is stable, it will be included in a future version of the |API| specification. + In future, companion documents will define *profiles* for this specification. A profile is a minimum mandatory subset of the interface that a compliant implementation must provide. diff --git a/doc/crypto/references b/doc/crypto/references index 196e15df..baf1fca4 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -396,3 +396,8 @@ :author: Thread Group :publication: July 2022 :url: www.threadgroup.org/ThreadSpec + +.. reference:: PSA-PQC + :title: PSA Certified Crypto API 1.3 PQC Extension + :doc_no: ARM AES 0119 + :url: arm-software.github.io/psa-api/crypto diff --git a/doc/crypto/terms b/doc/crypto/terms index fdcfed71..65ce3f3a 100644 --- a/doc/crypto/terms +++ b/doc/crypto/terms @@ -186,3 +186,8 @@ application instances. See :secref:`isolation`. + +.. term:: Post-Quantum Cryptography + :abbr: PQC + + A cryptographic scheme that relies on mathematical problems that do not have efficient algorithms for either classical or quantum computing. diff --git a/doc/ext-pqc/README.md b/doc/ext-pqc/README.md new file mode 100644 index 00000000..2ccf560c --- /dev/null +++ b/doc/ext-pqc/README.md @@ -0,0 +1,20 @@ + + +# PSA Certified Crypto API PQC Extension — specification sources + +The Crypto API PQC Extension specification source files are organized as follows: + +Folder | Content +-- | -- +Current directory | Configuration and front-matter +`overview` | Informative chapter 1 +`api` | API reference chapter 2 +`appendix` | Appendix chapters +`figure` | Image files + +---- + +*Copyright 2024, Arm Limited and/or its affiliates* diff --git a/doc/ext-pqc/about.rst b/doc/ext-pqc/about.rst new file mode 100644 index 00000000..f69ae950 --- /dev/null +++ b/doc/ext-pqc/about.rst @@ -0,0 +1,24 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. include:: releases + +.. include:: references + +.. include:: terms + +.. release-info:: + :extend: + + The detailed changes in each release are described in :secref:`changes`. + +.. potential-for-change:: + :hide: + +.. current-status:: + + This document is at Beta quality status which has a particular meaning to Arm of which the recipient must be aware. + A Beta quality specification will be sufficiently stable & committed for initial product development, however all aspects of the architecture described herein remain SUBJECT TO CHANGE. + Please ensure that you have the latest revision. + +.. about:: diff --git a/doc/ext-pqc/api.db/psa/crypto-pqc.h b/doc/ext-pqc/api.db/psa/crypto-pqc.h new file mode 100644 index 00000000..8f66b7e5 --- /dev/null +++ b/doc/ext-pqc/api.db/psa/crypto-pqc.h @@ -0,0 +1,44 @@ +// SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates +// SPDX-License-Identifier: Apache-2.0 + +typedef uint8_t psa_slh_dsa_family_t; +#define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \ + /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \ + /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_ML_DSA ((psa_algorithm_t) 0x06004500) +#define PSA_ALG_DETERMINISTIC_SLH_DSA ((psa_algorithm_t) 0x06004100) +#define PSA_ALG_HASH_ML_DSA(hash_alg) /* specification-defined value */ +#define PSA_ALG_HASH_SLH_DSA(hash_alg) /* specification-defined value */ +#define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \ + /* specification-defined value */ +#define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + /* specification-defined value */ +#define PSA_ALG_IS_HASH_ML_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HASH_SLH_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_ML_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_SLH_DSA(alg) /* specification-defined value */ +#define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400) +#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0b000200) +#define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016) +#define PSA_ALG_SLH_DSA ((psa_algorithm_t) 0x06004000) +#define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_ML_KEM(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + /* specification-defined value */ +#define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002) +#define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002) +#define PSA_KEY_TYPE_ML_KEM_KEY_PAIR ((psa_key_type_t)0x7004) +#define PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY ((psa_key_type_t)0x4004) +#define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */ +#define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04) +#define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02) +#define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d) +#define PSA_SLH_DSA_FAMILY_SHAKE_S ((psa_slh_dsa_family_t) 0x0b) diff --git a/doc/ext-pqc/api/hash.rst b/doc/ext-pqc/api/hash.rst new file mode 100644 index 00000000..0ab66f9a --- /dev/null +++ b/doc/ext-pqc/api/hash.rst @@ -0,0 +1,28 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. header:: psa/crypto-pqc + :seq: 1 + +.. _hashes: + +Additional Hash algorithms +========================== + +.. macro:: PSA_ALG_SHAKE128_256 + :definition: ((psa_algorithm_t)0x02000016) + + .. summary:: + The first 256 bits (32 bytes) of the SHAKE128 output. + + This can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`). + + SHAKE128 is defined in :cite:`FIPS202`. + + .. note:: + For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-256 is recommended. SHA3-256 has the same output size, and a theoretically higher security strength. + +.. comment + Update the description of PSA_ALG_SHAKE256_512 to state: + + This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`), and can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`). diff --git a/doc/ext-pqc/api/mldsa.rst b/doc/ext-pqc/api/mldsa.rst new file mode 100644 index 00000000..1d037f7e --- /dev/null +++ b/doc/ext-pqc/api/mldsa.rst @@ -0,0 +1,434 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. header:: psa/crypto-pqc + :seq: 3 + +.. _ml-dsa: + +Module Lattice-based signatures +=============================== + +.. _ml-dsa-keys: + +Module Lattice-based signature keys +----------------------------------- + +The |API| supports Module Lattice-based digital signatures (ML-DSA), as defined in :cite-title:`FIPS204`. + +.. macro:: PSA_KEY_TYPE_ML_DSA_KEY_PAIR + :definition: ((psa_key_type_t)0x7002) + + .. summary:: + ML-DSA key pair: both the private and public key. + + The key attribute size of an ML-DSA key is the numeric ML-DSA parameter-set identifier defined in `[FIPS204]`. + The values are based on the dimensions of the matrix :math:`A`, and do not directly define the key size in bytes: + + * ML-DSA-44 : ``key_bits = 44`` + * ML-DSA-65 : ``key_bits = 65`` + * ML-DSA-87 : ``key_bits = 87`` + + See also §4 in `[FIPS204]`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_DSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for ML-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-MLDSA`. + + The current proposed format is based on the current expected outcome of that process. + + An ML-DSA key pair is the :math:`(pk,sk)` pair of public key and secret key, which are generated from a secret 32-byte seed, :math:`\xi`. See `[FIPS204]` §5.1. + + The data format for import and export of the key pair is the 32-byte seed :math:`\xi`. + + .. rationale:: + + The IETF working group responsible for defining the format of the ML-DSA keys in *SubjectPublicKeyInfo* and *OneAsymmetricKey* structures is discussing the formats at present (September 2024), with the current consensus to using just the seed value as the private key, for the following reasons: + + * ML-DSA key pairs are several kB in size, but can be recomputed efficiently from the initial 32-byte seed. + * There is no need to validate an imported ML-DSA private key --- every 32-byte seed values is valid. + * The public key cannot be derived from the secret key, so a key pair must store both the secret key and the public key. + The size of the key pair depends on the ML-DSA parameter set as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Key-pair size in bytes + ML-DSA-44, 3872 + ML-DSA-65, 5984 + ML-DSA-87, 7488 + + * It is better for the standard to choose a single format to improve interoperability. + + See `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. admonition:: Implementation note + + An implementation can optionally compute and store the :math:`(pk,sk)` values, to accelerate operations that use the key. + It is recommended that an implementation retains the seed :math:`\xi` with the key pair, in order to export the key, or copy the key to a different location. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the 32-byte ML-DSA key-pair seed, :math:`xi`. + The key pair :math:`(pk, sk)` is generated from the seed as defined by ``ML-DSA.KeyGen_internal()`` in `[FIPS204]` §6.1. + + .. admonition:: Implementation note + + It is :scterm:`implementation defined` whether the seed :math:`xi` is expanded to :math:`(pk, sk)` at the point of derivation, or only just before the key is used. + +.. macro:: PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4002) + + .. summary:: + ML-DSA public key. + + The key attribute size of an ML-DSA public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ML_DSA_KEY_PAIR`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_DSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for ML-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-MLDSA`. + + The current proposed format is based on the current expected outcome of that process. + + An ML-DSA public key is the :math:`pk` output of ``ML-DSA.KeyGen()``, defined in `[FIPS204]` §5.1. + + The size of the public key depends on the ML-DSA parameter set as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Public-key size in bytes + ML-DSA-44, 1312 + ML-DSA-65, 1952 + ML-DSA-87, 2592 + +.. macro:: PSA_KEY_TYPE_IS_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-DSA key, either a key pair or a public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + + +.. _ml-dsa-algorithms: + +Module Lattice-based signature algorithms +----------------------------------------- + +The ML-DSA signature and verification scheme is defined in :cite-title:`FIPS204`. +ML-DSA has three parameter sets which provide differing security strengths. + +ML-DSA keys are large: 1.2--2.5kB for the public key, and triple that for the key pair. +ML-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 2.4kB and 4.6kB, depending on the selected parameter set. + +See `[FIPS204]` §4 for details on the parameter sets, and the key and generated signature sizes. + +The generation of an ML-DSA key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`ml-dsa-keys`. + +`[FIPS204]` defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. +Four algorithms are defined to support these variants: `PSA_ALG_ML_DSA`, `PSA_ALG_DETERMINISTIC_ML_DSA`, `PSA_ALG_HASH_ML_DSA()`, and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`. + +.. _ml-dsa-deterministic-signatures: + +.. rubric:: Hedged and deterministic signatures + +Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. +Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs. + +Signature verification does not distinguish between a hedged and a deterministic signature. +Either hedged or deterministic algorithms can be used when verifying a signature. + +When computing a signature, the key's permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. +When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key's permitted-algorithm policy. + +.. note:: + + The hedged version provides message secrecy and some protection against side-channels. + `[FIPS204]` recommends that users should use the hedged version if either of these issues are a concern. + The deterministic variant should only be used if the implementation does not include any source of randomness. + +.. admonition:: Implementation note + + `[FIPS204]` recommends that implementations use an approved random number generator to provide the random value in the hedged version. + However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant. + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS204]`. + + However, the |API| gives distinct algorithm identifiers for the hedged and deterministic variants, to enable an application use case to require a specific variant. + +.. rubric:: Pure and pre-hashed algorithms + +The pre-hashed signature computation *HashML-DSA* generates distinct signatures to a pure signature *ML-DSA*, with the same key and message hashing algorithm. + +An ML-DSA signature can only be verified with an ML-DSA algorithm. +A HashML-DSA signature can only be verified with a HashML-DSA algorithm. + +.. rubric:: Contexts + +Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. +A empty context string is used when computing or verifying ML-DSA signatures. + +A future version of this specification may add suitable functions and extend this algorithm to support contexts. + +.. macro:: PSA_ALG_ML_DSA + :definition: ((psa_algorithm_t) 0x06004400) + + .. summary:: + Module lattice-based digital signature algorithm without pre-hashing (ML-DSA). + + This algorithm can be only used with the :code:`psa_sign_message()` and :code:`psa_verify_message()` functions. + + This is the pure ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, using hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_ML_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_ML_DSA` as the algorithm in a call to :code:`psa_sign_message()`. + * `PSA_ALG_ML_DSA` or `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (`PSA_ALG_HASH_ML_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_ML_DSA + :definition: ((psa_algorithm_t) 0x06004500) + + .. summary:: + Deterministic module lattice-based digital signature algorithm without pre-hashing (ML-DSA). + + This algorithm can be only used with the :code:`psa_sign_message()` and :code:`psa_verify_message()` functions. + + This is the pure ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, without hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_ML_DSA` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_ML_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_sign_message()`. + * `PSA_ALG_ML_DSA` or `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (`PSA_ALG_HASH_ML_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | :code:`PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Module lattice-based digital signature algorithm with pre-hashing (HashML-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding HashML-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, using hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS204]` §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_HASH_ML_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_HASH_ML_DSA()` as the algorithm in a call to :code:`psa_sign_message()` and :code:`psa_sign_hash()`. + * `PSA_ALG_HASH_ML_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to :code:`psa_verify_message()` and :code:`psa_verify_hash()`. + + .. note:: + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Usage + + This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches: + + * Call :code:`psa_sign_message()` with the message. + + * Calculate the hash of the message with :code:`psa_hash_compute()`, or with a multi-part hash operation, using the ``hash_alg`` hash algorithm. + Note that ``hash_alg`` can be extracted from the signature algorithm using :code:`PSA_ALG_GET_HASH(sig_alg)`. + Then sign the calculated hash with :code:`psa_sign_hash()`. + + Verifying a signature is similar, using :code:`psa_verify_message()` or :code:`psa_verify_hash()` instead of the signature function. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + + .. comment + Add this algorithm to the list in PSA_ALG_GET_HASH() + +.. macro:: PSA_ALG_DETERMINISTIC_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Deterministic module lattice-based digital signature algorithm with pre-hashing (HashML-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding deterministic HashML-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, without hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS204]` §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_HASH_ML_DSA()` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to :code:`psa_sign_message()` and :code:`psa_sign_hash()`. + * `PSA_ALG_HASH_ML_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to :code:`psa_verify_message()` and :code:`psa_verify_hash()`. + + .. note:: + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Usage + + See `PSA_ALG_HASH_ML_DSA()` for example usage. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + + .. comment + Add this algorithm to the list in PSA_ALG_GET_HASH() + +.. macro:: PSA_ALG_IS_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is ML-DSA, without pre-hashing. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a pure ML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + .. note:: + Use `PSA_ALG_IS_HASH_ML_DSA()` to determine if an algorithm identifier is a HashML-DSA algorithm. + +.. macro:: PSA_ALG_IS_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashML-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + .. note:: + Use `PSA_ALG_IS_ML_DSA()` to determine if an algorithm identifier is a pre-hashed ML-DSA algorithm. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic HashML-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_ML_DSA()` and `PSA_ALG_IS_HEDGED_HASH_ML_DSA()`. + +.. macro:: PSA_ALG_IS_HEDGED_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is hedged HashML-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a hedged HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_ML_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA()`. diff --git a/doc/ext-pqc/api/mlkem.rst b/doc/ext-pqc/api/mlkem.rst new file mode 100644 index 00000000..518fcd3b --- /dev/null +++ b/doc/ext-pqc/api/mlkem.rst @@ -0,0 +1,168 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. header:: psa/crypto-pqc + :seq: 2 + +.. _ml-kem: + +Module Lattice-based key encapsulation +====================================== + +.. _ml-kem-keys: + +Module Lattice-based key-encapsulation keys +------------------------------------------- + +The |API| supports Module Lattice-based key ecapsulation (ML-KEM) as defined in :cite-title:`FIPS203`. + +.. macro:: PSA_KEY_TYPE_ML_KEM_KEY_PAIR + :definition: ((psa_key_type_t)0x7004) + + .. summary:: + ML-KEM key pair: both the decapsulation and encapsulation key. + + The |API| treats decapsulation keys as private keys and encapsulation keys as public keys. + + The key attribute size of an ML-KEM key is specified by the numeric part of the parameter-set identifier defined in `[FIPS203]`. + The parameter-set identifier refers to the key strength, and not to the actual size of the key. + The following values for the ``key_bits`` key attribute are used to select a specific ML-KEM parameter set: + + * ML-KEM-512 : ``key_bits = 512`` + * ML-KEM-768 : ``key_bits = 768`` + * ML-KEM-1024 : ``key_bits = 1024`` + + See also §8 in `[FIPS203]`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_KEM` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for ML-KEM public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-MLKEM`. + + The current proposed format is based on the current expected outcome of that process. + + An ML-KEM key pair is the :math:`(ek,dk)` pair of encapsulation key and decapsulation key, which are generated from two secret 32-byte seeds, :math:`d` and :math:`z`. See `[FIPS203]` §7.1. + + The data format for import and export of the key pair is the concatenation of the two seed values: :math:`d\ ||\ z`. + + .. rationale:: + + The IETF working group responsible for defining the format of the ML-DSA keys in *SubjectPublicKeyInfo* and *OneAsymmetricKey* structures is discussing the formats at present (September 2024), with the current consensus to using just the seed values as the private key, for the following reasons: + + * ML-KEM decapsulation keys are 1.5--3.0 kB in size, but can be recomputed efficiently from the initial 64-byte seed-pair. + * There is no need to validate an imported ML-KEM key pair --- every 64-byte pair of seed values is valid. + * It is better for the standard to choose a single format to improve interoperability. + + See `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. admonition:: Implementation note + + An implementation can optionally compute and store the :math:`dk` value, which also contains the encapsulation key :math:`ek`, to accelerate operations that use the key. + It is recommended that an implementation retains the seed pair :math:`(d,z)` with the decapsulation key, in order to export the key, or copy the key to a different location. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will construct an ML-KEM key pair using the following process: + + 1. Draw 32 bytes of output as the seed value :math:`d`. + #. Draw 32 bytes of output as the seed value :math:`z`. + + The key pair :math:`(ek,dk)` is generated from the seed as defined by ``ML-KEM.KeyGen_internal()`` in `[FIPS203]` §6.1. + + .. admonition:: Implementation note + + It is :scterm:`implementation defined` whether the seed-pair :math:`(d,z)` is expanded to :math:`(ek,dk)` at the point of derivation, or only just before the key is used. + +.. macro:: PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4004) + + .. summary:: + ML-KEM public (encapsulation) key. + + The key attribute size of an ML-KEM public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ML_KEM_KEY_PAIR`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_KEM` (encapsulation only) + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for ML-KEM public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-MLKEM`. + + The current proposed format is based on the current expected outcome of that process. + + An ML-KEM public key is the :math:`ek` output of ``ML-KEM.KeyGen()``, defined in `[FIPS203]` §7.1. + + The size of the public key depends on the ML-KEM parameter set as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Public-key size in bytes + ML-KEM-512, 800 + ML-KEM-768, 1184 + ML-KEM-1024, 1568 + +.. macro:: PSA_KEY_TYPE_IS_ML_KEM + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-DSA key, either a key pair or a public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +Module Lattice-based key-encapsulation algorithm +------------------------------------------------ + +ML-KEM is defined in :cite-title:`FIPS203`. +ML-KEM has three parameter sets which provide differing security strengths. + +The generation of an ML-KEM key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`ml-kem-keys`. + +See `[FIPS203]` §8 for details on the parameter sets. + +.. macro:: PSA_ALG_ML_KEM + :definition: ((psa_algorithm_t)0x0c000200) + + .. summary:: + Module Lattice-based key-encapsulation mechanism (ML-KEM). + + This is the ML-KEM key-encapsulation algorithm, defined by `[FIPS203]`. + ML-KEM requires an ML-KEM key, which determines the ML-KEM parameter set for the operation. + + When using ML-KEM, the size of the encapsulation data returned by a call to :code:`psa_encapsulate()` is as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Encapsulation data size in bytes + ML-KEM-512, 768 + ML-KEM-768, 1088 + ML-KEM-1024, 1568 + + The 32-byte shared output key that is produced by ML-KEM is pseudorandom. + Although it can be used directly as an encryption key, it is recommended to use the output key as an input to a key-derivation operation to produce additional cryptographic keys. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_KEM_KEY_PAIR` + | `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY` (encapsulation only) diff --git a/doc/ext-pqc/api/pqc.rst b/doc/ext-pqc/api/pqc.rst new file mode 100644 index 00000000..6512c453 --- /dev/null +++ b/doc/ext-pqc/api/pqc.rst @@ -0,0 +1,33 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. _pqc-api: + +~~~~~~~~~~~~~ +API Reference +~~~~~~~~~~~~~ + +.. note:: + + The API defined in this specification will be integrated into a future version of :cite:`PSA-CRYPT`. + +.. header:: psa/crypto-pqc + :copyright: Copyright 2018-2024 Arm Limited and/or its affiliates + :license: Apache-2.0 + + /* This file contains reference definitions for implementation of the + * PSA Certified Crypto API v1.3 PQC Extension beta + * + * These definitions must be embedded in, or included by, psa/crypto.h + */ + +This chapter is divided into sections for each of the PQC algorithms in the |API|: + +.. toctree:: + + hash + mlkem + mldsa + slhdsa + +See :secref:`pqc-encodings` for the encoding of the key types and algorithm identifiers added by this extension. diff --git a/doc/ext-pqc/api/slhdsa.rst b/doc/ext-pqc/api/slhdsa.rst new file mode 100644 index 00000000..9541f90c --- /dev/null +++ b/doc/ext-pqc/api/slhdsa.rst @@ -0,0 +1,518 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. header:: psa/crypto-pqc + :seq: 4 + +.. _slh-dsa: + +Stateless Hash-based signatures +=============================== + +.. _slh-dsa-keys: + +Stateless Hash-based signature keys +----------------------------------- + +The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined in :cite-title:`FIPS205`. + +.. typedef:: uint8_t psa_slh_dsa_family_t + + .. summary:: + The type of identifiers of a Stateless hash-based DSA parameter set. + + The parameter-set identifier is required to create an SLH-DSA key using the `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` or `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` macros. + + The specific SLH-DSA parameter set within a family is identified by the ``key_bits`` attribute of the key. + + The range of SLH-DSA family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to an SLH-DSA parameter-set family. + :code:`0x01 - 0x7f` + SLH-DSA parameter-set family identifiers defined by this standard. + Unallocated values in this range are reserved for future use. + :code:`0x80 - 0xff` + Invalid. + Values in this range must not be used. + + The least significant bit of an SLH-DSA family identifier is a parity bit for the whole key type. + See :secref:`slh-dsa-key-encoding` for details of the encoding of asymmetric key types. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA key pair: both the private key and public key. + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The key attribute size of of an SLH-DSA key pair is the bit-size of each component in the SLH-DSA keys defined in `[FIPS205]`. + That is, for a parameter set with security parameter :math:`n`, the bit-size in the key attributes is :math:`8n`. + See the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-SLHDSA`. + + The current proposed format is based on the current expected outcome of that process. + + A SLH-DSA key pair is defined in `[FIPS205]` §9.1 as the four :math:`n`\ -byte values, :math:`SK\text{.seed}`, :math:`SK\text{.prf}`, :math:`PK\text{.seed}`, and :math:`PK\text{.root}`, where :math:`n` is the security parameter. + + The data format for import and export of the key pair is the concatenation of the four octet strings: + + .. math:: + + SK\text{.seed}\ ||\ SK\text{.prf}\ ||\ PK\text{.seed}\ ||\ PK\text{.root} + + See `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will draw output bytes as follows: + + * 32 bytes are drawn as :math:`SK\text{.seed}`. + * 32 bytes are drawn as :math:`SK\text{.prf}`. + * 32 bytes are drawn as :math:`PK\text{.seed}`. + + The private key :math:`(SK\text{.seed},SK\text{.prf},PK\text{.seed},PK\text{.root})` is generated from these values as defined by ``slh_keygen_internal()`` in `[FIPS205]` §9.1. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA public key. + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The key attribute size of an SLH-DSA public key is the same as the corresponding private key. + See `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` and the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-SLHDSA`. + + The current proposed format is based on the current expected outcome of that process. + + A SLH-DSA public key is defined in `[FIPS205]` §9.1 as two :math:`n`\ -byte values, :math:`PK\text{.seed}` and :math:`PK\text{.root}`, where :math:`n` is the security parameter. + + The data format for export of the public key is the concatenation of the two octet strings: + + .. math:: + + PK\text{.seed}\ ||\ PK\text{.root} + +.. macro:: PSA_SLH_DSA_FAMILY_SHA2_S + :definition: ((psa_slh_dsa_family_t) 0x02) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHA2-\ *NNN*\ s parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128s : ``key_bits = 128`` + * SLH-DSA-SHA2-192s : ``key_bits = 192`` + * SLH-DSA-SHA2-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHA2_F + :definition: ((psa_slh_dsa_family_t) 0x04) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHA2-\ *NNN*\ f parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128f : ``key_bits = 128`` + * SLH-DSA-SHA2-192f : ``key_bits = 192`` + * SLH-DSA-SHA2-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_S + :definition: ((psa_slh_dsa_family_t) 0x0b) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ s parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128s : ``key_bits = 128`` + * SLH-DSA-SHAKE-192s : ``key_bits = 192`` + * SLH-DSA-SHAKE-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_F + :definition: ((psa_slh_dsa_family_t) 0x0d) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ f parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128f : ``key_bits = 128`` + * SLH-DSA-SHAKE-192f : ``key_bits = 192`` + * SLH-DSA-SHAKE-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key, either a key pair or a public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key pair. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA public key. + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_GET_FAMILY + :definition: /* specification-defined value */ + + .. summary:: + Extract the parameter-set family from an SLH-DSA key type. + + .. param:: type + An SLH-DSA key type: a value of type :code:`psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SLH_DSA(type)` is true. + + .. return:: psa_dh_family_t + The SLH-DSA parameter-set family id, if ``type`` is a supported SLH-DSA key. Unspecified if ``type`` is not a supported SLH-DSA key. + +.. _slh-dsa-algorithms: + +Stateless Hash-based signature algorithms +----------------------------------------- + +The SLH-DSA signature and verification scheme is defined in :cite-title:`FIPS205`. +SLH-DSA has twelve parameter sets which provide differing security strengths, trade-off between signature size and computation cost, and selection between SHA2 and SHAKE-based hashing. + +SLH-DSA keys are fairly compact, 32, 48, or 64 bytes for the public key, and double that for the key pair. +SLH-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 7.8kB and 49kB depending on the selected parameter set. +An SLH-DSA signature has the structure described in `[FIPS205]` §9.2, Figure 17. + +See `[FIPS205]` §11 for details on the parameter sets, and the public key and generated signature sizes. + +The generation of an SLH-DSA key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`slh-dsa-keys`. + +`[FIPS205]` defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. +Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_ALG_DETERMINISTIC_SLH_DSA`, `PSA_ALG_HASH_SLH_DSA()`, and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`. + +.. _slh-dsa-deterministic-signatures: + +.. rubric:: Hedged and deterministic signatures + +Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. +Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs. + +Signature verification does not distinguish between a hedged and a deterministic signature. +Either hedged or deterministic algorithms can be used when verifying a signature. + +When computing a signature, the key's permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. +When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key's permitted-algorithm policy. + +.. note:: + + The hedged version provides message secrecy and some protection against side-channels. + `[FIPS205]` recommends that users should use the hedged version if either of these issues are a concern. + The deterministic variant should only be used if the implementation does not include any source of randomness. + +.. admonition:: Implementation note + + `[FIPS205]` recommends that implementations use an approved random number generator to provide the random value in the hedged version. + However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant. + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS205]`. + + However, the |API| gives distinct algorithm identifiers for the hedged and deterministic variants for the following reasons: + + * `[FIPS205]` §9.1 recommends that SLH-DSA signing keys are only used to compute either deterministic, or hedged, signatures, but not both. + Supporting this recommendation requires separate algorithm identifiers, and requiring an exact policy match for signature computation. + * Enable an application use case to require a specific variant. + +.. rubric:: Pure and pre-hashed algorithms + +The pre-hashed signature computation *HashSLH-DSA* generates distinct signatures to a pure signature *SLH-DSA*, with the same key and message hashing algorithm. + +An SLH-DSA signature can only be verified with an SLH-DSA algorithm. A HashSLH-DSA signature can only be verified with a HashSLH-DSA algorithm. + +.. rubric:: Contexts + +Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. +A empty context string is used when computing or verifying SLH-DSA signatures. + +A future version of this specification may add suitable functions and extend this algorithm to support contexts. + +.. macro:: PSA_ALG_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004000) + + .. summary:: + Stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + This algorithm can be only used with the :code:`psa_sign_message()` and :code:`psa_verify_message()` functions. + + This is the pure SLH-DSA digital signature algorithm, defined by :cite-title:`FIPS205`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_SLH_DSA` as the algorithm in a call to :code:`psa_sign_message()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to :code:`psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (`PSA_ALG_HASH_SLH_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004100) + + .. summary:: + Deterministic stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + This algorithm can be only used with the :code:`psa_sign_message()` and :code:`psa_verify_message()` functions. + + This is the pure SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_SLH_DSA` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to :code:`psa_sign_message()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to :code:`psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (`PSA_ALG_HASH_SLH_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_HASH_SLH_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_HASH_SLH_DSA()` as the algorithm in a call to :code:`psa_sign_message()` and :code:`psa_sign_hash()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to :code:`psa_verify_message()` and :code:`psa_verify_hash()`. + + .. note:: + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Usage + + This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches: + + * Call :code:`psa_sign_message()` with the message. + + * Calculate the hash of the message with :code:`psa_hash_compute()`, or with a multi-part hash operation, using the ``hash_alg`` hash algorithm. + Note that ``hash_alg`` can be extracted from the signature algorithm using :code:`PSA_ALG_GET_HASH(sig_alg)`. + Then sign the calculated hash with :code:`psa_sign_hash()`. + + Verifying a signature is similar, using :code:`psa_verify_message()` or :code:`psa_verify_hash()` instead of the signature function. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + + .. comment + Add this algorithm to the list in PSA_ALG_GET_HASH() + +.. macro:: PSA_ALG_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Deterministic stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding deterministic HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_HASH_SLH_DSA()` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to :code:`psa_sign_message()` and :code:`psa_sign_hash()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to :code:`psa_verify_message()` and :code:`psa_verify_hash()`. + + .. note:: + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Usage + + See `PSA_ALG_HASH_SLH_DSA()` for example usage. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + + .. comment + Add this algorithm to the list in PSA_ALG_GET_HASH() + +.. macro:: PSA_ALG_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is SLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an SLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_HEDGED_HASH_SLH_DSA()`. + +.. macro:: PSA_ALG_IS_HEDGED_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is hedged HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a hedged HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA()`. diff --git a/doc/ext-pqc/appendix/encodings.rst b/doc/ext-pqc/appendix/encodings.rst new file mode 100644 index 00000000..3d168164 --- /dev/null +++ b/doc/ext-pqc/appendix/encodings.rst @@ -0,0 +1,146 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. _pqc-encodings: + +Algorithm and key type encoding +=============================== + +These are encodings for PQC algorithms and keys defined in this extension. +This information should be read in conjunction with :cite:`PSA-CRYPT` Appendix B. + +.. note:: + + These encodings will be integrated into a future version of `[PSA-CRYPT]`. + +.. _pqc-algorithm-encoding: + +Algorithm encoding +------------------ + + +.. _hash-encoding: + +Hash algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~ + +Additional hash algorithms defined by this extension are shown in :numref:`table-hash-type`. +See also *Hash algorithm encoding* in `[PSA-CRYPT]` Appendix B. + +.. csv-table:: Hash algorithm sub-type values + :name: table-hash-type + :header-rows: 1 + :align: left + :widths: auto + + Hash algorithm, HASH-TYPE, Algorithm identifier, Algorithm value + SHAKE128-256, ``0x16``, `PSA_ALG_SHAKE128_256`, ``0x02000016`` + +.. _sign-encoding: + +Asymmetric signature algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Additional signature algorithms defined by this extension are shown in :numref:`table-sign-type`. +See also *Asymmetric signature algorithm encoding* in `[PSA-CRYPT]` Appendix B. + +.. csv-table:: Asymmetric signature algorithm sub-type values + :name: table-sign-type + :header-rows: 1 + :align: left + :widths: auto + + Signature algorithm, SIGN-TYPE, Algorithm identifier, Algorithm value + Hedged ML-DSA, ``0x44``, `PSA_ALG_ML_DSA`, ``0x06004400`` + Deterministic ML-DSA, ``0x45``, `PSA_ALG_DETERMINISTIC_ML_DSA`, ``0x06004500`` + Hedged HashML-DSA, ``0x46``, :code:`PSA_ALG_HASH_ML_DSA(hash)`, ``0x060046hh`` :sup:`a` + Deterministic HashML-DSA, ``0x47``, :code:`PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash)`, ``0x060047hh`` :sup:`a` + Hedged SLH-DSA, ``0x40``, `PSA_ALG_SLH_DSA`, ``0x06004000`` + Deterministic SLH-DSA, ``0x41``, `PSA_ALG_DETERMINISTIC_SLH_DSA`, ``0x06004100`` + Hedged HashSLH-DSA, ``0x42``, :code:`PSA_ALG_HASH_SLH_DSA(hash)`, ``0x060042hh`` :sup:`a` + Deterministic HashSLH-DSA, ``0x43``, :code:`PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash)`, ``0x060043hh`` :sup:`a` + +a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the signature algorithm. + +.. _encapsulation-encoding: + +Key-encapsulation algorithm encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Additional key-encapsulation algorithms defined by this extension are shown in :numref:`table-encapsulation-type`. + +.. csv-table:: Encapsulation algorithm sub-type values + :name: table-encapsulation-type + :header-rows: 1 + :align: left + :widths: auto + + Encapsulation algorithm, ENCAPS-TYPE, Algorithm identifier, Algorithm value + ML-KEM, ``0x02``, `PSA_ALG_ML_KEM`, ``0x0C000200`` + +.. _pqc-key-encoding: + +Key encoding +------------ + +Additional asymmetric key types defined by this extension are shown in :numref:`table-asymmetric-type`. +See also *Asymmetric key encoding* in `[PSA-CRYPT]` Appendix B. + +.. csv-table:: Asymmetric key sub-type values + :name: table-asymmetric-type + :header-rows: 1 + :align: left + :widths: auto + + Asymmetric key type, ASYM-TYPE, Details + SLH-DSA, 3, See :secref:`slh-dsa-key-encoding` + +.. _simple-asymmetric-key-encoding: + +Non-parameterized asymmetric key encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Additional non-parameterized asymmetric key types defined by this extension are shown in :numref:`table-np-type`. +See also *Non-parameterized asymmetric key encoding* in `[PSA-CRYPT]` Appendix B. + +.. csv-table:: Non-parameterized asymmetric key family values + :name: table-np-type + :header-rows: 1 + :align: left + :widths: auto + + Key family, Public/pair, PAIR, NP-FAMILY, P, Key type, Key value + ML-DSA, Public key, 0, 1, 0, `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY`, ``0x4002`` + , Key pair, 3, 1, 0, `PSA_KEY_TYPE_ML_DSA_KEY_PAIR`, ``0x7002`` + ML-KEM, Public key, 0, 2, 0, `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY`, ``0x4004`` + , Key pair, 3, 2, 0, `PSA_KEY_TYPE_ML_KEM_KEY_PAIR`, ``0x7004`` + +.. _slh-dsa-key-encoding: + +SLH-DSA key encoding +~~~~~~~~~~~~~~~~~~~~ + +The key type for SLH-DSA keys defined in this specification are encoded as shown in :numref:`fig-slh-dsa-key-fields`. + +.. figure:: ../figure/encoding/slh_dsa_key.* + :name: fig-slh-dsa-key-fields + + SLH-DSA key encoding + +PAIR is either 0 for a public key, or 3 for a key pair. + +The defined values for FAMILY and P are shown in :numref:`table-slh-dsa-type`. + +.. csv-table:: SLH-DSA key family values + :name: table-slh-dsa-type + :header-rows: 1 + :align: left + :widths: auto + + SLH-DSA key family, FAMILY, P, SLH-DSA family :sup:`a`, Public-key value, Key-pair value + SLH-DSA-SHA2-\ *N*\ s, 0x01, 0, `PSA_SLH_DSA_FAMILY_SHA2_S`, ``0x4182``, ``0x7182`` + SLH-DSA-SHA2-\ *N*\ f, 0x02, 0, `PSA_SLH_DSA_FAMILY_SHA2_F`, ``0x4184``, ``0x7184`` + SLH-DSA-SHAKE-\ *N*\ s, 0x05, 1, `PSA_SLH_DSA_FAMILY_SHAKE_S`, ``0x418b``, ``0x718b`` + SLH-DSA-SHAKE-\ *N*\ f, 0x06, 1, `PSA_SLH_DSA_FAMILY_SHAKE_F`, ``0x418d``, ``0x718d`` + +a. The SLH-DSA family values defined in the API also include the parity bit. The key type value is constructed from the SLH-DSA family using either :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(family)` as required. diff --git a/doc/ext-pqc/appendix/example_header.rst b/doc/ext-pqc/appendix/example_header.rst new file mode 100644 index 00000000..e8998d75 --- /dev/null +++ b/doc/ext-pqc/appendix/example_header.rst @@ -0,0 +1,21 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. _example-header: + +Example header file +------------------- + +The API elements in this specification, once finalized, will be defined in :file:`psa/crypto.h`. + +This is an example of the header file definition of the PAKE API elements. This can be used as a starting point or reference for an implementation. + +.. note:: + Not all of the API elements are fully defined. An implementation must provide the full definition. + + The header will not compile without these missing definitions, and might require reordering to satisfy C compilation rules. + +psa/crypto.h +~~~~~~~~~~~~ + +.. insert-header:: psa/crypto-pqc diff --git a/doc/ext-pqc/appendix/history.rst b/doc/ext-pqc/appendix/history.rst new file mode 100644 index 00000000..4e68f74a --- /dev/null +++ b/doc/ext-pqc/appendix/history.rst @@ -0,0 +1,22 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +Changes to the API +================== + +.. _changes: + +Document change history +----------------------- + +Beta release +^^^^^^^^^^^^ + +* First release of the PQC Extension. + +* Added support for FIPS 203 ML-KEM key-encapsulation algorithm and keys. + See :secref:`ml-kem`. +* Added support for FIPS 204 ML-DSA signature algorithm and keys. + See :secref:`ml-dsa`. +* Added support for FIPS 205 SLH-DSA signature algorithm and keys. + See :secref:`slh-dsa`. diff --git a/doc/ext-pqc/appendix/specdef_values.rst b/doc/ext-pqc/appendix/specdef_values.rst new file mode 100644 index 00000000..269bd020 --- /dev/null +++ b/doc/ext-pqc/appendix/specdef_values.rst @@ -0,0 +1,103 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. _specification-defined-value: + +Example macro implementations +----------------------------- + +This section provides example implementations of the function-like macros that have specification-defined values. + +.. note:: + In a future version of this specification, these example implementations will be replaced with a pseudo-code representation of the macro's computation in the macro description. + +The examples here provide correct results for the valid inputs defined by each API, for an implementation that supports all of the defined algorithms and key types. An implementation can provide alternative definitions of these macros: + +Algorithm macros +~~~~~~~~~~~~~~~~ + +Updated macros +^^^^^^^^^^^^^^ + +.. code-block:: xref + + #define PSA_ALG_IS_HASH_AND_SIGN(alg) \ + (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \ + PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg) || \ + PSA_ALG_IS_HASH_ML_DSA(alg) || PSA_ALG_IS_HASH_SLH_DSA(alg)) + + #define PSA_ALG_IS_SIGN_HASH(alg) \ + (PSA_ALG_IS_SIGN(alg) && \ + (alg) != PSA_ALG_PURE_EDDSA && \ + !PSA_ALG_IS_SLH_DSA(alg) && \ + !PSA_ALG_IS_ML_DSA(alg)) + +New macros +^^^^^^^^^^ + +.. code-block:: xref + + #define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004700 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004300 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_HASH_ML_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004600 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_HASH_SLH_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004200 | ((hash_alg) & 0x000000ff))) + + #define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004700) + + #define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004300) + + #define PSA_ALG_IS_HASH_ML_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004600) + + #define PSA_ALG_IS_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004200) + + #define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004600) + + #define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004200) + + #define PSA_ALG_IS_ML_DSA(alg) \ + (((alg) & ~0x00000100) == 0x06004400) + + #define PSA_ALG_IS_SLH_DSA(alg) \ + (((alg) & ~0x00000100) == 0x06004000) + +Key type macros +~~~~~~~~~~~~~~~ + +.. code-block:: xref + + #define PSA_KEY_TYPE_IS_ML_DSA(type) \ + (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4002) + + #define PSA_KEY_TYPE_IS_ML_KEM(type) \ + (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4004) + + #define PSA_KEY_TYPE_IS_SLH_DSA(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + (((type) & 0xff80) == 0x7180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + (((type) & 0xff80) == 0x4180) + + #define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) \ + ((psa_slh_dsa_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) \ + ((psa_key_type_t) (0x7180 | ((set) & 0x007f))) + + #define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) \ + ((psa_key_type_t) (0x4180 | ((set) & 0x007f))) diff --git a/doc/ext-pqc/conf.py b/doc/ext-pqc/conf.py new file mode 100644 index 00000000..9f21af52 --- /dev/null +++ b/doc/ext-pqc/conf.py @@ -0,0 +1,119 @@ +# SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +# SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +# PSA Certified API document configuration +# +# This is used to generate all of the sphinx configuration data and determine +# the document file name etc. + +doc_info = { + # Document template + 'template': 'psa-api-2022', + + # Document title, MANDATORY + 'title': 'PSA Certified\nCrypto API', + 'author': 'Arm Limited', + + # Document copyright date, default to year of 'date' + 'copyright_date': '2024', + 'copyright': 'Arm Limited and/or its affiliates', + + # Arm document identifier, marked as open issue if not provided + 'doc_id': 'AES 0119', + + # The short X.Y version. MANDATORY + 'version': '1.3', + 'extension_doc': 'PQC Extension', + + # Arm document quality status, marked as open issue if not provided + 'quality': 'BET', + # Arm document issue number (within that version and quality status) + # Marked as open issue if not provided + 'issue_no': 0, + # Identifies the sequence number of a release candidate of the same issue + # default to None + #'release_candidate': 0, + # Draft status - use this to indicate the document is not ready for publication + 'draft': True, + + # Arm document confidentiality. Must be either Non-confidential or Confidential + # Marked as open issue if not provided + 'confidentiality': 'Non-confidential', + + # Id of the legal notice for this document + # Marked as open issue if not provided + 'license': 'psa-certified-api-license', + + # Document date, default to build date + #'date': '28/03/2024', + + # Default header file for API definitions + # default to None, and can be set in documentation source +# 'header': 'psa/crypto', + + # Doxygen annotation level of the generated header + # 0 : None (default) + # 1 : Primary API elements + # 2 : Sub-elements of API - parameters, fields, values + 'header_doxygen': 2, + + # Declare a watermark for the PDF output + #'watermark': 'DRAFT', + + # List of optional content that should be included in the build. + # Valid options are: + # 'rationale' : This enables output of ..rationale:: directives + # 'banner' : This enables output of the title page banner + # 'todo' : This enables output of ..todo:: directives + 'include_content': ['banner','rationale'], + + # Optional ordering of return error values + # This list is used to create a standard ordering of return value responses + # throughout the document, irrespective of their ordering in the source text + # Return values that are not in the ordering are sorted above any that are in + # the list and appear in source text order. + + 'error_order': [ + 'PSA_SUCCESS', + 'PSA_ERROR_BAD_STATE', + 'PSA_ERROR_INVALID_HANDLE', + 'PSA_ERROR_NOT_PERMITTED', + 'PSA_ERROR_INVALID_SIGNATURE', + 'PSA_ERROR_ALREADY_EXISTS', + 'PSA_ERROR_INSUFFICIENT_DATA', + 'PSA_ERROR_BUFFER_TOO_SMALL', + 'PSA_ERROR_INVALID_PADDING', + 'PSA_ERROR_INVALID_ARGUMENT', + 'PSA_ERROR_NOT_SUPPORTED', + 'PSA_ERROR_INSUFFICIENT_ENTROPY', + 'PSA_ERROR_INSUFFICIENT_MEMORY', + 'PSA_ERROR_INSUFFICIENT_STORAGE', + 'PSA_ERROR_COMMUNICATION_FAILURE', + 'PSA_ERROR_CORRUPTION_DETECTED', + 'PSA_ERROR_STORAGE_FAILURE', + 'PSA_ERROR_DATA_CORRUPT', + 'PSA_ERROR_DATA_INVALID' + ], + + # Include the C Identifier index. Default to True + 'identifier_index': True, + + # Specify where to add page breaks in main/appendix + # 'none' : no page breaks + # 'appendix' : just before the appendices + # 'chapter' : before every chapter + # Default to 'appendix' + 'page_break': 'chapter', + } + +# absolute or relative path to the psa_spec material from this file +# atg_sphinx_spec_dir = '../atg-sphinx-spec' + +# Set up and run the atg-sphinx-spec configuration + +import os + +atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir +exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'), + encoding='utf-8').read(), + 'atg-sphinx-conf.py', 'exec')) diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.json b/doc/ext-pqc/figure/encoding/slh_dsa_key.json new file mode 100644 index 00000000..4370da1d --- /dev/null +++ b/doc/ext-pqc/figure/encoding/slh_dsa_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "FAMILY", "bits": 6 }, + { "name": "3", "bits": 5 }, + { "name": "PAIR", "bits": 2 }, + { "name": "1", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "options": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.json.license b/doc/ext-pqc/figure/encoding/slh_dsa_key.json.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/ext-pqc/figure/encoding/slh_dsa_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf b/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf new file mode 100644 index 00000000..eab4b8a2 Binary files /dev/null and b/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf differ diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf.license b/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/ext-pqc/figure/encoding/slh_dsa_key.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.svg b/doc/ext-pqc/figure/encoding/slh_dsa_key.svg new file mode 100644 index 00000000..7610f237 --- /dev/null +++ b/doc/ext-pqc/figure/encoding/slh_dsa_key.svg @@ -0,0 +1,2 @@ + +01671112131415PFAMILY3PAIR10 \ No newline at end of file diff --git a/doc/ext-pqc/figure/encoding/slh_dsa_key.svg.license b/doc/ext-pqc/figure/encoding/slh_dsa_key.svg.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/ext-pqc/figure/encoding/slh_dsa_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/ext-pqc/index.rst b/doc/ext-pqc/index.rst new file mode 100644 index 00000000..a7f9e8d2 --- /dev/null +++ b/doc/ext-pqc/index.rst @@ -0,0 +1,30 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. title:: + + .. banner:: DRAFT + + This is an extension to the :cite-title:`PSA-CRYPT` specification. + + This is a DRAFT release: the proposed changes and interfaces are in development, and published for review and discussion. + + .. abstract:: + + This document is part of the PSA Certified API specifications. It defines an extension to the Crypto API, to introduce support for Post-Quantum Cryptography (PQC) algorithms. + +.. front-matter:: + + about + +.. maintoc:: + + overview/intro + api/pqc + +.. appendix:: + + appendix/example_header + appendix/encodings + appendix/specdef_values + appendix/history diff --git a/doc/ext-pqc/overview/intro.rst b/doc/ext-pqc/overview/intro.rst new file mode 100644 index 00000000..9d5af008 --- /dev/null +++ b/doc/ext-pqc/overview/intro.rst @@ -0,0 +1,54 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +Introduction +============ + +About Platform Security Architecture +------------------------------------ + +This document is one of a set of resources provided by Arm that can help organizations develop products that meet the security requirements of PSA Certified on Arm-based platforms. The PSA Certified scheme provides a framework and methodology that helps silicon manufacturers, system software providers and OEMs to develop more secure products. Arm resources that support PSA Certified range from threat models, standard architectures that simplify development and increase portability, and open-source partnerships that provide ready-to-use software. You can read more about PSA Certified here at :url:`www.psacertified.org` and find more Arm resources here at :url:`developer.arm.com/platform-security-resources`. + +About the |API| PQC Extension +----------------------------- + +This document defines an extension to the :cite-title:`PSA-CRYPT` specification, to provide support for :term:`Post-Quantum Cryptography` (PQC) algorithms, and specifically for the NIST-approved standards for ML-DSA, SLH-DSA, and ML-KEM. + +When the proposed extension is sufficiently stable to be classed as Final, it will be integrated into a future version of `[PSA-CRYPT]`. + +This specification must be read and implemented in conjunction with `[PSA-CRYPT]`. All of the conventions, design considerations, and implementation considerations that are described in `[PSA-CRYPT]` apply to this specification. + +Objectives for the PQC Extension +-------------------------------- + +Background +~~~~~~~~~~ + +The justification for developing new :term:`public-key cryptography` algorithms due to the risks posed by quantum computing are described by NIST in :cite-title:`NIST-PQC`. + +.. admonition:: Extract from *Post-Quantum Cryptography*: + + *In recent years, there has been a substantial amount of research on quantum computers --- machines that exploit quantum mechanical phenomena to solve mathematical problems that are difficult or intractable for conventional computers. If large-scale quantum computers are ever built, they will be able to break many of the public-key cryptosystems currently in use. This would seriously compromise the confidentiality and integrity of digital communications on the Internet and elsewhere. The goal of post-quantum cryptography (also called quantum-resistant cryptography) is to develop cryptographic systems that are secure against both quantum and classical computers, and can interoperate with existing communications protocols and networks.* + + *The question of when a large-scale quantum computer will be built is a complicated one. While in the past it was less clear that large quantum computers are a physical possibility, many scientists now believe it to be merely a significant engineering challenge. Some engineers even predict that within the next twenty or so years sufficiently large quantum computers will be built to break essentially all public key schemes currently in use. Historically, it has taken almost two decades to deploy our modern public key cryptography infrastructure. Therefore, regardless of whether we can estimate the exact time of the arrival of the quantum computing era, we must begin now to prepare our information security systems to be able to resist quantum computing.* + +NIST is hosting a project to collaboratively develop, analyze, refine, and select cryptographic schemes that are resistant to attack by both classical and quantum computing. + +Selection of algorithms +~~~~~~~~~~~~~~~~~~~~~~~ + +PQC algorithms that have been standardized are obvious candidates for inclusion in the |API|. The current set of standards is the following: + +* :cite-title:`FIPS203` +* :cite-title:`FIPS204` +* :cite-title:`FIPS205` + +Although the NIST standards for these algorithms are now finalized, the definition of keys in the |API| depends on import and export formats. +To maximize key exchange interoperability with other specifications, the default export format in the |API| should be aligned with the definitions selected for X.509 public-key infrastructure. +As the IETF process for defining the X.509 key formats is still ongoing at the time of publishing this document, the interfaces within this document are at BETA status. + +However, it is not expected that other aspects of the API in this document will change when it becomes FINAL. + +.. note:: + Although PQC algorithms that are draft standards could be considered, any definitions for these algorithms would be have to be considered experimental. + Significant aspects of the algorithm, such as approved parameter sets, can change before publication of a final standard, potentially requiring a revision of any proposed interface for the |API|. diff --git a/doc/ext-pqc/references b/doc/ext-pqc/references new file mode 100644 index 00000000..d316488c --- /dev/null +++ b/doc/ext-pqc/references @@ -0,0 +1,55 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. reference:: PSA-CRYPT + :title: PSA Certified Crypto API + :doc_no: IHI 0086 + :url: arm-software.github.io/psa-api/crypto + +.. reference:: FIPS202 + :title: FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions + :author: NIST + :publication: August 2015 + :url: doi.org/10.6028/NIST.FIPS.202 + +.. reference:: FIPS203 + :title: FIPS Publication 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.203 + +.. reference:: FIPS204 + :title: FIPS Publication 204: Module-Lattice-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.204 + +.. reference:: FIPS205 + :title: FIPS Publication 205: Stateless Hash-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.205 + +.. reference:: LAMPS-MLKEM + :title: Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) + :author: IETF + :publication: September 2024 (Draft 04) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-kyber-certificates-04 + +.. reference:: LAMPS-MLDSA + :title: Internet X.509 Public Key Infrastructure: Algorithm Identifiers for ML-DSA + :author: IETF + :publication: July 2024 (Draft 04) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-dilithium-certificates-04 + +.. reference:: LAMPS-SLHDSA + :title: Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA + :author: IETF + :publication: October 2024 (Draft 02) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-x509-slhdsa-02 + +.. reference:: NIST-PQC + :title: Post-Quantum Cryptography + :author: NIST + :publication: PQC Project page + :url: nist.gov/pqcrypto diff --git a/doc/ext-pqc/releases b/doc/ext-pqc/releases new file mode 100644 index 00000000..9ff58b12 --- /dev/null +++ b/doc/ext-pqc/releases @@ -0,0 +1,8 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. release:: Beta 0 + :date: ?? + :confidentiality: Non-confidential + + Initial release of the 1.3 PQC Extension specification diff --git a/doc/ext-pqc/terms b/doc/ext-pqc/terms new file mode 100644 index 00000000..ff5572fe --- /dev/null +++ b/doc/ext-pqc/terms @@ -0,0 +1,160 @@ +.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license + +.. term:: Algorithm + + A finite sequence of steps to perform a particular operation. + + In this specification, an algorithm is a :term:`cipher` or a related function. + Other texts call this a cryptographic mechanism. + +.. term:: Byte + + In this specification, a unit of storage comprising eight bits, also called an octet. + +.. term:: API + + Application Programming Interface. + +.. term:: Cipher + + An algorithm used for encryption or decryption with a :term:`symmetric` key. + +.. term:: Key agreement + + An algorithm for two or more parties to establish a common secret key. + +.. term:: Key identifier + + A reference to a cryptographic key. Key identifiers in the |API| are 32-bit integers. + +.. term:: Key type + + Key metadata that describes the structure and content of a key. + +.. term:: Key policy + + Key metadata that describes and restricts what a key can be used for. + +.. term:: Lifetime + + Key metadata that describes when a key is destroyed. + +.. scterm:: Implementation defined + + Behavior that is not defined by the architecture, but is defined and documented by individual implementations. + +.. scterm:: Specification defined + + Behavior that is defined by this specification. + +.. term:: Multi-part operation + + An :term:`API` which splits a single cryptographic operation into a sequence of separate steps. + +.. term:: Single-part function + + An :term:`API` that implements the cryptographic operation in a single function call. + +.. term:: Keystore + + A hardware or software component that protects, stores, and manages cryptographic keys. + +.. term:: Nonce + + Used as an input for certain :term:`AEAD` algorithms. + Nonces must not be reused with the same key because this can break a cryptographic protocol. + +.. term:: Authenticated Encryption with Associated Data + :abbr: AEAD + + A type of encryption that + provides confidentiality and authenticity of data using :term:`symmetric` keys. + +.. term:: Initialization vector + :abbr: IV + + An additional input that is not part of the message. It is used to prevent an attacker from making any + correlation between cipher text and plain text. + + This specification uses the term for such initial inputs + in all contexts. For example, the initial counter in CTR mode is called the IV. + +.. term:: Cryptoprocessor + + The component that performs cryptographic operations. + A cryptoprocessor might contain a :term:`keystore` and countermeasures against a range of physical and timing attacks. + +.. term:: Hash + + A cryptographic hash function, or the value returned by such a function. + +.. term:: Message digest + + A :term:`hash` of a message. Used to determine if a message has been tampered. + +.. term:: Signature + + The output of a digital signature scheme that uses an :term:`asymmetric` keypair. Used to establish who produced a message. + +.. term:: Key size + + The size of a key as defined by common conventions for each key type. + For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings. + + This specification expresses key sizes in bits. + +.. term:: Key Derivation Function + :abbr: KDF + + Key Derivation Function. An algorithm for deriving keys from secret material. + +.. term:: PSA + + Platform Security Architecture + +.. term:: Message Authentication Code + :abbr: MAC + + A short piece of information used to authenticate a message. + It is created and verified using a :term:`symmetric` key. + +.. term:: HMAC + + A type of :term:`MAC` that uses a cryptographic key with a :term:`hash` function. + +.. term:: Non-extractable key + + A key with a :term:`key policy` that prevents it from being read by ordinary means. + +.. term:: Persistent key + + A key that is stored in protected non-volatile memory. + +.. term:: Salt + + Used as an input for certain algorithms, such as key derivations. + +.. term:: Symmetric + + A type of cryptographic algorithm that uses a single key. A symmetric key can be used with + a block cipher or a stream cipher. + +.. term:: Asymmetric + + See :term:`Public-key cryptography`. + +.. term:: Public-key cryptography + + A type of cryptographic system that uses key pairs. A keypair consists of a (secret) private key + and a public key (not secret). A public-key cryptographic algorithm can be used for key distribution + and for digital signatures. + +.. term:: Volatile key + + A key that has a short lifespan and is guaranteed not to exist after a restart of an application instance. + +.. term:: Post-Quantum Cryptography + :abbr: PQC + + A cryptographic scheme that relies on mathematical problems that do not have efficient algorithms for either classical or quantum computing.