extlibs/mbedtls/mbedtls/include/mbedtls/ecdsa.h

   1 /**
   2  * \file ecdsa.h
   3  *
   4  * \brief Elliptic curve DSA
   5  *
   6  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
   7  *  SPDX-License-Identifier: Apache-2.0
   8  *
   9  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  10  *  not use this file except in compliance with the License.
  11  *  You may obtain a copy of the License at
  12  *
  13  *  http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  *  Unless required by applicable law or agreed to in writing, software
  16  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  17  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  *  See the License for the specific language governing permissions and
  19  *  limitations under the License.
  20  *
  21  *  This file is part of mbed TLS (https://tls.mbed.org)
  22  */
  23 #ifndef MBEDTLS_ECDSA_H
  24 #define MBEDTLS_ECDSA_H
  25
  26 #include "ecp.h"
  27 #include "md.h"
  28
  29 /*
  30  * RFC 4492 page 20:
  31  *
  32  *     Ecdsa-Sig-Value ::= SEQUENCE {
  33  *         r       INTEGER,
  34  *         s       INTEGER
  35  *     }
  36  *
  37  * Size is at most
  38  *    1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
  39  *    twice that + 1 (tag) + 2 (len) for the sequence
  40  * (assuming ECP_MAX_BYTES is less than 126 for r and s,
  41  * and less than 124 (total len <= 255) for the sequence)
  42  */
  43 #if MBEDTLS_ECP_MAX_BYTES > 124
  44 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
  45 #endif
  46 /** Maximum size of an ECDSA signature in bytes */
  47 #define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
  48
  49 /**
  50  * \brief           ECDSA context structure
  51  */
  52 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57
  58 /**
  59  * \brief           Compute ECDSA signature of a previously hashed message
  60  *
  61  * \note            The deterministic version is usually prefered.
  62  *
  63  * \param grp       ECP group
  64  * \param r         First output integer
  65  * \param s         Second output integer
  66  * \param d         Private signing key
  67  * \param buf       Message hash
  68  * \param blen      Length of buf
  69  * \param f_rng     RNG function
  70  * \param p_rng     RNG parameter
  71  *
  72  * \return          0 if successful,
  73  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  74  */
  75 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  76                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  77                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  78
  79 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
  80 /**
  81  * \brief           Compute ECDSA signature of a previously hashed message,
  82  *                  deterministic version (RFC 6979).
  83  *
  84  * \param grp       ECP group
  85  * \param r         First output integer
  86  * \param s         Second output integer
  87  * \param d         Private signing key
  88  * \param buf       Message hash
  89  * \param blen      Length of buf
  90  * \param md_alg    MD algorithm used to hash the message
  91  *
  92  * \return          0 if successful,
  93  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  94  */
  95 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  96                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  97                     mbedtls_md_type_t md_alg );
  98 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
  99
 100 /**
 101  * \brief           Verify ECDSA signature of a previously hashed message
 102  *
 103  * \param grp       ECP group
 104  * \param buf       Message hash
 105  * \param blen      Length of buf
 106  * \param Q         Public key to use for verification
 107  * \param r         First integer of the signature
 108  * \param s         Second integer of the signature
 109  *
 110  * \return          0 if successful,
 111  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
 112  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
 113  */
 114 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
 115                   const unsigned char *buf, size_t blen,
 116                   const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
 117
 118 /**
 119  * \brief           Compute ECDSA signature and write it to buffer,
 120  *                  serialized as defined in RFC 4492 page 20.
 121  *                  (Not thread-safe to use same context in multiple threads)
 122  *
 123  * \note            The deterministice version (RFC 6979) is used if
 124  *                  MBEDTLS_ECDSA_DETERMINISTIC is defined.
 125  *
 126  * \param ctx       ECDSA context
 127  * \param md_alg    Algorithm that was used to hash the message
 128  * \param hash      Message hash
 129  * \param hlen      Length of hash
 130  * \param sig       Buffer that will hold the signature
 131  * \param slen      Length of the signature written
 132  * \param f_rng     RNG function
 133  * \param p_rng     RNG parameter
 134  *
 135  * \note            The "sig" buffer must be at least as large as twice the
 136  *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
 137  *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
 138  *
 139  * \return          0 if successful,
 140  *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
 141  *                  MBEDTLS_ERR_ASN1_XXX error code
 142  */
 143 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
 144                            const unsigned char *hash, size_t hlen,
 145                            unsigned char *sig, size_t *slen,
 146                            int (*f_rng)(void *, unsigned char *, size_t),
 147                            void *p_rng );
 148
 149 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
 150 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
 151 #if defined(MBEDTLS_DEPRECATED_WARNING)
 152 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
 153 #else
 154 #define MBEDTLS_DEPRECATED
 155 #endif
 156 /**
 157  * \brief           Compute ECDSA signature and write it to buffer,
 158  *                  serialized as defined in RFC 4492 page 20.
 159  *                  Deterministic version, RFC 6979.
 160  *                  (Not thread-safe to use same context in multiple threads)
 161  *
 162  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
 163  *
 164  * \param ctx       ECDSA context
 165  * \param hash      Message hash
 166  * \param hlen      Length of hash
 167  * \param sig       Buffer that will hold the signature
 168  * \param slen      Length of the signature written
 169  * \param md_alg    MD algorithm used to hash the message
 170  *
 171  * \note            The "sig" buffer must be at least as large as twice the
 172  *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
 173  *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
 174  *
 175  * \return          0 if successful,
 176  *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
 177  *                  MBEDTLS_ERR_ASN1_XXX error code
 178  */
 179 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
 180                                const unsigned char *hash, size_t hlen,
 181                                unsigned char *sig, size_t *slen,
 182                                mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
 183 #undef MBEDTLS_DEPRECATED
 184 #endif /* MBEDTLS_DEPRECATED_REMOVED */
 185 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 186
 187 /**
 188  * \brief           Read and verify an ECDSA signature
 189  *
 190  * \param ctx       ECDSA context
 191  * \param hash      Message hash
 192  * \param hlen      Size of hash
 193  * \param sig       Signature to read and verify
 194  * \param slen      Size of sig
 195  *
 196  * \return          0 if successful,
 197  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
 198  *                  MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
 199  *                  valid but its actual length is less than siglen,
 200  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
 201  */
 202 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
 203                           const unsigned char *hash, size_t hlen,
 204                           const unsigned char *sig, size_t slen );
 205
 206 /**
 207  * \brief           Generate an ECDSA keypair on the given curve
 208  *
 209  * \param ctx       ECDSA context in which the keypair should be stored
 210  * \param gid       Group (elliptic curve) to use. One of the various
 211  *                  MBEDTLS_ECP_DP_XXX macros depending on configuration.
 212  * \param f_rng     RNG function
 213  * \param p_rng     RNG parameter
 214  *
 215  * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
 216  */
 217 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
 218                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 219
 220 /**
 221  * \brief           Set an ECDSA context from an EC key pair
 222  *
 223  * \param ctx       ECDSA context to set
 224  * \param key       EC key to use
 225  *
 226  * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
 227  */
 228 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
 229
 230 /**
 231  * \brief           Initialize context
 232  *
 233  * \param ctx       Context to initialize
 234  */
 235 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
 236
 237 /**
 238  * \brief           Free context
 239  *
 240  * \param ctx       Context to free
 241  */
 242 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
 243
 244 #ifdef __cplusplus
 245 }
 246 #endif
 247
 248 #endif /* ecdsa.h */