x509.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331
  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. /* \} name */
  74. /**
  75. * \name X509 Verify codes
  76. * \{
  77. */
  78. /* Reminder: update x509_crt_verify_strings[] in library/x509_crt.c */
  79. #define MBEDTLS_X509_BADCERT_EXPIRED 0x01 /**< The certificate validity has expired. */
  80. #define MBEDTLS_X509_BADCERT_REVOKED 0x02 /**< The certificate has been revoked (is on a CRL). */
  81. #define MBEDTLS_X509_BADCERT_CN_MISMATCH 0x04 /**< The certificate Common Name (CN) does not match with the expected CN. */
  82. #define MBEDTLS_X509_BADCERT_NOT_TRUSTED 0x08 /**< The certificate is not correctly signed by the trusted CA. */
  83. #define MBEDTLS_X509_BADCRL_NOT_TRUSTED 0x10 /**< The CRL is not correctly signed by the trusted CA. */
  84. #define MBEDTLS_X509_BADCRL_EXPIRED 0x20 /**< The CRL is expired. */
  85. #define MBEDTLS_X509_BADCERT_MISSING 0x40 /**< Certificate was missing. */
  86. #define MBEDTLS_X509_BADCERT_SKIP_VERIFY 0x80 /**< Certificate verification was skipped. */
  87. #define MBEDTLS_X509_BADCERT_OTHER 0x0100 /**< Other reason (can be used by verify callback) */
  88. #define MBEDTLS_X509_BADCERT_FUTURE 0x0200 /**< The certificate validity starts in the future. */
  89. #define MBEDTLS_X509_BADCRL_FUTURE 0x0400 /**< The CRL is from the future */
  90. #define MBEDTLS_X509_BADCERT_KEY_USAGE 0x0800 /**< Usage does not match the keyUsage extension. */
  91. #define MBEDTLS_X509_BADCERT_EXT_KEY_USAGE 0x1000 /**< Usage does not match the extendedKeyUsage extension. */
  92. #define MBEDTLS_X509_BADCERT_NS_CERT_TYPE 0x2000 /**< Usage does not match the nsCertType extension. */
  93. #define MBEDTLS_X509_BADCERT_BAD_MD 0x4000 /**< The certificate is signed with an unacceptable hash. */
  94. #define MBEDTLS_X509_BADCERT_BAD_PK 0x8000 /**< The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA). */
  95. #define MBEDTLS_X509_BADCERT_BAD_KEY 0x010000 /**< The certificate is signed with an unacceptable key (eg bad curve, RSA too short). */
  96. #define MBEDTLS_X509_BADCRL_BAD_MD 0x020000 /**< The CRL is signed with an unacceptable hash. */
  97. #define MBEDTLS_X509_BADCRL_BAD_PK 0x040000 /**< The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA). */
  98. #define MBEDTLS_X509_BADCRL_BAD_KEY 0x080000 /**< The CRL is signed with an unacceptable key (eg bad curve, RSA too short). */
  99. /* \} name */
  100. /* \} addtogroup x509_module */
  101. /*
  102. * X.509 v3 Key Usage Extension flags
  103. * Reminder: update x509_info_key_usage() when adding new flags.
  104. */
  105. #define MBEDTLS_X509_KU_DIGITAL_SIGNATURE (0x80) /* bit 0 */
  106. #define MBEDTLS_X509_KU_NON_REPUDIATION (0x40) /* bit 1 */
  107. #define MBEDTLS_X509_KU_KEY_ENCIPHERMENT (0x20) /* bit 2 */
  108. #define MBEDTLS_X509_KU_DATA_ENCIPHERMENT (0x10) /* bit 3 */
  109. #define MBEDTLS_X509_KU_KEY_AGREEMENT (0x08) /* bit 4 */
  110. #define MBEDTLS_X509_KU_KEY_CERT_SIGN (0x04) /* bit 5 */
  111. #define MBEDTLS_X509_KU_CRL_SIGN (0x02) /* bit 6 */
  112. #define MBEDTLS_X509_KU_ENCIPHER_ONLY (0x01) /* bit 7 */
  113. #define MBEDTLS_X509_KU_DECIPHER_ONLY (0x8000) /* bit 8 */
  114. /*
  115. * Netscape certificate types
  116. * (http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn3.html)
  117. */
  118. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT (0x80) /* bit 0 */
  119. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_SERVER (0x40) /* bit 1 */
  120. #define MBEDTLS_X509_NS_CERT_TYPE_EMAIL (0x20) /* bit 2 */
  121. #define MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING (0x10) /* bit 3 */
  122. #define MBEDTLS_X509_NS_CERT_TYPE_RESERVED (0x08) /* bit 4 */
  123. #define MBEDTLS_X509_NS_CERT_TYPE_SSL_CA (0x04) /* bit 5 */
  124. #define MBEDTLS_X509_NS_CERT_TYPE_EMAIL_CA (0x02) /* bit 6 */
  125. #define MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING_CA (0x01) /* bit 7 */
  126. /*
  127. * X.509 extension types
  128. *
  129. * Comments refer to the status for using certificates. Status can be
  130. * different for writing certificates or reading CRLs or CSRs.
  131. */
  132. #define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER (1 << 0)
  133. #define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER (1 << 1)
  134. #define MBEDTLS_X509_EXT_KEY_USAGE (1 << 2)
  135. #define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES (1 << 3)
  136. #define MBEDTLS_X509_EXT_POLICY_MAPPINGS (1 << 4)
  137. #define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME (1 << 5) /* Supported (DNS) */
  138. #define MBEDTLS_X509_EXT_ISSUER_ALT_NAME (1 << 6)
  139. #define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS (1 << 7)
  140. #define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS (1 << 8) /* Supported */
  141. #define MBEDTLS_X509_EXT_NAME_CONSTRAINTS (1 << 9)
  142. #define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS (1 << 10)
  143. #define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE (1 << 11)
  144. #define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS (1 << 12)
  145. #define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY (1 << 13)
  146. #define MBEDTLS_X509_EXT_FRESHEST_CRL (1 << 14)
  147. #define MBEDTLS_X509_EXT_NS_CERT_TYPE (1 << 16) /* Parsed (and then ?) */
  148. /*
  149. * Storage format identifiers
  150. * Recognized formats: PEM and DER
  151. */
  152. #define MBEDTLS_X509_FORMAT_DER 1
  153. #define MBEDTLS_X509_FORMAT_PEM 2
  154. #define MBEDTLS_X509_MAX_DN_NAME_SIZE 256 /**< Maximum value size of a DN entry */
  155. #ifdef __cplusplus
  156. extern "C" {
  157. #endif
  158. /**
  159. * \addtogroup x509_module
  160. * \{ */
  161. /**
  162. * \name Structures for parsing X.509 certificates, CRLs and CSRs
  163. * \{
  164. */
  165. /**
  166. * Type-length-value structure that allows for ASN1 using DER.
  167. */
  168. typedef mbedtls_asn1_buf mbedtls_x509_buf;
  169. /**
  170. * Container for ASN1 bit strings.
  171. */
  172. typedef mbedtls_asn1_bitstring mbedtls_x509_bitstring;
  173. /**
  174. * Container for ASN1 named information objects.
  175. * It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).
  176. */
  177. typedef mbedtls_asn1_named_data mbedtls_x509_name;
  178. /**
  179. * Container for a sequence of ASN.1 items
  180. */
  181. typedef mbedtls_asn1_sequence mbedtls_x509_sequence;
  182. /** Container for date and time (precision in seconds). */
  183. typedef struct mbedtls_x509_time
  184. {
  185. int year, mon, day; /**< Date. */
  186. int hour, min, sec; /**< Time. */
  187. }
  188. mbedtls_x509_time;
  189. /** \} name Structures for parsing X.509 certificates, CRLs and CSRs */
  190. /** \} addtogroup x509_module */
  191. /**
  192. * \brief Store the certificate DN in printable form into buf;
  193. * no more than size characters will be written.
  194. *
  195. * \param buf Buffer to write to
  196. * \param size Maximum size of buffer
  197. * \param dn The X509 name to represent
  198. *
  199. * \return The length of the string written (not including the
  200. * terminated nul byte), or a negative error code.
  201. */
  202. int mbedtls_x509_dn_gets( char *buf, size_t size, const mbedtls_x509_name *dn );
  203. /**
  204. * \brief Store the certificate serial in printable form into buf;
  205. * no more than size characters will be written.
  206. *
  207. * \param buf Buffer to write to
  208. * \param size Maximum size of buffer
  209. * \param serial The X509 serial to represent
  210. *
  211. * \return The length of the string written (not including the
  212. * terminated nul byte), or a negative error code.
  213. */
  214. int mbedtls_x509_serial_gets( char *buf, size_t size, const mbedtls_x509_buf *serial );
  215. /**
  216. * \brief Check a given mbedtls_x509_time against the system time
  217. * and tell if it's in the past.
  218. *
  219. * \note Intended usage is "if( is_past( valid_to ) ) ERROR".
  220. * Hence the return value of 1 if on internal errors.
  221. *
  222. * \param time mbedtls_x509_time to check
  223. *
  224. * \return 1 if the given time is in the past or an error occured,
  225. * 0 otherwise.
  226. */
  227. int mbedtls_x509_time_is_past( const mbedtls_x509_time *time );
  228. /**
  229. * \brief Check a given mbedtls_x509_time against the system time
  230. * and tell if it's in the future.
  231. *
  232. * \note Intended usage is "if( is_future( valid_from ) ) ERROR".
  233. * Hence the return value of 1 if on internal errors.
  234. *
  235. * \param time mbedtls_x509_time to check
  236. *
  237. * \return 1 if the given time is in the future or an error occured,
  238. * 0 otherwise.
  239. */
  240. int mbedtls_x509_time_is_future( const mbedtls_x509_time *time );
  241. /**
  242. * \brief Checkup routine
  243. *
  244. * \return 0 if successful, or 1 if the test failed
  245. */
  246. int mbedtls_x509_self_test( int verbose );
  247. /*
  248. * Internal module functions. You probably do not want to use these unless you
  249. * know you do.
  250. */
  251. int mbedtls_x509_get_name( unsigned char **p, const unsigned char *end,
  252. mbedtls_x509_name *cur );
  253. int mbedtls_x509_get_alg_null( unsigned char **p, const unsigned char *end,
  254. mbedtls_x509_buf *alg );
  255. int mbedtls_x509_get_alg( unsigned char **p, const unsigned char *end,
  256. mbedtls_x509_buf *alg, mbedtls_x509_buf *params );
  257. #if defined(MBEDTLS_X509_RSASSA_PSS_SUPPORT)
  258. int mbedtls_x509_get_rsassa_pss_params( const mbedtls_x509_buf *params,
  259. mbedtls_md_type_t *md_alg, mbedtls_md_type_t *mgf_md,
  260. int *salt_len );
  261. #endif
  262. int mbedtls_x509_get_sig( unsigned char **p, const unsigned char *end, mbedtls_x509_buf *sig );
  263. int mbedtls_x509_get_sig_alg( const mbedtls_x509_buf *sig_oid, const mbedtls_x509_buf *sig_params,
  264. mbedtls_md_type_t *md_alg, mbedtls_pk_type_t *pk_alg,
  265. void **sig_opts );
  266. int mbedtls_x509_get_time( unsigned char **p, const unsigned char *end,
  267. mbedtls_x509_time *time );
  268. int mbedtls_x509_get_serial( unsigned char **p, const unsigned char *end,
  269. mbedtls_x509_buf *serial );
  270. int mbedtls_x509_get_ext( unsigned char **p, const unsigned char *end,
  271. mbedtls_x509_buf *ext, int tag );
  272. int mbedtls_x509_sig_alg_gets( char *buf, size_t size, const mbedtls_x509_buf *sig_oid,
  273. mbedtls_pk_type_t pk_alg, mbedtls_md_type_t md_alg,
  274. const void *sig_opts );
  275. int mbedtls_x509_key_size_helper( char *buf, size_t buf_size, const char *name );
  276. int mbedtls_x509_string_to_names( mbedtls_asn1_named_data **head, const char *name );
  277. int mbedtls_x509_set_extension( mbedtls_asn1_named_data **head, const char *oid, size_t oid_len,
  278. int critical, const unsigned char *val,
  279. size_t val_len );
  280. int mbedtls_x509_write_extensions( unsigned char **p, unsigned char *start,
  281. mbedtls_asn1_named_data *first );
  282. int mbedtls_x509_write_names( unsigned char **p, unsigned char *start,
  283. mbedtls_asn1_named_data *first );
  284. int mbedtls_x509_write_sig( unsigned char **p, unsigned char *start,
  285. const char *oid, size_t oid_len,
  286. unsigned char *sig, size_t size );
  287. #define MBEDTLS_X509_SAFE_SNPRINTF \
  288. do { \
  289. if( ret < 0 || (size_t) ret >= n ) \
  290. return( MBEDTLS_ERR_X509_BUFFER_TOO_SMALL ); \
  291. \
  292. n -= (size_t) ret; \
  293. p += (size_t) ret; \
  294. } while( 0 )
  295. #ifdef __cplusplus
  296. }
  297. #endif
  298. #endif /* x509.h */