Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/ecdsa.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file ecdsa.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Elliptic curve DSA
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2013, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24 #ifndef POLARSSL_ECDSA_H
ansond 0:137634ff4186 25 #define POLARSSL_ECDSA_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #include "ecp.h"
ansond 0:137634ff4186 28 #include "md.h"
ansond 0:137634ff4186 29
ansond 0:137634ff4186 30 /**
ansond 0:137634ff4186 31 * \brief ECDSA context structure
ansond 0:137634ff4186 32 *
ansond 0:137634ff4186 33 * \note Purposefully begins with the same members as struct ecp_keypair.
ansond 0:137634ff4186 34 */
ansond 0:137634ff4186 35 typedef struct
ansond 0:137634ff4186 36 {
ansond 0:137634ff4186 37 ecp_group grp; /*!< elliptic curve used */
ansond 0:137634ff4186 38 mpi d; /*!< secret signature key */
ansond 0:137634ff4186 39 ecp_point Q; /*!< public signature key */
ansond 0:137634ff4186 40 mpi r; /*!< first integer from signature */
ansond 0:137634ff4186 41 mpi s; /*!< second integer from signature */
ansond 0:137634ff4186 42 }
ansond 0:137634ff4186 43 ecdsa_context;
ansond 0:137634ff4186 44
ansond 0:137634ff4186 45 #ifdef __cplusplus
ansond 0:137634ff4186 46 extern "C" {
ansond 0:137634ff4186 47 #endif
ansond 0:137634ff4186 48
ansond 0:137634ff4186 49 /**
ansond 0:137634ff4186 50 * \brief Compute ECDSA signature of a previously hashed message
ansond 0:137634ff4186 51 *
ansond 0:137634ff4186 52 * \param grp ECP group
ansond 0:137634ff4186 53 * \param r First output integer
ansond 0:137634ff4186 54 * \param s Second output integer
ansond 0:137634ff4186 55 * \param d Private signing key
ansond 0:137634ff4186 56 * \param buf Message hash
ansond 0:137634ff4186 57 * \param blen Length of buf
ansond 0:137634ff4186 58 * \param f_rng RNG function
ansond 0:137634ff4186 59 * \param p_rng RNG parameter
ansond 0:137634ff4186 60 *
ansond 0:137634ff4186 61 * \return 0 if successful,
ansond 0:137634ff4186 62 * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
ansond 0:137634ff4186 63 */
ansond 0:137634ff4186 64 int ecdsa_sign( ecp_group *grp, mpi *r, mpi *s,
ansond 0:137634ff4186 65 const mpi *d, const unsigned char *buf, size_t blen,
ansond 0:137634ff4186 66 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
ansond 0:137634ff4186 67
ansond 0:137634ff4186 68 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
ansond 0:137634ff4186 69 /**
ansond 0:137634ff4186 70 * \brief Compute ECDSA signature of a previously hashed message
ansond 0:137634ff4186 71 * (deterministic version)
ansond 0:137634ff4186 72 *
ansond 0:137634ff4186 73 * \param grp ECP group
ansond 0:137634ff4186 74 * \param r First output integer
ansond 0:137634ff4186 75 * \param s Second output integer
ansond 0:137634ff4186 76 * \param d Private signing key
ansond 0:137634ff4186 77 * \param buf Message hash
ansond 0:137634ff4186 78 * \param blen Length of buf
ansond 0:137634ff4186 79 * \param md_alg MD algorithm used to hash the message
ansond 0:137634ff4186 80 *
ansond 0:137634ff4186 81 * \return 0 if successful,
ansond 0:137634ff4186 82 * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
ansond 0:137634ff4186 83 */
ansond 0:137634ff4186 84 int ecdsa_sign_det( ecp_group *grp, mpi *r, mpi *s,
ansond 0:137634ff4186 85 const mpi *d, const unsigned char *buf, size_t blen,
ansond 0:137634ff4186 86 md_type_t md_alg );
ansond 0:137634ff4186 87 #endif /* POLARSSL_ECDSA_DETERMINISTIC */
ansond 0:137634ff4186 88
ansond 0:137634ff4186 89 /**
ansond 0:137634ff4186 90 * \brief Verify ECDSA signature of a previously hashed message
ansond 0:137634ff4186 91 *
ansond 0:137634ff4186 92 * \param grp ECP group
ansond 0:137634ff4186 93 * \param buf Message hash
ansond 0:137634ff4186 94 * \param blen Length of buf
ansond 0:137634ff4186 95 * \param Q Public key to use for verification
ansond 0:137634ff4186 96 * \param r First integer of the signature
ansond 0:137634ff4186 97 * \param s Second integer of the signature
ansond 0:137634ff4186 98 *
ansond 0:137634ff4186 99 * \return 0 if successful,
ansond 0:137634ff4186 100 * POLARSSL_ERR_ECP_BAD_INPUT_DATA if signature is invalid
ansond 0:137634ff4186 101 * or a POLARSSL_ERR_ECP_XXX or POLARSSL_MPI_XXX error code
ansond 0:137634ff4186 102 */
ansond 0:137634ff4186 103 int ecdsa_verify( ecp_group *grp,
ansond 0:137634ff4186 104 const unsigned char *buf, size_t blen,
ansond 0:137634ff4186 105 const ecp_point *Q, const mpi *r, const mpi *s);
ansond 0:137634ff4186 106
ansond 0:137634ff4186 107 /**
ansond 0:137634ff4186 108 * \brief Compute ECDSA signature and write it to buffer,
ansond 0:137634ff4186 109 * serialized as defined in RFC 4492 page 20.
ansond 0:137634ff4186 110 * (Not thread-safe to use same context in multiple threads)
ansond 0:137634ff4186 111 *
ansond 0:137634ff4186 112 * \param ctx ECDSA context
ansond 0:137634ff4186 113 * \param hash Message hash
ansond 0:137634ff4186 114 * \param hlen Length of hash
ansond 0:137634ff4186 115 * \param sig Buffer that will hold the signature
ansond 0:137634ff4186 116 * \param slen Length of the signature written
ansond 0:137634ff4186 117 * \param f_rng RNG function
ansond 0:137634ff4186 118 * \param p_rng RNG parameter
ansond 0:137634ff4186 119 *
ansond 0:137634ff4186 120 * \note The "sig" buffer must be at least as large as twice the
ansond 0:137634ff4186 121 * size of the curve used, plus 7 (eg. 71 bytes if a 256-bit
ansond 0:137634ff4186 122 * curve is used).
ansond 0:137634ff4186 123 *
ansond 0:137634ff4186 124 * \return 0 if successful,
ansond 0:137634ff4186 125 * or a POLARSSL_ERR_ECP, POLARSSL_ERR_MPI or
ansond 0:137634ff4186 126 * POLARSSL_ERR_ASN1 error code
ansond 0:137634ff4186 127 */
ansond 0:137634ff4186 128 int ecdsa_write_signature( ecdsa_context *ctx,
ansond 0:137634ff4186 129 const unsigned char *hash, size_t hlen,
ansond 0:137634ff4186 130 unsigned char *sig, size_t *slen,
ansond 0:137634ff4186 131 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 132 void *p_rng );
ansond 0:137634ff4186 133
ansond 0:137634ff4186 134 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
ansond 0:137634ff4186 135 /**
ansond 0:137634ff4186 136 * \brief Compute ECDSA signature and write it to buffer,
ansond 0:137634ff4186 137 * serialized as defined in RFC 4492 page 20.
ansond 0:137634ff4186 138 * Deterministic version, RFC 6979.
ansond 0:137634ff4186 139 * (Not thread-safe to use same context in multiple threads)
ansond 0:137634ff4186 140 *
ansond 0:137634ff4186 141 * \param ctx ECDSA context
ansond 0:137634ff4186 142 * \param hash Message hash
ansond 0:137634ff4186 143 * \param hlen Length of hash
ansond 0:137634ff4186 144 * \param sig Buffer that will hold the signature
ansond 0:137634ff4186 145 * \param slen Length of the signature written
ansond 0:137634ff4186 146 * \param md_alg MD algorithm used to hash the message
ansond 0:137634ff4186 147 *
ansond 0:137634ff4186 148 * \note The "sig" buffer must be at least as large as twice the
ansond 0:137634ff4186 149 * size of the curve used, plus 7 (eg. 71 bytes if a 256-bit
ansond 0:137634ff4186 150 * curve is used).
ansond 0:137634ff4186 151 *
ansond 0:137634ff4186 152 * \return 0 if successful,
ansond 0:137634ff4186 153 * or a POLARSSL_ERR_ECP, POLARSSL_ERR_MPI or
ansond 0:137634ff4186 154 * POLARSSL_ERR_ASN1 error code
ansond 0:137634ff4186 155 */
ansond 0:137634ff4186 156 int ecdsa_write_signature_det( ecdsa_context *ctx,
ansond 0:137634ff4186 157 const unsigned char *hash, size_t hlen,
ansond 0:137634ff4186 158 unsigned char *sig, size_t *slen,
ansond 0:137634ff4186 159 md_type_t md_alg );
ansond 0:137634ff4186 160 #endif /* POLARSSL_ECDSA_DETERMINISTIC */
ansond 0:137634ff4186 161
ansond 0:137634ff4186 162 /**
ansond 0:137634ff4186 163 * \brief Read and verify an ECDSA signature
ansond 0:137634ff4186 164 *
ansond 0:137634ff4186 165 * \param ctx ECDSA context
ansond 0:137634ff4186 166 * \param hash Message hash
ansond 0:137634ff4186 167 * \param hlen Size of hash
ansond 0:137634ff4186 168 * \param sig Signature to read and verify
ansond 0:137634ff4186 169 * \param slen Size of sig
ansond 0:137634ff4186 170 *
ansond 0:137634ff4186 171 * \return 0 if successful,
ansond 0:137634ff4186 172 * POLARSSL_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
ansond 0:137634ff4186 173 * POLARSSL_ERR_ECP_SIG_LEN_MISTMATCH if the signature is
ansond 0:137634ff4186 174 * valid but its actual length is less than siglen,
ansond 0:137634ff4186 175 * or a POLARSSL_ERR_ECP or POLARSSL_ERR_MPI error code
ansond 0:137634ff4186 176 */
ansond 0:137634ff4186 177 int ecdsa_read_signature( ecdsa_context *ctx,
ansond 0:137634ff4186 178 const unsigned char *hash, size_t hlen,
ansond 0:137634ff4186 179 const unsigned char *sig, size_t slen );
ansond 0:137634ff4186 180
ansond 0:137634ff4186 181 /**
ansond 0:137634ff4186 182 * \brief Generate an ECDSA keypair on the given curve
ansond 0:137634ff4186 183 *
ansond 0:137634ff4186 184 * \param ctx ECDSA context in which the keypair should be stored
ansond 0:137634ff4186 185 * \param gid Group (elliptic curve) to use. One of the various
ansond 0:137634ff4186 186 * POLARSSL_ECP_DP_XXX macros depending on configuration.
ansond 0:137634ff4186 187 * \param f_rng RNG function
ansond 0:137634ff4186 188 * \param p_rng RNG parameter
ansond 0:137634ff4186 189 *
ansond 0:137634ff4186 190 * \return 0 on success, or a POLARSSL_ERR_ECP code.
ansond 0:137634ff4186 191 */
ansond 0:137634ff4186 192 int ecdsa_genkey( ecdsa_context *ctx, ecp_group_id gid,
ansond 0:137634ff4186 193 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
ansond 0:137634ff4186 194
ansond 0:137634ff4186 195 /**
ansond 0:137634ff4186 196 * \brief Set an ECDSA context from an EC key pair
ansond 0:137634ff4186 197 *
ansond 0:137634ff4186 198 * \param ctx ECDSA context to set
ansond 0:137634ff4186 199 * \param key EC key to use
ansond 0:137634ff4186 200 *
ansond 0:137634ff4186 201 * \return 0 on success, or a POLARSSL_ERR_ECP code.
ansond 0:137634ff4186 202 */
ansond 0:137634ff4186 203 int ecdsa_from_keypair( ecdsa_context *ctx, const ecp_keypair *key );
ansond 0:137634ff4186 204
ansond 0:137634ff4186 205 /**
ansond 0:137634ff4186 206 * \brief Initialize context
ansond 0:137634ff4186 207 *
ansond 0:137634ff4186 208 * \param ctx Context to initialize
ansond 0:137634ff4186 209 */
ansond 0:137634ff4186 210 void ecdsa_init( ecdsa_context *ctx );
ansond 0:137634ff4186 211
ansond 0:137634ff4186 212 /**
ansond 0:137634ff4186 213 * \brief Free context
ansond 0:137634ff4186 214 *
ansond 0:137634ff4186 215 * \param ctx Context to free
ansond 0:137634ff4186 216 */
ansond 0:137634ff4186 217 void ecdsa_free( ecdsa_context *ctx );
ansond 0:137634ff4186 218
ansond 0:137634ff4186 219 /**
ansond 0:137634ff4186 220 * \brief Checkup routine
ansond 0:137634ff4186 221 *
ansond 0:137634ff4186 222 * \return 0 if successful, or 1 if the test failed
ansond 0:137634ff4186 223 */
ansond 0:137634ff4186 224 int ecdsa_self_test( int verbose );
ansond 0:137634ff4186 225
ansond 0:137634ff4186 226 #ifdef __cplusplus
ansond 0:137634ff4186 227 }
ansond 0:137634ff4186 228 #endif
ansond 0:137634ff4186 229
ansond 0:137634ff4186 230 #endif /* ecdsa.h */
ansond 0:137634ff4186 231