mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-11-22 18:25:42 +01:00
Polish API and documentation
This commit is contained in:
Manuel Pégourié-Gonnard
parent
e1927101fb
commit
f7368c983a
@ -24,20 +24,20 @@
|
||||
#define MBEDTLS_ECJPAKE_H
|
||||
|
||||
/*
|
||||
* Implementation based on Chapter 7.4 of the Thread v1.0 Specification,
|
||||
* available from the Thread Group http://threadgroup.org/
|
||||
*
|
||||
* J-PAKE is a password-authenticated key exchange that allows deriving a
|
||||
* strong shared secret from a (potentially low entropy) pre-shared
|
||||
* passphrase, with forward secrecy and mutual authentication.
|
||||
* https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
|
||||
*
|
||||
* This file implements the EC J-PAKE algorithm with payload serializations
|
||||
* suitable for use in TLS, but the result could be used outside TLS.
|
||||
* This file implements the Elliptic Curve variant of J-PAKE,
|
||||
* as defined in Chapter 7.4 of the Thread v1.0 Specification,
|
||||
* available to members of the Thread Group http://threadgroup.org/
|
||||
*
|
||||
* As the J-PAKE algorithm is inherently symmetric, so is our API.
|
||||
* Each party needs to send its first round message, in any order, to the
|
||||
* other party, then each sends its second round message, in any order.
|
||||
* The payloads are serialized in a way suitable for use in TLS, but could
|
||||
* also be use outside TLS.
|
||||
*/
|
||||
|
||||
#include "ecp.h"
|
||||
@ -84,7 +84,7 @@ typedef struct
|
||||
mbedtls_mpi s; /**< Pre-shared secret (passphrase) */
|
||||
} mbedtls_ecjpake_context;
|
||||
|
||||
/*
|
||||
/**
|
||||
* \brief Initialize a context
|
||||
* (just makes it ready for setup() or free()).
|
||||
*
|
||||
@ -92,7 +92,7 @@ typedef struct
|
||||
*/
|
||||
void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
|
||||
|
||||
/*
|
||||
/**
|
||||
* \brief Set up a context for use
|
||||
*
|
||||
* \note Currently the only values for hash/curve allowed by the
|
||||
@ -115,7 +115,7 @@ int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
|
||||
const unsigned char *secret,
|
||||
size_t len );
|
||||
|
||||
/*
|
||||
/**
|
||||
* \brief Generate and write the first round message
|
||||
* (TLS: contents of the Client/ServerHello extension,
|
||||
* excluding extension type and length bytes)
|
||||
@ -134,8 +134,9 @@ int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
/*
|
||||
* \brief Generate and write the first round message
|
||||
|
||||
/**
|
||||
* \brief Read and process the first round message
|
||||
* (TLS: contents of the Client/ServerHello extension,
|
||||
* excluding extension type and length bytes)
|
||||
*
|
||||
@ -150,9 +151,9 @@ int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
|
||||
const unsigned char *buf,
|
||||
size_t len );
|
||||
|
||||
/*
|
||||
* \brief Generate and write ClientECJPAKEParams
|
||||
* (the contents for the ClientKeyExchange)
|
||||
/**
|
||||
* \brief Generate and write the second round message
|
||||
* (TLS: contents of the Client/ServerKeyExchange)
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Buffer to write the contents to
|
||||
@ -169,9 +170,9 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
|
||||
/*
|
||||
* \brief Read and process ClientECJPAKEParams
|
||||
* (the contents for the ClientKeyExchange)
|
||||
/**
|
||||
* \brief Read and process the second round message
|
||||
* (TLS: contents of the Client/ServerKeyExchange)
|
||||
*
|
||||
* \param ctx Context to use
|
||||
* \param buf Pointer to the message
|
||||
@ -181,11 +182,12 @@ int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
|
||||
* a negative error code otherwise
|
||||
*/
|
||||
int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
|
||||
const unsigned char *buf,
|
||||
size_t len );
|
||||
const unsigned char *buf,
|
||||
size_t len );
|
||||
|
||||
/*
|
||||
* \brief Derive the Pre-Master Secret used by TLS
|
||||
/**
|
||||
* \brief Derive the shared secret
|
||||
* (TLS: Pre-Master Secret)
|
||||
*
|
||||
* \param ctx
|
||||
* \param buf Buffer to write the contents to
|
||||
@ -197,12 +199,12 @@ int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
|
||||
* \return 0 if successfull,
|
||||
* a negative error code otherwise
|
||||
*/
|
||||
int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx,
|
||||
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
|
||||
/*
|
||||
/**
|
||||
* \brief Free a context's content
|
||||
*
|
||||
* \param ctx context to free
|
||||
|
||||
@ -647,7 +647,7 @@ cleanup:
|
||||
/*
|
||||
* Derive PMS (7.4.2.7 / 7.4.2.8)
|
||||
*/
|
||||
int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx,
|
||||
int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
|
||||
unsigned char *buf, size_t len, size_t *olen,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng )
|
||||
@ -946,7 +946,7 @@ int mbedtls_ecjpake_self_test( int verbose )
|
||||
|
||||
TEST_ASSERT( mbedtls_ecjpake_read_round_two( &cli, buf, len ) == 0 );
|
||||
|
||||
TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli,
|
||||
TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli,
|
||||
pms, sizeof( pms ), &pmslen, ecjpake_lgc, NULL ) == 0 );
|
||||
|
||||
TEST_ASSERT( mbedtls_ecjpake_write_round_two( &cli,
|
||||
@ -954,7 +954,7 @@ int mbedtls_ecjpake_self_test( int verbose )
|
||||
|
||||
TEST_ASSERT( mbedtls_ecjpake_read_round_two( &srv, buf, len ) == 0 );
|
||||
|
||||
TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv,
|
||||
TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv,
|
||||
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
|
||||
|
||||
TEST_ASSERT( len == pmslen );
|
||||
@ -996,7 +996,7 @@ int mbedtls_ecjpake_self_test( int verbose )
|
||||
sizeof( ecjpake_test_cli_kx ) ) == 0 );
|
||||
|
||||
/* Server derives PMS */
|
||||
TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv,
|
||||
TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv,
|
||||
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
|
||||
|
||||
TEST_ASSERT( len == sizeof( ecjpake_test_pms ) );
|
||||
@ -1005,7 +1005,7 @@ int mbedtls_ecjpake_self_test( int verbose )
|
||||
memset( buf, 0, len ); /* Avoid interferences with next step */
|
||||
|
||||
/* Client derives PMS */
|
||||
TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli,
|
||||
TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli,
|
||||
buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
|
||||
|
||||
TEST_ASSERT( len == sizeof( ecjpake_test_pms ) );
|
||||
|
||||
Loading…
Reference in New Issue
Block a user