EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-08-27 09:37:35
0001 /** 0002 * \file x509_crt.h 0003 * 0004 * \brief X.509 certificate parsing and writing 0005 */ 0006 /* 0007 * Copyright The Mbed TLS Contributors 0008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0009 */ 0010 #ifndef MBEDTLS_X509_CRT_H 0011 #define MBEDTLS_X509_CRT_H 0012 #include "mbedtls/private_access.h" 0013 0014 #include "mbedtls/build_info.h" 0015 0016 #include "mbedtls/x509.h" 0017 #include "mbedtls/x509_crl.h" 0018 #include "mbedtls/bignum.h" 0019 0020 /** 0021 * \addtogroup x509_module 0022 * \{ 0023 */ 0024 0025 #ifdef __cplusplus 0026 extern "C" { 0027 #endif 0028 0029 /** 0030 * \name Structures and functions for parsing and writing X.509 certificates 0031 * \{ 0032 */ 0033 0034 /** 0035 * Container for an X.509 certificate. The certificate may be chained. 0036 * 0037 * Some fields of this structure are publicly readable. Do not modify 0038 * them except via Mbed TLS library functions: the effect of modifying 0039 * those fields or the data that those fields points to is unspecified. 0040 */ 0041 typedef struct mbedtls_x509_crt { 0042 int MBEDTLS_PRIVATE(own_buffer); /**< Indicates if \c raw is owned 0043 * by the structure or not. */ 0044 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */ 0045 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */ 0046 0047 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */ 0048 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */ 0049 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */ 0050 0051 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */ 0052 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */ 0053 0054 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */ 0055 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */ 0056 0057 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */ 0058 mbedtls_x509_time valid_to; /**< End time of certificate validity. */ 0059 0060 mbedtls_x509_buf pk_raw; 0061 mbedtls_pk_context pk; /**< Container for the public key context. */ 0062 0063 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */ 0064 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */ 0065 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */ 0066 mbedtls_x509_sequence subject_alt_names; /**< Optional list of raw entries of Subject Alternative Names extension. These can be later parsed by mbedtls_x509_parse_subject_alt_name. */ 0067 mbedtls_x509_buf subject_key_id; /**< Optional X.509 v3 extension subject key identifier. */ 0068 mbedtls_x509_authority authority_key_id; /**< Optional X.509 v3 extension authority key identifier. */ 0069 0070 mbedtls_x509_sequence certificate_policies; /**< Optional list of certificate policies (Only anyPolicy is printed and enforced, however the rest of the policies are still listed). */ 0071 0072 int MBEDTLS_PRIVATE(ext_types); /**< Bit string containing detected and parsed extensions */ 0073 int MBEDTLS_PRIVATE(ca_istrue); /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */ 0074 int MBEDTLS_PRIVATE(max_pathlen); /**< Optional Basic Constraint extension value: The maximum path length to the root certificate. Path length is 1 higher than RFC 5280 'meaning', so 1+ */ 0075 0076 unsigned int MBEDTLS_PRIVATE(key_usage); /**< Optional key usage extension value: See the values in x509.h */ 0077 0078 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */ 0079 0080 unsigned char MBEDTLS_PRIVATE(ns_cert_type); /**< Optional Netscape certificate type extension value: See the values in x509.h */ 0081 0082 mbedtls_x509_buf MBEDTLS_PRIVATE(sig); /**< Signature: hash of the tbs part signed with the private key. */ 0083 mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md); /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */ 0084 mbedtls_pk_type_t MBEDTLS_PRIVATE(sig_pk); /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */ 0085 void *MBEDTLS_PRIVATE(sig_opts); /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */ 0086 0087 /** Next certificate in the linked list that constitutes the CA chain. 0088 * \p NULL indicates the end of the list. 0089 * Do not modify this field directly. */ 0090 struct mbedtls_x509_crt *next; 0091 } 0092 mbedtls_x509_crt; 0093 0094 /** 0095 * Build flag from an algorithm/curve identifier (pk, md, ecp) 0096 * Since 0 is always XXX_NONE, ignore it. 0097 */ 0098 #define MBEDTLS_X509_ID_FLAG(id) (1 << ((id) - 1)) 0099 0100 /** 0101 * Security profile for certificate verification. 0102 * 0103 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG(). 0104 * 0105 * The fields of this structure are part of the public API and can be 0106 * manipulated directly by applications. Future versions of the library may 0107 * add extra fields or reorder existing fields. 0108 * 0109 * You can create custom profiles by starting from a copy of 0110 * an existing profile, such as mbedtls_x509_crt_profile_default or 0111 * mbedtls_x509_ctr_profile_none and then tune it to your needs. 0112 * 0113 * For example to allow SHA-224 in addition to the default: 0114 * 0115 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; 0116 * my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); 0117 * 0118 * Or to allow only RSA-3072+ with SHA-256: 0119 * 0120 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_none; 0121 * my_profile.allowed_mds = MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA256 ); 0122 * my_profile.allowed_pks = MBEDTLS_X509_ID_FLAG( MBEDTLS_PK_RSA ); 0123 * my_profile.rsa_min_bitlen = 3072; 0124 */ 0125 typedef struct mbedtls_x509_crt_profile { 0126 uint32_t allowed_mds; /**< MDs for signatures */ 0127 uint32_t allowed_pks; /**< PK algs for public keys; 0128 * this applies to all certificates 0129 * in the provided chain. */ 0130 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */ 0131 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */ 0132 } 0133 mbedtls_x509_crt_profile; 0134 0135 #define MBEDTLS_X509_CRT_VERSION_1 0 0136 #define MBEDTLS_X509_CRT_VERSION_2 1 0137 #define MBEDTLS_X509_CRT_VERSION_3 2 0138 0139 #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 20 0140 #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15 0141 0142 #if !defined(MBEDTLS_X509_MAX_FILE_PATH_LEN) 0143 #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 0144 #endif 0145 0146 /* This macro unfolds to the concatenation of macro invocations 0147 * X509_CRT_ERROR_INFO( error code, 0148 * error code as string, 0149 * human readable description ) 0150 * where X509_CRT_ERROR_INFO is defined by the user. 0151 * See x509_crt.c for an example of how to use this. */ 0152 #define MBEDTLS_X509_CRT_ERROR_INFO_LIST \ 0153 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXPIRED, \ 0154 "MBEDTLS_X509_BADCERT_EXPIRED", \ 0155 "The certificate validity has expired") \ 0156 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_REVOKED, \ 0157 "MBEDTLS_X509_BADCERT_REVOKED", \ 0158 "The certificate has been revoked (is on a CRL)") \ 0159 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_CN_MISMATCH, \ 0160 "MBEDTLS_X509_BADCERT_CN_MISMATCH", \ 0161 "The certificate Common Name (CN) does not match with the expected CN") \ 0162 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NOT_TRUSTED, \ 0163 "MBEDTLS_X509_BADCERT_NOT_TRUSTED", \ 0164 "The certificate is not correctly signed by the trusted CA") \ 0165 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_NOT_TRUSTED, \ 0166 "MBEDTLS_X509_BADCRL_NOT_TRUSTED", \ 0167 "The CRL is not correctly signed by the trusted CA") \ 0168 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_EXPIRED, \ 0169 "MBEDTLS_X509_BADCRL_EXPIRED", \ 0170 "The CRL is expired") \ 0171 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_MISSING, \ 0172 "MBEDTLS_X509_BADCERT_MISSING", \ 0173 "Certificate was missing") \ 0174 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_SKIP_VERIFY, \ 0175 "MBEDTLS_X509_BADCERT_SKIP_VERIFY", \ 0176 "Certificate verification was skipped") \ 0177 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_OTHER, \ 0178 "MBEDTLS_X509_BADCERT_OTHER", \ 0179 "Other reason (can be used by verify callback)") \ 0180 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_FUTURE, \ 0181 "MBEDTLS_X509_BADCERT_FUTURE", \ 0182 "The certificate validity starts in the future") \ 0183 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_FUTURE, \ 0184 "MBEDTLS_X509_BADCRL_FUTURE", \ 0185 "The CRL is from the future") \ 0186 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_KEY_USAGE, \ 0187 "MBEDTLS_X509_BADCERT_KEY_USAGE", \ 0188 "Usage does not match the keyUsage extension") \ 0189 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXT_KEY_USAGE, \ 0190 "MBEDTLS_X509_BADCERT_EXT_KEY_USAGE", \ 0191 "Usage does not match the extendedKeyUsage extension") \ 0192 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NS_CERT_TYPE, \ 0193 "MBEDTLS_X509_BADCERT_NS_CERT_TYPE", \ 0194 "Usage does not match the nsCertType extension") \ 0195 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_MD, \ 0196 "MBEDTLS_X509_BADCERT_BAD_MD", \ 0197 "The certificate is signed with an unacceptable hash.") \ 0198 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_PK, \ 0199 "MBEDTLS_X509_BADCERT_BAD_PK", \ 0200 "The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \ 0201 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_KEY, \ 0202 "MBEDTLS_X509_BADCERT_BAD_KEY", \ 0203 "The certificate is signed with an unacceptable key (eg bad curve, RSA too short).") \ 0204 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_MD, \ 0205 "MBEDTLS_X509_BADCRL_BAD_MD", \ 0206 "The CRL is signed with an unacceptable hash.") \ 0207 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_PK, \ 0208 "MBEDTLS_X509_BADCRL_BAD_PK", \ 0209 "The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \ 0210 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_KEY, \ 0211 "MBEDTLS_X509_BADCRL_BAD_KEY", \ 0212 "The CRL is signed with an unacceptable key (eg bad curve, RSA too short).") 0213 0214 /** 0215 * Container for writing a certificate (CRT) 0216 */ 0217 typedef struct mbedtls_x509write_cert { 0218 int MBEDTLS_PRIVATE(version); 0219 unsigned char MBEDTLS_PRIVATE(serial)[MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN]; 0220 size_t MBEDTLS_PRIVATE(serial_len); 0221 mbedtls_pk_context *MBEDTLS_PRIVATE(subject_key); 0222 mbedtls_pk_context *MBEDTLS_PRIVATE(issuer_key); 0223 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(subject); 0224 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(issuer); 0225 mbedtls_md_type_t MBEDTLS_PRIVATE(md_alg); 0226 char MBEDTLS_PRIVATE(not_before)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1]; 0227 char MBEDTLS_PRIVATE(not_after)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1]; 0228 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(extensions); 0229 } 0230 mbedtls_x509write_cert; 0231 0232 /** 0233 * \brief Set Subject Alternative Name 0234 * 0235 * \param ctx Certificate context to use 0236 * \param san_list List of SAN values 0237 * 0238 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 0239 * 0240 * \note "dnsName", "uniformResourceIdentifier", "IP address", 0241 * "otherName", and "DirectoryName", as defined in RFC 5280, 0242 * are supported. 0243 */ 0244 int mbedtls_x509write_crt_set_subject_alternative_name(mbedtls_x509write_cert *ctx, 0245 const mbedtls_x509_san_list *san_list); 0246 0247 /** 0248 * Item in a verification chain: cert and flags for it 0249 */ 0250 typedef struct { 0251 mbedtls_x509_crt *MBEDTLS_PRIVATE(crt); 0252 uint32_t MBEDTLS_PRIVATE(flags); 0253 } mbedtls_x509_crt_verify_chain_item; 0254 0255 /** 0256 * Max size of verification chain: end-entity + intermediates + trusted root 0257 */ 0258 #define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE (MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2) 0259 0260 /** 0261 * Verification chain as built by \c mbedtls_crt_verify_chain() 0262 */ 0263 typedef struct { 0264 mbedtls_x509_crt_verify_chain_item MBEDTLS_PRIVATE(items)[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE]; 0265 unsigned MBEDTLS_PRIVATE(len); 0266 0267 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 0268 /* This stores the list of potential trusted signers obtained from 0269 * the CA callback used for the CRT verification, if configured. 0270 * We must track it somewhere because the callback passes its 0271 * ownership to the caller. */ 0272 mbedtls_x509_crt *MBEDTLS_PRIVATE(trust_ca_cb_result); 0273 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 0274 } mbedtls_x509_crt_verify_chain; 0275 0276 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE) 0277 0278 /** 0279 * \brief Context for resuming X.509 verify operations 0280 */ 0281 typedef struct { 0282 /* for check_signature() */ 0283 mbedtls_pk_restart_ctx MBEDTLS_PRIVATE(pk); 0284 0285 /* for find_parent_in() */ 0286 mbedtls_x509_crt *MBEDTLS_PRIVATE(parent); /* non-null iff parent_in in progress */ 0287 mbedtls_x509_crt *MBEDTLS_PRIVATE(fallback_parent); 0288 int MBEDTLS_PRIVATE(fallback_signature_is_good); 0289 0290 /* for find_parent() */ 0291 int MBEDTLS_PRIVATE(parent_is_trusted); /* -1 if find_parent is not in progress */ 0292 0293 /* for verify_chain() */ 0294 enum { 0295 x509_crt_rs_none, 0296 x509_crt_rs_find_parent, 0297 } MBEDTLS_PRIVATE(in_progress); /* none if no operation is in progress */ 0298 int MBEDTLS_PRIVATE(self_cnt); 0299 mbedtls_x509_crt_verify_chain MBEDTLS_PRIVATE(ver_chain); 0300 0301 } mbedtls_x509_crt_restart_ctx; 0302 0303 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 0304 0305 /* Now we can declare functions that take a pointer to that */ 0306 typedef void mbedtls_x509_crt_restart_ctx; 0307 0308 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 0309 0310 #if defined(MBEDTLS_X509_CRT_PARSE_C) 0311 /** 0312 * Default security profile. Should provide a good balance between security 0313 * and compatibility with current deployments. 0314 * 0315 * This profile permits: 0316 * - SHA2 hashes with at least 256 bits: SHA-256, SHA-384, SHA-512. 0317 * - Elliptic curves with 255 bits and above except secp256k1. 0318 * - RSA with 2048 bits and above. 0319 * 0320 * New minor versions of Mbed TLS may extend this profile, for example if 0321 * new algorithms are added to the library. New minor versions of Mbed TLS will 0322 * not reduce this profile unless serious security concerns require it. 0323 */ 0324 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default; 0325 0326 /** 0327 * Expected next default profile. Recommended for new deployments. 0328 * Currently targets a 128-bit security level, except for allowing RSA-2048. 0329 * This profile may change at any time. 0330 */ 0331 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next; 0332 0333 /** 0334 * NSA Suite B profile. 0335 */ 0336 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb; 0337 0338 /** 0339 * Empty profile that allows nothing. Useful as a basis for constructing 0340 * custom profiles. 0341 */ 0342 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_none; 0343 0344 /** 0345 * \brief Parse a single DER formatted certificate and add it 0346 * to the end of the provided chained list. 0347 * 0348 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto 0349 * subsystem must have been initialized by calling 0350 * psa_crypto_init() before calling this function. 0351 * 0352 * \param chain The pointer to the start of the CRT chain to attach to. 0353 * When parsing the first CRT in a chain, this should point 0354 * to an instance of ::mbedtls_x509_crt initialized through 0355 * mbedtls_x509_crt_init(). 0356 * \param buf The buffer holding the DER encoded certificate. 0357 * \param buflen The size in Bytes of \p buf. 0358 * 0359 * \note This function makes an internal copy of the CRT buffer 0360 * \p buf. In particular, \p buf may be destroyed or reused 0361 * after this call returns. To avoid duplicating the CRT 0362 * buffer (at the cost of stricter lifetime constraints), 0363 * use mbedtls_x509_crt_parse_der_nocopy() instead. 0364 * 0365 * \return \c 0 if successful. 0366 * \return A negative error code on failure. 0367 */ 0368 int mbedtls_x509_crt_parse_der(mbedtls_x509_crt *chain, 0369 const unsigned char *buf, 0370 size_t buflen); 0371 0372 /** 0373 * \brief The type of certificate extension callbacks. 0374 * 0375 * Callbacks of this type are passed to and used by the 0376 * mbedtls_x509_crt_parse_der_with_ext_cb() routine when 0377 * it encounters either an unsupported extension or a 0378 * "certificate policies" extension containing any 0379 * unsupported certificate policies. 0380 * Future versions of the library may invoke the callback 0381 * in other cases, if and when the need arises. 0382 * 0383 * \param p_ctx An opaque context passed to the callback. 0384 * \param crt The certificate being parsed. 0385 * \param oid The OID of the extension. 0386 * \param critical Whether the extension is critical. 0387 * \param p Pointer to the start of the extension value 0388 * (the content of the OCTET STRING). 0389 * \param end End of extension value. 0390 * 0391 * \note The callback must fail and return a negative error code 0392 * if it can not parse or does not support the extension. 0393 * When the callback fails to parse a critical extension 0394 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails. 0395 * When the callback fails to parse a non critical extension 0396 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips 0397 * the extension and continues parsing. 0398 * 0399 * \return \c 0 on success. 0400 * \return A negative error code on failure. 0401 */ 0402 typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx, 0403 mbedtls_x509_crt const *crt, 0404 mbedtls_x509_buf const *oid, 0405 int critical, 0406 const unsigned char *p, 0407 const unsigned char *end); 0408 0409 /** 0410 * \brief Parse a single DER formatted certificate and add it 0411 * to the end of the provided chained list. 0412 * 0413 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto 0414 * subsystem must have been initialized by calling 0415 * psa_crypto_init() before calling this function. 0416 * 0417 * \param chain The pointer to the start of the CRT chain to attach to. 0418 * When parsing the first CRT in a chain, this should point 0419 * to an instance of ::mbedtls_x509_crt initialized through 0420 * mbedtls_x509_crt_init(). 0421 * \param buf The buffer holding the DER encoded certificate. 0422 * \param buflen The size in Bytes of \p buf. 0423 * \param make_copy When not zero this function makes an internal copy of the 0424 * CRT buffer \p buf. In particular, \p buf may be destroyed 0425 * or reused after this call returns. 0426 * When zero this function avoids duplicating the CRT buffer 0427 * by taking temporary ownership thereof until the CRT 0428 * is destroyed (like mbedtls_x509_crt_parse_der_nocopy()) 0429 * \param cb A callback invoked for every unsupported certificate 0430 * extension. 0431 * \param p_ctx An opaque context passed to the callback. 0432 * 0433 * \note This call is functionally equivalent to 0434 * mbedtls_x509_crt_parse_der(), and/or 0435 * mbedtls_x509_crt_parse_der_nocopy() 0436 * but it calls the callback with every unsupported 0437 * certificate extension and additionally the 0438 * "certificate policies" extension if it contains any 0439 * unsupported certificate policies. 0440 * The callback must return a negative error code if it 0441 * does not know how to handle such an extension. 0442 * When the callback fails to parse a critical extension 0443 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails. 0444 * When the callback fails to parse a non critical extension 0445 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips 0446 * the extension and continues parsing. 0447 * Future versions of the library may invoke the callback 0448 * in other cases, if and when the need arises. 0449 * 0450 * \return \c 0 if successful. 0451 * \return A negative error code on failure. 0452 */ 0453 int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain, 0454 const unsigned char *buf, 0455 size_t buflen, 0456 int make_copy, 0457 mbedtls_x509_crt_ext_cb_t cb, 0458 void *p_ctx); 0459 0460 /** 0461 * \brief Parse a single DER formatted certificate and add it 0462 * to the end of the provided chained list. This is a 0463 * variant of mbedtls_x509_crt_parse_der() which takes 0464 * temporary ownership of the CRT buffer until the CRT 0465 * is destroyed. 0466 * 0467 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto 0468 * subsystem must have been initialized by calling 0469 * psa_crypto_init() before calling this function. 0470 * 0471 * \param chain The pointer to the start of the CRT chain to attach to. 0472 * When parsing the first CRT in a chain, this should point 0473 * to an instance of ::mbedtls_x509_crt initialized through 0474 * mbedtls_x509_crt_init(). 0475 * \param buf The address of the readable buffer holding the DER encoded 0476 * certificate to use. On success, this buffer must be 0477 * retained and not be changed for the lifetime of the 0478 * CRT chain \p chain, that is, until \p chain is destroyed 0479 * through a call to mbedtls_x509_crt_free(). 0480 * \param buflen The size in Bytes of \p buf. 0481 * 0482 * \note This call is functionally equivalent to 0483 * mbedtls_x509_crt_parse_der(), but it avoids creating a 0484 * copy of the input buffer at the cost of stronger lifetime 0485 * constraints. This is useful in constrained environments 0486 * where duplication of the CRT cannot be tolerated. 0487 * 0488 * \return \c 0 if successful. 0489 * \return A negative error code on failure. 0490 */ 0491 int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain, 0492 const unsigned char *buf, 0493 size_t buflen); 0494 0495 /** 0496 * \brief Parse one DER-encoded or one or more concatenated PEM-encoded 0497 * certificates and add them to the chained list. 0498 * 0499 * For CRTs in PEM encoding, the function parses permissively: 0500 * if at least one certificate can be parsed, the function 0501 * returns the number of certificates for which parsing failed 0502 * (hence \c 0 if all certificates were parsed successfully). 0503 * If no certificate could be parsed, the function returns 0504 * the first (negative) error encountered during parsing. 0505 * 0506 * PEM encoded certificates may be interleaved by other data 0507 * such as human readable descriptions of their content, as 0508 * long as the certificates are enclosed in the PEM specific 0509 * '-----{BEGIN/END} CERTIFICATE-----' delimiters. 0510 * 0511 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto 0512 * subsystem must have been initialized by calling 0513 * psa_crypto_init() before calling this function. 0514 * 0515 * \param chain The chain to which to add the parsed certificates. 0516 * \param buf The buffer holding the certificate data in PEM or DER format. 0517 * For certificates in PEM encoding, this may be a concatenation 0518 * of multiple certificates; for DER encoding, the buffer must 0519 * comprise exactly one certificate. 0520 * \param buflen The size of \p buf, including the terminating \c NULL byte 0521 * in case of PEM encoded data. 0522 * 0523 * \return \c 0 if all certificates were parsed successfully. 0524 * \return The (positive) number of certificates that couldn't 0525 * be parsed if parsing was partly successful (see above). 0526 * \return A negative X509 or PEM error code otherwise. 0527 * 0528 */ 0529 int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen); 0530 0531 #if defined(MBEDTLS_FS_IO) 0532 /** 0533 * \brief Load one or more certificates and add them 0534 * to the chained list. Parses permissively. If some 0535 * certificates can be parsed, the result is the number 0536 * of failed certificates it encountered. If none complete 0537 * correctly, the first error is returned. 0538 * 0539 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto 0540 * subsystem must have been initialized by calling 0541 * psa_crypto_init() before calling this function. 0542 * 0543 * \param chain points to the start of the chain 0544 * \param path filename to read the certificates from 0545 * 0546 * \return 0 if all certificates parsed successfully, a positive number 0547 * if partly successful or a specific X509 or PEM error code 0548 */ 0549 int mbedtls_x509_crt_parse_file(mbedtls_x509_crt *chain, const char *path); 0550 0551 /** 0552 * \brief Load one or more certificate files from a path and add them 0553 * to the chained list. Parses permissively. If some 0554 * certificates can be parsed, the result is the number 0555 * of failed certificates it encountered. If none complete 0556 * correctly, the first error is returned. 0557 * 0558 * \param chain points to the start of the chain 0559 * \param path directory / folder to read the certificate files from 0560 * 0561 * \return 0 if all certificates parsed successfully, a positive number 0562 * if partly successful or a specific X509 or PEM error code 0563 */ 0564 int mbedtls_x509_crt_parse_path(mbedtls_x509_crt *chain, const char *path); 0565 0566 #endif /* MBEDTLS_FS_IO */ 0567 0568 #if !defined(MBEDTLS_X509_REMOVE_INFO) 0569 /** 0570 * \brief Returns an informational string about the 0571 * certificate. 0572 * 0573 * \param buf Buffer to write to 0574 * \param size Maximum size of buffer 0575 * \param prefix A line prefix 0576 * \param crt The X509 certificate to represent 0577 * 0578 * \return The length of the string written (not including the 0579 * terminated nul byte), or a negative error code. 0580 */ 0581 int mbedtls_x509_crt_info(char *buf, size_t size, const char *prefix, 0582 const mbedtls_x509_crt *crt); 0583 0584 /** 0585 * \brief Returns an informational string about the 0586 * verification status of a certificate. 0587 * 0588 * \param buf Buffer to write to 0589 * \param size Maximum size of buffer 0590 * \param prefix A line prefix 0591 * \param flags Verification flags created by mbedtls_x509_crt_verify() 0592 * 0593 * \return The length of the string written (not including the 0594 * terminated nul byte), or a negative error code. 0595 */ 0596 int mbedtls_x509_crt_verify_info(char *buf, size_t size, const char *prefix, 0597 uint32_t flags); 0598 #endif /* !MBEDTLS_X509_REMOVE_INFO */ 0599 0600 /** 0601 * \brief Verify a chain of certificates. 0602 * 0603 * The verify callback is a user-supplied callback that 0604 * can clear / modify / add flags for a certificate. If set, 0605 * the verification callback is called for each 0606 * certificate in the chain (from the trust-ca down to the 0607 * presented crt). The parameters for the callback are: 0608 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth, 0609 * int *flags). With the flags representing current flags for 0610 * that specific certificate and the certificate depth from 0611 * the bottom (Peer cert depth = 0). 0612 * 0613 * All flags left after returning from the callback 0614 * are also returned to the application. The function should 0615 * return 0 for anything (including invalid certificates) 0616 * other than fatal error, as a non-zero return code 0617 * immediately aborts the verification process. For fatal 0618 * errors, a specific error code should be used (different 0619 * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not 0620 * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR 0621 * can be used if no better code is available. 0622 * 0623 * \note In case verification failed, the results can be displayed 0624 * using \c mbedtls_x509_crt_verify_info() 0625 * 0626 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the 0627 * default security profile. 0628 * 0629 * \note It is your responsibility to provide up-to-date CRLs for 0630 * all trusted CAs. If no CRL is provided for the CA that was 0631 * used to sign the certificate, CRL verification is skipped 0632 * silently, that is *without* setting any flag. 0633 * 0634 * \note The \c trust_ca list can contain two types of certificates: 0635 * (1) those of trusted root CAs, so that certificates 0636 * chaining up to those CAs will be trusted, and (2) 0637 * self-signed end-entity certificates to be trusted (for 0638 * specific peers you know) - in that case, the self-signed 0639 * certificate doesn't need to have the CA bit set. 0640 * 0641 * \param crt The certificate chain to be verified. 0642 * \param trust_ca The list of trusted CAs. 0643 * \param ca_crl The list of CRLs for trusted CAs. 0644 * \param cn The expected Common Name. This will be checked to be 0645 * present in the certificate's subjectAltNames extension or, 0646 * if this extension is absent, as a CN component in its 0647 * Subject name. DNS names and IP addresses are fully 0648 * supported, while the URI subtype is partially supported: 0649 * only exact matching, without any normalization procedures 0650 * described in 7.4 of RFC5280, will result in a positive 0651 * URI verification. 0652 * This may be \c NULL if the CN need not be verified. 0653 * \param flags The address at which to store the result of the verification. 0654 * If the verification couldn't be completed, the flag value is 0655 * set to (uint32_t) -1. 0656 * \param f_vrfy The verification callback to use. See the documentation 0657 * of mbedtls_x509_crt_verify() for more information. 0658 * \param p_vrfy The context to be passed to \p f_vrfy. 0659 * 0660 * \return \c 0 if the chain is valid with respect to the 0661 * passed CN, CAs, CRLs and security profile. 0662 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the 0663 * certificate chain verification failed. In this case, 0664 * \c *flags will have one or more 0665 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX 0666 * flags set. 0667 * \return Another negative error code in case of a fatal error 0668 * encountered during the verification process. 0669 */ 0670 int mbedtls_x509_crt_verify(mbedtls_x509_crt *crt, 0671 mbedtls_x509_crt *trust_ca, 0672 mbedtls_x509_crl *ca_crl, 0673 const char *cn, uint32_t *flags, 0674 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 0675 void *p_vrfy); 0676 0677 /** 0678 * \brief Verify a chain of certificates with respect to 0679 * a configurable security profile. 0680 * 0681 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit 0682 * security profile. 0683 * 0684 * \note The restrictions on keys (RSA minimum size, allowed curves 0685 * for ECDSA) apply to all certificates: trusted root, 0686 * intermediate CAs if any, and end entity certificate. 0687 * 0688 * \param crt The certificate chain to be verified. 0689 * \param trust_ca The list of trusted CAs. 0690 * \param ca_crl The list of CRLs for trusted CAs. 0691 * \param profile The security profile to use for the verification. 0692 * \param cn The expected Common Name. This may be \c NULL if the 0693 * CN need not be verified. 0694 * \param flags The address at which to store the result of the verification. 0695 * If the verification couldn't be completed, the flag value is 0696 * set to (uint32_t) -1. 0697 * \param f_vrfy The verification callback to use. See the documentation 0698 * of mbedtls_x509_crt_verify() for more information. 0699 * \param p_vrfy The context to be passed to \p f_vrfy. 0700 * 0701 * \return \c 0 if the chain is valid with respect to the 0702 * passed CN, CAs, CRLs and security profile. 0703 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the 0704 * certificate chain verification failed. In this case, 0705 * \c *flags will have one or more 0706 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX 0707 * flags set. 0708 * \return Another negative error code in case of a fatal error 0709 * encountered during the verification process. 0710 */ 0711 int mbedtls_x509_crt_verify_with_profile(mbedtls_x509_crt *crt, 0712 mbedtls_x509_crt *trust_ca, 0713 mbedtls_x509_crl *ca_crl, 0714 const mbedtls_x509_crt_profile *profile, 0715 const char *cn, uint32_t *flags, 0716 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 0717 void *p_vrfy); 0718 0719 /** 0720 * \brief Restartable version of \c mbedtls_crt_verify_with_profile() 0721 * 0722 * \note Performs the same job as \c mbedtls_crt_verify_with_profile() 0723 * but can return early and restart according to the limit 0724 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 0725 * 0726 * \param crt The certificate chain to be verified. 0727 * \param trust_ca The list of trusted CAs. 0728 * \param ca_crl The list of CRLs for trusted CAs. 0729 * \param profile The security profile to use for the verification. 0730 * \param cn The expected Common Name. This may be \c NULL if the 0731 * CN need not be verified. 0732 * \param flags The address at which to store the result of the verification. 0733 * If the verification couldn't be completed, the flag value is 0734 * set to (uint32_t) -1. 0735 * \param f_vrfy The verification callback to use. See the documentation 0736 * of mbedtls_x509_crt_verify() for more information. 0737 * \param p_vrfy The context to be passed to \p f_vrfy. 0738 * \param rs_ctx The restart context to use. This may be set to \c NULL 0739 * to disable restartable ECC. 0740 * 0741 * \return See \c mbedtls_crt_verify_with_profile(), or 0742 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 0743 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 0744 */ 0745 int mbedtls_x509_crt_verify_restartable(mbedtls_x509_crt *crt, 0746 mbedtls_x509_crt *trust_ca, 0747 mbedtls_x509_crl *ca_crl, 0748 const mbedtls_x509_crt_profile *profile, 0749 const char *cn, uint32_t *flags, 0750 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 0751 void *p_vrfy, 0752 mbedtls_x509_crt_restart_ctx *rs_ctx); 0753 0754 /** 0755 * \brief The type of trusted certificate callbacks. 0756 * 0757 * Callbacks of this type are passed to and used by the CRT 0758 * verification routine mbedtls_x509_crt_verify_with_ca_cb() 0759 * when looking for trusted signers of a given certificate. 0760 * 0761 * On success, the callback returns a list of trusted 0762 * certificates to be considered as potential signers 0763 * for the input certificate. 0764 * 0765 * \param p_ctx An opaque context passed to the callback. 0766 * \param child The certificate for which to search a potential signer. 0767 * This will point to a readable certificate. 0768 * \param candidate_cas The address at which to store the address of the first 0769 * entry in the generated linked list of candidate signers. 0770 * This will not be \c NULL. 0771 * 0772 * \note The callback must only return a non-zero value on a 0773 * fatal error. If, in contrast, the search for a potential 0774 * signer completes without a single candidate, the 0775 * callback must return \c 0 and set \c *candidate_cas 0776 * to \c NULL. 0777 * 0778 * \return \c 0 on success. In this case, \c *candidate_cas points 0779 * to a heap-allocated linked list of instances of 0780 * ::mbedtls_x509_crt, and ownership of this list is passed 0781 * to the caller. 0782 * \return A negative error code on failure. 0783 */ 0784 typedef int (*mbedtls_x509_crt_ca_cb_t)(void *p_ctx, 0785 mbedtls_x509_crt const *child, 0786 mbedtls_x509_crt **candidate_cas); 0787 0788 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 0789 /** 0790 * \brief Version of \c mbedtls_x509_crt_verify_with_profile() which 0791 * uses a callback to acquire the list of trusted CA 0792 * certificates. 0793 * 0794 * \param crt The certificate chain to be verified. 0795 * \param f_ca_cb The callback to be used to query for potential signers 0796 * of a given child certificate. See the documentation of 0797 * ::mbedtls_x509_crt_ca_cb_t for more information. 0798 * \param p_ca_cb The opaque context to be passed to \p f_ca_cb. 0799 * \param profile The security profile for the verification. 0800 * \param cn The expected Common Name. This may be \c NULL if the 0801 * CN need not be verified. 0802 * \param flags The address at which to store the result of the verification. 0803 * If the verification couldn't be completed, the flag value is 0804 * set to (uint32_t) -1. 0805 * \param f_vrfy The verification callback to use. See the documentation 0806 * of mbedtls_x509_crt_verify() for more information. 0807 * \param p_vrfy The context to be passed to \p f_vrfy. 0808 * 0809 * \return See \c mbedtls_crt_verify_with_profile(). 0810 */ 0811 int mbedtls_x509_crt_verify_with_ca_cb(mbedtls_x509_crt *crt, 0812 mbedtls_x509_crt_ca_cb_t f_ca_cb, 0813 void *p_ca_cb, 0814 const mbedtls_x509_crt_profile *profile, 0815 const char *cn, uint32_t *flags, 0816 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 0817 void *p_vrfy); 0818 0819 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 0820 0821 /** 0822 * \brief Check usage of certificate against keyUsage extension. 0823 * 0824 * \param crt Leaf certificate used. 0825 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT 0826 * before using the certificate to perform an RSA key 0827 * exchange). 0828 * 0829 * \note Except for decipherOnly and encipherOnly, a bit set in the 0830 * usage argument means this bit MUST be set in the 0831 * certificate. For decipherOnly and encipherOnly, it means 0832 * that bit MAY be set. 0833 * 0834 * \return 0 is these uses of the certificate are allowed, 0835 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension 0836 * is present but does not match the usage argument. 0837 * 0838 * \note You should only call this function on leaf certificates, on 0839 * (intermediate) CAs the keyUsage extension is automatically 0840 * checked by \c mbedtls_x509_crt_verify(). 0841 */ 0842 int mbedtls_x509_crt_check_key_usage(const mbedtls_x509_crt *crt, 0843 unsigned int usage); 0844 0845 /** 0846 * \brief Check usage of certificate against extendedKeyUsage. 0847 * 0848 * \param crt Leaf certificate used. 0849 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or 0850 * MBEDTLS_OID_CLIENT_AUTH). 0851 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()). 0852 * 0853 * \return 0 if this use of the certificate is allowed, 0854 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not. 0855 * 0856 * \note Usually only makes sense on leaf certificates. 0857 */ 0858 int mbedtls_x509_crt_check_extended_key_usage(const mbedtls_x509_crt *crt, 0859 const char *usage_oid, 0860 size_t usage_len); 0861 0862 #if defined(MBEDTLS_X509_CRL_PARSE_C) 0863 /** 0864 * \brief Verify the certificate revocation status 0865 * 0866 * \param crt a certificate to be verified 0867 * \param crl the CRL to verify against 0868 * 0869 * \return 1 if the certificate is revoked, 0 otherwise 0870 * 0871 */ 0872 int mbedtls_x509_crt_is_revoked(const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl); 0873 #endif /* MBEDTLS_X509_CRL_PARSE_C */ 0874 0875 /** 0876 * \brief Initialize a certificate (chain) 0877 * 0878 * \param crt Certificate chain to initialize 0879 */ 0880 void mbedtls_x509_crt_init(mbedtls_x509_crt *crt); 0881 0882 /** 0883 * \brief Unallocate all certificate data 0884 * 0885 * \param crt Certificate chain to free 0886 */ 0887 void mbedtls_x509_crt_free(mbedtls_x509_crt *crt); 0888 0889 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE) 0890 /** 0891 * \brief Initialize a restart context 0892 */ 0893 void mbedtls_x509_crt_restart_init(mbedtls_x509_crt_restart_ctx *ctx); 0894 0895 /** 0896 * \brief Free the components of a restart context 0897 */ 0898 void mbedtls_x509_crt_restart_free(mbedtls_x509_crt_restart_ctx *ctx); 0899 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 0900 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 0901 0902 /** 0903 * \brief Query certificate for given extension type 0904 * 0905 * \param[in] ctx Certificate context to be queried, must not be \c NULL 0906 * \param ext_type Extension type being queried for, must be a valid 0907 * extension type. Must be one of the MBEDTLS_X509_EXT_XXX 0908 * values 0909 * 0910 * \return 0 if the given extension type is not present, 0911 * non-zero otherwise 0912 */ 0913 static inline int mbedtls_x509_crt_has_ext_type(const mbedtls_x509_crt *ctx, 0914 int ext_type) 0915 { 0916 return ctx->MBEDTLS_PRIVATE(ext_types) & ext_type; 0917 } 0918 0919 /** 0920 * \brief Access the ca_istrue field 0921 * 0922 * \param[in] crt Certificate to be queried, must not be \c NULL 0923 * 0924 * \return \c 1 if this a CA certificate \c 0 otherwise. 0925 * \return MBEDTLS_ERR_X509_INVALID_EXTENSIONS if the certificate does not contain 0926 * the Optional Basic Constraint extension. 0927 * 0928 */ 0929 int mbedtls_x509_crt_get_ca_istrue(const mbedtls_x509_crt *crt); 0930 0931 /** \} name Structures and functions for parsing and writing X.509 certificates */ 0932 0933 #if defined(MBEDTLS_X509_CRT_WRITE_C) 0934 /** 0935 * \brief Initialize a CRT writing context 0936 * 0937 * \param ctx CRT context to initialize 0938 */ 0939 void mbedtls_x509write_crt_init(mbedtls_x509write_cert *ctx); 0940 0941 /** 0942 * \brief Set the version for a Certificate 0943 * Default: MBEDTLS_X509_CRT_VERSION_3 0944 * 0945 * \param ctx CRT context to use 0946 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or 0947 * MBEDTLS_X509_CRT_VERSION_3) 0948 */ 0949 void mbedtls_x509write_crt_set_version(mbedtls_x509write_cert *ctx, int version); 0950 0951 #if defined(MBEDTLS_BIGNUM_C) && !defined(MBEDTLS_DEPRECATED_REMOVED) 0952 /** 0953 * \brief Set the serial number for a Certificate. 0954 * 0955 * \deprecated This function is deprecated and will be removed in a 0956 * future version of the library. Please use 0957 * mbedtls_x509write_crt_set_serial_raw() instead. 0958 * 0959 * \note Even though the MBEDTLS_BIGNUM_C guard looks redundant since 0960 * X509 depends on PK and PK depends on BIGNUM, this emphasizes 0961 * a direct dependency between X509 and BIGNUM which is going 0962 * to be deprecated in the future. 0963 * 0964 * \param ctx CRT context to use 0965 * \param serial serial number to set 0966 * 0967 * \return 0 if successful 0968 */ 0969 int MBEDTLS_DEPRECATED mbedtls_x509write_crt_set_serial( 0970 mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial); 0971 #endif // MBEDTLS_BIGNUM_C && !MBEDTLS_DEPRECATED_REMOVED 0972 0973 /** 0974 * \brief Set the serial number for a Certificate. 0975 * 0976 * \param ctx CRT context to use 0977 * \param serial A raw array of bytes containing the serial number in big 0978 * endian format 0979 * \param serial_len Length of valid bytes (expressed in bytes) in \p serial 0980 * input buffer 0981 * 0982 * \return 0 if successful, or 0983 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the provided input buffer 0984 * is too big (longer than MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN) 0985 */ 0986 int mbedtls_x509write_crt_set_serial_raw(mbedtls_x509write_cert *ctx, 0987 unsigned char *serial, size_t serial_len); 0988 0989 /** 0990 * \brief Set the validity period for a Certificate 0991 * Timestamps should be in string format for UTC timezone 0992 * i.e. "YYYYMMDDhhmmss" 0993 * e.g. "20131231235959" for December 31st 2013 0994 * at 23:59:59 0995 * 0996 * \param ctx CRT context to use 0997 * \param not_before not_before timestamp 0998 * \param not_after not_after timestamp 0999 * 1000 * \return 0 if timestamp was parsed successfully, or 1001 * a specific error code 1002 */ 1003 int mbedtls_x509write_crt_set_validity(mbedtls_x509write_cert *ctx, const char *not_before, 1004 const char *not_after); 1005 1006 /** 1007 * \brief Set the issuer name for a Certificate 1008 * Issuer names should contain a comma-separated list 1009 * of OID types and values: 1010 * e.g. "C=UK,O=ARM,CN=Mbed TLS CA" 1011 * 1012 * \param ctx CRT context to use 1013 * \param issuer_name issuer name to set 1014 * 1015 * \return 0 if issuer name was parsed successfully, or 1016 * a specific error code 1017 */ 1018 int mbedtls_x509write_crt_set_issuer_name(mbedtls_x509write_cert *ctx, 1019 const char *issuer_name); 1020 1021 /** 1022 * \brief Set the subject name for a Certificate 1023 * Subject names should contain a comma-separated list 1024 * of OID types and values: 1025 * e.g. "C=UK,O=ARM,CN=Mbed TLS Server 1" 1026 * 1027 * \param ctx CRT context to use 1028 * \param subject_name subject name to set 1029 * 1030 * \return 0 if subject name was parsed successfully, or 1031 * a specific error code 1032 */ 1033 int mbedtls_x509write_crt_set_subject_name(mbedtls_x509write_cert *ctx, 1034 const char *subject_name); 1035 1036 /** 1037 * \brief Set the subject public key for the certificate 1038 * 1039 * \param ctx CRT context to use 1040 * \param key public key to include 1041 */ 1042 void mbedtls_x509write_crt_set_subject_key(mbedtls_x509write_cert *ctx, mbedtls_pk_context *key); 1043 1044 /** 1045 * \brief Set the issuer key used for signing the certificate 1046 * 1047 * \param ctx CRT context to use 1048 * \param key private key to sign with 1049 */ 1050 void mbedtls_x509write_crt_set_issuer_key(mbedtls_x509write_cert *ctx, mbedtls_pk_context *key); 1051 1052 /** 1053 * \brief Set the MD algorithm to use for the signature 1054 * (e.g. MBEDTLS_MD_SHA1) 1055 * 1056 * \param ctx CRT context to use 1057 * \param md_alg MD algorithm to use 1058 */ 1059 void mbedtls_x509write_crt_set_md_alg(mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg); 1060 1061 /** 1062 * \brief Generic function to add to or replace an extension in the 1063 * CRT 1064 * 1065 * \param ctx CRT context to use 1066 * \param oid OID of the extension 1067 * \param oid_len length of the OID 1068 * \param critical if the extension is critical (per the RFC's definition) 1069 * \param val value of the extension OCTET STRING 1070 * \param val_len length of the value data 1071 * 1072 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 1073 */ 1074 int mbedtls_x509write_crt_set_extension(mbedtls_x509write_cert *ctx, 1075 const char *oid, size_t oid_len, 1076 int critical, 1077 const unsigned char *val, size_t val_len); 1078 1079 /** 1080 * \brief Set the basicConstraints extension for a CRT 1081 * 1082 * \param ctx CRT context to use 1083 * \param is_ca is this a CA certificate 1084 * \param max_pathlen maximum length of certificate chains below this 1085 * certificate (only for CA certificates, -1 is 1086 * unlimited) 1087 * 1088 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 1089 */ 1090 int mbedtls_x509write_crt_set_basic_constraints(mbedtls_x509write_cert *ctx, 1091 int is_ca, int max_pathlen); 1092 1093 #if defined(MBEDTLS_MD_CAN_SHA1) 1094 /** 1095 * \brief Set the subjectKeyIdentifier extension for a CRT 1096 * Requires that mbedtls_x509write_crt_set_subject_key() has been 1097 * called before 1098 * 1099 * \param ctx CRT context to use 1100 * 1101 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 1102 */ 1103 int mbedtls_x509write_crt_set_subject_key_identifier(mbedtls_x509write_cert *ctx); 1104 1105 /** 1106 * \brief Set the authorityKeyIdentifier extension for a CRT 1107 * Requires that mbedtls_x509write_crt_set_issuer_key() has been 1108 * called before 1109 * 1110 * \param ctx CRT context to use 1111 * 1112 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 1113 */ 1114 int mbedtls_x509write_crt_set_authority_key_identifier(mbedtls_x509write_cert *ctx); 1115 #endif /* MBEDTLS_MD_CAN_SHA1 */ 1116 1117 /** 1118 * \brief Set the Key Usage Extension flags 1119 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN) 1120 * 1121 * \param ctx CRT context to use 1122 * \param key_usage key usage flags to set 1123 * 1124 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 1125 */ 1126 int mbedtls_x509write_crt_set_key_usage(mbedtls_x509write_cert *ctx, 1127 unsigned int key_usage); 1128 1129 /** 1130 * \brief Set the Extended Key Usage Extension 1131 * (e.g. MBEDTLS_OID_SERVER_AUTH) 1132 * 1133 * \param ctx CRT context to use 1134 * \param exts extended key usage extensions to set, a sequence of 1135 * MBEDTLS_ASN1_OID objects 1136 * 1137 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 1138 */ 1139 int mbedtls_x509write_crt_set_ext_key_usage(mbedtls_x509write_cert *ctx, 1140 const mbedtls_asn1_sequence *exts); 1141 1142 /** 1143 * \brief Set the Netscape Cert Type flags 1144 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL) 1145 * 1146 * \param ctx CRT context to use 1147 * \param ns_cert_type Netscape Cert Type flags to set 1148 * 1149 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 1150 */ 1151 int mbedtls_x509write_crt_set_ns_cert_type(mbedtls_x509write_cert *ctx, 1152 unsigned char ns_cert_type); 1153 1154 /** 1155 * \brief Free the contents of a CRT write context 1156 * 1157 * \param ctx CRT context to free 1158 */ 1159 void mbedtls_x509write_crt_free(mbedtls_x509write_cert *ctx); 1160 1161 /** 1162 * \brief Write a built up certificate to a X509 DER structure 1163 * Note: data is written at the end of the buffer! Use the 1164 * return value to determine where you should start 1165 * using the buffer 1166 * 1167 * \param ctx certificate to write away 1168 * \param buf buffer to write to 1169 * \param size size of the buffer 1170 * \param f_rng RNG function. This must not be \c NULL. 1171 * \param p_rng RNG parameter 1172 * 1173 * \return length of data written if successful, or a specific 1174 * error code 1175 * 1176 * \note \p f_rng is used for the signature operation. 1177 */ 1178 int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, 1179 int (*f_rng)(void *, unsigned char *, size_t), 1180 void *p_rng); 1181 1182 #if defined(MBEDTLS_PEM_WRITE_C) 1183 /** 1184 * \brief Write a built up certificate to a X509 PEM string 1185 * 1186 * \param ctx certificate to write away 1187 * \param buf buffer to write to 1188 * \param size size of the buffer 1189 * \param f_rng RNG function. This must not be \c NULL. 1190 * \param p_rng RNG parameter 1191 * 1192 * \return 0 if successful, or a specific error code 1193 * 1194 * \note \p f_rng is used for the signature operation. 1195 */ 1196 int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, 1197 int (*f_rng)(void *, unsigned char *, size_t), 1198 void *p_rng); 1199 #endif /* MBEDTLS_PEM_WRITE_C */ 1200 #endif /* MBEDTLS_X509_CRT_WRITE_C */ 1201 1202 /** \} addtogroup x509_module */ 1203 1204 #ifdef __cplusplus 1205 } 1206 #endif 1207 1208 #endif /* mbedtls_x509_crt.h */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|