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 */ 249
