ecdsa.h

00001 /**
00002  * \file ecdsa.h
00003  *
00004  * \brief Elliptic curve DSA
00005  *
00006  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  *
00021  *  This file is part of mbed TLS (https://tls.mbed.org)
00022  */
00023 #ifndef MBEDTLS_ECDSA_H
00024 #define MBEDTLS_ECDSA_H
00025 
00026 #include "ecp.h"
00027 #include "md.h"
00028 
00029 /*
00030  * RFC 4492 page 20:
00031  *
00032  *     Ecdsa-Sig-Value ::= SEQUENCE {
00033  *         r       INTEGER,
00034  *         s       INTEGER
00035  *     }
00036  *
00037  * Size is at most
00038  *    1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
00039  *    twice that + 1 (tag) + 2 (len) for the sequence
00040  * (assuming ECP_MAX_BYTES is less than 126 for r and s,
00041  * and less than 124 (total len <= 255) for the sequence)
00042  */
00043 #if MBEDTLS_ECP_MAX_BYTES > 124
00044 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
00045 #endif
00046 /** Maximum size of an ECDSA signature in bytes */
00047 #define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
00048 
00049 /**
00050  * \brief           ECDSA context structure
00051  */
00052 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
00053 
00054 #ifdef __cplusplus
00055 extern "C" {
00056 #endif
00057 
00058 /**
00059  * \brief           Compute ECDSA signature of a previously hashed message
00060  *
00061  * \note            The deterministic version is usually prefered.
00062  *
00063  * \param grp       ECP group
00064  * \param r         First output integer
00065  * \param s         Second output integer
00066  * \param d         Private signing key
00067  * \param buf       Message hash
00068  * \param blen      Length of buf
00069  * \param f_rng     RNG function
00070  * \param p_rng     RNG parameter
00071  *
00072  * \note            If the bitlength of the message hash is larger than the
00073  *                  bitlength of the group order, then the hash is truncated as
00074  *                  prescribed by SEC1 4.1.3 step 5.
00075  *
00076  * \return          0 if successful,
00077  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
00078  */
00079 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
00080                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
00081                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00082 
00083 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00084 /**
00085  * \brief           Compute ECDSA signature of a previously hashed message,
00086  *                  deterministic version (RFC 6979).
00087  *
00088  * \param grp       ECP group
00089  * \param r         First output integer
00090  * \param s         Second output integer
00091  * \param d         Private signing key
00092  * \param buf       Message hash
00093  * \param blen      Length of buf
00094  * \param md_alg    MD algorithm used to hash the message
00095  *
00096  * \note            If the bitlength of the message hash is larger than the
00097  *                  bitlength of the group order, then the hash is truncated as
00098  *                  prescribed by SEC1 4.1.3 step 5.
00099  *
00100  * \return          0 if successful,
00101  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
00102  */
00103 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
00104                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
00105                     mbedtls_md_type_t md_alg );
00106 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00107 
00108 /**
00109  * \brief           Verify ECDSA signature of a previously hashed message
00110  *
00111  * \param grp       ECP group
00112  * \param buf       Message hash
00113  * \param blen      Length of buf
00114  * \param Q         Public key to use for verification
00115  * \param r         First integer of the signature
00116  * \param s         Second integer of the signature
00117  *
00118  * \note            If the bitlength of the message hash is larger than the
00119  *                  bitlength of the group order, then the hash is truncated as
00120  *                  prescribed by SEC1 4.1.4 step 3.
00121  *
00122  * \return          0 if successful,
00123  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
00124  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
00125  */
00126 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
00127                   const unsigned char *buf, size_t blen,
00128                   const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
00129 
00130 /**
00131  * \brief           Compute ECDSA signature and write it to buffer,
00132  *                  serialized as defined in RFC 4492 page 20.
00133  *                  (Not thread-safe to use same context in multiple threads)
00134  *
00135  * \note            The deterministic version (RFC 6979) is used if
00136  *                  MBEDTLS_ECDSA_DETERMINISTIC is defined.
00137  *
00138  * \param ctx       ECDSA context
00139  * \param md_alg    Algorithm that was used to hash the message
00140  * \param hash      Message hash
00141  * \param hlen      Length of hash
00142  * \param sig       Buffer that will hold the signature
00143  * \param slen      Length of the signature written
00144  * \param f_rng     RNG function
00145  * \param p_rng     RNG parameter
00146  *
00147  * \note            The "sig" buffer must be at least as large as twice the
00148  *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
00149  *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
00150  *
00151  * \note            If the bitlength of the message hash is larger than the
00152  *                  bitlength of the group order, then the hash is truncated as
00153  *                  prescribed by SEC1 4.1.3 step 5.
00154  *
00155  * \return          0 if successful,
00156  *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
00157  *                  MBEDTLS_ERR_ASN1_XXX error code
00158  */
00159 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
00160                            const unsigned char *hash, size_t hlen,
00161                            unsigned char *sig, size_t *slen,
00162                            int (*f_rng)(void *, unsigned char *, size_t),
00163                            void *p_rng );
00164 
00165 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
00166 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
00167 #if defined(MBEDTLS_DEPRECATED_WARNING)
00168 #define MBEDTLS_DEPRECATED    __attribute__((deprecated))
00169 #else
00170 #define MBEDTLS_DEPRECATED
00171 #endif
00172 /**
00173  * \brief           Compute ECDSA signature and write it to buffer,
00174  *                  serialized as defined in RFC 4492 page 20.
00175  *                  Deterministic version, RFC 6979.
00176  *                  (Not thread-safe to use same context in multiple threads)
00177  *
00178  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
00179  *
00180  * \param ctx       ECDSA context
00181  * \param hash      Message hash
00182  * \param hlen      Length of hash
00183  * \param sig       Buffer that will hold the signature
00184  * \param slen      Length of the signature written
00185  * \param md_alg    MD algorithm used to hash the message
00186  *
00187  * \note            The "sig" buffer must be at least as large as twice the
00188  *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
00189  *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
00190  *
00191  * \note            If the bitlength of the message hash is larger than the
00192  *                  bitlength of the group order, then the hash is truncated as
00193  *                  prescribed by SEC1 4.1.3 step 5.
00194  *
00195  * \return          0 if successful,
00196  *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
00197  *                  MBEDTLS_ERR_ASN1_XXX error code
00198  */
00199 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
00200                                const unsigned char *hash, size_t hlen,
00201                                unsigned char *sig, size_t *slen,
00202                                mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
00203 #undef MBEDTLS_DEPRECATED
00204 #endif /* MBEDTLS_DEPRECATED_REMOVED */
00205 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
00206 
00207 /**
00208  * \brief           Read and verify an ECDSA signature
00209  *
00210  * \param ctx       ECDSA context
00211  * \param hash      Message hash
00212  * \param hlen      Size of hash
00213  * \param sig       Signature to read and verify
00214  * \param slen      Size of sig
00215  *
00216  * \note            If the bitlength of the message hash is larger than the
00217  *                  bitlength of the group order, then the hash is truncated as
00218  *                  prescribed by SEC1 4.1.4 step 3.
00219  *
00220  * \return          0 if successful,
00221  *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
00222  *                  MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
00223  *                  valid but its actual length is less than siglen,
00224  *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
00225  */
00226 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
00227                           const unsigned char *hash, size_t hlen,
00228                           const unsigned char *sig, size_t slen );
00229 
00230 /**
00231  * \brief           Generate an ECDSA keypair on the given curve
00232  *
00233  * \param ctx       ECDSA context in which the keypair should be stored
00234  * \param gid       Group (elliptic curve) to use. One of the various
00235  *                  MBEDTLS_ECP_DP_XXX macros depending on configuration.
00236  * \param f_rng     RNG function
00237  * \param p_rng     RNG parameter
00238  *
00239  * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
00240  */
00241 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
00242                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00243 
00244 /**
00245  * \brief           Set an ECDSA context from an EC key pair
00246  *
00247  * \param ctx       ECDSA context to set
00248  * \param key       EC key to use
00249  *
00250  * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
00251  */
00252 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
00253 
00254 /**
00255  * \brief           Initialize context
00256  *
00257  * \param ctx       Context to initialize
00258  */
00259 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
00260 
00261 /**
00262  * \brief           Free context
00263  *
00264  * \param ctx       Context to free
00265  */
00266 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
00267 
00268 #ifdef __cplusplus
00269 }
00270 #endif
00271 
00272 #endif /* ecdsa.h */