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

Try to clarify ECDH interface documentation

Browse Source
This commit is contained in:
Manuel Pégourié-Gonnard 2014-06-25 13:55:10 +02:00
parent 5af0e5b194
commit 2361746452
1 changed files with 28 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
include/polarssl/ecdh.h
View File

@ -47,23 +47,24 @@ typedef enum
*/ */
typedef struct typedef struct
{ {
ecp_group grp; /*!< ellipitic curve used */ ecp_group grp; /*!< ellipitic curve used */
mpi d; /*!< our secret value */ mpi d; /*!< our secret value (private key) */
ecp_point Q; /*!< our public value */ ecp_point Q; /*!< our public value (public key) */
ecp_point Qp; /*!< peer's public value */ ecp_point Qp; /*!< peer's public value (public key) */
mpi z; /*!< shared secret */ mpi z; /*!< shared secret */
int point_format; /*!< format for point export */ int point_format; /*!< format for point export in TLS messages */
ecp_point Vi; /*!< blinding value (for later) */ ecp_point Vi; /*!< blinding value (for later) */
ecp_point Vf; /*!< un-blinding value (for later) */ ecp_point Vf; /*!< un-blinding value (for later) */
mpi _d; /*!< previous d */ mpi _d; /*!< previous d (for later) */
} }
ecdh_context; ecdh_context;
/** /**
* \brief Generate a public key * \brief Generate a public key.
* Raw function that only does the core computation.
* *
* \param grp ECP group * \param grp ECP group
* \param d Destination MPI (secret exponent) * \param d Destination MPI (secret exponent, aka private key)
* \param Q Destination point (public key) * \param Q Destination point (public key)
* \param f_rng RNG function * \param f_rng RNG function
* \param p_rng RNG parameter * \param p_rng RNG parameter
@ -77,11 +78,12 @@ int ecdh_gen_public( ecp_group *grp, mpi *d, ecp_point *Q,
/** /**
* \brief Compute shared secret * \brief Compute shared secret
* Raw function that only does the core computation.
* *
* \param grp ECP group * \param grp ECP group
* \param z Destination MPI (shared secret) * \param z Destination MPI (shared secret)
* \param Q Public key from other party * \param Q Public key from other party
* \param d Our secret exponent * \param d Our secret exponent (private key)
* \param f_rng RNG function (see notes) * \param f_rng RNG function (see notes)
* \param p_rng RNG parameter * \param p_rng RNG parameter
* *
@ -112,7 +114,8 @@ void ecdh_init( ecdh_context *ctx );
void ecdh_free( ecdh_context *ctx ); void ecdh_free( ecdh_context *ctx );
/** /**
* \brief Setup and write the ServerKeyExhange parameters * \brief Generate a public key and a TLS ServerKeyExchange payload.
* (First function used by a TLS server for ECDHE.)
* *
* \param ctx ECDH context * \param ctx ECDH context
* \param olen number of chars written * \param olen number of chars written
@ -132,7 +135,8 @@ int ecdh_make_params( ecdh_context *ctx, size_t *olen,
void *p_rng ); void *p_rng );
/** /**
* \brief Parse the ServerKeyExhange parameters * \brief Parse and procress a TLS ServerKeyExhange payload.
* (First function used by a TLS client for ECDHE.)
* *
* \param ctx ECDH context * \param ctx ECDH context
* \param buf pointer to start of input buffer * \param buf pointer to start of input buffer
@ -144,7 +148,10 @@ int ecdh_read_params( ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end ); const unsigned char **buf, const unsigned char *end );
/** /**
* \brief Setup an ECDH context from an EC key * \brief Setup an ECDH context from an EC key.
* (Used by clients and servers in place of the
* ServerKeyEchange for static ECDH: import ECDH parameters
* from a certificate's EC key information.)
* *
* \param ctx ECDH constext to set * \param ctx ECDH constext to set
* \param key EC key to use * \param key EC key to use
@ -156,7 +163,8 @@ int ecdh_get_params( ecdh_context *ctx, const ecp_keypair *key,
ecdh_side side ); ecdh_side side );
/** /**
* \brief Setup and export the client's public value * \brief Generate a public key and a TLS ClientKeyExchange payload.
* (Second function used by a TLS client for ECDH(E).)
* *
* \param ctx ECDH context * \param ctx ECDH context
* \param olen number of bytes actually written * \param olen number of bytes actually written
@ -173,7 +181,8 @@ int ecdh_make_public( ecdh_context *ctx, size_t *olen,
void *p_rng ); void *p_rng );
/** /**
* \brief Parse and import the client's public value * \brief Parse and process a TLS ClientKeyExchange payload.
* (Second function used by a TLS server for ECDH(E).)
* *
* \param ctx ECDH context * \param ctx ECDH context
* \param buf start of input buffer * \param buf start of input buffer
@ -185,7 +194,8 @@ int ecdh_read_public( ecdh_context *ctx,
const unsigned char *buf, size_t blen ); const unsigned char *buf, size_t blen );
/** /**
* \brief Derive and export the shared secret * \brief Derive and export the shared secret.
* (Last function used by both TLS client en servers.)
* *
* \param ctx ECDH context * \param ctx ECDH context
* \param olen number of bytes written * \param olen number of bytes written