ecdsa.h

00001 /**
00002  * \file ecdsa.h
00003  *
00004  * \brief Elliptic curve DSA
00005  *
00006  *  Copyright (C) 2006-2013, Brainspark B.V.
00007  *
00008  *  This file is part of PolarSSL (http://www.polarssl.org)
00009  *  Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
00010  *
00011  *  All rights reserved.
00012  *
00013  *  This program is free software; you can redistribute it and/or modify
00014  *  it under the terms of the GNU General Public License as published by
00015  *  the Free Software Foundation; either version 2 of the License, or
00016  *  (at your option) any later version.
00017  *
00018  *  This program is distributed in the hope that it will be useful,
00019  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00020  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00021  *  GNU General Public License for more details.
00022  *
00023  *  You should have received a copy of the GNU General Public License along
00024  *  with this program; if not, write to the Free Software Foundation, Inc.,
00025  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
00026  */
00027 #ifndef POLARSSL_ECDSA_H
00028 #define POLARSSL_ECDSA_H
00029 
00030 #include "ecp.h"
00031 
00032 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
00033 #include "md.h"
00034 #endif
00035 
00036 /**
00037  * \brief           ECDSA context structure
00038  *
00039  * \note Purposefully begins with the same members as struct ecp_keypair.
00040  */
00041 typedef struct
00042 {
00043     ecp_group grp ;      /*!<  ellipitic curve used          */
00044     mpi d ;              /*!<  secret signature key          */
00045     ecp_point Q ;        /*!<  public signature key          */
00046     mpi r ;              /*!<  first integer from signature  */
00047     mpi s ;              /*!<  second integer from signature */
00048 }
00049 ecdsa_context;
00050 
00051 #ifdef __cplusplus
00052 extern "C" {
00053 #endif
00054 
00055 /**
00056  * \brief           Compute ECDSA signature of a previously hashed message
00057  *
00058  * \param grp       ECP group
00059  * \param r         First output integer
00060  * \param s         Second output integer
00061  * \param d         Private signing key
00062  * \param buf       Message hash
00063  * \param blen      Length of buf
00064  * \param f_rng     RNG function
00065  * \param p_rng     RNG parameter
00066  *
00067  * \return          0 if successful,
00068  *                  or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
00069  */
00070 int ecdsa_sign( ecp_group *grp, mpi *r, mpi *s,
00071                 const mpi *d, const unsigned char *buf, size_t blen,
00072                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00073 
00074 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
00075 /**
00076  * \brief           Compute ECDSA signature of a previously hashed message
00077  *                  (deterministic version)
00078  *
00079  * \param grp       ECP group
00080  * \param r         First output integer
00081  * \param s         Second output integer
00082  * \param d         Private signing key
00083  * \param buf       Message hash
00084  * \param blen      Length of buf
00085  * \param md_alg    MD algorithm used to hash the message
00086  *
00087  * \return          0 if successful,
00088  *                  or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
00089  */
00090 int ecdsa_sign_det( ecp_group *grp, mpi *r, mpi *s,
00091                     const mpi *d, const unsigned char *buf, size_t blen,
00092                     md_type_t md_alg );
00093 #endif /* POLARSSL_ECDSA_DETERMINISTIC */
00094 
00095 /**
00096  * \brief           Verify ECDSA signature of a previously hashed message
00097  *
00098  * \param grp       ECP group
00099  * \param buf       Message hash
00100  * \param blen      Length of buf
00101  * \param Q         Public key to use for verification
00102  * \param r         First integer of the signature
00103  * \param s         Second integer of the signature
00104  *
00105  * \return          0 if successful,
00106  *                  POLARSSL_ERR_ECP_BAD_INPUT_DATA if signature is invalid
00107  *                  or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
00108  */
00109 int ecdsa_verify( ecp_group *grp,
00110                   const unsigned char *buf, size_t blen,
00111                   const ecp_point *Q, const mpi *r, const mpi *s);
00112 
00113 /**
00114  * \brief           Compute ECDSA signature and write it to buffer,
00115  *                  serialized as defined in RFC 4492 page 20.
00116  *                  (Not thread-safe to use same context in multiple threads)
00117  *
00118  * \param ctx       ECDSA context
00119  * \param hash      Message hash
00120  * \param hlen      Length of hash
00121  * \param sig       Buffer that will hold the signature
00122  * \param slen      Length of the signature written
00123  * \param f_rng     RNG function
00124  * \param p_rng     RNG parameter
00125  *
00126  * \note            The "sig" buffer must be at least as large as twice the
00127  *                  size of the curve used, plus 7 (eg. 71 bytes if a 256-bit
00128  *                  curve is used).
00129  *
00130  * \return          0 if successful,
00131  *                  or a POLARSSL_ERR_ECP, POLARSSL_ERR_MPI or
00132  *                  POLARSSL_ERR_ASN1 error code
00133  */
00134 int ecdsa_write_signature( ecdsa_context *ctx,
00135                            const unsigned char *hash, size_t hlen,
00136                            unsigned char *sig, size_t *slen,
00137                            int (*f_rng)(void *, unsigned char *, size_t),
00138                            void *p_rng );
00139 
00140 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
00141 /**
00142  * \brief           Compute ECDSA signature and write it to buffer,
00143  *                  serialized as defined in RFC 4492 page 20.
00144  *                  Deterministic version, RFC 6979.
00145  *                  (Not thread-safe to use same context in multiple threads)
00146  *
00147  * \param ctx       ECDSA context
00148  * \param hash      Message hash
00149  * \param hlen      Length of hash
00150  * \param sig       Buffer that will hold the signature
00151  * \param slen      Length of the signature written
00152  * \param md_alg    MD algorithm used to hash the message
00153  *
00154  * \note            The "sig" buffer must be at least as large as twice the
00155  *                  size of the curve used, plus 7 (eg. 71 bytes if a 256-bit
00156  *                  curve is used).
00157  *
00158  * \return          0 if successful,
00159  *                  or a POLARSSL_ERR_ECP, POLARSSL_ERR_MPI or
00160  *                  POLARSSL_ERR_ASN1 error code
00161  */
00162 int ecdsa_write_signature_det( ecdsa_context *ctx,
00163                                const unsigned char *hash, size_t hlen,
00164                                unsigned char *sig, size_t *slen,
00165                                md_type_t md_alg );
00166 #endif /* POLARSSL_ECDSA_DETERMINISTIC */
00167 
00168 /**
00169  * \brief           Read and verify an ECDSA signature
00170  *
00171  * \param ctx       ECDSA context
00172  * \param hash      Message hash
00173  * \param hlen      Size of hash
00174  * \param sig       Signature to read and verify
00175  * \param slen      Size of sig
00176  *
00177  * \return          0 if successful,
00178  *                  POLARSSL_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
00179  *                  POLARSSL_ERR_ECP_SIG_LEN_MISTMATCH if the signature is
00180  *                  valid but its actual length is less than siglen,
00181  *                  or a POLARSSL_ERR_ECP or POLARSSL_ERR_MPI error code
00182  */
00183 int ecdsa_read_signature( ecdsa_context *ctx,
00184                           const unsigned char *hash, size_t hlen,
00185                           const unsigned char *sig, size_t slen );
00186 
00187 /**
00188  * \brief           Generate an ECDSA keypair on the given curve
00189  *
00190  * \param ctx       ECDSA context in which the keypair should be stored
00191  * \param gid       Group (elliptic curve) to use. One of the various
00192  *                  POLARSSL_ECP_DP_XXX macros depending on configuration.
00193  * \param f_rng     RNG function
00194  * \param p_rng     RNG parameter
00195  *
00196  * \return          0 on success, or a POLARSSL_ERR_ECP code.
00197  */
00198 int ecdsa_genkey( ecdsa_context *ctx, ecp_group_id gid,
00199                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
00200 
00201 /**
00202  * \brief           Set an ECDSA context from an EC key pair
00203  *
00204  * \param ctx       ECDSA context to set
00205  * \param key       EC key to use
00206  *
00207  * \return          0 on success, or a POLARSSL_ERR_ECP code.
00208  */
00209 int ecdsa_from_keypair( ecdsa_context *ctx, const ecp_keypair *key );
00210 
00211 /**
00212  * \brief           Initialize context
00213  *
00214  * \param ctx       Context to initialize
00215  */
00216 void ecdsa_init( ecdsa_context *ctx );
00217 
00218 /**
00219  * \brief           Free context
00220  *
00221  * \param ctx       Context to free
00222  */
00223 void ecdsa_free( ecdsa_context *ctx );
00224 
00225 /**
00226  * \brief          Checkup routine
00227  *
00228  * \return         0 if successful, or 1 if the test failed
00229  */
00230 int ecdsa_self_test( int verbose );
00231 
00232 #ifdef __cplusplus
00233 }
00234 #endif
00235 
00236 #endif /* ecdsa.h */
00237 
00238