yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 00:25:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

Document parameter preconditions for ECJPAKE module

Browse Source
This commit is contained in:
Hanno Becker 2018-12-14 17:09:27 +00:00
parent af0c6cb9e0
commit c4e5aa5746
1 changed files with 83 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
include/mbedtls/ecjpake.h
View File

@ -92,28 +92,34 @@ typedef struct mbedtls_ecjpake_context
#endif /* MBEDTLS_ECJPAKE_ALT */ #endif /* MBEDTLS_ECJPAKE_ALT */
/** /**
* \brief Initialize a context * \brief Initialize an ECJPAKE context.
* (just makes it ready for setup() or free()).
* *
* \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 ); 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 * \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 ctx The ECJPAKE context to set up. This must be initialized.
* \param role Our role: client or server * \param role The role of the caller. This must be either
* \param hash hash function to use (MBEDTLS_MD_XXX) * #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
* \param curve elliptic curve identifier (MBEDTLS_ECP_DP_XXX) * \param hash The identifier of the hash function to use,
* \param secret pre-shared secret (passphrase) * for example #MBEDTLS_MD_SHA256.
* \param len length of the shared secret * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
mbedtls_ecjpake_role role, mbedtls_ecjpake_role role,
@ -123,29 +129,34 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
size_t len ); 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, * \return \c 0 if the context is ready for use.
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
*/ */
int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx ); int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
/** /**
* \brief Generate and write the first round message * \brief Generate and write the first round message
* (TLS: contents of the Client/ServerHello extension, * (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 ctx The ECJPAKE context to use. This must be
* \param buf Buffer to write the contents to * initialized and set up.
* \param len Buffer size * \param buf The buffer to write the contents to. This must be a
* \param olen Will be updated with the number of bytes written * writable buffer of length \p len Bytes.
* \param f_rng RNG function * \param len The length of \p buf in Bytes.
* \param p_rng RNG parameter * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen, 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 * \brief Read and process the first round message
* (TLS: contents of the Client/ServerHello extension, * (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 ctx The ECJPAKE context to use. This must be initialized
* \param buf Pointer to extension contents * and set up.
* \param len Extension length * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
const unsigned char *buf, 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 * \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 ctx The ECJPAKE context to use. This must be initialized,
* \param buf Buffer to write the contents to * set up, and already have performed round one.
* \param len Buffer size * \param buf The buffer to write the round two contents to.
* \param olen Will be updated with the number of bytes written * This must be a writable buffer of length \p len Bytes.
* \param f_rng RNG function * \param len The size of \p buf in Bytes.
* \param p_rng RNG parameter * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen, 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 * \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 ctx The ECJPAKE context to use. This must be initialized
* \param buf Pointer to the message * and set up and have performed roudn one.
* \param len Message length * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
const unsigned char *buf, const unsigned char *buf,
@ -204,17 +223,21 @@ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
/** /**
* \brief Derive the shared secret * \brief Derive the shared secret
* (TLS: Pre-Master Secret) * (TLS: Pre-Master Secret).
* *
* \param ctx Context to use * \param ctx The ECJPAKE context to use. This must be initialized,
* \param buf Buffer to write the contents to * set up and have performed both round one and two.
* \param len Buffer size * \param buf The buffer to write the derived secret to. This must
* \param olen Will be updated with the number of bytes written * be a writable buffer of length \p len Bytes.
* \param f_rng RNG function * \param len The length of \p buf in Bytes.
* \param p_rng RNG parameter * \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, * \return \c 0 if successful.
* a negative error code otherwise * \return A negative error code on failure.
*/ */
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx, int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
unsigned char *buf, size_t len, size_t *olen, 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 ); 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 ); void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
#if defined(MBEDTLS_SELF_TEST) #if defined(MBEDTLS_SELF_TEST)
/** /**