Skip to content

Commit bb207f0

Browse files
athoelkeathoelke
authored
Merge pull request #223 from athoelke/crypto-ext-pqc
PQC Extension specification for FIPS 203, 204 and 205
2 parents 8b4025c + e75fbb4 commit bb207f0

27 files changed

+2029
-0
lines changed

‎doc/crypto/overview/intro.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ This document includes:
2626
* 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`.
2727
* A detailed definition of the API. See :secref:`library-management`, :secref:`key-management`, and :secref:`crypto-operations`.
2828

29+
:cite-title:`PSA-PQC` is a companion document for version 1.3 of this specification.
30+
`[PSA-PQC]` defines an API for :term:`Post-Quantum Cryptography` (PQC) algorithms.
31+
The PQC API is a proposal at BETA status.
32+
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.
33+
When the PQC API is stable, it will be included in a future version of the |API| specification.
34+
2935
In future, companion documents will define *profiles* for this specification. A profile is
3036
a minimum mandatory subset of the interface that a compliant implementation must
3137
provide.

‎doc/crypto/references‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,3 +396,8 @@
396396
:author: Thread Group
397397
:publication: July 2022
398398
:url: www.threadgroup.org/ThreadSpec
399+
400+
.. reference:: PSA-PQC
401+
:title: PSA Certified Crypto API 1.3 PQC Extension
402+
:doc_no: ARM AES 0119
403+
:url: arm-software.github.io/psa-api/crypto

‎doc/crypto/terms‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,3 +186,8 @@
186186
application instances.
187187

188188
See :secref:`isolation`.
189+
190+
.. term:: Post-Quantum Cryptography
191+
:abbr: PQC
192+
193+
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‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!--
2+
SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
3+
SPDX-License-Identifier: CC-BY-SA-4.0
4+
-->
5+
6+
# PSA Certified Crypto API PQC Extension &mdash; specification sources
7+
8+
The Crypto API PQC Extension specification source files are organized as follows:
9+
10+
Folder | Content
11+
-- | --
12+
Current directory | Configuration and front-matter
13+
`overview` | Informative chapter 1
14+
`api` | API reference chapter 2
15+
`appendix` | Appendix chapters
16+
`figure` | Image files
17+
18+
----
19+
20+
*Copyright 2024, Arm Limited and/or its affiliates*

‎doc/ext-pqc/about.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
2+
.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
3+
4+
.. include:: releases
5+
6+
.. include:: references
7+
8+
.. include:: terms
9+
10+
.. release-info::
11+
:extend:
12+
13+
The detailed changes in each release are described in :secref:`changes`.
14+
15+
.. potential-for-change::
16+
:hide:
17+
18+
.. current-status::
19+
20+
This document is at Beta quality status which has a particular meaning to Arm of which the recipient must be aware.
21+
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.
22+
Please ensure that you have the latest revision.
23+
24+
.. about::

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <[email protected]>
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
typedef uint8_t psa_slh_dsa_family_t;
5+
#define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \
6+
/* specification-defined value */
7+
#define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \
8+
/* specification-defined value */
9+
#define PSA_ALG_DETERMINISTIC_ML_DSA ((psa_algorithm_t) 0x06004500)
10+
#define PSA_ALG_DETERMINISTIC_SLH_DSA ((psa_algorithm_t) 0x06004100)
11+
#define PSA_ALG_HASH_ML_DSA(hash_alg) /* specification-defined value */
12+
#define PSA_ALG_HASH_SLH_DSA(hash_alg) /* specification-defined value */
13+
#define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \
14+
/* specification-defined value */
15+
#define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \
16+
/* specification-defined value */
17+
#define PSA_ALG_IS_HASH_ML_DSA(alg) /* specification-defined value */
18+
#define PSA_ALG_IS_HASH_SLH_DSA(alg) /* specification-defined value */
19+
#define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) /* specification-defined value */
20+
#define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) /* specification-defined value */
21+
#define PSA_ALG_IS_ML_DSA(alg) /* specification-defined value */
22+
#define PSA_ALG_IS_SLH_DSA(alg) /* specification-defined value */
23+
#define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400)
24+
#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0b000200)
25+
#define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016)
26+
#define PSA_ALG_SLH_DSA ((psa_algorithm_t) 0x06004000)
27+
#define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */
28+
#define PSA_KEY_TYPE_IS_ML_KEM(type) /* specification-defined value */
29+
#define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */
30+
#define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \
31+
/* specification-defined value */
32+
#define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \
33+
/* specification-defined value */
34+
#define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
35+
#define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
36+
#define PSA_KEY_TYPE_ML_KEM_KEY_PAIR ((psa_key_type_t)0x7004)
37+
#define PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY ((psa_key_type_t)0x4004)
38+
#define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */
39+
#define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */
40+
#define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */
41+
#define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04)
42+
#define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02)
43+
#define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d)
44+
#define PSA_SLH_DSA_FAMILY_SHAKE_S ((psa_slh_dsa_family_t) 0x0b)

‎doc/ext-pqc/api/hash.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates <[email protected]>
2+
.. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
3+
4+
.. header:: psa/crypto-pqc
5+
:seq: 1
6+
7+
.. _hashes:
8+
9+
Additional Hash algorithms
10+
==========================
11+
12+
.. macro:: PSA_ALG_SHAKE128_256
13+
:definition: ((psa_algorithm_t)0x02000016)
14+
15+
.. summary::
16+
The first 256 bits (32 bytes) of the SHAKE128 output.
17+
18+
This can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`).
19+
20+
SHAKE128 is defined in :cite:`FIPS202`.
21+
22+
.. note::
23+
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.
24+
25+
.. comment
26+
Update the description of PSA_ALG_SHAKE256_512 to state:
27+
28+
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()`).

0 commit comments

Comments
 (0)