From e171b75d9a1410d484bb37596c4973420c54fe5e Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 18 Oct 2023 15:05:16 +0100 Subject: [PATCH 1/2] Configure PAKE extension version as v1.2 --- doc/ext-pake/api/pake.rst | 2 +- doc/ext-pake/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 79f23ecb..479b58a9 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -56,7 +56,7 @@ Changes and additions to the Programming API :license: Apache-2.0 /* This file contains reference definitions for implementation of the - * PSA Certified Crypto API v1.1 PAKE Extension beta.1 + * PSA Certified Crypto API v1.2 PAKE Extension beta.2 * * These definitions must be embedded in, or included by, psa/crypto.h */ diff --git a/doc/ext-pake/conf.py b/doc/ext-pake/conf.py index a07755a6..fa9f741f 100644 --- a/doc/ext-pake/conf.py +++ b/doc/ext-pake/conf.py @@ -22,7 +22,7 @@ 'doc_id': 'AES 0058', # The short X.Y version. MANDATORY - 'version': '1.1', + 'version': '1.2', 'extension_doc': 'PAKE Extension', # Arm document quality status, marked as open issue if not provided From ed5b116e86b8c063bdb368b6179c2a4b227a7e0f Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 1 Nov 2023 12:28:23 +0000 Subject: [PATCH 2/2] Add a hash algorithm parameter to the PAKE input and output size macros --- doc/ext-pake/api.db/psa/crypto-pake.h | 6 +++--- doc/ext-pake/api/pake.rst | 18 +++++++++++------- doc/ext-pake/appendix/history.rst | 5 +++++ 3 files changed, 19 insertions(+), 10 deletions(-) diff --git a/doc/ext-pake/api.db/psa/crypto-pake.h b/doc/ext-pake/api.db/psa/crypto-pake.h index d27bce00..d9686d33 100644 --- a/doc/ext-pake/api.db/psa/crypto-pake.h +++ b/doc/ext-pake/api.db/psa/crypto-pake.h @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates +// SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates // SPDX-License-Identifier: Apache-2.0 typedef /* implementation-defined type */ psa_pake_cipher_suite_t; @@ -12,11 +12,11 @@ typedef uint8_t psa_pake_step_t; #define PSA_ALG_JPAKE ((psa_algorithm_t)0x0a000100) #define PSA_PAKE_CIPHER_SUITE_INIT /* implementation-defined value */ #define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */ -#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \ +#define PSA_PAKE_INPUT_SIZE(alg, primitive, hash_alg, input_step) \ /* implementation-defined value */ #define PSA_PAKE_OPERATION_INIT /* implementation-defined value */ #define PSA_PAKE_OUTPUT_MAX_SIZE /* implementation-defined value */ -#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) \ +#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, hash_alg, output_step) \ /* implementation-defined value */ #define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \ /* specification-defined value */ diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 479b58a9..cadabb32 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -935,7 +935,7 @@ Multi-part PAKE operations Size of the ``output`` buffer in bytes. This must be appropriate for the cipher suite and output step: - * A sufficient output size is :code:`PSA_PAKE_OUTPUT_SIZE(alg, primitive, step)` where ``alg`` and ``primitive`` are the PAKE algorithm and primitive in the operation's cipher suite, and ``step`` is the output step. + * A sufficient output size is :code:`PSA_PAKE_OUTPUT_SIZE(alg, primitive, hash_alg, step)` where ``alg``, ``primitive``, and ``hash_alg`` are the PAKE algorithm, primitive, and hash algorithm in the operation's cipher suite, and ``step`` is the output step. * `PSA_PAKE_OUTPUT_MAX_SIZE` evaluates to the maximum output size of any supported PAKE algorithm, primitive and step. .. param:: size_t *output_length On success, the number of bytes of the returned output. @@ -1111,12 +1111,14 @@ Support macros A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. .. param:: primitive A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. + .. param:: hash_alg + A hash algorithm that is compatible with algorithm ``alg``: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(alg)` is true. .. param:: output_step A value of type `psa_pake_step_t` that is valid for the algorithm ``alg``. .. return:: - A sufficient output buffer size for the specified PAKE algorithm, primitive, and output step. - An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, and output step that it recognizes, but does not support. + A sufficient output buffer size for the specified PAKE algorithm, primitive, hash algorithm, and output step. + An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, hash algorithm, and output step that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. If the size of the output buffer is at least this large, it is guaranteed that `psa_pake_output()` will not fail due to an insufficient buffer size. @@ -1128,7 +1130,7 @@ Support macros :definition: /* implementation-defined value */ .. summary:: - Sufficient output buffer size for `psa_pake_output()` for any of the supported PAKE algorithms, primitives and output steps. + Sufficient output buffer size for `psa_pake_output()` for any of the supported PAKE algorithms, primitives, hash algorithms, and output steps. If the size of the output buffer is at least this large, it is guaranteed that `psa_pake_output()` will not fail due to an insufficient buffer size. @@ -1144,12 +1146,14 @@ Support macros A PAKE algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_PAKE(alg)` is true. .. param:: primitive A primitive of type `psa_pake_primitive_t` that is compatible with algorithm ``alg``. + .. param:: hash_alg + A hash algorithm that is compatible with algorithm ``alg``: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(alg)` is true. .. param:: input_step A value of type `psa_pake_step_t` that is valid for the algorithm ``alg``. .. return:: - A sufficient buffer size for the specified PAKE algorithm, primitive, and input step. - An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, and output step that it recognizes, but does not support. + A sufficient buffer size for the specified PAKE algorithm, primitive, hash algorithm, and input step. + An implementation can return either ``0`` or a correct size for a PAKE algorithm, primitive, hash algorithm, and input step that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified. The value returned by this macro is guaranteed to be large enough for any valid input to `psa_pake_input()` in an operation with the specified parameters. @@ -1163,7 +1167,7 @@ Support macros :definition: /* implementation-defined value */ .. summary:: - Sufficient buffer size for inputs to `psa_pake_input()` for any of the supported PAKE algorithms, primitives and input steps. + Sufficient buffer size for inputs to `psa_pake_input()` for any of the supported PAKE algorithms, primitives, hash algorithms, and input steps. This macro can be useful when transferring inputs from the peer into the PAKE operation. diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index d90e278b..741cc2ac 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.rst @@ -14,6 +14,11 @@ This section provides the detailed changes made between published version of the Changes between *Beta 1* and *Beta 2* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +API changes +~~~~~~~~~~~ + +* Added a hash algorithm parameter to the `PSA_PAKE_INPUT_SIZE()` and `PSA_PAKE_OUTPUT_SIZE()` macros. This is required for some PAKE algorithms where the size of the inputs and outputs can depend on the hash algorithm used in the PAKE cipher suite. + Clarifications ~~~~~~~~~~~~~~