mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-11-22 18:35:42 +01:00
Document parameter preconditions for ECJPAKE module
This commit is contained in:
Hanno Becker
parent
af0c6cb9e0
commit
c4e5aa5746
@ -92,28 +92,34 @@ typedef struct mbedtls_ecjpake_context
|
||||
#endif /* MBEDTLS_ECJPAKE_ALT */
|
||||
|
||||
/**
|
||||
* \brief Initialize a context
|
||||
* (just makes it ready for setup() or free()).
|
||||
* \brief Initialize an ECJPAKE context.
|
||||
*
|
||||
* \param ctx context to initialize
|
||||
* \param ctx The ECJPAKE context to initialize.
|
||||
* This must not be \c NULL.
|
||||
*/
|
||||
void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
|
||||
|
||||
/**
|
||||
* \brief Set up a context for use
|
||||
* \brief Set up an ECJPAKE context for use.
|
||||
*
|
||||
* \note Currently the only values for hash/curve allowed by the
|
||||
* standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
|
||||
* standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
|
||||
*
|
||||
* \param ctx context to set up
|
||||
* \param role Our role: client or server
|
||||
* \param hash hash function to use (MBEDTLS_MD_XXX)
|
||||
* \param curve elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
|
||||
* \param secret pre-shared secret (passphrase)
|
||||
* \param len length of the shared secret
|
||||
* \param ctx The ECJPAKE context to set up. This must be initialized.
|
||||
* \param role The role of the caller. This must be either
|
||||
* #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
|
||||
* \param hash The identifier of the hash function to use,
|
||||
* for example #MBEDTLS_MD_SHA256.
|
||||
* \param curve The identifier of the Telliptic curve to use,
|
||||
* for example #MBEDTLS_ECP_SECP192k1.
|
||||
* \param secret The pre-shared secret (passphrase). This must be
|
||||
* a readable buffer of length \p len Bytes, but need
|
||||
* only be valid for the duration of this call. It may
|
||||
* be \c NULL if \p len is zero.
|
||||
* \param len The length of the pre-shared secret \p secret.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
|
||||
mbedtls_ecjpake_role role,
|
||||
@ -123,29 +129,34 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
|
||||
size_t len );
|
||||
|
||||
/**
|
||||
* \brief Check if a context is ready for use
|
||||
* \brief Check if an ECJPAKE context is ready for use.
|
||||
*
|
||||
* \param ctx Context to check
|
||||
* \param ctx The ECJPAKE context to check. This must be
|
||||
* initialized.
|
||||
*
|
||||
* \return 0 if the context is ready for use,
|
||||
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
|
||||
* \return \c 0 if the context is ready for use.
|
||||
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
|
||||
*/
|
||||
int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
|
||||
|
||||
/**
|
||||
* \brief Generate and write the first round message
|
||||
* (TLS: contents of the Client/ServerHello extension,
|
||||
* excluding extension type and length bytes)
|
||||
* excluding extension type and length bytes).
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Buffer to write the contents to
|
||||
* \param len Buffer size
|
||||
* \param olen Will be updated with the number of bytes written
|
||||
* \param f_rng RNG function
|
||||
* \param p_rng RNG parameter
|
||||
* \param ctx The ECJPAKE context to use. This must be
|
||||
* initialized and set up.
|
||||
* \param buf The buffer to write the contents to. This must be a
|
||||
* writable buffer of length \p len Bytes.
|
||||
* \param len The length of \p buf in Bytes.
|
||||
* \param olen The address at which to store the total number
|
||||
* of Bytes written to \p buf. This must not be \c NULL.
|
||||
* \param f_rng The RNG function to use. This must not be \c NULL.
|
||||
* \param p_rng The RNG parameter to be passed to \p f_rng. This
|
||||
* may be \c NULL if \p f_rng doesn't use a context.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
@ -155,14 +166,16 @@ int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
|
||||
/**
|
||||
* \brief Read and process the first round message
|
||||
* (TLS: contents of the Client/ServerHello extension,
|
||||
* excluding extension type and length bytes)
|
||||
* excluding extension type and length bytes).
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Pointer to extension contents
|
||||
* \param len Extension length
|
||||
* \param ctx The ECJPAKE context to use. This must be initialized
|
||||
* and set up.
|
||||
* \param buf The buffer holding the first round message. This must
|
||||
* be a readable buffer of length \p len Bytes.
|
||||
* \param len The length in Bytes of \p buf.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
|
||||
const unsigned char *buf,
|
||||
@ -170,17 +183,21 @@ int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
|
||||
|
||||
/**
|
||||
* \brief Generate and write the second round message
|
||||
* (TLS: contents of the Client/ServerKeyExchange)
|
||||
* (TLS: contents of the Client/ServerKeyExchange).
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Buffer to write the contents to
|
||||
* \param len Buffer size
|
||||
* \param olen Will be updated with the number of bytes written
|
||||
* \param f_rng RNG function
|
||||
* \param p_rng RNG parameter
|
||||
* \param ctx The ECJPAKE context to use. This must be initialized,
|
||||
* set up, and already have performed round one.
|
||||
* \param buf The buffer to write the round two contents to.
|
||||
* This must be a writable buffer of length \p len Bytes.
|
||||
* \param len The size of \p buf in Bytes.
|
||||
* \param olen The address at which to store the total number of Bytes
|
||||
* written to \p buf. This must not be \c NULL.
|
||||
* \param f_rng The RNG function to use. This must not be \c NULL.
|
||||
* \param p_rng The RNG parameter to be passed to \p f_rng. This
|
||||
* may be \c NULL if \p f_rng doesn't use a context.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
@ -189,14 +206,16 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
|
||||
|
||||
/**
|
||||
* \brief Read and process the second round message
|
||||
* (TLS: contents of the Client/ServerKeyExchange)
|
||||
* (TLS: contents of the Client/ServerKeyExchange).
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Pointer to the message
|
||||
* \param len Message length
|
||||
* \param ctx The ECJPAKE context to use. This must be initialized
|
||||
* and set up and have performed roudn one.
|
||||
* \param buf The buffer holding the second round message. This must
|
||||
* be a readable buffer of length \p len Bytes.
|
||||
* \param len The length in Bytes of \p buf.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
|
||||
const unsigned char *buf,
|
||||
@ -204,17 +223,21 @@ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
|
||||
|
||||
/**
|
||||
* \brief Derive the shared secret
|
||||
* (TLS: Pre-Master Secret)
|
||||
* (TLS: Pre-Master Secret).
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Buffer to write the contents to
|
||||
* \param len Buffer size
|
||||
* \param olen Will be updated with the number of bytes written
|
||||
* \param f_rng RNG function
|
||||
* \param p_rng RNG parameter
|
||||
* \param ctx The ECJPAKE context to use. This must be initialized,
|
||||
* set up and have performed both round one and two.
|
||||
* \param buf The buffer to write the derived secret to. This must
|
||||
* be a writable buffer of length \p len Bytes.
|
||||
* \param len The length of \p buf in Bytes.
|
||||
* \param olen The address at which to store the total number of Bytes
|
||||
* written to \p buf. This must not be \c NULL.
|
||||
* \param f_rng The RNG function to use. This must not be \c NULL.
|
||||
* \param p_rng The RNG parameter to be passed to \p f_rng. This
|
||||
* may be \c NULL if \p f_rng doesn't use a context.
|
||||
*
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
* \return \c 0 if successful.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
@ -222,14 +245,14 @@ int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
|
||||
void *p_rng );
|
||||
|
||||
/**
|
||||
* \brief Free a context's content
|
||||
* \brief Free an ECJPAKE context.
|
||||
*
|
||||
* \param ctx context to free
|
||||
* \param ctx The ECJPAKE context to free. This may be \c NULL,
|
||||
* in which case this function does nothing. If it is not
|
||||
* \c NULL, it must point to an initialized ECJPAKE context.
|
||||
*/
|
||||
void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
|
||||
|
||||
|
||||
|
||||
#if defined(MBEDTLS_SELF_TEST)
|
||||
|
||||
/**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user