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 #if !defined(MBEDTLS_CONFIG_FILE)
00036 #include "mbedtls/config.h"
00037 #else
00038 #include MBEDTLS_CONFIG_FILE
00039 #endif
00040 
00041 #include "mbedtls/ecp.h"
00042 #include "mbedtls/md.h"
00043 
00044 /**
00045  * \brief           Maximum ECDSA signature size for a given curve bit size
00046  *
00047  * \param bits      Curve size in bits
00048  * \return          Maximum signature size in bytes
00049  *
00050  * \note            This macro returns a compile-time constant if its argument
00051  *                  is one. It may evaluate its argument multiple times.
00052  */
00053 /*
00054  *     Ecdsa-Sig-Value ::= SEQUENCE {
00055  *         r       INTEGER,
00056  *         s       INTEGER
00057  *     }
00058  *
00059  * For each of r and s, the value (V) may include an extra initial "0" bit.
00060  */
00061 #define MBEDTLS_ECDSA_MAX_SIG_LEN( bits )                               \
00062     ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) +              \
00063       /*T,L of r,s*/        2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) +     \
00064       /*V of r,s*/                ( ( bits ) + 8 ) / 8 ) )
00065 
00066 /** The maximal size of an ECDSA signature in Bytes. */
00067 #define MBEDTLS_ECDSA_MAX_LEN  MBEDTLS_ECDSA_MAX_SIG_LEN( MBEDTLS_ECP_MAX_BITS )
00068 
00069 #ifdef __cplusplus
00070 extern "C" {
00071 #endif
00072 
00073 /**
00074  * \brief           The ECDSA context structure.
00075  *
00076  * \warning         Performing multiple operations concurrently on the same
00077  *                  ECDSA context is not supported; objects of this type
00078  *                  should not be shared between multiple threads.
00079  */
00080 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
00081 
00082 #if defined(MBEDTLS_ECP_RESTARTABLE)
00083 
00084 /**
00085  * \brief           Internal restart context for ecdsa_verify()
00086  *
00087  * \note            Opaque struct, defined in ecdsa.c
00088  */
00089 typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
00090 
00091 /**
00092  * \brief           Internal restart context for ecdsa_sign()
00093  *
00094  * \note            Opaque struct, defined in ecdsa.c
00095  */
00096 typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx;
00097 
00098 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00099 /**
00100  * \brief           Internal restart context for ecdsa_sign_det()
00101  *
00102  * \note            Opaque struct, defined in ecdsa.c
00103  */
00104 typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
00105 #endif
00106 
00107 /**
00108  * \brief           General context for resuming ECDSA operations
00109  */
00110 typedef struct
00111 {
00112     mbedtls_ecp_restart_ctx ecp;        /*!<  base context for ECP restart and
00113                                               shared administrative info    */
00114     mbedtls_ecdsa_restart_ver_ctx *ver ; /*!<  ecdsa_verify() sub-context    */
00115     mbedtls_ecdsa_restart_sig_ctx *sig ; /*!<  ecdsa_sign() sub-context      */
00116 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00117     mbedtls_ecdsa_restart_det_ctx *det ; /*!<  ecdsa_sign_det() sub-context  */
00118 #endif
00119 } mbedtls_ecdsa_restart_ctx;
00120 
00121 #else /* MBEDTLS_ECP_RESTARTABLE */
00122 
00123 /* Now we can declare functions that take a pointer to that */
00124 typedef void mbedtls_ecdsa_restart_ctx;
00125 
00126 #endif /* MBEDTLS_ECP_RESTARTABLE */
00127 
00128 /**
00129  * \brief          This function checks whether a given group can be used
00130  *                 for ECDSA.
00131  *
00132  * \param gid      The ECP group ID to check.
00133  *
00134  * \return         \c 1 if the group can be used, \c 0 otherwise
00135  */
00136 int mbedtls_ecdsa_can_do( mbedtls_ecp_group_id gid );
00137 
00138 /**
00139  * \brief           This function computes the ECDSA signature of a
00140  *                  previously-hashed message.
00141  *
00142  * \note            The deterministic version implemented in
00143  *                  mbedtls_ecdsa_sign_det() is usually preferred.
00144  *
00145  * \note            If the bitlength of the message hash is larger than the
00146  *                  bitlength of the group order, then the hash is truncated
00147  *                  as defined in <em>Standards for Efficient Cryptography Group
00148  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00149  *                  4.1.3, step 5.
00150  *
00151  * \see             ecp.h
00152  *
00153  * \param grp       The context for the elliptic curve to use.
00154  *                  This must be initialized and have group parameters
00155  *                  set, for example through mbedtls_ecp_group_load().
00156  * \param r         The MPI context in which to store the first part
00157  *                  the signature. This must be initialized.
00158  * \param s         The MPI context in which to store the second part
00159  *                  the signature. This must be initialized.
00160  * \param d         The private signing key. This must be initialized.
00161  * \param buf       The content to be signed. This is usually the hash of
00162  *                  the original data to be signed. This must be a readable
00163  *                  buffer of length \p blen Bytes. It may be \c NULL if
00164  *                  \p blen is zero.
00165  * \param blen      The length of \p buf in Bytes.
00166  * \param f_rng     The RNG function. This must not be \c NULL.
00167  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00168  *                  \c NULL if \p f_rng doesn't need a context parameter.
00169  *
00170  * \return          \c 0 on success.
00171  * \return          An \c MBEDTLS_ERR_ECP_XXX
00172  *                  or \c MBEDTLS_MPI_XXX error code on failure.
00173  */
00174 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
00175                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
00176                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00177 
00178 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00179 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
00180 #if defined(MBEDTLS_DEPRECATED_WARNING)
00181 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
00182 #else
00183 #define MBEDTLS_DEPRECATED
00184 #endif
00185 /**
00186  * \brief           This function computes the ECDSA signature of a
00187  *                  previously-hashed message, deterministic version.
00188  *
00189  *                  For more information, see <em>RFC-6979: Deterministic
00190  *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
00191  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
00192  *
00193  * \note            If the bitlength of the message hash is larger than the
00194  *                  bitlength of the group order, then the hash is truncated as
00195  *                  defined in <em>Standards for Efficient Cryptography Group
00196  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00197  *                  4.1.3, step 5.
00198  *
00199  * \warning         Since the output of the internal RNG is always the same for
00200  *                  the same key and message, this limits the efficiency of
00201  *                  blinding and leaks information through side channels. For
00202  *                  secure behavior use mbedtls_ecdsa_sign_det_ext() instead.
00203  *
00204  *                  (Optimally the blinding is a random value that is different
00205  *                  on every execution. In this case the blinding is still
00206  *                  random from the attackers perspective, but is the same on
00207  *                  each execution. This means that this blinding does not
00208  *                  prevent attackers from recovering secrets by combining
00209  *                  several measurement traces, but may prevent some attacks
00210  *                  that exploit relationships between secret data.)
00211  *
00212  * \see             ecp.h
00213  *
00214  * \param grp       The context for the elliptic curve to use.
00215  *                  This must be initialized and have group parameters
00216  *                  set, for example through mbedtls_ecp_group_load().
00217  * \param r         The MPI context in which to store the first part
00218  *                  the signature. This must be initialized.
00219  * \param s         The MPI context in which to store the second part
00220  *                  the signature. This must be initialized.
00221  * \param d         The private signing key. This must be initialized
00222  *                  and setup, for example through mbedtls_ecp_gen_privkey().
00223  * \param buf       The hashed content to be signed. This must be a readable
00224  *                  buffer of length \p blen Bytes. It may be \c NULL if
00225  *                  \p blen is zero.
00226  * \param blen      The length of \p buf in Bytes.
00227  * \param md_alg    The hash algorithm used to hash the original data.
00228  *
00229  * \return          \c 0 on success.
00230  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
00231  *                  error code on failure.
00232  */
00233 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r,
00234                             mbedtls_mpi *s, const mbedtls_mpi *d,
00235                             const unsigned char *buf, size_t blen,
00236                             mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
00237 #undef MBEDTLS_DEPRECATED
00238 #endif /* MBEDTLS_DEPRECATED_REMOVED */
00239 
00240 /**
00241  * \brief           This function computes the ECDSA signature of a
00242  *                  previously-hashed message, deterministic version.
00243  *
00244  *                  For more information, see <em>RFC-6979: Deterministic
00245  *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
00246  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
00247  *
00248  * \note            If the bitlength of the message hash is larger than the
00249  *                  bitlength of the group order, then the hash is truncated as
00250  *                  defined in <em>Standards for Efficient Cryptography Group
00251  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00252  *                  4.1.3, step 5.
00253  *
00254  * \see             ecp.h
00255  *
00256  * \param grp           The context for the elliptic curve to use.
00257  *                      This must be initialized and have group parameters
00258  *                      set, for example through mbedtls_ecp_group_load().
00259  * \param r             The MPI context in which to store the first part
00260  *                      the signature. This must be initialized.
00261  * \param s             The MPI context in which to store the second part
00262  *                      the signature. This must be initialized.
00263  * \param d             The private signing key. This must be initialized
00264  *                      and setup, for example through mbedtls_ecp_gen_privkey().
00265  * \param buf           The hashed content to be signed. This must be a readable
00266  *                      buffer of length \p blen Bytes. It may be \c NULL if
00267  *                      \p blen is zero.
00268  * \param blen          The length of \p buf in Bytes.
00269  * \param md_alg        The hash algorithm used to hash the original data.
00270  * \param f_rng_blind   The RNG function used for blinding. This must not be
00271  *                      \c NULL.
00272  * \param p_rng_blind   The RNG context to be passed to \p f_rng. This may be
00273  *                      \c NULL if \p f_rng doesn't need a context parameter.
00274  *
00275  * \return          \c 0 on success.
00276  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
00277  *                  error code on failure.
00278  */
00279 int mbedtls_ecdsa_sign_det_ext( mbedtls_ecp_group *grp, mbedtls_mpi *r,
00280                             mbedtls_mpi *s, const mbedtls_mpi *d,
00281                             const unsigned char *buf, size_t blen,
00282                             mbedtls_md_type_t md_alg,
00283                             int (*f_rng_blind)(void *, unsigned char *, size_t),
00284                             void *p_rng_blind );
00285 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00286 
00287 /**
00288  * \brief           This function verifies the ECDSA signature of a
00289  *                  previously-hashed message.
00290  *
00291  * \note            If the bitlength of the message hash is larger than the
00292  *                  bitlength of the group order, then the hash is truncated as
00293  *                  defined in <em>Standards for Efficient Cryptography Group
00294  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00295  *                  4.1.4, step 3.
00296  *
00297  * \see             ecp.h
00298  *
00299  * \param grp       The ECP group to use.
00300  *                  This must be initialized and have group parameters
00301  *                  set, for example through mbedtls_ecp_group_load().
00302  * \param buf       The hashed content that was signed. This must be a readable
00303  *                  buffer of length \p blen Bytes. It may be \c NULL if
00304  *                  \p blen is zero.
00305  * \param blen      The length of \p buf in Bytes.
00306  * \param Q         The public key to use for verification. This must be
00307  *                  initialized and setup.
00308  * \param r         The first integer of the signature.
00309  *                  This must be initialized.
00310  * \param s         The second integer of the signature.
00311  *                  This must be initialized.
00312  *
00313  * \return          \c 0 on success.
00314  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
00315  *                  is invalid.
00316  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
00317  *                  error code on failure for any other reason.
00318  */
00319 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
00320                           const unsigned char *buf, size_t blen,
00321                           const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
00322                           const mbedtls_mpi *s);
00323 
00324 /**
00325  * \brief           This function computes the ECDSA signature and writes it
00326  *                  to a buffer, serialized as defined in <em>RFC-4492:
00327  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
00328  *                  Transport Layer Security (TLS)</em>.
00329  *
00330  * \warning         It is not thread-safe to use the same context in
00331  *                  multiple threads.
00332  *
00333  * \note            The deterministic version is used if
00334  *                  #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
00335  *                  information, see <em>RFC-6979: Deterministic Usage
00336  *                  of the Digital Signature Algorithm (DSA) and Elliptic
00337  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
00338  *
00339  * \note            If the bitlength of the message hash is larger than the
00340  *                  bitlength of the group order, then the hash is truncated as
00341  *                  defined in <em>Standards for Efficient Cryptography Group
00342  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00343  *                  4.1.3, step 5.
00344  *
00345  * \see             ecp.h
00346  *
00347  * \param ctx       The ECDSA context to use. This must be initialized
00348  *                  and have a group and private key bound to it, for example
00349  *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
00350  * \param md_alg    The message digest that was used to hash the message.
00351  * \param hash      The message hash to be signed. This must be a readable
00352  *                  buffer of length \p blen Bytes.
00353  * \param hlen      The length of the hash \p hash in Bytes.
00354  * \param sig       The buffer to which to write the signature. This must be a
00355  *                  writable buffer of length at least twice as large as the
00356  *                  size of the curve used, plus 9. For example, 73 Bytes if
00357  *                  a 256-bit curve is used. A buffer length of
00358  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
00359  * \param slen      The address at which to store the actual length of
00360  *                  the signature written. Must not be \c NULL.
00361  * \param f_rng     The RNG function. This must not be \c NULL if
00362  *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
00363  *                  it is used only for blinding and may be set to \c NULL, but
00364  *                  doing so is DEPRECATED.
00365  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00366  *                  \c NULL if \p f_rng is \c NULL or doesn't use a context.
00367  *
00368  * \return          \c 0 on success.
00369  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
00370  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00371  */
00372 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
00373                                    mbedtls_md_type_t md_alg,
00374                            const unsigned char *hash, size_t hlen,
00375                            unsigned char *sig, size_t *slen,
00376                            int (*f_rng)(void *, unsigned char *, size_t),
00377                            void *p_rng );
00378 
00379 /**
00380  * \brief           This function computes the ECDSA signature and writes it
00381  *                  to a buffer, in a restartable way.
00382  *
00383  * \see             \c mbedtls_ecdsa_write_signature()
00384  *
00385  * \note            This function is like \c mbedtls_ecdsa_write_signature()
00386  *                  but it can return early and restart according to the limit
00387  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
00388  *
00389  * \param ctx       The ECDSA context to use. This must be initialized
00390  *                  and have a group and private key bound to it, for example
00391  *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
00392  * \param md_alg    The message digest that was used to hash the message.
00393  * \param hash      The message hash to be signed. This must be a readable
00394  *                  buffer of length \p blen Bytes.
00395  * \param hlen      The length of the hash \p hash in Bytes.
00396  * \param sig       The buffer to which to write the signature. This must be a
00397  *                  writable buffer of length at least twice as large as the
00398  *                  size of the curve used, plus 9. For example, 73 Bytes if
00399  *                  a 256-bit curve is used. A buffer length of
00400  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
00401  * \param slen      The address at which to store the actual length of
00402  *                  the signature written. Must not be \c NULL.
00403  * \param f_rng     The RNG function. This must not be \c NULL if
00404  *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
00405  *                  it is unused and may be set to \c NULL.
00406  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00407  *                  \c NULL if \p f_rng is \c NULL or doesn't use a context.
00408  * \param rs_ctx    The restart context to use. This may be \c NULL to disable
00409  *                  restarting. If it is not \c NULL, it must point to an
00410  *                  initialized restart context.
00411  *
00412  * \return          \c 0 on success.
00413  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00414  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00415  * \return          Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
00416  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00417  */
00418 int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx,
00419                            mbedtls_md_type_t md_alg,
00420                            const unsigned char *hash, size_t hlen,
00421                            unsigned char *sig, size_t *slen,
00422                            int (*f_rng)(void *, unsigned char *, size_t),
00423                            void *p_rng,
00424                            mbedtls_ecdsa_restart_ctx *rs_ctx );
00425 
00426 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00427 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
00428 #if defined(MBEDTLS_DEPRECATED_WARNING)
00429 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
00430 #else
00431 #define MBEDTLS_DEPRECATED
00432 #endif
00433 /**
00434  * \brief           This function computes an ECDSA signature and writes
00435  *                  it to a buffer, serialized as defined in <em>RFC-4492:
00436  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
00437  *                  Transport Layer Security (TLS)</em>.
00438  *
00439  *                  The deterministic version is defined in <em>RFC-6979:
00440  *                  Deterministic Usage of the Digital Signature Algorithm (DSA)
00441  *                  and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
00442  *
00443  * \warning         It is not thread-safe to use the same context in
00444  *                  multiple threads.
00445  *
00446  * \note            If the bitlength of the message hash is larger than the
00447  *                  bitlength of the group order, then the hash is truncated as
00448  *                  defined in <em>Standards for Efficient Cryptography Group
00449  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00450  *                  4.1.3, step 5.
00451  *
00452  * \see             ecp.h
00453  *
00454  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in
00455  *                  Mbed TLS version 2.0 and later.
00456  *
00457  * \param ctx       The ECDSA context to use. This must be initialized
00458  *                  and have a group and private key bound to it, for example
00459  *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
00460  * \param hash      The message hash to be signed. This must be a readable
00461  *                  buffer of length \p blen Bytes.
00462  * \param hlen      The length of the hash \p hash in Bytes.
00463  * \param sig       The buffer to which to write the signature. This must be a
00464  *                  writable buffer of length at least twice as large as the
00465  *                  size of the curve used, plus 9. For example, 73 Bytes if
00466  *                  a 256-bit curve is used. A buffer length of
00467  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
00468  * \param slen      The address at which to store the actual length of
00469  *                  the signature written. Must not be \c NULL.
00470  * \param md_alg    The message digest that was used to hash the message.
00471  *
00472  * \return          \c 0 on success.
00473  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
00474  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
00475  */
00476 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
00477                                const unsigned char *hash, size_t hlen,
00478                                unsigned char *sig, size_t *slen,
00479                                mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
00480 #undef MBEDTLS_DEPRECATED
00481 #endif /* MBEDTLS_DEPRECATED_REMOVED */
00482 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00483 
00484 /**
00485  * \brief           This function reads and verifies an ECDSA signature.
00486  *
00487  * \note            If the bitlength of the message hash is larger than the
00488  *                  bitlength of the group order, then the hash is truncated as
00489  *                  defined in <em>Standards for Efficient Cryptography Group
00490  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
00491  *                  4.1.4, step 3.
00492  *
00493  * \see             ecp.h
00494  *
00495  * \param ctx       The ECDSA context to use. This must be initialized
00496  *                  and have a group and public key bound to it.
00497  * \param hash      The message hash that was signed. This must be a readable
00498  *                  buffer of length \p size Bytes.
00499  * \param hlen      The size of the hash \p hash.
00500  * \param sig       The signature to read and verify. This must be a readable
00501  *                  buffer of length \p slen Bytes.
00502  * \param slen      The size of \p sig in Bytes.
00503  *
00504  * \return          \c 0 on success.
00505  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
00506  * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
00507  *                  signature in \p sig, but its length is less than \p siglen.
00508  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
00509  *                  error code on failure for any other reason.
00510  */
00511 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
00512                           const unsigned char *hash, size_t hlen,
00513                           const unsigned char *sig, size_t slen );
00514 
00515 /**
00516  * \brief           This function reads and verifies an ECDSA signature,
00517  *                  in a restartable way.
00518  *
00519  * \see             \c mbedtls_ecdsa_read_signature()
00520  *
00521  * \note            This function is like \c mbedtls_ecdsa_read_signature()
00522  *                  but it can return early and restart according to the limit
00523  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
00524  *
00525  * \param ctx       The ECDSA context to use. This must be initialized
00526  *                  and have a group and public key bound to it.
00527  * \param hash      The message hash that was signed. This must be a readable
00528  *                  buffer of length \p size Bytes.
00529  * \param hlen      The size of the hash \p hash.
00530  * \param sig       The signature to read and verify. This must be a readable
00531  *                  buffer of length \p slen Bytes.
00532  * \param slen      The size of \p sig in Bytes.
00533  * \param rs_ctx    The restart context to use. This may be \c NULL to disable
00534  *                  restarting. If it is not \c NULL, it must point to an
00535  *                  initialized restart context.
00536  *
00537  * \return          \c 0 on success.
00538  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
00539  * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
00540  *                  signature in \p sig, but its length is less than \p siglen.
00541  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00542  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00543  * \return          Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
00544  *                  error code on failure for any other reason.
00545  */
00546 int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
00547                           const unsigned char *hash, size_t hlen,
00548                           const unsigned char *sig, size_t slen,
00549                           mbedtls_ecdsa_restart_ctx *rs_ctx );
00550 
00551 /**
00552  * \brief          This function generates an ECDSA keypair on the given curve.
00553  *
00554  * \see            ecp.h
00555  *
00556  * \param ctx      The ECDSA context to store the keypair in.
00557  *                 This must be initialized.
00558  * \param gid      The elliptic curve to use. One of the various
00559  *                 \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
00560  * \param f_rng    The RNG function to use. This must not be \c NULL.
00561  * \param p_rng    The RNG context to be passed to \p f_rng. This may be
00562  *                 \c NULL if \p f_rng doesn't need a context argument.
00563  *
00564  * \return         \c 0 on success.
00565  * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
00566  */
00567 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
00568                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00569 
00570 /**
00571  * \brief           This function sets up an ECDSA context from an EC key pair.
00572  *
00573  * \see             ecp.h
00574  *
00575  * \param ctx       The ECDSA context to setup. This must be initialized.
00576  * \param key       The EC key to use. This must be initialized and hold
00577  *                  a private-public key pair or a public key. In the former
00578  *                  case, the ECDSA context may be used for signature creation
00579  *                  and verification after this call. In the latter case, it
00580  *                  may be used for signature verification.
00581  *
00582  * \return          \c 0 on success.
00583  * \return          An \c MBEDTLS_ERR_ECP_XXX code on failure.
00584  */
00585 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
00586                                 const mbedtls_ecp_keypair *key );
00587 
00588 /**
00589  * \brief           This function initializes an ECDSA context.
00590  *
00591  * \param ctx       The ECDSA context to initialize.
00592  *                  This must not be \c NULL.
00593  */
00594 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
00595 
00596 /**
00597  * \brief           This function frees an ECDSA context.
00598  *
00599  * \param ctx       The ECDSA context to free. This may be \c NULL,
00600  *                  in which case this function does nothing. If it
00601  *                  is not \c NULL, it must be initialized.
00602  */
00603 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
00604 
00605 #if defined(MBEDTLS_ECP_RESTARTABLE)
00606 /**
00607  * \brief           Initialize a restart context.
00608  *
00609  * \param ctx       The restart context to initialize.
00610  *                  This must not be \c NULL.
00611  */
00612 void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
00613 
00614 /**
00615  * \brief           Free the components of a restart context.
00616  *
00617  * \param ctx       The restart context to free. This may be \c NULL,
00618  *                  in which case this function does nothing. If it
00619  *                  is not \c NULL, it must be initialized.
00620  */
00621 void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
00622 #endif /* MBEDTLS_ECP_RESTARTABLE */
00623 
00624 #ifdef __cplusplus
00625 }
00626 #endif
00627 
00628 #endif /* ecdsa.h */