psa_crypto_pake.h: adapt function descriptions
Signed-off-by: Przemek Stekiel <przemyslaw.stekiel@mobica.com>
This commit is contained in:
Przemek Stekiel
parent
96ae8b939d
commit
ca67483b15
1 changed files with 28 additions and 126 deletions
|
|
@ -25,73 +25,24 @@
|
|||
|
||||
/** 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().
|
||||
* \note The signature of this function is that of a PSA driver
|
||||
* pake_setup entry point. This function behaves as a pake_setup
|
||||
* entry point as defined in the PSA driver interface specification for
|
||||
* transparent drivers.
|
||||
*
|
||||
* \param[in,out] operation The operation object to set up. It must have
|
||||
* been initialized but not set up yet.
|
||||
* \param[in] cipher_suite The cipher suite to use. (A cipher suite fully
|
||||
* characterizes a PAKE algorithm and determines
|
||||
* the algorithm as well.)
|
||||
* \param[in] inputs Inputs required for PAKE operation (role, password,
|
||||
* key lifetime, cipher suite)
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* Success.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* The algorithm in \p cipher_suite is not a PAKE algorithm, or the
|
||||
* PAKE primitive in \p cipher_suite is not compatible with the
|
||||
* PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid
|
||||
* or not compatible with the PAKE algorithm and primitive.
|
||||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||||
* The algorithm in \p cipher_suite is not a supported PAKE algorithm,
|
||||
* or the PAKE primitive in \p cipher_suite is not supported or not
|
||||
* compatible with the PAKE algorithm, or the hash algorithm in
|
||||
* \p cipher_suite is not supported or not compatible with the PAKE
|
||||
* algorithm and primitive.
|
||||
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
||||
* \retval #PSA_ERROR_CORRUPTION_DETECTED
|
||||
* \retval #PSA_ERROR_BAD_STATE
|
||||
* The operation state is not valid, or
|
||||
* 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 mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation,
|
||||
const psa_crypto_driver_pake_inputs_t *inputs);
|
||||
|
|
@ -99,17 +50,10 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation,
|
|||
|
||||
/** 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().
|
||||
* \note The signature of this function is that of a PSA driver
|
||||
* pake_output entry point. This function behaves as a pake_output
|
||||
* entry point as defined in the PSA driver interface specification for
|
||||
* transparent drivers.
|
||||
*
|
||||
* \param[in,out] operation Active PAKE operation.
|
||||
* \param step The step of the algorithm for which the output is
|
||||
|
|
@ -147,8 +91,7 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation,
|
|||
* \retval #PSA_ERROR_BAD_STATE
|
||||
* The operation state is not valid (it must be active, and fully set
|
||||
* up, and this call must conform to the algorithm's requirements
|
||||
* for ordering of input and output steps), or
|
||||
* the library has not been previously initialized by psa_crypto_init().
|
||||
* for ordering of input and output steps).
|
||||
* It is implementation-dependent whether a failure to initialize
|
||||
* results in this error code.
|
||||
*/
|
||||
|
|
@ -160,17 +103,10 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation,
|
|||
|
||||
/** 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().
|
||||
* \note The signature of this function is that of a PSA driver
|
||||
* key_agreement entry point. This function behaves as a key_agreement
|
||||
* entry point as defined in the PSA driver interface specification for
|
||||
* transparent drivers.
|
||||
*
|
||||
* \param[in,out] operation Active PAKE operation.
|
||||
* \param step The step for which the input is provided.
|
||||
|
|
@ -186,7 +122,7 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation,
|
|||
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
||||
* The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* \p is not compatible with the \p operation’s algorithm, or the
|
||||
* \p step is not compatible with the \p operation’s algorithm, or the
|
||||
* \p input is not valid for the \p operation's algorithm, cipher suite
|
||||
* or \p step.
|
||||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||||
|
|
@ -202,8 +138,7 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation,
|
|||
* \retval #PSA_ERROR_BAD_STATE
|
||||
* The operation state is not valid (it must be active, and fully set
|
||||
* up, and this call must conform to the algorithm's requirements
|
||||
* for ordering of input and output steps), or
|
||||
* the library has not been previously initialized by psa_crypto_init().
|
||||
* for ordering of input and output steps).
|
||||
* It is implementation-dependent whether a failure to initialize
|
||||
* results in this error code.
|
||||
*/
|
||||
|
|
@ -214,42 +149,17 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation,
|
|||
|
||||
/** 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 it claims to be and was able to do so.
|
||||
*
|
||||
* That is, the authentication is only implicit. Since the peer is not
|
||||
* authenticated yet, no action should be taken yet that assumes that the peer
|
||||
* is who it claims to be. For example, do not access restricted files on the
|
||||
* peer's behalf until an explicit authentication has succeeded.
|
||||
*
|
||||
* 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.
|
||||
* \note The signature of this function is that of a PSA driver
|
||||
* pake_get_implicit_key entry point. This function behaves as a
|
||||
* pake_get_implicit_key entry point as defined in the PSA driver
|
||||
* interface specification for transparent drivers.
|
||||
*
|
||||
* \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.
|
||||
* \param[out] output Output buffer for implicit key
|
||||
* \param[out] output_size Size of the returned implicit key
|
||||
*
|
||||
* \retval #PSA_SUCCESS
|
||||
* Success.
|
||||
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
||||
* #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the
|
||||
* algorithm in the \p output key derivation operation.
|
||||
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||||
* Input from a PAKE is not supported by the algorithm in the \p output
|
||||
* key derivation operation.
|
||||
|
|
@ -261,8 +171,7 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation,
|
|||
* \retval #PSA_ERROR_DATA_INVALID
|
||||
* \retval #PSA_ERROR_BAD_STATE
|
||||
* The PAKE operation state is not valid (it must be active, but beyond
|
||||
* that validity is specific to the algorithm), or
|
||||
* the library has not been previously initialized by psa_crypto_init(),
|
||||
* that validity is specific to the algorithm),
|
||||
* or 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
|
||||
|
|
@ -276,16 +185,10 @@ psa_status_t mbedtls_psa_pake_get_implicit_key(
|
|||
|
||||
/** Abort a PAKE operation.
|
||||
*
|
||||
* Aborting an operation frees all associated resources except for the \c
|
||||
* operation structure itself. Once aborted, the operation object can be reused
|
||||
* for another operation by calling psa_pake_setup() again.
|
||||
*
|
||||
* This function may be called at any time after the operation
|
||||
* object has been initialized as described in #psa_pake_operation_t.
|
||||
*
|
||||
* In particular, calling psa_pake_abort() after the operation has been
|
||||
* terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key()
|
||||
* is safe and has no effect.
|
||||
* \note The signature of this function is that of a PSA driver
|
||||
* pake_abort entry point. This function behaves as a pake_abort
|
||||
* entry point as defined in the PSA driver interface specification for
|
||||
* transparent drivers.
|
||||
*
|
||||
* \param[in,out] operation The operation to abort.
|
||||
*
|
||||
|
|
@ -294,7 +197,6 @@ psa_status_t mbedtls_psa_pake_get_implicit_key(
|
|||
* \retval #PSA_ERROR_COMMUNICATION_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.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue