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

Document parameter preconditions in ECP module

Browse Source
This commit is contained in:
Hanno Becker 2018-12-14 15:07:50 +00:00
parent af0c6cb9e0
commit ebffa7995b
1 changed files with 239 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

348
include/mbedtls/ecp.h
View File

@ -497,24 +497,37 @@ void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
/** /**
* \brief This function frees the components of an ECP group. * \brief This function frees the components of an ECP group.
* \param grp The group to free. *
* \param grp The group to free. This may be \c NULL, in which
* case this function is a no-op. If it is not \c NULL,
* it must point to an initialized ECP group.
*/ */
void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
/** /**
* \brief This function frees the components of a key pair. * \brief This function frees the components of a key pair.
* \param key The key pair to free. *
* \param key The key pair to free. This may be \c NULL, in which
* case this function is a no-op. If it is not \c NULL,
* it must point to an initialized ECP key pair.
*/ */
void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
#if defined(MBEDTLS_ECP_RESTARTABLE) #if defined(MBEDTLS_ECP_RESTARTABLE)
/** /**
* \brief Initialize a restart context * \brief Initialize a restart context.
*
* \param ctx The restart context to initialize. This must
* not be \c NULL.
*/ */
void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx ); void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
/** /**
* \brief Free the components of a restart context * \brief Free the components of a restart context.
*
* \param ctx The restart context to free. This may be \c NULL, in which
* case this function is a no-op. If it is not \c NULL,
* it must point to an initialized restart context.
*/ */
void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx ); void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
#endif /* MBEDTLS_ECP_RESTARTABLE */ #endif /* MBEDTLS_ECP_RESTARTABLE */
@ -523,11 +536,12 @@ void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
* \brief This function copies the contents of point \p Q into * \brief This function copies the contents of point \p Q into
* point \p P. * point \p P.
* *
* \param P The destination point. * \param P The destination point. This must be initialized.
* \param Q The source point. * \param Q The source point. This must be initialized.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code for other kinds of failure.
*/ */
int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
@ -535,31 +549,35 @@ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
* \brief This function copies the contents of group \p src into * \brief This function copies the contents of group \p src into
* group \p dst. * group \p dst.
* *
* \param dst The destination group. * \param dst The destination group. This must be initialized.
* \param src The source group. * \param src The source group. This must be initialized.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
const mbedtls_ecp_group *src );
/** /**
* \brief This function sets a point to zero. * \brief This function sets a point to the point at infinity.
* *
* \param pt The point to set. * \param pt The point to set. This must be initialized.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
/** /**
* \brief This function checks if a point is zero. * \brief This function checks if a point is the point at infinity.
* *
* \param pt The point to test. * \param pt The point to test. This must be initialized.
* *
* \return \c 1 if the point is zero. * \return \c 1 if the point is zero.
* \return \c 0 if the point is non-zero. * \return \c 0 if the point is non-zero.
* \return A negative error code on failure.
*/ */
int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt ); int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
@ -569,8 +587,8 @@ int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
* \note This assumes that the points are normalized. Otherwise, * \note This assumes that the points are normalized. Otherwise,
* they may compare as "not equal" even if they are. * they may compare as "not equal" even if they are.
* *
* \param P The first point to compare. * \param P The first point to compare. This must be initialized.
* \param Q The second point to compare. * \param Q The second point to compare. This must be initialized.
* *
* \return \c 0 if the points are equal. * \return \c 0 if the points are equal.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
@ -582,7 +600,7 @@ int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
* \brief This function imports a non-zero point from two ASCII * \brief This function imports a non-zero point from two ASCII
* strings. * strings.
* *
* \param P The destination point. * \param P The destination point. This must be initialized.
* \param radix The numeric base of the input. * \param radix The numeric base of the input.
* \param x The first affine coordinate, as a null-terminated string. * \param x The first affine coordinate, as a null-terminated string.
* \param y The second affine coordinate, as a null-terminated string. * \param y The second affine coordinate, as a null-terminated string.
@ -597,15 +615,21 @@ int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
* \brief This function exports a point into unsigned binary data. * \brief This function exports a point into unsigned binary data.
* *
* \param grp The group to which the point should belong. * \param grp The group to which the point should belong.
* \param P The point to export. * This must be initialized and have group parameters
* \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro. * set, for example through mbedtls_ecp_group_load().
* \param olen The length of the output. * \param P The point to export. This must be initialized.
* \param buf The output buffer. * \param format The point format. This must be either
* \param buflen The length of the output buffer. * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
* \param olen The address at which to store the length of
* the output in Bytes.
* \param buf The output buffer. This must be a writable buffer
* of length \p buflen Bytes.
* \param buflen The length of the output buffer \p buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
* or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. * is too small to hold the point.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P, int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
int format, size_t *olen, int format, size_t *olen,
@ -619,18 +643,22 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_
* for that. * for that.
* *
* \param grp The group to which the point should belong. * \param grp The group to which the point should belong.
* \param P The point to import. * This must be initialized and have group parameters
* \param buf The input buffer. * set, for example through mbedtls_ecp_group_load().
* \param ilen The length of the input. * \param P The destination context to import the point to.
* This must be initialized.
* \param buf The input buffer. This must be a readable buffer
* of length \p ilen Bytes.
* \param ilen The length of the input buffer \p buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
* is not implemented. * is not implemented.
*
*/ */
int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P, int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
mbedtls_ecp_point *P,
const unsigned char *buf, size_t ilen ); const unsigned char *buf, size_t ilen );
/** /**
@ -639,7 +667,9 @@ int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_poi
* \note On function return, \p *buf is updated to point immediately * \note On function return, \p *buf is updated to point immediately
* after the ECPoint record. * after the ECPoint record.
* *
* \param grp The ECP group used. * \param grp The ECP group to use.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param pt The destination point. * \param pt The destination point.
* \param buf The address of the pointer to the start of the input buffer. * \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the buffer. * \param len The length of the buffer.
@ -649,99 +679,122 @@ int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_poi
* failure. * failure.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
*/ */
int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
mbedtls_ecp_point *pt,
const unsigned char **buf, size_t len ); const unsigned char **buf, size_t len );
/** /**
* \brief This function exports a point as a TLS ECPoint record. * \brief This function exports a point as a TLS ECPoint record
* defined in RFC 4492, Section 5.4.
* *
* \param grp The ECP group used. * \param grp The ECP group to use.
* \param pt The point format to export to. The point format is an * This must be initialized and have group parameters
* \c MBEDTLS_ECP_PF_XXX constant. * set, for example through mbedtls_ecp_group_load().
* \param format The export format. * \param pt The point to be exported. This must be initialized.
* \param olen The length of the data written. * \param format The point format to use. This must be either
* \param buf The buffer to write to. * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
* \param blen The length of the buffer. * \param olen The address at which to store the length in Bytes
* of the data written.
* \param buf The target buffer. This must be a writable buffer of
* length \p blen Bytes.
* \param blen The length of the target buffer \p buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
* #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
* is too small to hold the exported point.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt, int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,
const mbedtls_ecp_point *pt,
int format, size_t *olen, int format, size_t *olen,
unsigned char *buf, size_t blen ); unsigned char *buf, size_t blen );
/** /**
* \brief This function sets a group using standardized domain parameters. * \brief This function sets up an ECP group context
* from a standardized set of domain parameters.
* *
* \note The index should be a value of the NamedCurve enum, * \note The index should be a value of the NamedCurve enum,
* as defined in <em>RFC-4492: Elliptic Curve Cryptography * as defined in <em>RFC-4492: Elliptic Curve Cryptography
* (ECC) Cipher Suites for Transport Layer Security (TLS)</em>, * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
* usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
* *
* \param grp The destination group. * \param grp The group context to setup. This must be initialized.
* \param id The identifier of the domain parameter set to load. * \param id The identifier of the domain parameter set to load.
* *
* \return \c 0 on success, * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. * correspond to a known group.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
/** /**
* \brief This function sets a group from a TLS ECParameters record. * \brief This function sets up an ECP group context from a TLS
* ECParameters record as defined in RFC 4492, Section 5.4.
* *
* \note \p buf is updated to point right after the ECParameters * \note The read pointer \p buf is updated to point right after
* record on exit. * the ECParameters record on exit.
* *
* \param grp The destination group. * \param grp The group context to setup. This must be initialized.
* \param buf The address of the pointer to the start of the input buffer. * \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the buffer. * \param len The length of the input buffer \c *buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
* failure.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
* recognised. * recognized.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len ); int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
const unsigned char **buf, size_t len );
/** /**
* \brief This function reads a group from a TLS ECParameters record. * \brief This function extracts an elliptic curve group ID from a
* TLS ECParameters record as defined in RFC 4492, Section 5.4.
* *
* \note \p buf is updated to point right after the ECParameters * \note The read pointer \p buf is updated to point right after
* record on exit. * the ECParameters record on exit.
* *
* \param grp Output parameter to hold the group id. * \param grp The address at which to store the group id.
* This must not be \c NULL.
* \param buf The address of the pointer to the start of the input buffer. * \param buf The address of the pointer to the start of the input buffer.
* \param len The length of the buffer. * \param len The length of the input buffer \c *buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
* recognised. * recognized.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp, int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
const unsigned char **buf, size_t len ); const unsigned char **buf,
size_t len );
/** /**
* \brief This function writes the TLS ECParameters record for a group. * \brief This function exports an elliptic curve as a TLS
* ECParameters record as defined in RFC 4492, Section 5.4.
* *
* \param grp The ECP group used. * \param grp The ECP group to be exported.
* \param olen The number of Bytes written. * This must be initialized and have group parameters
* \param buf The buffer to write to. * set, for example through mbedtls_ecp_group_load().
* \param blen The length of the buffer. * \param olen The address at which to store the number of Bytes written.
* This must not be \c NULL.
* \param buf The buffer to write to. This must be a writable buffer
* of length \p blen Bytes.
* \param blen The length of the output buffer \p buf in Bytes.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
* buffer is too small to hold the exported group.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
size_t *olen,
unsigned char *buf, size_t blen ); unsigned char *buf, size_t blen );
/** /**
* \brief This function performs multiplication of a point by * \brief This function performs a scalaar multiplication of a point
* an integer: \p R = \p m * \p P. * by an integer: \p R = \p m * \p P.
* *
* It is not thread-safe to use same group in multiple threads. * It is not thread-safe to use same group in multiple threads.
* *
@ -755,17 +808,22 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
* targeting these results. We recommend always providing * targeting these results. We recommend always providing
* a non-NULL \p f_rng. The overhead is negligible. * a non-NULL \p f_rng. The overhead is negligible.
* *
* \param grp The ECP group. * \param grp The ECP group to use.
* \param R The destination point. * This must be initialized and have group parameters
* \param m The integer by which to multiply. * set, for example through mbedtls_ecp_group_load().
* \param P The point to multiply. * \param R The point in which to store the result of the calculation.
* \param f_rng The RNG function. * This must be initialized.
* \param p_rng The RNG context. * \param m The integer by which to multiply. This must be initialized.
* \param P The point to multiply. This must be initialized.
* \param f_rng The RNG function. This may be \c NULL if randomization
* of intermediate results isn't desired (discouraged).
* \param p_rng The RNG context to be passed to \p p_rng.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
* key, or \p P is not a valid public key. * key, or \p P is not a valid public key.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P, const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@ -781,12 +839,16 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* it can return early and restart according to the limit set * it can return early and restart according to the limit set
* with \c mbedtls_ecp_set_max_ops() to reduce blocking. * with \c mbedtls_ecp_set_max_ops() to reduce blocking.
* *
* \param grp The ECP group. * \param grp The ECP group to use.
* \param R The destination point. * This must be initialized and have group parameters
* \param m The integer by which to multiply. * set, for example through mbedtls_ecp_group_load().
* \param P The point to multiply. * \param R The point in which to store the result of the calculation.
* \param f_rng The RNG function. * This must be initialized.
* \param p_rng The RNG context. * \param m The integer by which to multiply. This must be initialized.
* \param P The point to multiply. This must be initialized.
* \param f_rng The RNG function. This may be \c NULL if randomization
* of intermediate results isn't desired (discouraged).
* \param p_rng The RNG context to be passed to \p p_rng.
* \param rs_ctx The restart context (NULL disables restart). * \param rs_ctx The restart context (NULL disables restart).
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -795,6 +857,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops(). * operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P, const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@ -810,18 +873,25 @@ int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* \note In contrast to mbedtls_ecp_mul(), this function does not * \note In contrast to mbedtls_ecp_mul(), this function does not
* guarantee a constant execution flow and timing. * guarantee a constant execution flow and timing.
* *
* \param grp The ECP group. * \param grp The ECP group to use.
* \param R The destination point. * This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply \p P. * \param m The integer by which to multiply \p P.
* \param P The point to multiply by \p m. * This must be initialized.
* \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q. * \param n The integer by which to multiply \p Q.
* This must be initialized.
* \param Q The point to be multiplied by \p n. * \param Q The point to be multiplied by \p n.
* This must be initialized.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
* valid private keys, or \p P or \p Q are not valid public * valid private keys, or \p P or \p Q are not valid public
* keys. * keys.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
const mbedtls_mpi *m, const mbedtls_ecp_point *P, const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@ -838,12 +908,18 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* but it can return early and restart according to the limit * but it can return early and restart according to the limit
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking. * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
* *
* \param grp The ECP group. * \param grp The ECP group to use.
* \param R The destination point. * This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param R The point in which to store the result of the calculation.
* This must be initialized.
* \param m The integer by which to multiply \p P. * \param m The integer by which to multiply \p P.
* \param P The point to multiply by \p m. * This must be initialized.
* \param P The point to multiply by \p m. This must be initialized.
* \param n The integer by which to multiply \p Q. * \param n The integer by which to multiply \p Q.
* This must be initialized.
* \param Q The point to be multiplied by \p n. * \param Q The point to be multiplied by \p n.
* This must be initialized.
* \param rs_ctx The restart context (NULL disables restart). * \param rs_ctx The restart context (NULL disables restart).
* *
* \return \c 0 on success. * \return \c 0 on success.
@ -853,6 +929,7 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
* \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
* operations was reached: see \c mbedtls_ecp_set_max_ops(). * operations was reached: see \c mbedtls_ecp_set_max_ops().
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_muladd_restartable( int mbedtls_ecp_muladd_restartable(
mbedtls_ecp_group *grp, mbedtls_ecp_point *R, mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
@ -877,38 +954,51 @@ int mbedtls_ecp_muladd_restartable(
* structures, such as ::mbedtls_ecdh_context or * structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context. * ::mbedtls_ecdsa_context.
* *
* \param grp The curve the point should lie on. * \param grp The ECP group the point should belong to.
* \param pt The point to check. * This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param pt The point to check. This must be initialized.
* *
* \return \c 0 if the point is a valid public key. * \return \c 0 if the point is a valid public key.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
* a valid public key for the given curve.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
const mbedtls_ecp_point *pt );
/** /**
* \brief This function checks that an \p mbedtls_mpi is a valid private * \brief This function checks that an \p mbedtls_mpi is a
* key for this curve. * valid private key for this curve.
* *
* \note This function uses bare components rather than an * \note This function uses bare components rather than an
* ::mbedtls_ecp_keypair structure to ease use with other * ::mbedtls_ecp_keypair structure to ease use with other
* structures, such as ::mbedtls_ecdh_context or * structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context. * ::mbedtls_ecdsa_context.
* *
* \param grp The group used. * \param grp The ECP group the private key should belong to.
* \param d The integer to check. * This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param d The integer to check. This must be initialized.
* *
* \return \c 0 if the point is a valid private key. * \return \c 0 if the point is a valid private key.
* \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
* private key for the given curve.
* \return Another negative error code on other kinds of failure.
*/ */
int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
const mbedtls_mpi *d );
/** /**
* \brief This function generates a private key. * \brief This function generates a private key.
* *
* \param grp The ECP group. * \param grp The ECP group to generate a private key for.
* \param d The destination MPI (secret part). * This must be initialized and have group parameters
* \param f_rng The RNG function. * set, for example through mbedtls_ecp_group_load().
* \param p_rng The RNG parameter. * \param d The destination MPI (secret part). This must be initialized.
* \param f_rng The RNG function. 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 need a context argument.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
@ -928,12 +1018,19 @@ int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
* structures, such as ::mbedtls_ecdh_context or * structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context. * ::mbedtls_ecdsa_context.
* *
* \param grp The ECP group. * \param grp The ECP group to generate a key pair for.
* \param G The chosen base point. * This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param G The base point to use. This must be initialized
* and belong to \p grp. It replaces the default base
* point \c grp->G used by mbedtls_ecp_gen_keypair().
* \param d The destination MPI (secret part). * \param d The destination MPI (secret part).
* This must be initialized.
* \param Q The destination point (public part). * \param Q The destination point (public part).
* \param f_rng The RNG function. * This must be initialized.
* \param p_rng The RNG context. * \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
@ -953,17 +1050,23 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
* structures, such as ::mbedtls_ecdh_context or * structures, such as ::mbedtls_ecdh_context or
* ::mbedtls_ecdsa_context. * ::mbedtls_ecdsa_context.
* *
* \param grp The ECP group. * \param grp The ECP group to generate a key pair for.
* This must be initialized and have group parameters
* set, for example through mbedtls_ecp_group_load().
* \param d The destination MPI (secret part). * \param d The destination MPI (secret part).
* This must be initialized.
* \param Q The destination point (public part). * \param Q The destination point (public part).
* \param f_rng The RNG function. * This must be initialized.
* \param p_rng The RNG context. * \param f_rng The RNG function. This must not be \c NULL.
* \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure. * on failure.
*/ */
int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,
mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng ); void *p_rng );
@ -971,16 +1074,18 @@ int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp
* \brief This function generates an ECP key. * \brief This function generates an ECP key.
* *
* \param grp_id The ECP group identifier. * \param grp_id The ECP group identifier.
* \param key The destination key. * \param key The destination key. This must be initialized.
* \param f_rng The RNG function. * \param f_rng The RNG function to use. This must not be \c NULL.
* \param p_rng The RNG context. * \param p_rng The RNG context to be passed to \p f_rng. This may
* be \c NULL if \p f_rng doesn't need a context argument.
* *
* \return \c 0 on success. * \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
* on failure. * on failure.
*/ */
int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/** /**
* \brief This function checks that the keypair objects * \brief This function checks that the keypair objects
@ -988,16 +1093,19 @@ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
* same public point, and that the private key in * same public point, and that the private key in
* \p prv is consistent with the public key. * \p prv is consistent with the public key.
* *
* \param pub The keypair structure holding the public key. * \param pub The keypair structure holding the public key. This
* If it contains a private key, that part is ignored. * must be initialized. If it contains a private key, that
* part is ignored.
* \param prv The keypair structure holding the full keypair. * \param prv The keypair structure holding the full keypair.
* This must be initialized.
* *
* \return \c 0 on success, meaning that the keys are valid and match. * \return \c 0 on success, meaning that the keys are valid and match.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
* \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
* error code on calculation failure. * error code on calculation failure.
*/ */
int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
const mbedtls_ecp_keypair *prv );
#if defined(MBEDTLS_SELF_TEST) #if defined(MBEDTLS_SELF_TEST)