Document parameter preconditions in ECP module
This commit is contained in:
parent
af0c6cb9e0
commit
ebffa7995b
1 changed files with 239 additions and 131 deletions
|
@ -497,24 +497,37 @@ void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
|
|||
|
||||
/**
|
||||
* \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 );
|
||||
|
||||
/**
|
||||
* \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 );
|
||||
|
||||
#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 );
|
||||
|
||||
/**
|
||||
* \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 );
|
||||
#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
|
||||
* point \p P.
|
||||
*
|
||||
* \param P The destination point.
|
||||
* \param Q The source point.
|
||||
* \param P The destination point. This must be initialized.
|
||||
* \param Q The source point. This must be initialized.
|
||||
*
|
||||
* \return \c 0 on success.
|
||||
* \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 );
|
||||
|
||||
|
@ -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
|
||||
* group \p dst.
|
||||
*
|
||||
* \param dst The destination group.
|
||||
* \param src The source group.
|
||||
* \param dst The destination group. This must be initialized.
|
||||
* \param src The source group. This must be initialized.
|
||||
*
|
||||
* \return \c 0 on success.
|
||||
* \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 #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 );
|
||||
|
||||
/**
|
||||
* \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 0 if the point is non-zero.
|
||||
* \return A negative error code on failure.
|
||||
*/
|
||||
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,
|
||||
* they may compare as "not equal" even if they are.
|
||||
*
|
||||
* \param P The first point to compare.
|
||||
* \param Q The second point to compare.
|
||||
* \param P The first point to compare. This must be initialized.
|
||||
* \param Q The second point to compare. This must be initialized.
|
||||
*
|
||||
* \return \c 0 if the points are 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
|
||||
* strings.
|
||||
*
|
||||
* \param P The destination point.
|
||||
* \param P The destination point. This must be initialized.
|
||||
* \param radix The numeric base of the input.
|
||||
* \param x The first 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.
|
||||
*
|
||||
* \param grp The group to which the point should belong.
|
||||
* \param P The point to export.
|
||||
* \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro.
|
||||
* \param olen The length of the output.
|
||||
* \param buf The output buffer.
|
||||
* \param buflen The length of the output buffer.
|
||||
* This must be initialized and have group parameters
|
||||
* set, for example through mbedtls_ecp_group_load().
|
||||
* \param P The point to export. This must be initialized.
|
||||
* \param format The point format. This must be either
|
||||
* #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 #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
|
||||
* or #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 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 format, size_t *olen,
|
||||
|
@ -619,19 +643,23 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_
|
|||
* for that.
|
||||
*
|
||||
* \param grp The group to which the point should belong.
|
||||
* \param P The point to import.
|
||||
* \param buf The input buffer.
|
||||
* \param ilen The length of the input.
|
||||
* This must be initialized and have group parameters
|
||||
* set, for example through mbedtls_ecp_group_load().
|
||||
* \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 #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_ECP_FEATURE_UNAVAILABLE if the point format
|
||||
* is not implemented.
|
||||
*
|
||||
*/
|
||||
int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
|
||||
const unsigned char *buf, size_t ilen );
|
||||
int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
|
||||
mbedtls_ecp_point *P,
|
||||
const unsigned char *buf, size_t ilen );
|
||||
|
||||
/**
|
||||
* \brief This function imports a point from a TLS ECPoint record.
|
||||
|
@ -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
|
||||
* 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 buf The address of the pointer to the start of the input 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.
|
||||
* \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,
|
||||
const unsigned char **buf, size_t len );
|
||||
int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
|
||||
mbedtls_ecp_point *pt,
|
||||
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 pt The point format to export to. The point format is an
|
||||
* \c MBEDTLS_ECP_PF_XXX constant.
|
||||
* \param format The export format.
|
||||
* \param olen The length of the data written.
|
||||
* \param buf The buffer to write to.
|
||||
* \param blen The length of the buffer.
|
||||
* \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 point to be exported. This must be initialized.
|
||||
* \param format The point format to use. This must be either
|
||||
* #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
|
||||
* \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 #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
|
||||
* #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
|
||||
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
|
||||
* \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 format, size_t *olen,
|
||||
unsigned char *buf, size_t blen );
|
||||
int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,
|
||||
const mbedtls_ecp_point *pt,
|
||||
int format, size_t *olen,
|
||||
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,
|
||||
* as defined in <em>RFC-4492: Elliptic Curve Cryptography
|
||||
* (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
|
||||
* 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.
|
||||
*
|
||||
* \return \c 0 on success,
|
||||
* \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
|
||||
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups.
|
||||
|
||||
* \return \c 0 on success.
|
||||
* \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
|
||||
* 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 );
|
||||
|
||||
/**
|
||||
* \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
|
||||
* record on exit.
|
||||
* \note The read pointer \p buf is updated to point right after
|
||||
* 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 len The length of the buffer.
|
||||
* \param len The length of the input buffer \c *buf in Bytes.
|
||||
*
|
||||
* \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_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
|
||||
* record on exit.
|
||||
* \note The read pointer \p buf is updated to point right after
|
||||
* 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 len The length of the buffer.
|
||||
* \param len The length of the input buffer \c *buf in Bytes.
|
||||
*
|
||||
* \return \c 0 on success.
|
||||
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
|
||||
* \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,
|
||||
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 olen The number of Bytes written.
|
||||
* \param buf The buffer to write to.
|
||||
* \param blen The length of the buffer.
|
||||
* \param grp The ECP group to be exported.
|
||||
* This must be initialized and have group parameters
|
||||
* set, for example through mbedtls_ecp_group_load().
|
||||
* \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 #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,
|
||||
unsigned char *buf, size_t blen );
|
||||
int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
|
||||
size_t *olen,
|
||||
unsigned char *buf, size_t blen );
|
||||
|
||||
/**
|
||||
* \brief This function performs multiplication of a point by
|
||||
* an integer: \p R = \p m * \p P.
|
||||
* \brief This function performs a scalaar multiplication of a point
|
||||
* by an integer: \p R = \p m * \p P.
|
||||
*
|
||||
* 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
|
||||
* a non-NULL \p f_rng. The overhead is negligible.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param R The destination point.
|
||||
* \param m The integer by which to multiply.
|
||||
* \param P The point to multiply.
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG context.
|
||||
* \param grp The ECP group to use.
|
||||
* 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. 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 #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
|
||||
* key, or \p P is not a valid public key.
|
||||
* \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,
|
||||
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
|
||||
* with \c mbedtls_ecp_set_max_ops() to reduce blocking.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param R The destination point.
|
||||
* \param m The integer by which to multiply.
|
||||
* \param P The point to multiply.
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG context.
|
||||
* \param grp The ECP group to use.
|
||||
* 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. 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).
|
||||
*
|
||||
* \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_ECP_IN_PROGRESS if maximum number of
|
||||
* 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,
|
||||
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
|
||||
* guarantee a constant execution flow and timing.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param R The destination point.
|
||||
* \param grp The ECP group to use.
|
||||
* 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 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.
|
||||
* This must be initialized.
|
||||
* \param Q The point to be multiplied by \p n.
|
||||
* This must be initialized.
|
||||
*
|
||||
* \return \c 0 on success.
|
||||
* \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
|
||||
* keys.
|
||||
* \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,
|
||||
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
|
||||
* set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param R The destination point.
|
||||
* \param grp The ECP group to use.
|
||||
* 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 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.
|
||||
* This must be initialized.
|
||||
* \param Q The point to be multiplied by \p n.
|
||||
* This must be initialized.
|
||||
* \param rs_ctx The restart context (NULL disables restart).
|
||||
*
|
||||
* \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_ECP_IN_PROGRESS if maximum number of
|
||||
* 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(
|
||||
mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
|
||||
|
@ -877,38 +954,51 @@ int mbedtls_ecp_muladd_restartable(
|
|||
* structures, such as ::mbedtls_ecdh_context or
|
||||
* ::mbedtls_ecdsa_context.
|
||||
*
|
||||
* \param grp The curve the point should lie on.
|
||||
* \param pt The point to check.
|
||||
* \param grp The ECP group the point should belong to.
|
||||
* 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 #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
|
||||
* key for this curve.
|
||||
* \brief This function checks that an \p mbedtls_mpi is a
|
||||
* valid private key for this curve.
|
||||
*
|
||||
* \note This function uses bare components rather than an
|
||||
* ::mbedtls_ecp_keypair structure to ease use with other
|
||||
* structures, such as ::mbedtls_ecdh_context or
|
||||
* ::mbedtls_ecdsa_context.
|
||||
*
|
||||
* \param grp The group used.
|
||||
* \param d The integer to check.
|
||||
* \param grp The ECP group the private key should belong to.
|
||||
* 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 #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.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param d The destination MPI (secret part).
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG parameter.
|
||||
* \param grp The ECP group to generate a private key for.
|
||||
* This must be initialized and have group parameters
|
||||
* set, for example through mbedtls_ecp_group_load().
|
||||
* \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 An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
|
||||
|
@ -928,22 +1018,29 @@ int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
|
|||
* structures, such as ::mbedtls_ecdh_context or
|
||||
* ::mbedtls_ecdsa_context.
|
||||
*
|
||||
* \param grp The ECP group.
|
||||
* \param G The chosen base point.
|
||||
* \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 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).
|
||||
* This must be initialized.
|
||||
* \param Q The destination point (public part).
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG context.
|
||||
* This must be initialized.
|
||||
* \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 An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
|
||||
* on failure.
|
||||
*/
|
||||
int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
|
||||
const mbedtls_ecp_point *G,
|
||||
mbedtls_mpi *d, mbedtls_ecp_point *Q,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
const mbedtls_ecp_point *G,
|
||||
mbedtls_mpi *d, mbedtls_ecp_point *Q,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
|
||||
/**
|
||||
* \brief This function generates an ECP keypair.
|
||||
|
@ -953,34 +1050,42 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
|
|||
* structures, such as ::mbedtls_ecdh_context or
|
||||
* ::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).
|
||||
* This must be initialized.
|
||||
* \param Q The destination point (public part).
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG context.
|
||||
* This must be initialized.
|
||||
* \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 An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
|
||||
* on failure.
|
||||
*/
|
||||
int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,
|
||||
mbedtls_ecp_point *Q,
|
||||
int (*f_rng)(void *, unsigned char *, size_t),
|
||||
void *p_rng );
|
||||
|
||||
/**
|
||||
* \brief This function generates an ECP key.
|
||||
*
|
||||
* \param grp_id The ECP group identifier.
|
||||
* \param key The destination key.
|
||||
* \param f_rng The RNG function.
|
||||
* \param p_rng The RNG context.
|
||||
* \param key The destination key. This must be initialized.
|
||||
* \param f_rng The RNG function to use. 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 An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
|
||||
* on failure.
|
||||
*/
|
||||
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
|
||||
|
@ -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
|
||||
* \p prv is consistent with the public key.
|
||||
*
|
||||
* \param pub The keypair structure holding the public key.
|
||||
* If it contains a private key, that part is ignored.
|
||||
* \param pub The keypair structure holding the public key. This
|
||||
* must be initialized. If it contains a private key, that
|
||||
* part is ignored.
|
||||
* \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 #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
|
||||
* 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)
|
||||
|
||||
|
|
Loading…
Reference in a new issue