sdk/include/reactos/libs/mbedtls/ecdsa.h

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