Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
ecdsa.h
00001 /** 00002 * \file ecdsa.h 00003 * 00004 * \brief This file contains ECDSA definitions and functions. 00005 * 00006 * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in 00007 * <em>Standards for Efficient Cryptography Group (SECG): 00008 * SEC1 Elliptic Curve Cryptography</em>. 00009 * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve 00010 * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>. 00011 * 00012 */ 00013 /* 00014 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 00015 * SPDX-License-Identifier: Apache-2.0 00016 * 00017 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00018 * not use this file except in compliance with the License. 00019 * You may obtain a copy of the License at 00020 * 00021 * http://www.apache.org/licenses/LICENSE-2.0 00022 * 00023 * Unless required by applicable law or agreed to in writing, software 00024 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00025 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00026 * See the License for the specific language governing permissions and 00027 * limitations under the License. 00028 * 00029 * This file is part of Mbed TLS (https://tls.mbed.org) 00030 */ 00031 00032 #ifndef MBEDTLS_ECDSA_H 00033 #define MBEDTLS_ECDSA_H 00034 00035 #include "ecp.h" 00036 #include "md.h" 00037 00038 /* 00039 * RFC-4492 page 20: 00040 * 00041 * Ecdsa-Sig-Value ::= SEQUENCE { 00042 * r INTEGER, 00043 * s INTEGER 00044 * } 00045 * 00046 * Size is at most 00047 * 1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s, 00048 * twice that + 1 (tag) + 2 (len) for the sequence 00049 * (assuming ECP_MAX_BYTES is less than 126 for r and s, 00050 * and less than 124 (total len <= 255) for the sequence) 00051 */ 00052 #if MBEDTLS_ECP_MAX_BYTES > 124 00053 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" 00054 #endif 00055 /** The maximal size of an ECDSA signature in Bytes. */ 00056 #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) ) 00057 00058 /** 00059 * \brief The ECDSA context structure. 00060 */ 00061 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; 00062 00063 #ifdef __cplusplus 00064 extern "C" { 00065 #endif 00066 00067 /** 00068 * \brief This function computes the ECDSA signature of a 00069 * previously-hashed message. 00070 * 00071 * \note The deterministic version is usually preferred. 00072 * 00073 * \note If the bitlength of the message hash is larger than the 00074 * bitlength of the group order, then the hash is truncated 00075 * as defined in <em>Standards for Efficient Cryptography Group 00076 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00077 * 4.1.3, step 5. 00078 * 00079 * \see ecp.h 00080 * 00081 * \param grp The ECP group. 00082 * \param r The first output integer. 00083 * \param s The second output integer. 00084 * \param d The private signing key. 00085 * \param buf The message hash. 00086 * \param blen The length of \p buf. 00087 * \param f_rng The RNG function. 00088 * \param p_rng The RNG context. 00089 * 00090 * \return \c 0 on success. 00091 * \return An \c MBEDTLS_ERR_ECP_XXX 00092 * or \c MBEDTLS_MPI_XXX error code on failure. 00093 */ 00094 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 00095 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 00096 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 00097 00098 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 00099 /** 00100 * \brief This function computes the ECDSA signature of a 00101 * previously-hashed message, deterministic version. 00102 * 00103 * For more information, see <em>RFC-6979: Deterministic 00104 * Usage of the Digital Signature Algorithm (DSA) and Elliptic 00105 * Curve Digital Signature Algorithm (ECDSA)</em>. 00106 * 00107 * \note If the bitlength of the message hash is larger than the 00108 * bitlength of the group order, then the hash is truncated as 00109 * defined in <em>Standards for Efficient Cryptography Group 00110 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00111 * 4.1.3, step 5. 00112 * 00113 * \see ecp.h 00114 * 00115 * \param grp The ECP group. 00116 * \param r The first output integer. 00117 * \param s The second output integer. 00118 * \param d The private signing key. 00119 * \param buf The message hash. 00120 * \param blen The length of \p buf. 00121 * \param md_alg The MD algorithm used to hash the message. 00122 * 00123 * \return \c 0 on success. 00124 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 00125 * error code on failure. 00126 */ 00127 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 00128 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 00129 mbedtls_md_type_t md_alg ); 00130 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 00131 00132 /** 00133 * \brief This function verifies the ECDSA signature of a 00134 * previously-hashed message. 00135 * 00136 * \note If the bitlength of the message hash is larger than the 00137 * bitlength of the group order, then the hash is truncated as 00138 * defined in <em>Standards for Efficient Cryptography Group 00139 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00140 * 4.1.4, step 3. 00141 * 00142 * \see ecp.h 00143 * 00144 * \param grp The ECP group. 00145 * \param buf The message hash. 00146 * \param blen The length of \p buf. 00147 * \param Q The public key to use for verification. 00148 * \param r The first integer of the signature. 00149 * \param s The second integer of the signature. 00150 * 00151 * \return \c 0 on success. 00152 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature 00153 * is invalid. 00154 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 00155 * error code on failure for any other reason. 00156 */ 00157 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, 00158 const unsigned char *buf, size_t blen, 00159 const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s); 00160 00161 /** 00162 * \brief This function computes the ECDSA signature and writes it 00163 * to a buffer, serialized as defined in <em>RFC-4492: 00164 * Elliptic Curve Cryptography (ECC) Cipher Suites for 00165 * Transport Layer Security (TLS)</em>. 00166 * 00167 * \warning It is not thread-safe to use the same context in 00168 * multiple threads. 00169 * 00170 * \note The deterministic version is used if 00171 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more 00172 * information, see <em>RFC-6979: Deterministic Usage 00173 * of the Digital Signature Algorithm (DSA) and Elliptic 00174 * Curve Digital Signature Algorithm (ECDSA)</em>. 00175 * 00176 * \note The \p sig buffer must be at least twice as large as the 00177 * size of the curve used, plus 9. For example, 73 Bytes if 00178 * a 256-bit curve is used. A buffer length of 00179 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 00180 * 00181 * \note If the bitlength of the message hash is larger than the 00182 * bitlength of the group order, then the hash is truncated as 00183 * defined in <em>Standards for Efficient Cryptography Group 00184 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00185 * 4.1.3, step 5. 00186 * 00187 * \see ecp.h 00188 * 00189 * \param ctx The ECDSA context. 00190 * \param md_alg The message digest that was used to hash the message. 00191 * \param hash The message hash. 00192 * \param hlen The length of the hash. 00193 * \param sig The buffer that holds the signature. 00194 * \param slen The length of the signature written. 00195 * \param f_rng The RNG function. 00196 * \param p_rng The RNG context. 00197 * 00198 * \return \c 0 on success. 00199 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 00200 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 00201 */ 00202 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, 00203 const unsigned char *hash, size_t hlen, 00204 unsigned char *sig, size_t *slen, 00205 int (*f_rng)(void *, unsigned char *, size_t), 00206 void *p_rng ); 00207 00208 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 00209 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 00210 #if defined(MBEDTLS_DEPRECATED_WARNING) 00211 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 00212 #else 00213 #define MBEDTLS_DEPRECATED 00214 #endif 00215 /** 00216 * \brief This function computes an ECDSA signature and writes 00217 * it to a buffer, serialized as defined in <em>RFC-4492: 00218 * Elliptic Curve Cryptography (ECC) Cipher Suites for 00219 * Transport Layer Security (TLS)</em>. 00220 * 00221 * The deterministic version is defined in <em>RFC-6979: 00222 * Deterministic Usage of the Digital Signature Algorithm (DSA) 00223 * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>. 00224 * 00225 * \warning It is not thread-safe to use the same context in 00226 * multiple threads. 00227 * 00228 * \note The \p sig buffer must be at least twice as large as the 00229 * size of the curve used, plus 9. For example, 73 Bytes if a 00230 * 256-bit curve is used. A buffer length of 00231 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 00232 * 00233 * \note If the bitlength of the message hash is larger than the 00234 * bitlength of the group order, then the hash is truncated as 00235 * defined in <em>Standards for Efficient Cryptography Group 00236 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00237 * 4.1.3, step 5. 00238 * 00239 * \see ecp.h 00240 * 00241 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 00242 * Mbed TLS version 2.0 and later. 00243 * 00244 * \param ctx The ECDSA context. 00245 * \param hash The message hash. 00246 * \param hlen The length of the hash. 00247 * \param sig The buffer that holds the signature. 00248 * \param slen The length of the signature written. 00249 * \param md_alg The MD algorithm used to hash the message. 00250 * 00251 * \return \c 0 on success. 00252 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 00253 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 00254 */ 00255 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, 00256 const unsigned char *hash, size_t hlen, 00257 unsigned char *sig, size_t *slen, 00258 mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED; 00259 #undef MBEDTLS_DEPRECATED 00260 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 00261 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 00262 00263 /** 00264 * \brief This function reads and verifies an ECDSA signature. 00265 * 00266 * \note If the bitlength of the message hash is larger than the 00267 * bitlength of the group order, then the hash is truncated as 00268 * defined in <em>Standards for Efficient Cryptography Group 00269 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 00270 * 4.1.4, step 3. 00271 * 00272 * \see ecp.h 00273 * 00274 * \param ctx The ECDSA context. 00275 * \param hash The message hash. 00276 * \param hlen The size of the hash. 00277 * \param sig The signature to read and verify. 00278 * \param slen The size of \p sig. 00279 * 00280 * \return \c 0 on success. 00281 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 00282 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 00283 * signature in \p sig, but its length is less than \p siglen. 00284 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 00285 * error code on failure for any other reason. 00286 */ 00287 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, 00288 const unsigned char *hash, size_t hlen, 00289 const unsigned char *sig, size_t slen ); 00290 00291 /** 00292 * \brief This function generates an ECDSA keypair on the given curve. 00293 * 00294 * \see ecp.h 00295 * 00296 * \param ctx The ECDSA context to store the keypair in. 00297 * \param gid The elliptic curve to use. One of the various 00298 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration. 00299 * \param f_rng The RNG function. 00300 * \param p_rng The RNG context. 00301 * 00302 * \return \c 0 on success. 00303 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 00304 */ 00305 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, 00306 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 00307 00308 /** 00309 * \brief This function sets an ECDSA context from an EC key pair. 00310 * 00311 * \see ecp.h 00312 * 00313 * \param ctx The ECDSA context to set. 00314 * \param key The EC key to use. 00315 * 00316 * \return \c 0 on success. 00317 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 00318 */ 00319 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key ); 00320 00321 /** 00322 * \brief This function initializes an ECDSA context. 00323 * 00324 * \param ctx The ECDSA context to initialize. 00325 */ 00326 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); 00327 00328 /** 00329 * \brief This function frees an ECDSA context. 00330 * 00331 * \param ctx The ECDSA context to free. 00332 */ 00333 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx ); 00334 00335 #ifdef __cplusplus 00336 } 00337 #endif 00338 00339 #endif /* ecdsa.h */
Generated on Tue Jul 12 2022 12:43:51 by
