x509.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332
  1. /**
  2. * \file x509.h
  3. *
  4. * \brief X.509 generic defines and structures
  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_X509_H
  24. #define MBEDTLS_X509_H
  25. #if !defined(MBEDTLS_CONFIG_FILE)
  26. #include "config.h"
  27. #else
  28. #include MBEDTLS_CONFIG_FILE
  29. #endif
  30. #include "asn1.h"
  31. #include "pk.h"
  32. #if defined(MBEDTLS_RSA_C)
  33. #include "rsa.h"
  34. #endif
  35. /**
  36. * \addtogroup x509_module
  37. * \{
  38. */
  39. #if !defined(MBEDTLS_X509_MAX_INTERMEDIATE_CA)
  40. /**
  41. * Maximum number of intermediate CAs in a verification chain.
  42. * That is, maximum length of the chain, excluding the end-entity certificate
  43. * and the trusted root certificate.
  44. *
  45. * Set this to a low value to prevent an adversary from making you waste
  46. * resources verifying an overlong certificate chain.
  47. */
  48. #define MBEDTLS_X509_MAX_INTERMEDIATE_CA 8
  49. #endif
  50. /**
  51. * \name X509 Error codes
  52. * \{
  53. */
  54. #define MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE -0x2080 /**< Unavailable feature, e.g. RSA hashing/encryption combination. */
  55. #define MBEDTLS_ERR_X509_UNKNOWN_OID -0x2100 /**< Requested OID is unknown. */
  56. #define MBEDTLS_ERR_X509_INVALID_FORMAT -0x2180 /**< The CRT/CRL/CSR format is invalid, e.g. different type expected. */
  57. #define MBEDTLS_ERR_X509_INVALID_VERSION -0x2200 /**< The CRT/CRL/CSR version element is invalid. */
  58. #define MBEDTLS_ERR_X509_INVALID_SERIAL -0x2280 /**< The serial tag or value is invalid. */
  59. #define MBEDTLS_ERR_X509_INVALID_ALG -0x2300 /**< The algorithm tag or value is invalid. */
  60. #define MBEDTLS_ERR_X509_INVALID_NAME -0x2380 /**< The name tag or value is invalid. */
  61. #define MBEDTLS_ERR_X509_INVALID_DATE -0x2400 /**< The date tag or value is invalid. */
  62. #define MBEDTLS_ERR_X509_INVALID_SIGNATURE -0x2480 /**< The signature tag or value invalid. */
  63. #define MBEDTLS_ERR_X509_INVALID_EXTENSIONS -0x2500 /**< The extension tag or value is invalid. */
  64. #define MBEDTLS_ERR_X509_UNKNOWN_VERSION -0x2580 /**< CRT/CRL/CSR has an unsupported version number. */
  65. #define MBEDTLS_ERR_X509_UNKNOWN_SIG_ALG -0x2600 /**< Signature algorithm (oid) is unsupported. */
  66. #define MBEDTLS_ERR_X509_SIG_MISMATCH -0x2680 /**< Signature algorithms do not match. (see \c ::mbedtls_x509_crt sig_oid) */
  67. #define MBEDTLS_ERR_X509_CERT_VERIFY_FAILED -0x2700 /**< Certificate verification failed, e.g. CRL, CA or signature check failed. */
  68. #define MBEDTLS_ERR_X509_CERT_UNKNOWN_FORMAT -0x2780 /**< Format not recognized as DER or PEM. */
  69. #define MBEDTLS_ERR_X509_BAD_INPUT_DATA -0x2800 /**< Input invalid. */
  70. #define MBEDTLS_ERR_X509_ALLOC_FAILED -0x2880 /**< Allocation of memory failed. */
  71. #define MBEDTLS_ERR_X509_FILE_IO_ERROR -0x2900 /**< Read/write of file failed. */
  72. #define MBEDTLS_ERR_X509_BUFFER_TOO_SMALL -0x2980 /**< Destination buffer is too small. */
  73. #define MBEDTLS_ERR_X509_FATAL_ERROR -0x3000 /**< A fatal error occured, eg the chain is too long or the vrfy callback failed. */
  74. /* \} name */
  75. /**
  76. * \name X509 Verify codes
  77. * \{
  78. */
  79. /* Reminder: update x509_crt_verify_strings[] in library/x509_crt.c */
  80. #define MBEDTLS_X509_BADCERT_EXPIRED 0x01 /**< The certificate validity has expired. */
  81. #define MBEDTLS_X509_BADCERT_REVOKED 0x02 /**< The certificate has been revoked (is on a CRL). */
  82. #define MBEDTLS_X509_BADCERT_CN_MISMATCH 0x04 /**< The certificate Common Name (CN) does not match with the expected CN. */
  83. #define MBEDTLS_X509_BADCERT_NOT_TRUSTED 0x08 /**< The certificate is not correctly signed by the trusted CA. */
  84. #define MBEDTLS_X509_BADCRL_NOT_TRUSTED 0x10 /**< The CRL is not correctly signed by the trusted CA. */
  85. #define MBEDTLS_X509_BADCRL_EXPIRED 0x20 /**< The CRL is expired. */
  86. #define MBEDTLS_X509_BADCERT_MISSING 0x40 /**< Certificate was missing. */
  87. #define MBEDTLS_X509_BADCERT_SKIP_VERIFY 0x80 /**< Certificate verification was skipped. */
  88. #define MBEDTLS_X509_BADCERT_OTHER 0x0100 /**< Other reason (can be used by verify callback) */
  89. #define MBEDTLS_X509_BADCERT_FUTURE 0x0200 /**< The certificate validity starts in the future. */
  90. #define MBEDTLS_X509_BADCRL_FUTURE 0x0400 /**< The CRL is from the future */
  91. #define MBEDTLS_X509_BADCERT_KEY_USAGE 0x0800 /**< Usage does not match the keyUsage extension. */
  92. #define MBEDTLS_X509_BADCERT_EXT_KEY_USAGE 0x1000 /**< Usage does not match the extendedKeyUsage extension. */
  93. #define MBEDTLS_X509_BADCERT_NS_CERT_TYPE 0x2000 /**< Usage does not match the nsCertType extension. */
  94. #define MBEDTLS_X509_BADCERT_BAD_MD 0x4000 /**< The certificate is signed with an unacceptable hash. */
  95. #define MBEDTLS_X509_BADCERT_BAD_PK 0x8000 /**< The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA). */
  96. #define MBEDTLS_X509_BADCERT_BAD_KEY 0x010000 /**< The certificate is signed with an unacceptable key (eg bad curve, RSA too short). */
  97. #define MBEDTLS_X509_BADCRL_BAD_MD 0x020000 /**< The CRL is signed with an unacceptable hash. */
  98. #define MBEDTLS_X509_BADCRL_BAD_PK 0x040000 /**< The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA). */
  99. #define MBEDTLS_X509_BADCRL_BAD_KEY 0x080000 /**< The CRL is signed with an unacceptable key (eg bad curve, RSA too short). */
  100. /* \} name */
  101. /* \} addtogroup x509_module */
  102. /*
  103. * X.509 v3 Key Usage Extension flags
  104. * Reminder: update x509_info_key_usage() when adding new flags.
  105. */
  106. #define MBEDTLS_X509_KU_DIGITAL_SIGNATURE (0x80) /* bit 0 */
  107. #define MBEDTLS_X509_KU_NON_REPUDIATION (0x40) /* bit 1 */
  108. #define MBEDTLS_X509_KU_KEY_ENCIPHERMENT (0x20) /* bit 2 */
  109. #define MBEDTLS_X509_KU_DATA_ENCIPHERMENT (0x10) /* bit 3 */
  110. #define MBEDTLS_X509_KU_KEY_AGREEMENT (0x08) /* bit 4 */
  111. #define MBEDTLS_X509_KU_KEY_CERT_SIGN (0x04) /* bit 5 */
  112. #define MBEDTLS_X509_KU_CRL_SIGN (0x02) /* bit 6 */
  113. #define MBEDTLS_X509_KU_ENCIPHER_ONLY (0x01) /* bit 7 */
  114. #define MBEDTLS_X509_KU_DECIPHER_ONLY (0x8000) /* bit 8 */
  115. /*
  116. * Netscape certificate types
  117. * (http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn3.html)
  118. */
  119. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT (0x80) /* bit 0 */
  120. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_SERVER (0x40) /* bit 1 */
  121. #define MBEDTLS_X509_NS_CERT_TYPE_EMAIL (0x20) /* bit 2 */
  122. #define MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING (0x10) /* bit 3 */
  123. #define MBEDTLS_X509_NS_CERT_TYPE_RESERVED (0x08) /* bit 4 */
  124. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_CA (0x04) /* bit 5 */
  125. #define MBEDTLS_X509_NS_CERT_TYPE_EMAIL_CA (0x02) /* bit 6 */
  126. #define MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING_CA (0x01) /* bit 7 */
  127. /*
  128. * X.509 extension types
  129. *
  130. * Comments refer to the status for using certificates. Status can be
  131. * different for writing certificates or reading CRLs or CSRs.
  132. */
  133. #define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER (1 << 0)
  134. #define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER (1 << 1)
  135. #define MBEDTLS_X509_EXT_KEY_USAGE (1 << 2)
  136. #define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES (1 << 3)
  137. #define MBEDTLS_X509_EXT_POLICY_MAPPINGS (1 << 4)
  138. #define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME (1 << 5) /* Supported (DNS) */
  139. #define MBEDTLS_X509_EXT_ISSUER_ALT_NAME (1 << 6)
  140. #define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS (1 << 7)
  141. #define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS (1 << 8) /* Supported */
  142. #define MBEDTLS_X509_EXT_NAME_CONSTRAINTS (1 << 9)
  143. #define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS (1 << 10)
  144. #define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE (1 << 11)
  145. #define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS (1 << 12)
  146. #define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY (1 << 13)
  147. #define MBEDTLS_X509_EXT_FRESHEST_CRL (1 << 14)
  148. #define MBEDTLS_X509_EXT_NS_CERT_TYPE (1 << 16)
  149. /*
  150. * Storage format identifiers
  151. * Recognized formats: PEM and DER
  152. */
  153. #define MBEDTLS_X509_FORMAT_DER 1
  154. #define MBEDTLS_X509_FORMAT_PEM 2
  155. #define MBEDTLS_X509_MAX_DN_NAME_SIZE 256 /**< Maximum value size of a DN entry */
  156. #ifdef __cplusplus
  157. extern "C" {
  158. #endif
  159. /**
  160. * \addtogroup x509_module
  161. * \{ */
  162. /**
  163. * \name Structures for parsing X.509 certificates, CRLs and CSRs
  164. * \{
  165. */
  166. /**
  167. * Type-length-value structure that allows for ASN1 using DER.
  168. */
  169. typedef mbedtls_asn1_buf mbedtls_x509_buf;
  170. /**
  171. * Container for ASN1 bit strings.
  172. */
  173. typedef mbedtls_asn1_bitstring mbedtls_x509_bitstring;
  174. /**
  175. * Container for ASN1 named information objects.
  176. * It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).
  177. */
  178. typedef mbedtls_asn1_named_data mbedtls_x509_name;
  179. /**
  180. * Container for a sequence of ASN.1 items
  181. */
  182. typedef mbedtls_asn1_sequence mbedtls_x509_sequence;
  183. /** Container for date and time (precision in seconds). */
  184. typedef struct mbedtls_x509_time
  185. {
  186. int year, mon, day; /**< Date. */
  187. int hour, min, sec; /**< Time. */
  188. }
  189. mbedtls_x509_time;
  190. /** \} name Structures for parsing X.509 certificates, CRLs and CSRs */
  191. /** \} addtogroup x509_module */
  192. /**
  193. * \brief Store the certificate DN in printable form into buf;
  194. * no more than size characters will be written.
  195. *
  196. * \param buf Buffer to write to
  197. * \param size Maximum size of buffer
  198. * \param dn The X509 name to represent
  199. *
  200. * \return The length of the string written (not including the
  201. * terminated nul byte), or a negative error code.
  202. */
  203. int mbedtls_x509_dn_gets( char *buf, size_t size, const mbedtls_x509_name *dn );
  204. /**
  205. * \brief Store the certificate serial in printable form into buf;
  206. * no more than size characters will be written.
  207. *
  208. * \param buf Buffer to write to
  209. * \param size Maximum size of buffer
  210. * \param serial The X509 serial to represent
  211. *
  212. * \return The length of the string written (not including the
  213. * terminated nul byte), or a negative error code.
  214. */
  215. int mbedtls_x509_serial_gets( char *buf, size_t size, const mbedtls_x509_buf *serial );
  216. /**
  217. * \brief Check a given mbedtls_x509_time against the system time
  218. * and tell if it's in the past.
  219. *
  220. * \note Intended usage is "if( is_past( valid_to ) ) ERROR".
  221. * Hence the return value of 1 if on internal errors.
  222. *
  223. * \param to mbedtls_x509_time to check
  224. *
  225. * \return 1 if the given time is in the past or an error occured,
  226. * 0 otherwise.
  227. */
  228. int mbedtls_x509_time_is_past( const mbedtls_x509_time *to );
  229. /**
  230. * \brief Check a given mbedtls_x509_time against the system time
  231. * and tell if it's in the future.
  232. *
  233. * \note Intended usage is "if( is_future( valid_from ) ) ERROR".
  234. * Hence the return value of 1 if on internal errors.
  235. *
  236. * \param from mbedtls_x509_time to check
  237. *
  238. * \return 1 if the given time is in the future or an error occured,
  239. * 0 otherwise.
  240. */
  241. int mbedtls_x509_time_is_future( const mbedtls_x509_time *from );
  242. /**
  243. * \brief Checkup routine
  244. *
  245. * \return 0 if successful, or 1 if the test failed
  246. */
  247. int mbedtls_x509_self_test( int verbose );
  248. /*
  249. * Internal module functions. You probably do not want to use these unless you
  250. * know you do.
  251. */
  252. int mbedtls_x509_get_name( unsigned char **p, const unsigned char *end,
  253. mbedtls_x509_name *cur );
  254. int mbedtls_x509_get_alg_null( unsigned char **p, const unsigned char *end,
  255. mbedtls_x509_buf *alg );
  256. int mbedtls_x509_get_alg( unsigned char **p, const unsigned char *end,
  257. mbedtls_x509_buf *alg, mbedtls_x509_buf *params );
  258. #if defined(MBEDTLS_X509_RSASSA_PSS_SUPPORT)
  259. int mbedtls_x509_get_rsassa_pss_params( const mbedtls_x509_buf *params,
  260. mbedtls_md_type_t *md_alg, mbedtls_md_type_t *mgf_md,
  261. int *salt_len );
  262. #endif
  263. int mbedtls_x509_get_sig( unsigned char **p, const unsigned char *end, mbedtls_x509_buf *sig );
  264. int mbedtls_x509_get_sig_alg( const mbedtls_x509_buf *sig_oid, const mbedtls_x509_buf *sig_params,
  265. mbedtls_md_type_t *md_alg, mbedtls_pk_type_t *pk_alg,
  266. void **sig_opts );
  267. int mbedtls_x509_get_time( unsigned char **p, const unsigned char *end,
  268. mbedtls_x509_time *t );
  269. int mbedtls_x509_get_serial( unsigned char **p, const unsigned char *end,
  270. mbedtls_x509_buf *serial );
  271. int mbedtls_x509_get_ext( unsigned char **p, const unsigned char *end,
  272. mbedtls_x509_buf *ext, int tag );
  273. int mbedtls_x509_sig_alg_gets( char *buf, size_t size, const mbedtls_x509_buf *sig_oid,
  274. mbedtls_pk_type_t pk_alg, mbedtls_md_type_t md_alg,
  275. const void *sig_opts );
  276. int mbedtls_x509_key_size_helper( char *buf, size_t buf_size, const char *name );
  277. int mbedtls_x509_string_to_names( mbedtls_asn1_named_data **head, const char *name );
  278. int mbedtls_x509_set_extension( mbedtls_asn1_named_data **head, const char *oid, size_t oid_len,
  279. int critical, const unsigned char *val,
  280. size_t val_len );
  281. int mbedtls_x509_write_extensions( unsigned char **p, unsigned char *start,
  282. mbedtls_asn1_named_data *first );
  283. int mbedtls_x509_write_names( unsigned char **p, unsigned char *start,
  284. mbedtls_asn1_named_data *first );
  285. int mbedtls_x509_write_sig( unsigned char **p, unsigned char *start,
  286. const char *oid, size_t oid_len,
  287. unsigned char *sig, size_t size );
  288. #define MBEDTLS_X509_SAFE_SNPRINTF \
  289. do { \
  290. if( ret < 0 || (size_t) ret >= n ) \
  291. return( MBEDTLS_ERR_X509_BUFFER_TOO_SMALL ); \
  292. \
  293. n -= (size_t) ret; \
  294. p += (size_t) ret; \
  295. } while( 0 )
  296. #ifdef __cplusplus
  297. }
  298. #endif
  299. #endif /* x509.h */