yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-24 16:15:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update ecdsa.h

Browse source 
Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*p_rng descriptions changed from "parameter" to "context".
This commit is contained in:
Rose Zadik 2018-03-27 11:30:14 +01:00 committed by GitHub
parent f65379bc40
commit 817297fcd7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 91 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

177
include/mbedtls/ecdsa.h
View file

@ -1,9 +1,10 @@
/** /**
* \file ecdsa.h * \file ecdsa.h
* *
* \brief The Elliptic Curve Digital Signature Algorithm (ECDSA). * \brief This file contains ECDSA definitions and functions.
* *
* ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG): * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
* <em>Standards for Efficient Cryptography Group (SECG):
* SEC1 Elliptic Curve Cryptography</em>. * SEC1 Elliptic Curve Cryptography</em>.
* The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
* Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>. * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
@ -69,6 +70,14 @@ extern "C" {
* *
* \note The deterministic version is usually preferred. * \note The deterministic version is usually preferred.
* *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated
* as defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
* \see ecp.h
*
* \param grp The ECP group. * \param grp The ECP group.
* \param r The first output integer. * \param r The first output integer.
* \param s The second output integer. * \param s The second output integer.
@ -76,18 +85,11 @@ extern "C" {
* \param buf The message hash. * \param buf The message hash.
* \param blen The length of \p buf. * \param blen The length of \p buf.
* \param f_rng The RNG function. * \param f_rng The RNG function.
* \param p_rng The RNG parameter. * \param p_rng The RNG context.
* *
* \note If the bitlength of the message hash is larger than the * \return \c 0 on success.
* bitlength of the group order, then the hash is truncated * \return An \c MBEDTLS_ERR_ECP_XXX
* as defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
* or \c MBEDTLS_MPI_XXX error code on failure. * or \c MBEDTLS_MPI_XXX error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen, const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@ -97,10 +99,19 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
/** /**
* \brief This function computes the ECDSA signature of a * \brief This function computes the ECDSA signature of a
* previously-hashed message, deterministic version. * previously-hashed message, deterministic version.
*
* For more information, see <em>RFC-6979: Deterministic * For more information, see <em>RFC-6979: Deterministic
* Usage of the Digital Signature Algorithm (DSA) and Elliptic * Usage of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>. * Curve Digital Signature Algorithm (ECDSA)</em>.
* *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
* \see ecp.h
*
* \param grp The ECP group. * \param grp The ECP group.
* \param r The first output integer. * \param r The first output integer.
* \param s The second output integer. * \param s The second output integer.
@ -109,17 +120,9 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
* \param blen The length of \p buf. * \param blen The length of \p buf.
* \param md_alg The MD algorithm used to hash the message. * \param md_alg The MD algorithm used to hash the message.
* *
* \note If the bitlength of the message hash is larger than the * \return \c 0 on success.
* bitlength of the group order, then the hash is truncated as * \return or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
* \return \c 0 on success,
* or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure. * error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen, const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@ -130,6 +133,14 @@ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi
* \brief This function verifies the ECDSA signature of a * \brief This function verifies the ECDSA signature of a
* previously-hashed message. * previously-hashed message.
* *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
*
* \see ecp.h
*
* \param grp The ECP group. * \param grp The ECP group.
* \param buf The message hash. * \param buf The message hash.
* \param blen The length of \p buf. * \param blen The length of \p buf.
@ -137,18 +148,10 @@ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi
* \param r The first integer of the signature. * \param r The first integer of the signature.
* \param s The second integer of the signature. * \param s The second integer of the signature.
* *
* \note If the bitlength of the message hash is larger than the * \return \c 0 on success.
* bitlength of the group order, then the hash is truncated as * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
* defined in <em>Standards for Efficient Cryptography Group * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
*
* \return \c 0 on success,
* #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
* or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure for any other reason. * error code on failure for any other reason.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen, const unsigned char *buf, size_t blen,
@ -169,15 +172,6 @@ int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
* of the Digital Signature Algorithm (DSA) and Elliptic * of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>. * Curve Digital Signature Algorithm (ECDSA)</em>.
* *
* \param ctx The ECDSA context.
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash.
* \param hlen The length of the hash.
* \param sig The buffer that holds the signature.
* \param slen The length of the signature written.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \note The \p sig buffer must be at least twice as large as the * \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if * size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of * a 256-bit curve is used. A buffer length of
@ -189,11 +183,20 @@ int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5. * 4.1.3, step 5.
* *
* \return \c 0 on success,
* or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*
* \see ecp.h * \see ecp.h
*
* \param ctx The ECDSA context.
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash.
* \param hlen The length of the hash.
* \param sig The buffer that holds the signature.
* \param slen The length of the signature written.
* \param f_rng The RNG function.
* \param p_rng The RNG context.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/ */
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
@ -209,26 +212,17 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief This function computes an ECDSA signature and writes it to a buffer, * \brief This function computes an ECDSA signature and writes
* serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography * it to a buffer, serialized as defined in <em>RFC-4492:
* (ECC) Cipher Suites for Transport Layer Security (TLS)</em>. * Elliptic Curve Cryptography (ECC) Cipher Suites for
* Transport Layer Security (TLS)</em>.
* *
* The deterministic version is defined in <em>RFC-6979: * The deterministic version is defined in <em>RFC-6979:
* Deterministic Usage of the Digital Signature Algorithm (DSA) and * Deterministic Usage of the Digital Signature Algorithm (DSA)
* Elliptic Curve Digital Signature Algorithm (ECDSA)</em>. * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
* *
* \warning It is not thread-safe to use the same context in * \warning It is not thread-safe to use the same context in
* multiple threads. * multiple threads.
*
* \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
*
* \param ctx The ECDSA context.
* \param hash The Message hash.
* \param hlen The length of the hash.
* \param sig The buffer that holds the signature.
* \param slen The length of the signature written.
* \param md_alg The MD algorithm used to hash the message.
* *
* \note The \p sig buffer must be at least twice as large as the * \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if a * size of the curve used, plus 9. For example, 73 Bytes if a
@ -241,11 +235,20 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5. * 4.1.3, step 5.
* *
* \return \c 0 on success,
* or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*
* \see ecp.h * \see ecp.h
*
* \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
*
* \param ctx The ECDSA context.
* \param hash The Message hash.
* \param hlen The length of the hash.
* \param sig The buffer that holds the signature.
* \param slen The length of the signature written.
* \param md_alg The MD algorithm used to hash the message.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/ */
int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
@ -258,26 +261,26 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
/** /**
* \brief This function reads and verifies an ECDSA signature. * \brief This function reads and verifies an ECDSA signature.
* *
* \param ctx The ECDSA context.
* \param hash The message hash.
* \param hlen The size of the hash.
* \param sig The signature to read and verify.
* \param slen The size of \p sig.
*
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3. * 4.1.4, step 3.
* *
* \return \c 0 on success,
* #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
* #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
* valid but its actual length is less than \p siglen,
* or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
* error code on failure for any other reason.
*
* \see ecp.h * \see ecp.h
*
* \param ctx The ECDSA context.
* \param hash The message hash.
* \param hlen The size of the hash.
* \param sig The signature to read and verify.
* \param slen The size of \p sig.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
* \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
* valid but its actual length is less than \p siglen.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
* error code on failure for any other reason.
*/ */
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
@ -286,16 +289,16 @@ int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
/** /**
* \brief This function generates an ECDSA keypair on the given curve. * \brief This function generates an ECDSA keypair on the given curve.
* *
* \see ecp.h
*
* \param ctx The ECDSA context to store the keypair in. * \param ctx The ECDSA context to store the keypair in.
* \param gid The elliptic curve to use. One of the various * \param gid The elliptic curve to use. One of the various
* \c MBEDTLS_ECP_DP_XXX macros depending on configuration. * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
* \param f_rng The RNG function. * \param f_rng The RNG function.
* \param p_rng The RNG parameter. * \param p_rng The RNG context.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on * \return \c 0 on success.
* failure. * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
@ -303,13 +306,13 @@ int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
/** /**
* \brief This function sets an ECDSA context from an EC key pair. * \brief This function sets an ECDSA context from an EC key pair.
* *
* \see ecp.h
*
* \param ctx The ECDSA context to set. * \param ctx The ECDSA context to set.
* \param key The EC key to use. * \param key The EC key to use.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on * \return \c 0 on success.
* failure. * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key ); int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );