git.zerfleddert.de Git - proxmark3-svn/blob - common/mbedtls/ecdsa.h

   1 /**
   2  * \file ecdsa.h
   3  *
   4  * \brief This file contains ECDSA definitions and functions.
   5  *
   6  * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
   7  * <em>Standards for Efficient Cryptography Group (SECG):
   8  * SEC1 Elliptic Curve Cryptography</em>.
   9  * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
  10  * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
  11  *
  12  */
  13 /*
  14  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  15  *  SPDX-License-Identifier: GPL-2.0
  16  *
  17  *  This program is free software; you can redistribute it and/or modify
  18  *  it under the terms of the GNU General Public License as published by
  19  *  the Free Software Foundation; either version 2 of the License, or
  20  *  (at your option) any later version.
  21  *
  22  *  This program is distributed in the hope that it will be useful,
  23  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  *  GNU General Public License for more details.
  26  *
  27  *  You should have received a copy of the GNU General Public License along
  28  *  with this program; if not, write to the Free Software Foundation, Inc.,
  29  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  30  *
  31  *  This file is part of Mbed TLS (https://tls.mbed.org)
  32  */
  33
  34 #ifndef MBEDTLS_ECDSA_H
  35 #define MBEDTLS_ECDSA_H
  36
  37 #include "ecp.h"
  38 #include "md.h"
  39
  40 /*
  41  * RFC-4492 page 20:
  42  *
  43  *     Ecdsa-Sig-Value ::= SEQUENCE {
  44  *         r       INTEGER,
  45  *         s       INTEGER
  46  *     }
  47  *
  48  * Size is at most
  49  *    1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
  50  *    twice that + 1 (tag) + 2 (len) for the sequence
  51  * (assuming ECP_MAX_BYTES is less than 126 for r and s,
  52  * and less than 124 (total len <= 255) for the sequence)
  53  */
  54 #if MBEDTLS_ECP_MAX_BYTES > 124
  55 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
  56 #endif
  57 /** The maximal size of an ECDSA signature in Bytes. */
  58 #define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
  59
  60 /**
  61  * \brief           The ECDSA context structure.
  62  */
  63 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /**
  70  * \brief           This function computes the ECDSA signature of a
  71  *                  previously-hashed message.
  72  *
  73  * \note            The deterministic version is usually preferred.
  74  *
  75  * \note            If the bitlength of the message hash is larger than the
  76  *                  bitlength of the group order, then the hash is truncated
  77  *                  as defined in <em>Standards for Efficient Cryptography Group
  78  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  79  *                  4.1.3, step 5.
  80  *
  81  * \see             ecp.h
  82  *
  83  * \param grp       The ECP group.
  84  * \param r         The first output integer.
  85  * \param s         The second output integer.
  86  * \param d         The private signing key.
  87  * \param buf       The message hash.
  88  * \param blen      The length of \p buf.
  89  * \param f_rng     The RNG function.
  90  * \param p_rng     The RNG context.
  91  *
  92  * \return          \c 0 on success.
  93  * \return          An \c MBEDTLS_ERR_ECP_XXX
  94  *                  or \c MBEDTLS_MPI_XXX error code on failure.
  95  */
  96 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  97                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  98                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  99
 100 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
 101 /**
 102  * \brief           This function computes the ECDSA signature of a
 103  *                  previously-hashed message, deterministic version.
 104  *
 105  *                  For more information, see <em>RFC-6979: Deterministic
 106  *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
 107  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
 108  *
 109  * \note            If the bitlength of the message hash is larger than the
 110  *                  bitlength of the group order, then the hash is truncated as
 111  *                  defined in <em>Standards for Efficient Cryptography Group
 112  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
 113  *                  4.1.3, step 5.
 114  *
 115  * \see             ecp.h
 116  *
 117  * \param grp       The ECP group.
 118  * \param r         The first output integer.
 119  * \param s         The second output integer.
 120  * \param d         The private signing key.
 121  * \param buf       The message hash.
 122  * \param blen      The length of \p buf.
 123  * \param md_alg    The MD algorithm used to hash the message.
 124  *
 125  * \return          \c 0 on success.
 126  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
 127  *                  error code on failure.
 128  */
 129 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
 130                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
 131                     mbedtls_md_type_t md_alg );
 132 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 133
 134 /**
 135  * \brief           This function verifies the ECDSA signature of a
 136  *                  previously-hashed message.
 137  *
 138  * \note            If the bitlength of the message hash is larger than the
 139  *                  bitlength of the group order, then the hash is truncated as
 140  *                  defined in <em>Standards for Efficient Cryptography Group
 141  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
 142  *                  4.1.4, step 3.
 143  *
 144  * \see             ecp.h
 145  *
 146  * \param grp       The ECP group.
 147  * \param buf       The message hash.
 148  * \param blen      The length of \p buf.
 149  * \param Q         The public key to use for verification.
 150  * \param r         The first integer of the signature.
 151  * \param s         The second integer of the signature.
 152  *
 153  * \return          \c 0 on success.
 154  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
 155  *                  is invalid.
 156  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
 157  *                  error code on failure for any other reason.
 158  */
 159 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
 160                   const unsigned char *buf, size_t blen,
 161                   const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
 162
 163 /**
 164  * \brief           This function computes the ECDSA signature and writes it
 165  *                  to a buffer, serialized as defined in <em>RFC-4492:
 166  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
 167  *                  Transport Layer Security (TLS)</em>.
 168  *
 169  * \warning         It is not thread-safe to use the same context in
 170  *                  multiple threads.
 171  *
 172  * \note            The deterministic version is used if
 173  *                  #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
 174  *                  information, see <em>RFC-6979: Deterministic Usage
 175  *                  of the Digital Signature Algorithm (DSA) and Elliptic
 176  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
 177  *
 178  * \note            The \p sig buffer must be at least twice as large as the
 179  *                  size of the curve used, plus 9. For example, 73 Bytes if
 180  *                  a 256-bit curve is used. A buffer length of
 181  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
 182  *
 183  * \note            If the bitlength of the message hash is larger than the
 184  *                  bitlength of the group order, then the hash is truncated as
 185  *                  defined in <em>Standards for Efficient Cryptography Group
 186  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
 187  *                  4.1.3, step 5.
 188  *
 189  * \see             ecp.h
 190  *
 191  * \param ctx       The ECDSA context.
 192  * \param md_alg    The message digest that was used to hash the message.
 193  * \param hash      The message hash.
 194  * \param hlen      The length of the hash.
 195  * \param sig       The buffer that holds the signature.
 196  * \param slen      The length of the signature written.
 197  * \param f_rng     The RNG function.
 198  * \param p_rng     The RNG context.
 199  *
 200  * \return          \c 0 on success.
 201  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
 202  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
 203  */
 204 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
 205                            const unsigned char *hash, size_t hlen,
 206                            unsigned char *sig, size_t *slen,
 207                            int (*f_rng)(void *, unsigned char *, size_t),
 208                            void *p_rng );
 209
 210 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
 211 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
 212 #if defined(MBEDTLS_DEPRECATED_WARNING)
 213 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
 214 #else
 215 #define MBEDTLS_DEPRECATED
 216 #endif
 217 /**
 218  * \brief           This function computes an ECDSA signature and writes
 219  *                  it to a buffer, serialized as defined in <em>RFC-4492:
 220  *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
 221  *                  Transport Layer Security (TLS)</em>.
 222  *
 223  *                  The deterministic version is defined in <em>RFC-6979:
 224  *                  Deterministic Usage of the Digital Signature Algorithm (DSA)
 225  *                  and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
 226  *
 227  * \warning         It is not thread-safe to use the same context in
 228  *                  multiple threads.
 229  *
 230  * \note            The \p sig buffer must be at least twice as large as the
 231  *                  size of the curve used, plus 9. For example, 73 Bytes if a
 232  *                  256-bit curve is used. A buffer length of
 233  *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
 234  *
 235  * \note            If the bitlength of the message hash is larger than the
 236  *                  bitlength of the group order, then the hash is truncated as
 237  *                  defined in <em>Standards for Efficient Cryptography Group
 238  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
 239  *                  4.1.3, step 5.
 240  *
 241  * \see             ecp.h
 242  *
 243  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in
 244  *                  Mbed TLS version 2.0 and later.
 245  *
 246  * \param ctx       The ECDSA context.
 247  * \param hash      The message hash.
 248  * \param hlen      The length of the hash.
 249  * \param sig       The buffer that holds the signature.
 250  * \param slen      The length of the signature written.
 251  * \param md_alg    The MD algorithm used to hash the message.
 252  *
 253  * \return          \c 0 on success.
 254  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
 255  *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
 256  */
 257 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
 258                                const unsigned char *hash, size_t hlen,
 259                                unsigned char *sig, size_t *slen,
 260                                mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
 261 #undef MBEDTLS_DEPRECATED
 262 #endif /* MBEDTLS_DEPRECATED_REMOVED */
 263 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 264
 265 /**
 266  * \brief           This function reads and verifies an ECDSA signature.
 267  *
 268  * \note            If the bitlength of the message hash is larger than the
 269  *                  bitlength of the group order, then the hash is truncated as
 270  *                  defined in <em>Standards for Efficient Cryptography Group
 271  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
 272  *                  4.1.4, step 3.
 273  *
 274  * \see             ecp.h
 275  *
 276  * \param ctx       The ECDSA context.
 277  * \param hash      The message hash.
 278  * \param hlen      The size of the hash.
 279  * \param sig       The signature to read and verify.
 280  * \param slen      The size of \p sig.
 281  *
 282  * \return          \c 0 on success.
 283  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
 284  * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
 285  *                  signature in \p sig, but its length is less than \p siglen.
 286  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
 287  *                  error code on failure for any other reason.
 288  */
 289 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
 290                           const unsigned char *hash, size_t hlen,
 291                           const unsigned char *sig, size_t slen );
 292
 293 /**
 294  * \brief          This function generates an ECDSA keypair on the given curve.
 295  *
 296  * \see            ecp.h
 297  *
 298  * \param ctx      The ECDSA context to store the keypair in.
 299  * \param gid      The elliptic curve to use. One of the various
 300  *                 \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
 301  * \param f_rng    The RNG function.
 302  * \param p_rng    The RNG context.
 303  *
 304  * \return         \c 0 on success.
 305  * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
 306  */
 307 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
 308                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 309
 310 /**
 311  * \brief           This function sets an ECDSA context from an EC key pair.
 312  *
 313  * \see             ecp.h
 314  *
 315  * \param ctx       The ECDSA context to set.
 316  * \param key       The EC key to use.
 317  *
 318  * \return          \c 0 on success.
 319  * \return          An \c MBEDTLS_ERR_ECP_XXX code on failure.
 320  */
 321 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
 322
 323 /**
 324  * \brief           This function initializes an ECDSA context.
 325  *
 326  * \param ctx       The ECDSA context to initialize.
 327  */
 328 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
 329
 330 /**
 331  * \brief           This function frees an ECDSA context.
 332  *
 333  * \param ctx       The ECDSA context to free.
 334  */
 335 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
 336
 337 #ifdef __cplusplus
 338 }
 339 #endif
 340
 341 #endif /* ecdsa.h */