PQC Extension specification for FIPS 203, 204 and 205

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.

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

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.

doc/ext-pqc/README.md

@@ -0,0 +1,20 @@
+<!--
+SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# PSA Certified Crypto API PQC Extension &mdash; 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*

doc/ext-pqc/about.rst

@@ -0,0 +1,24 @@
+.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
+.. 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::

doc/ext-pqc/api.db/psa/crypto-pqc.h

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <[email protected]>
+// 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)

doc/ext-pqc/api/hash.rst

@@ -0,0 +1,28 @@
+.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
+.. 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()`).