ecdsa.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272
  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. #include "ecp.h"
  26. #include "md.h"
  27. /*
  28. * RFC 4492 page 20:
  29. *
  30. * Ecdsa-Sig-Value ::= SEQUENCE {
  31. * r INTEGER,
  32. * s INTEGER
  33. * }
  34. *
  35. * Size is at most
  36. * 1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
  37. * twice that + 1 (tag) + 2 (len) for the sequence
  38. * (assuming ECP_MAX_BYTES is less than 126 for r and s,
  39. * and less than 124 (total len <= 255) for the sequence)
  40. */
  41. #if MBEDTLS_ECP_MAX_BYTES > 124
  42. #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
  43. #endif
  44. /** Maximum size of an ECDSA signature in bytes */
  45. #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
  46. /**
  47. * \brief ECDSA context structure
  48. */
  49. typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53. /**
  54. * \brief Compute ECDSA signature of a previously hashed message
  55. *
  56. * \note The deterministic version is usually prefered.
  57. *
  58. * \param grp ECP group
  59. * \param r First output integer
  60. * \param s Second output integer
  61. * \param d Private signing key
  62. * \param buf Message hash
  63. * \param blen Length of buf
  64. * \param f_rng RNG function
  65. * \param p_rng RNG parameter
  66. *
  67. * \note If the bitlength of the message hash is larger than the
  68. * bitlength of the group order, then the hash is truncated as
  69. * prescribed by SEC1 4.1.3 step 5.
  70. *
  71. * \return 0 if successful,
  72. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  73. */
  74. int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  75. const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  76. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  77. #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
  78. /**
  79. * \brief Compute ECDSA signature of a previously hashed message,
  80. * deterministic version (RFC 6979).
  81. *
  82. * \param grp ECP group
  83. * \param r First output integer
  84. * \param s Second output integer
  85. * \param d Private signing key
  86. * \param buf Message hash
  87. * \param blen Length of buf
  88. * \param md_alg MD algorithm used to hash the message
  89. *
  90. * \note If the bitlength of the message hash is larger than the
  91. * bitlength of the group order, then the hash is truncated as
  92. * prescribed by SEC1 4.1.3 step 5.
  93. *
  94. * \return 0 if successful,
  95. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  96. */
  97. int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
  98. const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
  99. mbedtls_md_type_t md_alg );
  100. #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
  101. /**
  102. * \brief Verify ECDSA signature of a previously hashed message
  103. *
  104. * \param grp ECP group
  105. * \param buf Message hash
  106. * \param blen Length of buf
  107. * \param Q Public key to use for verification
  108. * \param r First integer of the signature
  109. * \param s Second integer of the signature
  110. *
  111. * \note If the bitlength of the message hash is larger than the
  112. * bitlength of the group order, then the hash is truncated as
  113. * prescribed by SEC1 4.1.4 step 3.
  114. *
  115. * \return 0 if successful,
  116. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
  117. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  118. */
  119. int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
  120. const unsigned char *buf, size_t blen,
  121. const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
  122. /**
  123. * \brief Compute ECDSA signature and write it to buffer,
  124. * serialized as defined in RFC 4492 page 20.
  125. * (Not thread-safe to use same context in multiple threads)
  126. *
  127. * \note The deterministic version (RFC 6979) is used if
  128. * MBEDTLS_ECDSA_DETERMINISTIC is defined.
  129. *
  130. * \param ctx ECDSA context
  131. * \param md_alg Algorithm that was used to hash the message
  132. * \param hash Message hash
  133. * \param hlen Length of hash
  134. * \param sig Buffer that will hold the signature
  135. * \param slen Length of the signature written
  136. * \param f_rng RNG function
  137. * \param p_rng RNG parameter
  138. *
  139. * \note The "sig" buffer must be at least as large as twice the
  140. * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
  141. * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
  142. *
  143. * \note If the bitlength of the message hash is larger than the
  144. * bitlength of the group order, then the hash is truncated as
  145. * prescribed by SEC1 4.1.3 step 5.
  146. *
  147. * \return 0 if successful,
  148. * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
  149. * MBEDTLS_ERR_ASN1_XXX error code
  150. */
  151. int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
  152. const unsigned char *hash, size_t hlen,
  153. unsigned char *sig, size_t *slen,
  154. int (*f_rng)(void *, unsigned char *, size_t),
  155. void *p_rng );
  156. #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
  157. #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
  158. #if defined(MBEDTLS_DEPRECATED_WARNING)
  159. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  160. #else
  161. #define MBEDTLS_DEPRECATED
  162. #endif
  163. /**
  164. * \brief Compute ECDSA signature and write it to buffer,
  165. * serialized as defined in RFC 4492 page 20.
  166. * Deterministic version, RFC 6979.
  167. * (Not thread-safe to use same context in multiple threads)
  168. *
  169. * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
  170. *
  171. * \param ctx ECDSA context
  172. * \param hash Message hash
  173. * \param hlen Length of hash
  174. * \param sig Buffer that will hold the signature
  175. * \param slen Length of the signature written
  176. * \param md_alg MD algorithm used to hash the message
  177. *
  178. * \note The "sig" buffer must be at least as large as twice the
  179. * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
  180. * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
  181. *
  182. * \note If the bitlength of the message hash is larger than the
  183. * bitlength of the group order, then the hash is truncated as
  184. * prescribed by SEC1 4.1.3 step 5.
  185. *
  186. * \return 0 if successful,
  187. * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
  188. * MBEDTLS_ERR_ASN1_XXX error code
  189. */
  190. int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
  191. const unsigned char *hash, size_t hlen,
  192. unsigned char *sig, size_t *slen,
  193. mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
  194. #undef MBEDTLS_DEPRECATED
  195. #endif /* MBEDTLS_DEPRECATED_REMOVED */
  196. #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
  197. /**
  198. * \brief Read and verify an ECDSA signature
  199. *
  200. * \param ctx ECDSA context
  201. * \param hash Message hash
  202. * \param hlen Size of hash
  203. * \param sig Signature to read and verify
  204. * \param slen Size of sig
  205. *
  206. * \note If the bitlength of the message hash is larger than the
  207. * bitlength of the group order, then the hash is truncated as
  208. * prescribed by SEC1 4.1.4 step 3.
  209. *
  210. * \return 0 if successful,
  211. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
  212. * MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
  213. * valid but its actual length is less than siglen,
  214. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
  215. */
  216. int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
  217. const unsigned char *hash, size_t hlen,
  218. const unsigned char *sig, size_t slen );
  219. /**
  220. * \brief Generate an ECDSA keypair on the given curve
  221. *
  222. * \param ctx ECDSA context in which the keypair should be stored
  223. * \param gid Group (elliptic curve) to use. One of the various
  224. * MBEDTLS_ECP_DP_XXX macros depending on configuration.
  225. * \param f_rng RNG function
  226. * \param p_rng RNG parameter
  227. *
  228. * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
  229. */
  230. int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
  231. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  232. /**
  233. * \brief Set an ECDSA context from an EC key pair
  234. *
  235. * \param ctx ECDSA context to set
  236. * \param key EC key to use
  237. *
  238. * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code.
  239. */
  240. int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
  241. /**
  242. * \brief Initialize context
  243. *
  244. * \param ctx Context to initialize
  245. */
  246. void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
  247. /**
  248. * \brief Free context
  249. *
  250. * \param ctx Context to free
  251. */
  252. void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
  253. #ifdef __cplusplus
  254. }
  255. #endif
  256. #endif /* ecdsa.h */