mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-03-29 22:20:30 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

PSA PAKE: Call the scheme algorithm

Browse Source 
The documentation is calling PAKEs protocols but it has an
psa_algorithm_t identifier. To align the terminology, the documentation
should call them algorithms as well.

Signed-off-by: Janos Follath <janos.follath@arm.com>
This commit is contained in:
Janos Follath 2021-04-19 09:53:17 +01:00
parent 020da462d2
commit fb4203dcff
3 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
include/psa/crypto.h
View File

@ -4239,9 +4239,9 @@ static psa_pake_operation_t psa_pake_operation_init(void);
* -# Call psa_pake_get_implicit_key() for accessing the shared secret.
*
* The exact sequence of calls to perform a password-authenticated key exchange
* depends on the protocol in use:
* -# Some protocols exchange more data than just a single key share. When using
* such a protocol, call psa_pake_output() and psa_pake_input() one or more
* depends on the algorithm in use:
* -# Some algorithms exchange more data than just a single key share. When using
* such a algorithm, call psa_pake_output() and psa_pake_input() one or more
* times to exchange any further data that is needed to derive the shared
* secret.
*
@ -4270,12 +4270,12 @@ static psa_pake_operation_t psa_pake_operation_init(void);
* type PSA_KEY_TYPE_PASSWORD or
* #PSA_KEY_TYPE_DERIVE. It has to allow the usage
* #PSA_KEY_USAGE_DERIVE.
* \param alg The PAKE protocol to use
* \param alg The PAKE algorithm to use
* (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_PAKE(\p alg) is true).
* \param cipher_suite The cipher suite to use with the PAKE algorithm.
* \param side A value of type ::psa_pake_side_t signaling the
* side of the protocol that is being set up. For
* side of the algorithm that is being set up. For
* more information see the documentation of \c
* PSA_PAKE_SIDE_XXX constants.
* \param[in] user_id The user ID to authenticate with.
@ -4283,9 +4283,9 @@ static psa_pake_operation_t psa_pake_operation_init(void);
* \param[in] peer_id The peer's ID to authenticate.
* \param peer_id_len Size of the \p peer_id buffer in bytes.
* \param[in] session_data Additional session related data if it is allowed
* or required by the protocol. This must be empty
* or required by the algorithm. This must be empty
* if additional session data is not used by the
* protocol.
* algorithm.
* \param session_data_len Size of the \p session_data buffer in bytes.
*
* \retval #PSA_SUCCESS
@ -4331,7 +4331,7 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
* This function returns a simple key share (eg. group element).
*
* The exact sequence of calls to perform a password-authenticated key
* exchange depends on the protocol in use. Refer to the documentation of
* exchange depends on the algorithm in use. Refer to the documentation of
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
* information.
@ -4349,7 +4349,7 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active, but beyond that
* validity is specific to the protocol).
* validity is specific to the algorithm).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p key_share buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -4369,14 +4369,14 @@ psa_status_t psa_pake_get_key_share(psa_pake_operation_t *operation,
/** Get additional key share from a password-authenticated key exchange.
*
* Depending on the protocol being executed, you might need to call this
* Depending on the algorithm being executed, you might need to call this
* function several times or you might not need to call this at all.
*
* Calling this function with PSA_PAKE_DATA_KEY_SHARE as \p type is equivalent
* to calling psa_pake_get_key_share().
*
* The exact sequence of calls to perform a password-authenticated key
* exchange depends on the protocol in use. Refer to the documentation of
* exchange depends on the algorithm in use. Refer to the documentation of
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
* information.
@ -4395,7 +4395,7 @@ psa_status_t psa_pake_get_key_share(psa_pake_operation_t *operation,
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active, but beyond that
* validity is specific to the protocol).
* validity is specific to the algorithm).
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
* The size of the \p output buffer is too small.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@ -4419,7 +4419,7 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
* This function inputs a simple key share (eg. group element).
*
* The exact sequence of calls to perform a password-authenticated key
* exchange depends on the protocol in use. Refer to the documentation of
* exchange depends on the algorithm in use. Refer to the documentation of
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
* information.
@ -4432,7 +4432,7 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation,
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active, but beyond that
* validity is specific to the protocol).
* validity is specific to the algorithm).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@ -4449,14 +4449,14 @@ psa_status_t psa_pake_set_key_share(psa_pake_operation_t *operation,
/** Provide additional peer key share for a password-authenticated key exchange.
*
* Depending on the protocol being executed, you might need to call this
* Depending on the algorithm being executed, you might need to call this
* function several times or you might not need to call this at all.
*
* Calling this function with PSA_PAKE_DATA_KEY_SHARE as \p type is equivalent
* to calling psa_pake_set_key_share().
*
* The exact sequence of calls to perform a password-authenticated key
* exchange depends on the protocol in use. Refer to the documentation of
* exchange depends on the algorithm in use. Refer to the documentation of
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
* information.
@ -4473,7 +4473,7 @@ psa_status_t psa_pake_set_key_share(psa_pake_operation_t *operation,
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active, but beyond that
* validity is specific to the protocol).
* validity is specific to the algorithm).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@ -4498,7 +4498,7 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
* material in the key derivation operation.
*
* The exact sequence of calls to perform a password-authenticated key
* exchange depends on the protocol in use. Refer to the documentation of
* exchange depends on the algorithm in use. Refer to the documentation of
* individual PAKE algorithm types (`PSA_ALG_XXX` values of type
* ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more
* information.
@ -4515,7 +4515,7 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation,
* Success.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active, but beyond that
* validity is specific to the protocol).
* validity is specific to the algorithm).
* \retval #PSA_ERROR_BAD_STATE
* The state of \p output is not valid for
* the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the

6
include/psa/crypto_types.h
View File

@ -386,16 +386,16 @@ typedef uint16_t psa_key_derivation_step_t;
/** \brief Encoding of the side of PAKE
*
* Encodes which side of the protocol is being executed. For more information
* Encodes which side of the algorithm is being executed. For more information
* see the documentation of individual PSA_PAKE_SIDE_XXX constants.
*/
typedef uint16_t psa_pake_side_t;
/** Encoding of input and output indicators for PAKE.
*
* Some PAKE protocols need to exchange more data than just a single key share.
* Some PAKE algorithms need to exchange more data than just a single key share.
* This type is for encoding additional input and output data for such
* protocols.
* algorithms.
*/
typedef uint8_t psa_pake_data_t;

22
include/psa/crypto_values.h
View File

@ -1966,14 +1966,14 @@
#define PSA_ALG_GET_HASH(alg) \
(((alg) & 0x000000ff) == 0 ? ((psa_algorithm_t)0) : 0x02000000 | ((alg) & 0x000000ff))
/** The Password-authenticated key exchange by juggling (J-PAKE) protocol.
/** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
*
* J-PAKE can be instantiated over finite fields or elliptic curves. This can
* be achieved by passing either #PSA_PAKE_PRIMITIVE_TYPE_FIELD_DH or
* #PSA_PAKE_PRIMITIVE_TYPE_CURVE to #PSA_PAKE_PRIMITIVE respectively, when
* creating the cipher suite.
*
* In theory the protocol works with any non-interactive zero-knowledge proof.
* In theory the algorithm works with any non-interactive zero-knowledge proof.
* Implementations of the present specification use Schnorr NIZKP and this does
* not need to be configured in the cipher suites.
*
@ -2452,8 +2452,8 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
/** The first peer in a balanced PAKE.
*
* Although balanced PAKE protocols are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the protocol does not
* Although balanced PAKE algorithms are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the algorithm does not
* need this, either #PSA_PAKE_SIDE_FIRST or #PSA_PAKE_SIDE_SECOND are
* accepted.
*/
@ -2461,8 +2461,8 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
/** The second peer in a balanced PAKE.
*
* Although balanced PAKE protocols are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the protocol does not
* Although balanced PAKE algorithms are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the algorithm does not
* need this, either #PSA_PAKE_SIDE_FIRST or #PSA_PAKE_SIDE_SECOND are
* accepted.
*/
@ -2470,13 +2470,13 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
/** The client in an augmented PAKE.
*
* Augmented PAKE protocols need to differentiate between client and server.
* Augmented PAKE algorithms need to differentiate between client and server.
*/
#define PSA_PAKE_SIDE_CLIENT ((psa_pake_side_t)0x0101)
/** The server in an augmented PAKE.
*
* Augmented PAKE protocols need to differentiate between client and server.
* Augmented PAKE algorithms need to differentiate between client and server.
*/
#define PSA_PAKE_SIDE_SERVER ((psa_pake_side_t)0x0102)
@ -2544,7 +2544,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
* For information regarding representation consult the documentation of
* individual ::psa_pake_primitive_type_t constants.
*
* Some PAKE protocols need to exchange several key shares. If that is the
* Some PAKE algorithms need to exchange several key shares. If that is the
* case, this value marks the first key share sent and the first key share
* received. For values sent or received afterwards, use
* #PSA_PAKE_DATA_KEY_SHARE_2 and #PSA_PAKE_DATA_KEY_SHARE_3.
@ -2559,7 +2559,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
* For information regarding representation consult the documentation of
* individual ::psa_pake_primitive_type_t constants.
*
* Some PAKE protocols need to perform several zero-knowledge proofs. If that
* Some PAKE algorithms need to perform several zero-knowledge proofs. If that
* is the case, this value marks the first public key sent and the first public
* key received. For values sent or received afterwards, use
* #PSA_PAKE_DATA_ZK_PUBLIC_2 and #PSA_PAKE_DATA_ZK_PUBLIC_3.
@ -2574,7 +2574,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
* For information regarding representation consult the documentation of
* individual ::psa_pake_primitive_type_t constants.
*
* Some PAKE protocols need to perform several zero-knowledge proofs. If that
* Some PAKE algorithms need to perform several zero-knowledge proofs. If that
* is the case, this value marks the first proof sent and the first proof
* received. For values sent or received afterwards, use
* #PSA_PAKE_DATA_ZK_PROOF_2 and #PSA_PAKE_DATA_ZK_PROOF_3.