ecdsa.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. /**
  2. * \file ecdsa.h
  3. *
  4. * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
  5. *
  6. * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
  7. * SEC1 Elliptic Curve Cryptography</em>.
  8. * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
  9. * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
  10. *
  11. */
  12. /*
  13. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  14. * SPDX-License-Identifier: Apache-2.0
  15. *
  16. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  17. * not use this file except in compliance with the License.
  18. * You may obtain a copy of the License at
  19. *
  20. * http://www.apache.org/licenses/LICENSE-2.0
  21. *
  22. * Unless required by applicable law or agreed to in writing, software
  23. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  24. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  25. * See the License for the specific language governing permissions and
  26. * limitations under the License.
  27. *
  28. * This file is part of Mbed TLS (https://tls.mbed.org)
  29. */
  30. #ifndef MBEDTLS_ECDSA_H
  31. #define MBEDTLS_ECDSA_H
  32. #include "ecp.h"
  33. #include "md.h"
  34. /*
  35. * RFC-4492 page 20:
  36. *
  37. * Ecdsa-Sig-Value ::= SEQUENCE {
  38. * r INTEGER,
  39. * s INTEGER
  40. * }
  41. *
  42. * Size is at most
  43. * 1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
  44. * twice that + 1 (tag) + 2 (len) for the sequence
  45. * (assuming ECP_MAX_BYTES is less than 126 for r and s,
  46. * and less than 124 (total len <= 255) for the sequence)
  47. */
  48. #if MBEDTLS_ECP_MAX_BYTES > 124
  49. #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
  50. #endif
  51. /** The maximal size of an ECDSA signature in Bytes. */
  52. #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
  53. /**
  54. * \brief The ECDSA context structure.
  55. */
  56. typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
  57. #ifdef __cplusplus
  58. extern "C" {
  59. #endif
  60. /**
  61. * \brief This function computes the ECDSA signature of a
  62. * previously-hashed message.
  63. *
  64. * \note The deterministic version is usually preferred.
  65. *
  66. * \param grp The ECP group.
  67. * \param r The first output integer.
  68. * \param s The second output integer.
  69. * \param d The private signing key.
  70. * \param buf The message hash.
  71. * \param blen The length of \p buf.
  72. * \param f_rng The RNG function.
  73. * \param p_rng The RNG parameter.
  74. *
  75. * \note If the bitlength of the message hash is larger than the
  76. * bitlength of the group order, then the hash is truncated
  77. * as defined in <em>Standards for Efficient Cryptography Group
  78. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  79. * 4.1.3, step 5.
  80. *
  81. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
  82. * or \c MBEDTLS_MPI_XXX error code on failure.
  83. *
  84. * \see ecp.h
  85. */
  86. int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  87. const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  88. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  89. #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
  90. /**
  91. * \brief This function computes the ECDSA signature of a
  92. * previously-hashed message, deterministic version.
  93. * For more information, see <em>RFC-6979: Deterministic
  94. * Usage of the Digital Signature Algorithm (DSA) and Elliptic
  95. * Curve Digital Signature Algorithm (ECDSA)</em>.
  96. *
  97. * \param grp The ECP group.
  98. * \param r The first output integer.
  99. * \param s The second output integer.
  100. * \param d The private signing key.
  101. * \param buf The message hash.
  102. * \param blen The length of \p buf.
  103. * \param md_alg The MD algorithm used to hash the message.
  104. *
  105. * \note If the bitlength of the message hash is larger than the
  106. * bitlength of the group order, then the hash is truncated as
  107. * defined in <em>Standards for Efficient Cryptography Group
  108. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  109. * 4.1.3, step 5.
  110. *
  111. * \return \c 0 on success,
  112. * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
  113. * error code on failure.
  114. *
  115. * \see ecp.h
  116. */
  117. int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  118. const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  119. mbedtls_md_type_t md_alg );
  120. #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
  121. /**
  122. * \brief This function verifies the ECDSA signature of a
  123. * previously-hashed message.
  124. *
  125. * \param grp The ECP group.
  126. * \param buf The message hash.
  127. * \param blen The length of \p buf.
  128. * \param Q The public key to use for verification.
  129. * \param r The first integer of the signature.
  130. * \param s The second integer of the signature.
  131. *
  132. * \note If the bitlength of the message hash is larger than the
  133. * bitlength of the group order, then the hash is truncated as
  134. * defined in <em>Standards for Efficient Cryptography Group
  135. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  136. * 4.1.4, step 3.
  137. *
  138. * \return \c 0 on success,
  139. * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
  140. * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
  141. * error code on failure for any other reason.
  142. *
  143. * \see ecp.h
  144. */
  145. int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
  146. const unsigned char *buf, size_t blen,
  147. const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
  148. /**
  149. * \brief This function computes the ECDSA signature and writes it
  150. * to a buffer, serialized as defined in <em>RFC-4492:
  151. * Elliptic Curve Cryptography (ECC) Cipher Suites for
  152. * Transport Layer Security (TLS)</em>.
  153. *
  154. * \warning It is not thread-safe to use the same context in
  155. * multiple threads.
  156. *
  157. * \note The deterministic version is used if
  158. * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
  159. * information, see <em>RFC-6979: Deterministic Usage
  160. * of the Digital Signature Algorithm (DSA) and Elliptic
  161. * Curve Digital Signature Algorithm (ECDSA)</em>.
  162. *
  163. * \param ctx The ECDSA context.
  164. * \param md_alg The message digest that was used to hash the message.
  165. * \param hash The message hash.
  166. * \param hlen The length of the hash.
  167. * \param sig The buffer that holds the signature.
  168. * \param slen The length of the signature written.
  169. * \param f_rng The RNG function.
  170. * \param p_rng The RNG parameter.
  171. *
  172. * \note The \p sig buffer must be at least twice as large as the
  173. * size of the curve used, plus 9. For example, 73 Bytes if
  174. * a 256-bit curve is used. A buffer length of
  175. * #MBEDTLS_ECDSA_MAX_LEN is always safe.
  176. *
  177. * \note If the bitlength of the message hash is larger than the
  178. * bitlength of the group order, then the hash is truncated as
  179. * defined in <em>Standards for Efficient Cryptography Group
  180. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  181. * 4.1.3, step 5.
  182. *
  183. * \return \c 0 on success,
  184. * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
  185. * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  186. *
  187. * \see ecp.h
  188. */
  189. int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
  190. const unsigned char *hash, size_t hlen,
  191. unsigned char *sig, size_t *slen,
  192. int (*f_rng)(void *, unsigned char *, size_t),
  193. void *p_rng );
  194. #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
  195. #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
  196. #if defined(MBEDTLS_DEPRECATED_WARNING)
  197. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  198. #else
  199. #define MBEDTLS_DEPRECATED
  200. #endif
  201. /**
  202. * \brief This function computes an ECDSA signature and writes it to a buffer,
  203. * serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
  204. * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
  205. *
  206. * The deterministic version is defined in <em>RFC-6979:
  207. * Deterministic Usage of the Digital Signature Algorithm (DSA) and
  208. * Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
  209. *
  210. * \warning It is not thread-safe to use the same context in
  211. * multiple threads.
  212. *
  213. * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
  214. *
  215. * \param ctx The ECDSA context.
  216. * \param hash The Message hash.
  217. * \param hlen The length of the hash.
  218. * \param sig The buffer that holds the signature.
  219. * \param slen The length of the signature written.
  220. * \param md_alg The MD algorithm used to hash the message.
  221. *
  222. * \note The \p sig buffer must be at least twice as large as the
  223. * size of the curve used, plus 9. For example, 73 Bytes if a
  224. * 256-bit curve is used. A buffer length of
  225. * #MBEDTLS_ECDSA_MAX_LEN is always safe.
  226. *
  227. * \note If the bitlength of the message hash is larger than the
  228. * bitlength of the group order, then the hash is truncated as
  229. * defined in <em>Standards for Efficient Cryptography Group
  230. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  231. * 4.1.3, step 5.
  232. *
  233. * \return \c 0 on success,
  234. * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
  235. * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  236. *
  237. * \see ecp.h
  238. */
  239. int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
  240. const unsigned char *hash, size_t hlen,
  241. unsigned char *sig, size_t *slen,
  242. mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
  243. #undef MBEDTLS_DEPRECATED
  244. #endif /* MBEDTLS_DEPRECATED_REMOVED */
  245. #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
  246. /**
  247. * \brief This function reads and verifies an ECDSA signature.
  248. *
  249. * \param ctx The ECDSA context.
  250. * \param hash The message hash.
  251. * \param hlen The size of the hash.
  252. * \param sig The signature to read and verify.
  253. * \param slen The size of \p sig.
  254. *
  255. * \note If the bitlength of the message hash is larger than the
  256. * bitlength of the group order, then the hash is truncated as
  257. * defined in <em>Standards for Efficient Cryptography Group
  258. * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  259. * 4.1.4, step 3.
  260. *
  261. * \return \c 0 on success,
  262. * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
  263. * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
  264. * valid but its actual length is less than \p siglen,
  265. * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
  266. * error code on failure for any other reason.
  267. *
  268. * \see ecp.h
  269. */
  270. int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
  271. const unsigned char *hash, size_t hlen,
  272. const unsigned char *sig, size_t slen );
  273. /**
  274. * \brief This function generates an ECDSA keypair on the given curve.
  275. *
  276. * \param ctx The ECDSA context to store the keypair in.
  277. * \param gid The elliptic curve to use. One of the various
  278. * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
  279. * \param f_rng The RNG function.
  280. * \param p_rng The RNG parameter.
  281. *
  282. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
  283. * failure.
  284. *
  285. * \see ecp.h
  286. */
  287. int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
  288. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  289. /**
  290. * \brief This function sets an ECDSA context from an EC key pair.
  291. *
  292. * \param ctx The ECDSA context to set.
  293. * \param key The EC key to use.
  294. *
  295. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
  296. * failure.
  297. *
  298. * \see ecp.h
  299. */
  300. int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
  301. /**
  302. * \brief This function initializes an ECDSA context.
  303. *
  304. * \param ctx The ECDSA context to initialize.
  305. */
  306. void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
  307. /**
  308. * \brief This function frees an ECDSA context.
  309. *
  310. * \param ctx The ECDSA context to free.
  311. */
  312. void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
  313. #ifdef __cplusplus
  314. }
  315. #endif
  316. #endif /* ecdsa.h */