PSA PAKE: move the API to crypto_extra.h
At this point this is a proposed PAKE interface for the PSA Crypto API
and not part of the official standard. Place the interface in
crypto_extra.h to make this clear.
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index e84c757..534902f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -4091,612 +4091,6 @@
/**@}*/
-
-/** \defgroup pake Password-authenticated key exchange (PAKE)
- * @{
- */
-
-/** The type of the data strucure for PAKE cipher suites.
- *
- * This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure.
- * Implementation details can change in future versions without notice.
- */
-typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
-
-/** Retrieve the PAKE algorithm from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] cipher_suite The cipher suite structure to query.
- *
- * \return The PAKE algorithm stored in the cipher suite structure.
- */
-static psa_algorithm_t psa_pake_cs_get_algorithm(
- const psa_pake_cipher_suite_t* cipher_suite
- );
-
-/** Declare the PAKE algorithm for the cipher suite.
- *
- * This function overwrites any PAKE algorithm
- * previously set in \p cipher_suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] cipher_suite The cipher suite structure to write to.
- * \param algorithm The PAKE algorithm to write.
- * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
- * such that #PSA_ALG_IS_PAKE(\c alg) is true.)
- * If this is 0, the PAKE algorithm in
- * \p cipher_suite becomes unspecified.
- */
-static void psa_pake_cs_set_algorithm(
- psa_pake_cipher_suite_t* cipher_suite,
- psa_algorithm_t algorithm
- );
-
-/** Retrieve the primitive from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external linkage).
- * This function may be provided as a function-like macro, but in this case it
- * must evaluate its argument exactly once.
- *
- * \param[in] cipher_suite The cipher suite structure to query.
- *
- * \return The primitive stored in the cipher suite structure.
- */
-static psa_pake_primitive_t psa_pake_cs_get_primitive(
- const psa_pake_cipher_suite_t* cipher_suite
- );
-
-/** Declare the primitive for a PAKE cipher suite.
- *
- * This function overwrites any primitive previously set in \p cipher_suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * \param[out] cipher_suite The cipher suite structure to write to.
- * \param primitive The primitive to write. If this is 0, the
- * primitive type in \p cipher_suite becomes
- * unspecified.
- */
-static void psa_pake_cs_set_primitive(
- psa_pake_cipher_suite_t* cipher_suite,
- psa_pake_primitive_t primitive
- );
-
-/** Retrieve the hash algorithm from a PAKE cipher suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate its argument exactly once.
- *
- * \param[in] cipher_suite The cipher suite structure to query.
- *
- * \return The hash algorithm stored in the cipher suite structure. The return
- * value is 0 if the PAKE is not parametrised by a hash algorithm or if
- * the hash algorithm is not set.
- */
-static psa_algorithm_t psa_pake_cs_get_hash(
- const psa_pake_cipher_suite_t* cipher_suite
- );
-
-/** Declare the hash algorithm for a PAKE cipher suite.
- *
- * This function overwrites any hash algorithm
- * previously set in \p cipher_suite.
- *
- * This function may be declared as `static` (i.e. without external
- * linkage). This function may be provided as a function-like macro,
- * but in this case it must evaluate each of its arguments exactly once.
- *
- * 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.
- *
- * \param[out] cipher_suite The cipher suite structure to write to.
- * \param hash The hash involved in the cipher suite.
- * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
- * such that #PSA_ALG_IS_HASH(\c alg) is true.)
- * If this is 0, the hash algorithm in
- * \p cipher_suite becomes unspecified.
- */
-static void psa_pake_cs_set_hash(
- psa_pake_cipher_suite_t* cipher_suite,
- psa_algorithm_t hash
- );
-
-/** The type of the state data structure for PAKE operations.
- *
- * Before calling any function on a PAKE operation object, the application
- * must initialize it by any of the following means:
- * - Set the structure to all-bits-zero, for example:
- * \code
- * psa_pake_operation_t operation;
- * memset(&operation, 0, sizeof(operation));
- * \endcode
- * - Initialize the structure to logical zero values, for example:
- * \code
- * psa_pake_operation_t operation = {0};
- * \endcode
- * - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT,
- * for example:
- * \code
- * psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
- * \endcode
- * - Assign the result of the function psa_pake_operation_init()
- * to the structure, for example:
- * \code
- * psa_pake_operation_t operation;
- * operation = psa_pake_operation_init();
- * \endcode
- *
- * This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure.
- * Implementation details can change in future versions without notice. */
-typedef struct psa_pake_operation_s psa_pake_operation_t;
-
-/** Return an initial value for an PAKE operation object.
- */
-static psa_pake_operation_t psa_pake_operation_init(void);
-
-/** Set the session information for a password-authenticated key exchange.
- *
- * The sequence of operations to set up a password-authenticated key exchange
- * is as follows:
- * -# Allocate an operation object which will be passed to all the functions
- * listed here.
- * -# Initialize the operation object with one of the methods described in the
- * documentation for #psa_pake_operation_t, e.g.
- * #PSA_PAKE_OPERATION_INIT.
- * -# Call psa_pake_setup() to specify the cipher suite.
- * -# Call \c psa_pake_set_xxx() functions on the operation to complete the
- * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
- * to be called 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.
- *
- * A typical sequence of calls to perform a password-authenticated key
- * exchange:
- * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the
- * key share that needs to be sent to the peer.
- * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide
- * the key share that was received from the peer.
- * -# Depending on the algorithm additional calls to psa_pake_output() and
- * psa_pake_input() might be necessary.
- * -# Call psa_pake_get_implicit_key() for accessing the shared secret.
- *
- * 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.
- *
- * If an error occurs at any step after a call to psa_pake_setup(),
- * the operation will need to be reset by a call to psa_pake_abort(). The
- * application may call psa_pake_abort() at any time after the operation
- * has been initialized.
- *
- * After a successful call to psa_pake_setup(), the application must
- * eventually terminate the operation. The following events terminate an
- * operation:
- * - A call to psa_pake_abort().
- * - A successful call to psa_pake_get_implicit_key().
- *
- * \param[in,out] operation The operation object to set up. It must have
- * been initialized as per the documentation for
- * #psa_pake_operation_t and not yet in use (no
- * other function has been called on it since the
- * last initialization).
- * \param cipher_suite The cipher suite to use. (A cipher suite fully
- * characterizes a PAKE algorithm and determines
- * the algorithm as well.)
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * The \p cipher_suite is not supported or is not valid.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
- psa_pake_cipher_suite_t cipher_suite);
-
-/** Set the password for a password-authenticated key exchange from key ID.
- *
- * Call this function when the password, or a value derived from the password,
- * is already present in the key store. To calculate the password-derived value
- * from a password input, use the key derivation interface and
- * psa_pake_set_password_stretch() instead.
- *
- * \param[in,out] operation The operation object to set the password for. It
- * must have been set up by psa_pake_setup() and
- * not yet in use (neither psa_pake_output() nor
- * psa_pake_input() has been called yet). It must
- * be on operation for which the password hasn't
- * been set yet (neither
- * psa_pake_set_password_stretch() nor
- * psa_pake_set_password_key() has been called
- * yet).
- * \param password Identifier of the key holding the password or a
- * value derived from the password (eg. by a
- * memory-hard function). It must remain valid
- * until the operation terminates. It must be of
- * type #PSA_KEY_TYPE_PASSWORD or
- * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
- * the usage #PSA_KEY_USAGE_DERIVE.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (it must have been set up.)
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval #PSA_ERROR_NOT_PERMITTED
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p key is not compatible with the algorithm or the cipher suite.
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
- mbedtls_svc_key_id_t password);
-
-/** Set the password for a password-authenticated key exchange via a key
- * stretching function.
- *
- * Some protocols use values derived from passwords via key stretching
- * functions to mitigate dictionary attacks. Key stretching functions can be
- * accessed through the key derivation interface and the result can be supplied
- * to the PAKE operation in the form of a key derivation object.
- *
- * This function draws bytes from a key derivation algorithm and sets those
- * bytes as a password for the password-authenticated key exchange. If you
- * view the key derivation's output as a stream of bytes, this function
- * destructively reads the requested number of bytes from the stream.
- * The key derivation operation's capacity decreases by the number of bytes read.
- *
- * If this function returns anything other than #PSA_SUCCESS, both \p operation
- * and \p key_derivation operations enter an error state and must be aborted by
- * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
- *
- * \param[in,out] operation The operation object to set the password for.
- * It must have been set up by psa_pake_setup()
- * and not yet in use (neither psa_pake_output()
- * nor psa_pake_input() has been called yet). It
- * must be on operation for which the password
- * hasn't been set yet (neither
- * psa_pake_set_password_stretch() nor
- * psa_pake_set_password_key() has been called
- * yet).
- * \param[in,out] key_derivation An ongoing key derivation operation set up
- * from the password and in a state suitable for
- * calling psa_key_derivation_output_bytes().
- * \param input_length Number of bytes to input from the
- * \p key_derivation operation.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The state of \p operation or \p key_derivation is not valid.
- * \retval #PSA_ERROR_INSUFFICIENT_DATA
- * The \p key_derivation operation's capacity was less than
- * \p input_length bytes.
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval #PSA_ERROR_NOT_PERMITTED
- * One of the inputs to \p key_derivation was a key whose policy didn't
- * allow #PSA_KEY_USAGE_DERIVE.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p key is not compatible with the algorithm or the cipher suite.
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_set_password_stretch(
- psa_pake_operation_t *operation,
- psa_key_derivation_operation_t *key_derivation,
- size_t input_length
- );
-
-/** Set the user ID for a password-authenticated key exchange.
- *
- * Call this function to set the user ID. For PAKE algorithms that associate a
- * user identifier with each side of the session you need to call
- * psa_pake_set_peer() as well. For PAKE algorithms that associate a single
- * user identifier with the session, call psa_pake_set_user() only.
- *
- * 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.
- *
- * \param[in,out] operation The operation object to set the user ID for. It
- * must have been set up by psa_pake_setup() and
- * not yet in use (neither psa_pake_output() nor
- * psa_pake_input() has been called yet). It must
- * be on operation for which the user ID hasn't
- * been set (psa_pake_set_user() hasn't been
- * called yet).
- * \param[in] user_id The user ID to authenticate with.
- * \param user_id_len Size of the \p user_id buffer in bytes.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p user_id is NULL.
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
- const uint8_t *user_id,
- size_t user_id_len);
-
-/** Set the peer ID for a password-authenticated key exchange.
- *
- * Call this function in addition to psa_pake_set_user() for PAKE algorithms
- * that associate a user identifier with each side of the session. For PAKE
- * algorithms that associate a single user identifier with the session, call
- * psa_pake_set_user() only.
- *
- * 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.
- *
- * \param[in,out] operation The operation object to set the peer ID for. It
- * must have been set up by psa_pake_setup() and
- * not yet in use (neither psa_pake_output() nor
- * psa_pake_input() has been called yet). It must
- * be on operation for which the peer ID hasn't
- * been set (psa_pake_set_peer() hasn't been
- * called yet).
- * \param[in] peer_id The peer's ID to authenticate.
- * \param peer_id_len Size of the \p peer_id buffer in bytes.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * The algorithm doesn't associate a second identity with the session.
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * \p user_id is NULL.
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
- const uint8_t *peer_id,
- size_t peer_id_len);
-
-/** Set the side for a password-authenticated key exchange.
- *
- * Not all PAKE algorithms need to differentiate the communicating entities.
- * It is optional to call this function for PAKEs that don't require a side
- * parameter. For such PAKEs the side parameter is ignored.
- *
- * 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.
- *
- * \param[in,out] operation The operation object to set the side for. It
- * must have been set up by psa_pake_setup() and
- * not yet in use (neither psa_pake_output() nor
- * psa_pake_input() has been called yet). It must
- * be on operation for which the side hasn't been
- * set (psa_pake_set_side() hasn't been called
- * yet).
- * \param side A value of type ::psa_pake_side_t signaling the
- * side of the algorithm that is being set up. For
- * more information see the documentation of \c
- * PSA_PAKE_SIDE_XXX constants.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * The \p side for this algorithm is not supported or is not valid.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
- psa_pake_side_t side);
-
-/** Get output for a step of a password-authenticated key exchange.
- *
- * 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.
- *
- * The exact sequence of calls to perform a password-authenticated key
- * 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.
- *
- * If this function returns an error status, the operation enters an error
- * state and must be aborted by calling psa_pake_abort().
- *
- * \param[in,out] operation Active PAKE operation.
- * \param step The step of the algorithm for which the output is
- * requested.
- * \param[out] output Buffer where the output is to be written in the
- * format appropriate for this \p step. Refer to
- * the documentation of the individual
- * \c PSA_PAKE_STEP_XXX constants for more
- * information.
- * \param output_size Size of the \p output buffer in bytes. This must
- * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c
- * cipher_suite, \p type).
- *
- * \param[out] output_length On success, the number of bytes of the returned
- * output.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (it must be active, but beyond that
- * 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
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_output(psa_pake_operation_t *operation,
- psa_pake_step_t step,
- uint8_t *output,
- size_t output_size,
- size_t *output_length);
-
-/** Provide input for a step of a password-authenticated key exchange.
- *
- * 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.
- *
- * The exact sequence of calls to perform a password-authenticated key
- * 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.
- *
- * If this function returns an error status, the operation enters an error
- * state and must be aborted by calling psa_pake_abort().
- *
- * \param[in,out] operation Active PAKE operation.
- * \param step The step for which the input is provided.
- * \param[out] input Buffer containing the input in the format
- * appropriate for this \p step. Refer to the
- * documentation of the individual
- * \c PSA_PAKE_STEP_XXX constants for more
- * information.
- * \param[out] input_length Size of the \p input buffer in bytes.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (it must be active, but beyond that
- * validity is specific to the algorithm).
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * The input is not valid for the algorithm, ciphersuite or \p step.
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_input(psa_pake_operation_t *operation,
- psa_pake_step_t step,
- uint8_t *input,
- size_t input_length);
-
-/** Get implicitly confirmed shared secret from a PAKE.
- *
- * At this point there is a cryptographic guarantee that only the authenticated
- * party who used the same password is able to compute the key. But there is no
- * guarantee that the peer is the party he claims to be and was able to do so.
- *
- * That is, the authentication is only implicit (the peer is not authenticated
- * at this point, and no action should be taken that assume that they are - like
- * for example accessing restricted files).
- *
- * This function can be called after the key exchange phase of the operation
- * has completed. It imports the shared secret output of the PAKE into the
- * provided derivation operation. The input step
- * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key
- * material in the key derivation operation.
- *
- * The exact sequence of calls to perform a password-authenticated key
- * 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.
- *
- * When this function returns successfully, \p operation becomes inactive.
- * If this function returns an error status, both \p operation
- * and \p key_derivation operations enter an error state and must be aborted by
- * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
- *
- * \param[in,out] operation Active PAKE operation.
- * \param[out] output A key derivation operation that is ready
- * for an input step of type
- * #PSA_KEY_DERIVATION_INPUT_SECRET.
- *
- * \retval #PSA_SUCCESS
- * Success.
- * \retval #PSA_ERROR_BAD_STATE
- * The operation state is not valid (it must be active, but beyond that
- * 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
- * step is out of order or the application has done this step already
- * and it may not be repeated.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- * #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the output’s
- * algorithm.
- * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval #PSA_ERROR_BAD_STATE
- * The library has not been previously initialized by psa_crypto_init().
- * It is implementation-dependent whether a failure to initialize
- * results in this error code.
- */
-psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
- psa_key_derivation_operation_t *output);
-/**@}*/
-
#ifdef __cplusplus
}
#endif
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index a7b4ab5..615b651 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -813,6 +813,1047 @@
/** @} */
+/** \addtogroup crypto_types
+ * @{
+ */
+
+#define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t)0x0a000000)
+
+/** Whether the specified algorithm is a password-authenticated key exchange.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a password-authenticated key exchange (PAKE)
+ * algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
+#define PSA_ALG_IS_PAKE(alg) \
+ (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
+
+/** The Password-authenticated key exchange by juggling (J-PAKE) algorithm.
+ *
+ * This is J-PAKE as defined by RFC 8236, instantiated with the following
+ * parameters:
+ *
+ * - The group can be either an elliptic curve or defined over a finite field.
+ * - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
+ * J-PAKE algorithm.
+ * - A secure cryptographic hash function.
+ *
+ * To select these parameters and set up the cipher suite, call
+ * psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
+ * psa_pake_cs_set_primitive(cipher_suite,
+ * PSA_PAKE_PRIMITIVE(type, family, bits));
+ * psa_pake_cs_set_hash(cipher_suite, hash);
+ *
+ * For more information on how to set a specific curve or field, refer to the
+ * documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
+ *
+ * After initializing a J-PAKE operation, call
+ * psa_pake_setup(operation, cipher_suite);
+ * psa_pake_set_user(operation, ...);
+ * psa_pake_set_peer(operation, ...);
+ * and either
+ * psa_pake_set_password_stretch(operation, ...);
+ * or
+ * psa_pake_set_password_key(operation, ...);
+ *
+ * Either way the password is read as a byte array and must be non-empty. This
+ * can be the password itself (in some pre-defined character encoding) or some
+ * value derived from the password as mandated by some higher level protocol.
+ *
+ * (The implementation converts this byte array to a number as described in
+ * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
+ * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
+ * \c q is order of the group defined by the primitive set in the cipher suite.
+ * The \c psa_pake_set_password_xxx() functions return an error if the result
+ * of the reduction is 0.)
+ *
+ * The key exchange flow for J-PAKE is as follows:
+ * -# To get the first round data that needs to be sent to the peer, call
+ * // Get g1
+ * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Get the ZKP public key for x1
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Get the ZKP proof for x1
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * // Get g2
+ * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Get the ZKP public key for x2
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Get the ZKP proof for x2
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * -# To provide the first round data received from the peer to the operation,
+ * call
+ * // Set g3
+ * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Set the ZKP public key for x3
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Set the ZKP proof for x3
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * // Set g4
+ * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Set the ZKP public key for x4
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Set the ZKP proof for x4
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * -# To get the second round data that needs to be sent to the peer, call
+ * // Get A
+ * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Get ZKP public key for x2*s
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Get ZKP proof for x2*s
+ * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * -# To provide the second round data received from the peer to the operation,
+ * call
+ * // Set B
+ * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
+ * // Set ZKP public key for x4*s
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
+ * // Set ZKP proof for x4*s
+ * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
+ * -# To access the shared secret call
+ * // Get Ka=Kb=K
+ * psa_pake_get_implicit_key()
+ *
+ * For more information consult the documentation of the individual
+ * \c PSA_PAKE_STEP_XXX constants.
+ *
+ * At this point there is a cryptographic guarantee that only the authenticated
+ * party who used the same password is able to compute the key. But there is no
+ * guarantee that the peer is the party he claims to be and was able to do so.
+ *
+ * That is, the authentication is only implicit (the peer is not authenticated
+ * at this point, and no action should be taken that assume that they are - like
+ * for example accessing restricted files).
+ *
+ * To make the authentication explicit there are various methods, see Section 5
+ * of RFC 8236 for two examples.
+ *
+ */
+#define PSA_ALG_JPAKE ((psa_algorithm_t)0x0a000100)
+
+/** @} */
+
+/** \defgroup pake Password-authenticated key exchange (PAKE)
+ * @{
+ */
+
+/** \brief Encoding of the side of PAKE
+ *
+ * Encodes which side of the algorithm is being executed. For more information
+ * see the documentation of individual \c PSA_PAKE_SIDE_XXX constants.
+ */
+typedef uint8_t psa_pake_side_t;
+
+/** Encoding of input and output indicators for PAKE.
+ *
+ * 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
+ * algorithms.
+ */
+typedef uint8_t psa_pake_step_t;
+
+/** Encoding of the type of the PAKE's primitive.
+ *
+ * Values defined by this standard will never be in the range 0x80-0xff.
+ * Vendors who define additional types must use an encoding in this range.
+ *
+ * For more information see the documentation of individual
+ * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
+ */
+typedef uint8_t psa_pake_primitive_type_t;
+
+/** \brief Encoding of the family of the primitive associated with the PAKE.
+ *
+ * For more information see the documentation of individual
+ * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
+ */
+typedef uint8_t psa_pake_family_t;
+
+/** \brief Encoding of the primitive associated with the PAKE.
+ *
+ * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
+ */
+typedef uint32_t psa_pake_primitive_t;
+
+/** The first peer in a balanced PAKE.
+ *
+ * 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, both #PSA_PAKE_SIDE_FIRST and #PSA_PAKE_SIDE_SECOND are
+ * accepted.
+ */
+#define PSA_PAKE_SIDE_FIRST ((psa_pake_side_t)0x01)
+
+/** The second peer in a balanced PAKE.
+ *
+ * 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.
+ */
+#define PSA_PAKE_SIDE_SECOND ((psa_pake_side_t)0x02)
+
+/** The client in an augmented PAKE.
+ *
+ * Augmented PAKE algorithms need to differentiate between client and server.
+ */
+#define PSA_PAKE_SIDE_CLIENT ((psa_pake_side_t)0x11)
+
+/** The server in an augmented PAKE.
+ *
+ * Augmented PAKE algorithms need to differentiate between client and server.
+ */
+#define PSA_PAKE_SIDE_SERVER ((psa_pake_side_t)0x12)
+
+/** The PAKE primitive type indicating the use of elliptic curves.
+ *
+ * The values of the \c family and \c bits fields of the cipher suite identify a
+ * specific elliptic curve, using the same mapping that is used for ECC
+ * (::psa_ecc_family_t) keys.
+ *
+ * (Here \c family means the value returned by psa_pake_cs_get_family() and
+ * \c bits means the value returned by psa_pake_cs_get_bits().)
+ *
+ * Input and output during the operation can involve group elements and scalar
+ * values:
+ * -# The format for group elements is the same as for public keys on the
+ * specific curve would be. For more information, consult the documentation of
+ * psa_export_public_key().
+ * -# The format for scalars is the same as for private keys on the specific
+ * curve would be. For more information, consult the documentation of
+ * psa_export_key().
+ */
+#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01)
+
+/** The PAKE primitive type indicating the use of Diffie-Hellman groups.
+ *
+ * The values of the \c family and \c bits fields of the cipher suite identify
+ * a specific Diffie-Hellman group, using the same mapping that is used for
+ * Diffie-Hellman (::psa_dh_family_t) keys.
+ *
+ * (Here \c family means the value returned by psa_pake_cs_get_family() and
+ * \c bits means the value returned by psa_pake_cs_get_bits().)
+ *
+ * Input and output during the operation can involve group elements and scalar
+ * values:
+ * -# The format for group elements is the same as for public keys on the
+ * specific group would be. For more information, consult the documentation of
+ * psa_export_public_key().
+ * -# The format for scalars is the same as for private keys on the specific
+ * group would be. For more information, consult the documentation of
+ * psa_export_key().
+ */
+#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02)
+
+/** Construct a PAKE primitive from type, family and bit-size.
+ *
+ * \param pake_type The type of the primitive
+ * (value of type ::psa_pake_primitive_type_t).
+ * \param pake_family The family of the primitive
+ * (the type and interpretation of this parameter depends
+ * on \p type, for more information consult the
+ * documentation of individual ::psa_pake_primitive_type_t
+ * constants).
+ * \param pake_bits The bit-size of the primitive
+ * (Value of type \c size_t. The interpretation
+ * of this parameter depends on \p family, for more
+ * information consult the documentation of individual
+ * ::psa_pake_primitive_type_t constants).
+ *
+ * \return The constructed primitive value of type ::psa_pake_primitive_t.
+ * Return 0 if the requested primitive can't be encoded as
+ * ::psa_pake_primitive_t.
+ */
+#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
+ ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
+ ((psa_pake_primitive_t) (((pake_type) << 24 | \
+ (pake_family) << 16) | (pake_bits)))
+
+/** The key share being sent to or received from the peer.
+ *
+ * The format for both input and output at this step is the same as for public
+ * keys on the group determined by the primitive (::psa_pake_primitive_t) would
+ * be.
+ *
+ * For more information on the format, consult the documentation of
+ * psa_export_public_key().
+ *
+ * For information regarding how the group is determined, consult the
+ * documentation #PSA_PAKE_PRIMITIVE.
+ */
+#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01)
+
+/** A Schnorr NIZKP public key.
+ *
+ * The format for both input and output at this step is the same as for public
+ * keys on the group determined by the primitive (::psa_pake_primitive_t) would
+ * be.
+ *
+ * For more information on the format, consult the documentation of
+ * psa_export_public_key().
+ *
+ * For information regarding how the group is determined, consult the
+ * documentation #PSA_PAKE_PRIMITIVE.
+ */
+#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t)0x02)
+
+/** A Schnorr NIZKP proof.
+ *
+ * The format for both input and output at this step is the same as for private
+ * keys on the group determined by the primitive (::psa_pake_primitive_t) would
+ * be.
+ *
+ * Some public key algorithms mask the private keys and this might be reflected
+ * in the export format. Even if this is the case the masking is omitted at
+ * this step.
+ *
+ * For more information on the format, consult the documentation of
+ * psa_export_key().
+ *
+ * For information regarding how the group is determined, consult the
+ * documentation #PSA_PAKE_PRIMITIVE.
+ */
+#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t)0x03)
+
+/** The type of the data strucure for PAKE cipher suites.
+ *
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice.
+ */
+typedef struct psa_pake_cipher_suite_s psa_pake_cipher_suite_t;
+
+/** Retrieve the PAKE algorithm from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite The cipher suite structure to query.
+ *
+ * \return The PAKE algorithm stored in the cipher suite structure.
+ */
+static psa_algorithm_t psa_pake_cs_get_algorithm(
+ const psa_pake_cipher_suite_t* cipher_suite
+ );
+
+/** Declare the PAKE algorithm for the cipher suite.
+ *
+ * This function overwrites any PAKE algorithm
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite The cipher suite structure to write to.
+ * \param algorithm The PAKE algorithm to write.
+ * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
+ * such that #PSA_ALG_IS_PAKE(\c alg) is true.)
+ * If this is 0, the PAKE algorithm in
+ * \p cipher_suite becomes unspecified.
+ */
+static void psa_pake_cs_set_algorithm(
+ psa_pake_cipher_suite_t* cipher_suite,
+ psa_algorithm_t algorithm
+ );
+
+/** Retrieve the primitive from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external linkage).
+ * This function may be provided as a function-like macro, but in this case it
+ * must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite The cipher suite structure to query.
+ *
+ * \return The primitive stored in the cipher suite structure.
+ */
+static psa_pake_primitive_t psa_pake_cs_get_primitive(
+ const psa_pake_cipher_suite_t* cipher_suite
+ );
+
+/** Declare the primitive for a PAKE cipher suite.
+ *
+ * This function overwrites any primitive previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * \param[out] cipher_suite The cipher suite structure to write to.
+ * \param primitive The primitive to write. If this is 0, the
+ * primitive type in \p cipher_suite becomes
+ * unspecified.
+ */
+static void psa_pake_cs_set_primitive(
+ psa_pake_cipher_suite_t* cipher_suite,
+ psa_pake_primitive_t primitive
+ );
+
+/** Retrieve the hash algorithm from a PAKE cipher suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate its argument exactly once.
+ *
+ * \param[in] cipher_suite The cipher suite structure to query.
+ *
+ * \return The hash algorithm stored in the cipher suite structure. The return
+ * value is 0 if the PAKE is not parametrised by a hash algorithm or if
+ * the hash algorithm is not set.
+ */
+static psa_algorithm_t psa_pake_cs_get_hash(
+ const psa_pake_cipher_suite_t* cipher_suite
+ );
+
+/** Declare the hash algorithm for a PAKE cipher suite.
+ *
+ * This function overwrites any hash algorithm
+ * previously set in \p cipher_suite.
+ *
+ * This function may be declared as `static` (i.e. without external
+ * linkage). This function may be provided as a function-like macro,
+ * but in this case it must evaluate each of its arguments exactly once.
+ *
+ * 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.
+ *
+ * \param[out] cipher_suite The cipher suite structure to write to.
+ * \param hash The hash involved in the cipher suite.
+ * (`PSA_ALG_XXX` values of type ::psa_algorithm_t
+ * such that #PSA_ALG_IS_HASH(\c alg) is true.)
+ * If this is 0, the hash algorithm in
+ * \p cipher_suite becomes unspecified.
+ */
+static void psa_pake_cs_set_hash(
+ psa_pake_cipher_suite_t* cipher_suite,
+ psa_algorithm_t hash
+ );
+
+/** The type of the state data structure for PAKE operations.
+ *
+ * Before calling any function on a PAKE operation object, the application
+ * must initialize it by any of the following means:
+ * - Set the structure to all-bits-zero, for example:
+ * \code
+ * psa_pake_operation_t operation;
+ * memset(&operation, 0, sizeof(operation));
+ * \endcode
+ * - Initialize the structure to logical zero values, for example:
+ * \code
+ * psa_pake_operation_t operation = {0};
+ * \endcode
+ * - Initialize the structure to the initializer #PSA_PAKE_OPERATION_INIT,
+ * for example:
+ * \code
+ * psa_pake_operation_t operation = PSA_PAKE_OPERATION_INIT;
+ * \endcode
+ * - Assign the result of the function psa_pake_operation_init()
+ * to the structure, for example:
+ * \code
+ * psa_pake_operation_t operation;
+ * operation = psa_pake_operation_init();
+ * \endcode
+ *
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice. */
+typedef struct psa_pake_operation_s psa_pake_operation_t;
+
+/** Return an initial value for an PAKE operation object.
+ */
+static psa_pake_operation_t psa_pake_operation_init(void);
+
+/** Set the session information for a password-authenticated key exchange.
+ *
+ * The sequence of operations to set up a password-authenticated key exchange
+ * is as follows:
+ * -# Allocate an operation object which will be passed to all the functions
+ * listed here.
+ * -# Initialize the operation object with one of the methods described in the
+ * documentation for #psa_pake_operation_t, e.g.
+ * #PSA_PAKE_OPERATION_INIT.
+ * -# Call psa_pake_setup() to specify the cipher suite.
+ * -# Call \c psa_pake_set_xxx() functions on the operation to complete the
+ * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
+ * to be called 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.
+ *
+ * A typical sequence of calls to perform a password-authenticated key
+ * exchange:
+ * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the
+ * key share that needs to be sent to the peer.
+ * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide
+ * the key share that was received from the peer.
+ * -# Depending on the algorithm additional calls to psa_pake_output() and
+ * psa_pake_input() might be necessary.
+ * -# Call psa_pake_get_implicit_key() for accessing the shared secret.
+ *
+ * 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.
+ *
+ * If an error occurs at any step after a call to psa_pake_setup(),
+ * the operation will need to be reset by a call to psa_pake_abort(). The
+ * application may call psa_pake_abort() at any time after the operation
+ * has been initialized.
+ *
+ * After a successful call to psa_pake_setup(), the application must
+ * eventually terminate the operation. The following events terminate an
+ * operation:
+ * - A call to psa_pake_abort().
+ * - A successful call to psa_pake_get_implicit_key().
+ *
+ * \param[in,out] operation The operation object to set up. It must have
+ * been initialized as per the documentation for
+ * #psa_pake_operation_t and not yet in use (no
+ * other function has been called on it since the
+ * last initialization).
+ * \param cipher_suite The cipher suite to use. (A cipher suite fully
+ * characterizes a PAKE algorithm and determines
+ * the algorithm as well.)
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * The \p cipher_suite is not supported or is not valid.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
+ psa_pake_cipher_suite_t cipher_suite);
+
+/** Set the password for a password-authenticated key exchange from key ID.
+ *
+ * Call this function when the password, or a value derived from the password,
+ * is already present in the key store. To calculate the password-derived value
+ * from a password input, use the key derivation interface and
+ * psa_pake_set_password_stretch() instead.
+ *
+ * \param[in,out] operation The operation object to set the password for. It
+ * must have been set up by psa_pake_setup() and
+ * not yet in use (neither psa_pake_output() nor
+ * psa_pake_input() has been called yet). It must
+ * be on operation for which the password hasn't
+ * been set yet (neither
+ * psa_pake_set_password_stretch() nor
+ * psa_pake_set_password_key() has been called
+ * yet).
+ * \param password Identifier of the key holding the password or a
+ * value derived from the password (eg. by a
+ * memory-hard function). It must remain valid
+ * until the operation terminates. It must be of
+ * type #PSA_KEY_TYPE_PASSWORD or
+ * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
+ * the usage #PSA_KEY_USAGE_DERIVE.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must have been set up.)
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with the algorithm or the cipher suite.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_set_password_key(psa_pake_operation_t *operation,
+ mbedtls_svc_key_id_t password);
+
+/** Set the password for a password-authenticated key exchange via a key
+ * stretching function.
+ *
+ * Some protocols use values derived from passwords via key stretching
+ * functions to mitigate dictionary attacks. Key stretching functions can be
+ * accessed through the key derivation interface and the result can be supplied
+ * to the PAKE operation in the form of a key derivation object.
+ *
+ * This function draws bytes from a key derivation algorithm and sets those
+ * bytes as a password for the password-authenticated key exchange. If you
+ * view the key derivation's output as a stream of bytes, this function
+ * destructively reads the requested number of bytes from the stream.
+ * The key derivation operation's capacity decreases by the number of bytes read.
+ *
+ * If this function returns anything other than #PSA_SUCCESS, both \p operation
+ * and \p key_derivation operations enter an error state and must be aborted by
+ * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
+ *
+ * \param[in,out] operation The operation object to set the password for.
+ * It must have been set up by psa_pake_setup()
+ * and not yet in use (neither psa_pake_output()
+ * nor psa_pake_input() has been called yet). It
+ * must be on operation for which the password
+ * hasn't been set yet (neither
+ * psa_pake_set_password_stretch() nor
+ * psa_pake_set_password_key() has been called
+ * yet).
+ * \param[in,out] key_derivation An ongoing key derivation operation set up
+ * from the password and in a state suitable for
+ * calling psa_key_derivation_output_bytes().
+ * \param input_length Number of bytes to input from the
+ * \p key_derivation operation.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The state of \p operation or \p key_derivation is not valid.
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
+ * The \p key_derivation operation's capacity was less than
+ * \p input_length bytes.
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * One of the inputs to \p key_derivation was a key whose policy didn't
+ * allow #PSA_KEY_USAGE_DERIVE.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with the algorithm or the cipher suite.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_set_password_stretch(
+ psa_pake_operation_t *operation,
+ psa_key_derivation_operation_t *key_derivation,
+ size_t input_length
+ );
+
+/** Set the user ID for a password-authenticated key exchange.
+ *
+ * Call this function to set the user ID. For PAKE algorithms that associate a
+ * user identifier with each side of the session you need to call
+ * psa_pake_set_peer() as well. For PAKE algorithms that associate a single
+ * user identifier with the session, call psa_pake_set_user() only.
+ *
+ * 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.
+ *
+ * \param[in,out] operation The operation object to set the user ID for. It
+ * must have been set up by psa_pake_setup() and
+ * not yet in use (neither psa_pake_output() nor
+ * psa_pake_input() has been called yet). It must
+ * be on operation for which the user ID hasn't
+ * been set (psa_pake_set_user() hasn't been
+ * called yet).
+ * \param[in] user_id The user ID to authenticate with.
+ * \param user_id_len Size of the \p user_id buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p user_id is NULL.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_set_user(psa_pake_operation_t *operation,
+ const uint8_t *user_id,
+ size_t user_id_len);
+
+/** Set the peer ID for a password-authenticated key exchange.
+ *
+ * Call this function in addition to psa_pake_set_user() for PAKE algorithms
+ * that associate a user identifier with each side of the session. For PAKE
+ * algorithms that associate a single user identifier with the session, call
+ * psa_pake_set_user() only.
+ *
+ * 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.
+ *
+ * \param[in,out] operation The operation object to set the peer ID for. It
+ * must have been set up by psa_pake_setup() and
+ * not yet in use (neither psa_pake_output() nor
+ * psa_pake_input() has been called yet). It must
+ * be on operation for which the peer ID hasn't
+ * been set (psa_pake_set_peer() hasn't been
+ * called yet).
+ * \param[in] peer_id The peer's ID to authenticate.
+ * \param peer_id_len Size of the \p peer_id buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * The algorithm doesn't associate a second identity with the session.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p user_id is NULL.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation,
+ const uint8_t *peer_id,
+ size_t peer_id_len);
+
+/** Set the side for a password-authenticated key exchange.
+ *
+ * Not all PAKE algorithms need to differentiate the communicating entities.
+ * It is optional to call this function for PAKEs that don't require a side
+ * parameter. For such PAKEs the side parameter is ignored.
+ *
+ * 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.
+ *
+ * \param[in,out] operation The operation object to set the side for. It
+ * must have been set up by psa_pake_setup() and
+ * not yet in use (neither psa_pake_output() nor
+ * psa_pake_input() has been called yet). It must
+ * be on operation for which the side hasn't been
+ * set (psa_pake_set_side() hasn't been called
+ * yet).
+ * \param side A value of type ::psa_pake_side_t signaling the
+ * side of the algorithm that is being set up. For
+ * more information see the documentation of \c
+ * PSA_PAKE_SIDE_XXX constants.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * The \p side for this algorithm is not supported or is not valid.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_set_side(psa_pake_operation_t *operation,
+ psa_pake_side_t side);
+
+/** Get output for a step of a password-authenticated key exchange.
+ *
+ * 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.
+ *
+ * The exact sequence of calls to perform a password-authenticated key
+ * 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.
+ *
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_pake_abort().
+ *
+ * \param[in,out] operation Active PAKE operation.
+ * \param step The step of the algorithm for which the output is
+ * requested.
+ * \param[out] output Buffer where the output is to be written in the
+ * format appropriate for this \p step. Refer to
+ * the documentation of the individual
+ * \c PSA_PAKE_STEP_XXX constants for more
+ * information.
+ * \param output_size Size of the \p output buffer in bytes. This must
+ * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c
+ * cipher_suite, \p type).
+ *
+ * \param[out] output_length On success, the number of bytes of the returned
+ * output.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active, but beyond that
+ * 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
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_output(psa_pake_operation_t *operation,
+ psa_pake_step_t step,
+ uint8_t *output,
+ size_t output_size,
+ size_t *output_length);
+
+/** Provide input for a step of a password-authenticated key exchange.
+ *
+ * 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.
+ *
+ * The exact sequence of calls to perform a password-authenticated key
+ * 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.
+ *
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_pake_abort().
+ *
+ * \param[in,out] operation Active PAKE operation.
+ * \param step The step for which the input is provided.
+ * \param[out] input Buffer containing the input in the format
+ * appropriate for this \p step. Refer to the
+ * documentation of the individual
+ * \c PSA_PAKE_STEP_XXX constants for more
+ * information.
+ * \param[out] input_length Size of the \p input buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active, but beyond that
+ * validity is specific to the algorithm).
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * The input is not valid for the algorithm, ciphersuite or \p step.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_input(psa_pake_operation_t *operation,
+ psa_pake_step_t step,
+ uint8_t *input,
+ size_t input_length);
+
+/** Get implicitly confirmed shared secret from a PAKE.
+ *
+ * At this point there is a cryptographic guarantee that only the authenticated
+ * party who used the same password is able to compute the key. But there is no
+ * guarantee that the peer is the party he claims to be and was able to do so.
+ *
+ * That is, the authentication is only implicit (the peer is not authenticated
+ * at this point, and no action should be taken that assume that they are - like
+ * for example accessing restricted files).
+ *
+ * This function can be called after the key exchange phase of the operation
+ * has completed. It imports the shared secret output of the PAKE into the
+ * provided derivation operation. The input step
+ * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key
+ * material in the key derivation operation.
+ *
+ * The exact sequence of calls to perform a password-authenticated key
+ * 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.
+ *
+ * When this function returns successfully, \p operation becomes inactive.
+ * If this function returns an error status, both \p operation
+ * and \p key_derivation operations enter an error state and must be aborted by
+ * calling psa_pake_abort() and psa_key_derivation_abort() respectively.
+ *
+ * \param[in,out] operation Active PAKE operation.
+ * \param[out] output A key derivation operation that is ready
+ * for an input step of type
+ * #PSA_KEY_DERIVATION_INPUT_SECRET.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active, but beyond that
+ * 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
+ * step is out of order or the application has done this step already
+ * and it may not be repeated.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the output’s
+ * algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ * The library has not been previously initialized by psa_crypto_init().
+ * It is implementation-dependent whether a failure to initialize
+ * results in this error code.
+ */
+psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
+ psa_key_derivation_operation_t *output);
+
+/**@}*/
+
+/** A sufficient output buffer size for psa_pake_output().
+ *
+ * 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 output buffer
+ * size. The actual size of the output might be smaller in any given call.
+ *
+ * See also #PSA_PAKE_OUTPUT_MAX_SIZE
+ *
+ * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_PAKE(\p alg) is true).
+ * \param primitive A primitive of type ::psa_pake_primitive_t that is
+ * compatible with algorithm \p alg.
+ * \param output_step A value of type ::psa_pake_step_t that is valid for the
+ * algorithm \p alg.
+ * \return A sufficient output buffer size for the specified
+ * output, cipher suite and algorithm. If the cipher suite,
+ * the output type or PAKE algorithm is not recognized, or
+ * the parameters are incompatible, return 0.
+ */
+#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) 0
+
+/** A sufficient input buffer size for psa_pake_input().
+ *
+ * If the size of the input is larger than this, it is guaranteed
+ * that psa_pake_input() will fail with #PSA_ERROR_INVALID_ARGUMENT.
+ *
+ * See also #PSA_PAKE_INPUT_MAX_SIZE
+ *
+ * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_PAKE(\p alg) is true).
+ * \param primitive A primitive of type ::psa_pake_primitive_t that is
+ * compatible with algorithm \p alg.
+ * \param output_step A value of type ::psa_pake_step_t that is valid for the
+ * algorithm \p alg.
+ * \return A sufficient output buffer size for the specified
+ * output, cipher suite and algorithm. If the cipher suite,
+ * the output type or PAKE algorithm is not recognized, or
+ * the parameters are incompatible, return 0.
+ */
+#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) 0
+
+/** Output buffer size for psa_pake_output() for any of the supported cipher
+ * suites and PAKE algorithms.
+ *
+ * This macro must expand to a compile-time constant integer.
+ *
+ * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p cipher_suite, \p output).
+ */
+#define PSA_PAKE_OUTPUT_MAX_SIZE 0
+
+/** Input buffer size for psa_pake_input() for any of the supported cipher
+ * suites and PAKE algorithms.
+ *
+ * This macro must expand to a compile-time constant integer.
+ *
+ * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p cipher_suite, \p output).
+ */
+#define PSA_PAKE_INPUT_MAX_SIZE 0
+
+struct psa_pake_cipher_suite_s
+{
+ psa_algorithm_t algorithm;
+ psa_pake_primitive_type_t type;
+ psa_pake_family_t family;
+ uint16_t bits;
+ psa_algorithm_t hash;
+};
+
+static inline psa_algorithm_t psa_pake_cs_get_algorithm(
+ const psa_pake_cipher_suite_t *cipher_suite)
+{
+ return(cipher_suite->algorithm);
+}
+
+static inline void psa_pake_cs_set_algorithm(
+ psa_pake_cipher_suite_t *cipher_suite,
+ psa_algorithm_t algorithm)
+{
+ if(!PSA_ALG_IS_PAKE(algorithm))
+ cipher_suite->algorithm = 0;
+ else
+ cipher_suite->algorithm = algorithm;
+}
+
+static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
+ const psa_pake_cipher_suite_t *cipher_suite)
+{
+ return(PSA_PAKE_PRIMITIVE(cipher_suite->type, cipher_suite->family,
+ cipher_suite->bits));
+}
+
+static inline void psa_pake_cs_set_primitive(
+ psa_pake_cipher_suite_t *cipher_suite,
+ psa_pake_primitive_t primitive)
+{
+ cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
+ cipher_suite->family = (psa_pake_family_t) (0xFF & (primitive >> 16));
+ cipher_suite->bits = (uint16_t) (0xFFFF & primitive);
+}
+
+static inline psa_algorithm_t psa_pake_cs_get_hash(
+ const psa_pake_cipher_suite_t *cipher_suite)
+{
+ return(cipher_suite->hash);
+}
+
+static inline void psa_pake_cs_set_hash(
+ psa_pake_cipher_suite_t *cipher_suite,
+ psa_algorithm_t hash)
+{
+ if(!PSA_ALG_IS_HASH(hash))
+ cipher_suite->hash = 0;
+ else
+ cipher_suite->hash = hash;
+}
+
+struct psa_pake_operation_s
+{
+ psa_algorithm_t alg;
+ union
+ {
+ /* Make the union non-empty even with no supported algorithms. */
+ uint8_t dummy;
+ } ctx;
+};
+
+/* This only zeroes out the first byte in the union, the rest is unspecified. */
+#define PSA_PAKE_OPERATION_INIT {0, {0}}
+static inline struct psa_pake_operation_s psa_pake_operation_init(void)
+{
+ const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
+ return(v);
+}
+
#ifdef __cplusplus
}
#endif
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index 62254fa..79f9673 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -1132,63 +1132,4 @@
#define PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE \
(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
-/** A sufficient output buffer size for psa_pake_output().
- *
- * 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 output buffer
- * size. The actual size of the output might be smaller in any given call.
- *
- * See also #PSA_PAKE_OUTPUT_MAX_SIZE
- *
- * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
- * #PSA_ALG_IS_PAKE(\p alg) is true).
- * \param primitive A primitive of type ::psa_pake_primitive_t that is
- * compatible with algorithm \p alg.
- * \param output_step A value of type ::psa_pake_step_t that is valid for the
- * algorithm \p alg.
- * \return A sufficient output buffer size for the specified
- * output, cipher suite and algorithm. If the cipher suite,
- * the output type or PAKE algorithm is not recognized, or
- * the parameters are incompatible, return 0.
- */
-#define PSA_PAKE_OUTPUT_SIZE(alg, primitive, output_step) 0
-
-/** A sufficient input buffer size for psa_pake_input().
- *
- * If the size of the input is larger than this, it is guaranteed
- * that psa_pake_input() will fail with #PSA_ERROR_INVALID_ARGUMENT.
- *
- * See also #PSA_PAKE_INPUT_MAX_SIZE
- *
- * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
- * #PSA_ALG_IS_PAKE(\p alg) is true).
- * \param primitive A primitive of type ::psa_pake_primitive_t that is
- * compatible with algorithm \p alg.
- * \param output_step A value of type ::psa_pake_step_t that is valid for the
- * algorithm \p alg.
- * \return A sufficient output buffer size for the specified
- * output, cipher suite and algorithm. If the cipher suite,
- * the output type or PAKE algorithm is not recognized, or
- * the parameters are incompatible, return 0.
- */
-#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) 0
-
-/** Output buffer size for psa_pake_output() for any of the supported cipher
- * suites and PAKE algorithms.
- *
- * This macro must expand to a compile-time constant integer.
- *
- * See also #PSA_PAKE_OUTPUT_SIZE(\p alg, \p cipher_suite, \p output).
- */
-#define PSA_PAKE_OUTPUT_MAX_SIZE 0
-
-/** Input buffer size for psa_pake_input() for any of the supported cipher
- * suites and PAKE algorithms.
- *
- * This macro must expand to a compile-time constant integer.
- *
- * See also #PSA_PAKE_INPUT_SIZE(\p alg, \p cipher_suite, \p output).
- */
-#define PSA_PAKE_INPUT_MAX_SIZE 0
-
#endif /* PSA_CRYPTO_SIZES_H */
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index b20a179..47012fd 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -461,81 +461,6 @@
return( attributes->core.bits );
}
-struct psa_pake_cipher_suite_s
-{
- psa_algorithm_t algorithm;
- psa_pake_primitive_type_t type;
- psa_pake_family_t family;
- uint16_t bits;
- psa_algorithm_t hash;
-};
-
-static inline psa_algorithm_t psa_pake_cs_get_algorithm(
- const psa_pake_cipher_suite_t *cipher_suite)
-{
- return( cipher_suite->algorithm );
-}
-
-static inline void psa_pake_cs_set_algorithm(
- psa_pake_cipher_suite_t *cipher_suite,
- psa_algorithm_t algorithm)
-{
- if( !PSA_ALG_IS_PAKE(algorithm) )
- cipher_suite->algorithm = 0;
- else
- cipher_suite->algorithm = algorithm;
-}
-
-static inline psa_pake_primitive_t psa_pake_cs_get_primitive(
- const psa_pake_cipher_suite_t *cipher_suite)
-{
- return( PSA_PAKE_PRIMITIVE( cipher_suite->type, cipher_suite->family,
- cipher_suite->bits) );
-}
-
-static inline void psa_pake_cs_set_primitive(
- psa_pake_cipher_suite_t *cipher_suite,
- psa_pake_primitive_t primitive)
-{
- cipher_suite->type = (psa_pake_primitive_type_t) (primitive >> 24);
- cipher_suite->family = (psa_pake_family_t) ( 0xFF & (primitive >> 16) );
- cipher_suite->bits = (uint16_t) ( 0xFFFF & primitive );
-}
-
-static inline psa_algorithm_t psa_pake_cs_get_hash(
- const psa_pake_cipher_suite_t *cipher_suite)
-{
- return( cipher_suite->hash );
-}
-
-static inline void psa_pake_cs_set_hash(
- psa_pake_cipher_suite_t *cipher_suite,
- psa_algorithm_t hash)
-{
- if( !PSA_ALG_IS_HASH(hash) )
- cipher_suite->hash = 0;
- else
- cipher_suite->hash = hash;
-}
-
-struct psa_pake_operation_s
-{
- psa_algorithm_t alg;
- union
- {
- /* Make the union non-empty even with no supported algorithms. */
- uint8_t dummy;
- } ctx;
-};
-
-/* This only zeroes out the first byte in the union, the rest is unspecified. */
-#define PSA_PAKE_OPERATION_INIT {0, {0}}
-static inline struct psa_pake_operation_s psa_pake_operation_init( void )
-{
- const struct psa_pake_operation_s v = PSA_PAKE_OPERATION_INIT;
- return( v );
-}
-
#ifdef __cplusplus
}
#endif
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 5a66a87..386c7d7 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -380,46 +380,4 @@
/**@}*/
-/** \defgroup pake Password-authenticated key exchange (PAKE)
- * @{
- */
-
-/** \brief Encoding of the side of PAKE
- *
- * Encodes which side of the algorithm is being executed. For more information
- * see the documentation of individual \c PSA_PAKE_SIDE_XXX constants.
- */
-typedef uint8_t psa_pake_side_t;
-
-/** Encoding of input and output indicators for PAKE.
- *
- * 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
- * algorithms.
- */
-typedef uint8_t psa_pake_step_t;
-
-/** Encoding of the type of the PAKE's primitive.
- *
- * Values defined by this standard will never be in the range 0x80-0xff.
- * Vendors who define additional types must use an encoding in this range.
- *
- * For more information see the documentation of individual
- * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
- */
-typedef uint8_t psa_pake_primitive_type_t;
-
-/** \brief Encoding of the family of the primitive associated with the PAKE.
- *
- * For more information see the documentation of individual
- * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
- */
-typedef uint8_t psa_pake_family_t;
-
-/** \brief Encoding of the primitive associated with the PAKE.
- *
- * For more information see the documentation of the #PSA_PAKE_PRIMITIVE macro.
- */
-typedef uint32_t psa_pake_primitive_t;
-/**@}*/
#endif /* PSA_CRYPTO_TYPES_H */
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 37cd030..497bd8f 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -731,7 +731,6 @@
#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x07000000)
#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x08000000)
#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x09000000)
-#define PSA_ALG_CATEGORY_PAKE ((psa_algorithm_t)0x0a000000)
/** Whether an algorithm is vendor-defined.
*
@@ -849,18 +848,6 @@
(PSA_ALG_IS_KEY_DERIVATION(alg) && \
(alg) & PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG)
-/** Whether the specified algorithm is a password-authenticated key exchange.
- *
- * \param alg An algorithm identifier (value of type #psa_algorithm_t).
- *
- * \return 1 if \p alg is a password-authenticated key exchange (PAKE)
- * algorithm, 0 otherwise.
- * This macro may return either 0 or 1 if \p alg is not a supported
- * algorithm identifier.
- */
-#define PSA_ALG_IS_PAKE(alg) \
- (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_PAKE)
-
#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
/** MD2 */
#define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)
@@ -1966,109 +1953,6 @@
#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) algorithm.
- *
- * This is J-PAKE as defined by RFC 8236, instantiated with the following
- * parameters:
- *
- * - The group can be either an elliptic curve or defined over a finite field.
- * - Schnorr NIZK proof as defined by RFC 8235 and using the same group as the
- * J-PAKE algorithm.
- * - A secure cryptographic hash function.
- *
- * To select these parameters and set up the cipher suite, call
- * psa_pake_cs_set_algorithm(cipher_suite, PSA_ALG_JPAKE);
- * psa_pake_cs_set_primitive(cipher_suite,
- * PSA_PAKE_PRIMITIVE(type, family, bits));
- * psa_pake_cs_set_hash(cipher_suite, hash);
- *
- * For more information on how to set a specific curve or field, refer to the
- * documentation of the individual \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.
- *
- * After initializing a J-PAKE operation, call
- * psa_pake_setup(operation, cipher_suite);
- * psa_pake_set_user(operation, ...);
- * psa_pake_set_peer(operation, ...);
- * and either
- * psa_pake_set_password_stretch(operation, ...);
- * or
- * psa_pake_set_password_key(operation, ...);
- *
- * Either way the password is read as a byte array and must be non-empty. This
- * can be the password itself (in some pre-defined character encoding) or some
- * value derived from the password as mandated by some higher level protocol.
- *
- * (The implementation converts this byte array to a number as described in
- * Section 2.3.8 of _SEC 1: Elliptic Curve Cryptography_
- * (https://www.secg.org/sec1-v2.pdf), before reducing it modulo \c q. Here
- * \c q is order of the group defined by the primitive set in the cipher suite.
- * The \c psa_pake_set_password_xxx() functions return an error if the result
- * of the reduction is 0.)
- *
- * The key exchange flow for J-PAKE is as follows:
- * -# To get the first round data that needs to be sent to the peer, call
- * // Get g1
- * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Get the ZKP public key for x1
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Get the ZKP proof for x1
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * // Get g2
- * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Get the ZKP public key for x2
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Get the ZKP proof for x2
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * -# To provide the first round data received from the peer to the operation,
- * call
- * // Set g3
- * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Set the ZKP public key for x3
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Set the ZKP proof for x3
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * // Set g4
- * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Set the ZKP public key for x4
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Set the ZKP proof for x4
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * -# To get the second round data that needs to be sent to the peer, call
- * // Get A
- * psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Get ZKP public key for x2*s
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Get ZKP proof for x2*s
- * psa_pake_output(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * -# To provide the second round data received from the peer to the operation,
- * call
- * // Set B
- * psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...);
- * // Set ZKP public key for x4*s
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PUBLIC, ...);
- * // Set ZKP proof for x4*s
- * psa_pake_input(operation, #PSA_PAKE_STEP_ZK_PROOF, ...);
- * -# To access the shared secret call
- * // Get Ka=Kb=K
- * psa_pake_get_implicit_key()
- *
- * For more information consult the documentation of the individual
- * \c PSA_PAKE_STEP_XXX constants.
- *
- * At this point there is a cryptographic guarantee that only the authenticated
- * party who used the same password is able to compute the key. But there is no
- * guarantee that the peer is the party he claims to be and was able to do so.
- *
- * That is, the authentication is only implicit (the peer is not authenticated
- * at this point, and no action should be taken that assume that they are - like
- * for example accessing restricted files).
- *
- * To make the authentication explicit there are various methods, see Section 5
- * of RFC 8236 for two examples.
- *
- */
-#define PSA_ALG_JPAKE ((psa_algorithm_t)0x0a000100)
-
/**@}*/
/** \defgroup key_lifetimes Key lifetimes
@@ -2497,149 +2381,4 @@
/**@}*/
-/** \defgroup pake Password-authenticated key exchange (PAKE)
- * @{
- */
-
-/** The first peer in a balanced PAKE.
- *
- * 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, both #PSA_PAKE_SIDE_FIRST and #PSA_PAKE_SIDE_SECOND are
- * accepted.
- */
-#define PSA_PAKE_SIDE_FIRST ((psa_pake_side_t)0x01)
-
-/** The second peer in a balanced PAKE.
- *
- * 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.
- */
-#define PSA_PAKE_SIDE_SECOND ((psa_pake_side_t)0x02)
-
-/** The client in an augmented PAKE.
- *
- * Augmented PAKE algorithms need to differentiate between client and server.
- */
-#define PSA_PAKE_SIDE_CLIENT ((psa_pake_side_t)0x11)
-
-/** The server in an augmented PAKE.
- *
- * Augmented PAKE algorithms need to differentiate between client and server.
- */
-#define PSA_PAKE_SIDE_SERVER ((psa_pake_side_t)0x12)
-
-/** The PAKE primitive type indicating the use of elliptic curves.
- *
- * The values of the \c family and \c bits fields of the cipher suite identify a
- * specific elliptic curve, using the same mapping that is used for ECC
- * (::psa_ecc_family_t) keys.
- *
- * (Here \c family means the value returned by psa_pake_cs_get_family() and
- * \c bits means the value returned by psa_pake_cs_get_bits().)
- *
- * Input and output during the operation can involve group elements and scalar
- * values:
- * -# The format for group elements is the same as for public keys on the
- * specific curve would be. For more information, consult the documentation of
- * psa_export_public_key().
- * -# The format for scalars is the same as for private keys on the specific
- * curve would be. For more information, consult the documentation of
- * psa_export_key().
- */
-#define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01)
-
-/** The PAKE primitive type indicating the use of Diffie-Hellman groups.
- *
- * The values of the \c family and \c bits fields of the cipher suite identify
- * a specific Diffie-Hellman group, using the same mapping that is used for
- * Diffie-Hellman (::psa_dh_family_t) keys.
- *
- * (Here \c family means the value returned by psa_pake_cs_get_family() and
- * \c bits means the value returned by psa_pake_cs_get_bits().)
- *
- * Input and output during the operation can involve group elements and scalar
- * values:
- * -# The format for group elements is the same as for public keys on the
- * specific group would be. For more information, consult the documentation of
- * psa_export_public_key().
- * -# The format for scalars is the same as for private keys on the specific
- * group would be. For more information, consult the documentation of
- * psa_export_key().
- */
-#define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02)
-
-/** Construct a PAKE primitive from type, family and bit-size.
- *
- * \param pake_type The type of the primitive
- * (value of type ::psa_pake_primitive_type_t).
- * \param pake_family The family of the primitive
- * (the type and interpretation of this parameter depends
- * on \p type, for more information consult the
- * documentation of individual ::psa_pake_primitive_type_t
- * constants).
- * \param pake_bits The bit-size of the primitive
- * (Value of type \c size_t. The interpretation
- * of this parameter depends on \p family, for more
- * information consult the documentation of individual
- * ::psa_pake_primitive_type_t constants).
- *
- * \return The constructed primitive value of type ::psa_pake_primitive_t.
- * Return 0 if the requested primitive can't be encoded as
- * ::psa_pake_primitive_t.
- */
-#define PSA_PAKE_PRIMITIVE(pake_type, pake_family, pake_bits) \
- ((pake_bits & 0xFFFF) != pake_bits) ? 0 : \
- ((psa_pake_primitive_t) (((pake_type) << 24 | \
- (pake_family) << 16) | (pake_bits)))
-
-/** The key share being sent to or received from the peer.
- *
- * The format for both input and output at this step is the same as for public
- * keys on the group determined by the primitive (::psa_pake_primitive_t) would
- * be.
- *
- * For more information on the format, consult the documentation of
- * psa_export_public_key().
- *
- * For information regarding how the group is determined, consult the
- * documentation #PSA_PAKE_PRIMITIVE.
- */
-#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01)
-
-/** A Schnorr NIZKP public key.
- *
- * The format for both input and output at this step is the same as for public
- * keys on the group determined by the primitive (::psa_pake_primitive_t) would
- * be.
- *
- * For more information on the format, consult the documentation of
- * psa_export_public_key().
- *
- * For information regarding how the group is determined, consult the
- * documentation #PSA_PAKE_PRIMITIVE.
- */
-#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t)0x02)
-
-/** A Schnorr NIZKP proof.
- *
- * The format for both input and output at this step is the same as for private
- * keys on the group determined by the primitive (::psa_pake_primitive_t) would
- * be.
- *
- * Some public key algorithms mask the private keys and this might be reflected
- * in the export format. Even if this is the case the masking is omitted at
- * this step.
- *
- * For more information on the format, consult the documentation of
- * psa_export_key().
- *
- * For information regarding how the group is determined, consult the
- * documentation #PSA_PAKE_PRIMITIVE.
- */
-#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t)0x03)
-
-/**@}*/
#endif /* PSA_CRYPTO_VALUES_H */