ecdsa.h

00001 /**
00002  * \file ecdsa.h
00003  *
00004  * \brief This file contains ECDSA definitions and functions.
00005  *
00006  * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
00007  * <em>Standards for Efficient Cryptography Group (SECG):
00008  * SEC1 Elliptic Curve Cryptography</em>.
00009  * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
00010  * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
00011  *
00012  */
00013 /*
00014  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00015  *  SPDX-License-Identifier: Apache-2.0
00016  *
00017  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00018  *  not use this file except in compliance with the License.
00019  *  You may obtain a copy of the License at
00020  *
00021  *  http://www.apache.org/licenses/LICENSE-2.0
00022  *
00023  *  Unless required by applicable law or agreed to in writing, software
00024  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00025  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00026  *  See the License for the specific language governing permissions and
00027  *  limitations under the License.
00028  *
00029  *  This file is part of Mbed TLS (https://tls.mbed.org)
00030  */
00031 
00032 #ifndef MBEDTLS_ECDSA_H
00033 #define MBEDTLS_ECDSA_H
00034 
00035 #include "ecp.h"
00036 #include "md.h"
00037 
00038 /*
00039  * RFC-4492 page 20:
00040  *
00041  *     Ecdsa-Sig-Value ::= SEQUENCE {
00042  *         r       INTEGER,
00043  *         s       INTEGER
00044  *     }
00045  *
00046  * Size is at most
00047  *    1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
00048  *    twice that + 1 (tag) + 2 (len) for the sequence
00049  * (assuming ECP_MAX_BYTES is less than 126 for r and s,
00050  * and less than 124 (total len <= 255) for the sequence)
00051  */
00052 #if MBEDTLS_ECP_MAX_BYTES > 124
00053 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
00054 #endif
00055 /** The maximal size of an ECDSA signature in Bytes. */
00056 #define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
00057 
00058 /**
00059  * \brief           The ECDSA context structure.
00060  */
00061 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
00062 
00063 #ifdef __cplusplus
00064 extern "C" {
00065 #endif
00066 
00067 /**
00068  * \brief           This function computes the ECDSA signature of a
00069  *                  previously-hashed message.
00070  *
00071  * \note            The deterministic version is usually preferred.
00072  *
00073  * \note            If the bitlength of the message hash is larger than the
00074  *                  bitlength of the group order, then the hash is truncated
00075  *                  as defined in <em>Standards for Efficient Cryptography Group
00076  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00077  *                  4.1.3, step 5.
00078  *
00079  * \see             ecp.h
00080  *
00081  * \param grp       The ECP group.
00082  * \param r         The first output integer.
00083  * \param s         The second output integer.
00084  * \param d         The private signing key.
00085  * \param buf       The message hash.
00086  * \param blen      The length of \p buf.
00087  * \param f_rng     The RNG function.
00088  * \param p_rng     The RNG context.
00089  *
00090  * \return          \c 0 on success.
00091  * \return          An \c MBEDTLS_ERR_ECP_XXX
00092  *                  or \c MBEDTLS_MPI_XXX error code on failure.
00093  */
00094 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
00095                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
00096                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00097 
00098 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00099 /**
00100  * \brief           This function computes the ECDSA signature of a
00101  *                  previously-hashed message, deterministic version.
00102  *
00103  *                  For more information, see <em>RFC-6979: Deterministic
00104  *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
00105  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
00106  *
00107  * \note            If the bitlength of the message hash is larger than the
00108  *                  bitlength of the group order, then the hash is truncated as
00109  *                  defined in <em>Standards for Efficient Cryptography Group
00110  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00111  *                  4.1.3, step 5.
00112  *
00113  * \see             ecp.h
00114  *
00115  * \param grp       The ECP group.
00116  * \param r         The first output integer.
00117  * \param s         The second output integer.
00118  * \param d         The private signing key.
00119  * \param buf       The message hash.
00120  * \param blen      The length of \p buf.
00121  * \param md_alg    The MD algorithm used to hash the message.
00122  *
00123  * \return          \c 0 on success.
00124  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
00125  *                  error code on failure.
00126  */
00127 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
00128                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
00129                     mbedtls_md_type_t md_alg );
00130 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00131 
00132 /**
00133  * \brief           This function verifies the ECDSA signature of a
00134  *                  previously-hashed message.
00135  *
00136  * \note            If the bitlength of the message hash is larger than the
00137  *                  bitlength of the group order, then the hash is truncated as
00138  *                  defined in <em>Standards for Efficient Cryptography Group
00139  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00140  *                  4.1.4, step 3.
00141  *
00142  * \see             ecp.h
00143  *
00144  * \param grp       The ECP group.
00145  * \param buf       The message hash.
00146  * \param blen      The length of \p buf.
00147  * \param Q         The public key to use for verification.
00148  * \param r         The first integer of the signature.
00149  * \param s         The second integer of the signature.
00150  *
00151  * \return          \c 0 on success.
00152  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
00153  *                  is invalid.
00154  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
00155  *                  error code on failure for any other reason.
00156  */
00157 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
00158                   const unsigned char *buf, size_t blen,
00159                   const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
00160 
00161 /**
00162  * \brief           This function computes the ECDSA signature and writes it
00163  *                  to a buffer, serialized as defined in <em>RFC-4492:
00164  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
00165  *                  Transport Layer Security (TLS)</em>.
00166  *
00167  * \warning         It is not thread-safe to use the same context in
00168  *                  multiple threads.
00169  *
00170  * \note            The deterministic version is used if
00171  *                  #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
00172  *                  information, see <em>RFC-6979: Deterministic Usage
00173  *                  of the Digital Signature Algorithm (DSA) and Elliptic
00174  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
00175  *
00176  * \note            The \p sig buffer must be at least twice as large as the
00177  *                  size of the curve used, plus 9. For example, 73 Bytes if
00178  *                  a 256-bit curve is used. A buffer length of
00179  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
00180  *
00181  * \note            If the bitlength of the message hash is larger than the
00182  *                  bitlength of the group order, then the hash is truncated as
00183  *                  defined in <em>Standards for Efficient Cryptography Group
00184  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00185  *                  4.1.3, step 5.
00186  *
00187  * \see             ecp.h
00188  *
00189  * \param ctx       The ECDSA context.
00190  * \param md_alg    The message digest that was used to hash the message.
00191  * \param hash      The message hash.
00192  * \param hlen      The length of the hash.
00193  * \param sig       The buffer that holds the signature.
00194  * \param slen      The length of the signature written.
00195  * \param f_rng     The RNG function.
00196  * \param p_rng     The RNG context.
00197  *
00198  * \return          \c 0 on success.
00199  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
00200  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00201  */
00202 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
00203                            const unsigned char *hash, size_t hlen,
00204                            unsigned char *sig, size_t *slen,
00205                            int (*f_rng)(void *, unsigned char *, size_t),
00206                            void *p_rng );
00207 
00208 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00209 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
00210 #if defined(MBEDTLS_DEPRECATED_WARNING)
00211 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
00212 #else
00213 #define MBEDTLS_DEPRECATED
00214 #endif
00215 /**
00216  * \brief           This function computes an ECDSA signature and writes
00217  *                  it to a buffer, serialized as defined in <em>RFC-4492:
00218  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
00219  *                  Transport Layer Security (TLS)</em>.
00220  *
00221  *                  The deterministic version is defined in <em>RFC-6979:
00222  *                  Deterministic Usage of the Digital Signature Algorithm (DSA)
00223  *                  and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
00224  *
00225  * \warning         It is not thread-safe to use the same context in
00226  *                  multiple threads.
00227  *
00228  * \note            The \p sig buffer must be at least twice as large as the
00229  *                  size of the curve used, plus 9. For example, 73 Bytes if a
00230  *                  256-bit curve is used. A buffer length of
00231  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
00232  *
00233  * \note            If the bitlength of the message hash is larger than the
00234  *                  bitlength of the group order, then the hash is truncated as
00235  *                  defined in <em>Standards for Efficient Cryptography Group
00236  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00237  *                  4.1.3, step 5.
00238  *
00239  * \see             ecp.h
00240  *
00241  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in
00242  *                  Mbed TLS version 2.0 and later.
00243  *
00244  * \param ctx       The ECDSA context.
00245  * \param hash      The message hash.
00246  * \param hlen      The length of the hash.
00247  * \param sig       The buffer that holds the signature.
00248  * \param slen      The length of the signature written.
00249  * \param md_alg    The MD algorithm used to hash the message.
00250  *
00251  * \return          \c 0 on success.
00252  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
00253  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00254  */
00255 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
00256                                const unsigned char *hash, size_t hlen,
00257                                unsigned char *sig, size_t *slen,
00258                                mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
00259 #undef MBEDTLS_DEPRECATED
00260 #endif /* MBEDTLS_DEPRECATED_REMOVED */
00261 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00262 
00263 /**
00264  * \brief           This function reads and verifies an ECDSA signature.
00265  *
00266  * \note            If the bitlength of the message hash is larger than the
00267  *                  bitlength of the group order, then the hash is truncated as
00268  *                  defined in <em>Standards for Efficient Cryptography Group
00269  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00270  *                  4.1.4, step 3.
00271  *
00272  * \see             ecp.h
00273  *
00274  * \param ctx       The ECDSA context.
00275  * \param hash      The message hash.
00276  * \param hlen      The size of the hash.
00277  * \param sig       The signature to read and verify.
00278  * \param slen      The size of \p sig.
00279  *
00280  * \return          \c 0 on success.
00281  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
00282  * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
00283  *                  signature in \p sig, but its length is less than \p siglen.
00284  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
00285  *                  error code on failure for any other reason.
00286  */
00287 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
00288                           const unsigned char *hash, size_t hlen,
00289                           const unsigned char *sig, size_t slen );
00290 
00291 /**
00292  * \brief          This function generates an ECDSA keypair on the given curve.
00293  *
00294  * \see            ecp.h
00295  *
00296  * \param ctx      The ECDSA context to store the keypair in.
00297  * \param gid      The elliptic curve to use. One of the various
00298  *                 \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
00299  * \param f_rng    The RNG function.
00300  * \param p_rng    The RNG context.
00301  *
00302  * \return         \c 0 on success.
00303  * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
00304  */
00305 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
00306                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00307 
00308 /**
00309  * \brief           This function sets an ECDSA context from an EC key pair.
00310  *
00311  * \see             ecp.h
00312  *
00313  * \param ctx       The ECDSA context to set.
00314  * \param key       The EC key to use.
00315  *
00316  * \return          \c 0 on success.
00317  * \return          An \c MBEDTLS_ERR_ECP_XXX code on failure.
00318  */
00319 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
00320 
00321 /**
00322  * \brief           This function initializes an ECDSA context.
00323  *
00324  * \param ctx       The ECDSA context to initialize.
00325  */
00326 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
00327 
00328 /**
00329  * \brief           This function frees an ECDSA context.
00330  *
00331  * \param ctx       The ECDSA context to free.
00332  */
00333 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
00334 
00335 #ifdef __cplusplus
00336 }
00337 #endif
00338 
00339 #endif /* ecdsa.h */