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 79f23ecb..cadabb32 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 */ @@ -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 ~~~~~~~~~~~~~~ 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