1 /**
2 * \file x509_crt.h
3 *
4 * \brief X.509 certificate parsing and writing
5 */
6 /*
7 * Copyright The Mbed TLS Contributors
8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
9 */
10 #ifndef MBEDTLS_X509_CRT_H
11 #define MBEDTLS_X509_CRT_H
12 #include "mbedtls/private_access.h"
13
14 #include "mbedtls/build_info.h"
15
16 #include "mbedtls/x509.h"
17 #include "mbedtls/x509_crl.h"
18 #include "mbedtls/bignum.h"
19
20 /**
21 * \addtogroup x509_module
22 * \{
23 */
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /**
30 * \name Structures and functions for parsing and writing X.509 certificates
31 * \{
32 */
33
34 /**
35 * Container for an X.509 certificate. The certificate may be chained.
36 *
37 * Some fields of this structure are publicly readable. Do not modify
38 * them except via Mbed TLS library functions: the effect of modifying
39 * those fields or the data that those fields points to is unspecified.
40 */
41 typedef struct mbedtls_x509_crt {
42 int MBEDTLS_PRIVATE(own_buffer); /**< Indicates if \c raw is owned
43 * by the structure or not. */
44 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
45 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
46
47 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
48 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */
49 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */
50
51 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */
52 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */
53
54 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */
55 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
56
57 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
58 mbedtls_x509_time valid_to; /**< End time of certificate validity. */
59
60 mbedtls_x509_buf pk_raw;
61 mbedtls_pk_context pk; /**< Container for the public key context. */
62
63 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
64 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */
65 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */
66 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. */
67 mbedtls_x509_buf subject_key_id; /**< Optional X.509 v3 extension subject key identifier. */
68 mbedtls_x509_authority authority_key_id; /**< Optional X.509 v3 extension authority key identifier. */
69
70 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). */
71
72 int MBEDTLS_PRIVATE(ext_types); /**< Bit string containing detected and parsed extensions */
73 int MBEDTLS_PRIVATE(ca_istrue); /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
74 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+ */
75
76 unsigned int MBEDTLS_PRIVATE(key_usage); /**< Optional key usage extension value: See the values in x509.h */
77
78 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
79
80 unsigned char MBEDTLS_PRIVATE(ns_cert_type); /**< Optional Netscape certificate type extension value: See the values in x509.h */
81
82 mbedtls_x509_buf MBEDTLS_PRIVATE(sig); /**< Signature: hash of the tbs part signed with the private key. */
83 mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md); /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
84 mbedtls_pk_type_t MBEDTLS_PRIVATE(sig_pk); /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
85 void *MBEDTLS_PRIVATE(sig_opts); /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
86
87 /** Next certificate in the linked list that constitutes the CA chain.
88 * \p NULL indicates the end of the list.
89 * Do not modify this field directly. */
90 struct mbedtls_x509_crt *next;
91 }
92 mbedtls_x509_crt;
93
94 /**
95 * Build flag from an algorithm/curve identifier (pk, md, ecp)
96 * Since 0 is always XXX_NONE, ignore it.
97 */
98 #define MBEDTLS_X509_ID_FLAG(id) (1 << ((id) - 1))
99
100 /**
101 * Security profile for certificate verification.
102 *
103 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
104 *
105 * The fields of this structure are part of the public API and can be
106 * manipulated directly by applications. Future versions of the library may
107 * add extra fields or reorder existing fields.
108 *
109 * You can create custom profiles by starting from a copy of
110 * an existing profile, such as mbedtls_x509_crt_profile_default or
111 * mbedtls_x509_ctr_profile_none and then tune it to your needs.
112 *
113 * For example to allow SHA-224 in addition to the default:
114 *
115 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default;
116 * my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 );
117 *
118 * Or to allow only RSA-3072+ with SHA-256:
119 *
120 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_none;
121 * my_profile.allowed_mds = MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA256 );
122 * my_profile.allowed_pks = MBEDTLS_X509_ID_FLAG( MBEDTLS_PK_RSA );
123 * my_profile.rsa_min_bitlen = 3072;
124 */
125 typedef struct mbedtls_x509_crt_profile {
126 uint32_t allowed_mds; /**< MDs for signatures */
127 uint32_t allowed_pks; /**< PK algs for public keys;
128 * this applies to all certificates
129 * in the provided chain. */
130 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */
131 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */
132 }
133 mbedtls_x509_crt_profile;
134
135 #define MBEDTLS_X509_CRT_VERSION_1 0
136 #define MBEDTLS_X509_CRT_VERSION_2 1
137 #define MBEDTLS_X509_CRT_VERSION_3 2
138
139 #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 20
140 #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15
141
142 #if !defined(MBEDTLS_X509_MAX_FILE_PATH_LEN)
143 #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
144 #endif
145
146 /* This macro unfolds to the concatenation of macro invocations
147 * X509_CRT_ERROR_INFO( error code,
148 * error code as string,
149 * human readable description )
150 * where X509_CRT_ERROR_INFO is defined by the user.
151 * See x509_crt.c for an example of how to use this. */
152 #define MBEDTLS_X509_CRT_ERROR_INFO_LIST \
153 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXPIRED, \
154 "MBEDTLS_X509_BADCERT_EXPIRED", \
155 "The certificate validity has expired") \
156 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_REVOKED, \
157 "MBEDTLS_X509_BADCERT_REVOKED", \
158 "The certificate has been revoked (is on a CRL)") \
159 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_CN_MISMATCH, \
160 "MBEDTLS_X509_BADCERT_CN_MISMATCH", \
161 "The certificate Common Name (CN) does not match with the expected CN") \
162 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NOT_TRUSTED, \
163 "MBEDTLS_X509_BADCERT_NOT_TRUSTED", \
164 "The certificate is not correctly signed by the trusted CA") \
165 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_NOT_TRUSTED, \
166 "MBEDTLS_X509_BADCRL_NOT_TRUSTED", \
167 "The CRL is not correctly signed by the trusted CA") \
168 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_EXPIRED, \
169 "MBEDTLS_X509_BADCRL_EXPIRED", \
170 "The CRL is expired") \
171 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_MISSING, \
172 "MBEDTLS_X509_BADCERT_MISSING", \
173 "Certificate was missing") \
174 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_SKIP_VERIFY, \
175 "MBEDTLS_X509_BADCERT_SKIP_VERIFY", \
176 "Certificate verification was skipped") \
177 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_OTHER, \
178 "MBEDTLS_X509_BADCERT_OTHER", \
179 "Other reason (can be used by verify callback)") \
180 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_FUTURE, \
181 "MBEDTLS_X509_BADCERT_FUTURE", \
182 "The certificate validity starts in the future") \
183 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_FUTURE, \
184 "MBEDTLS_X509_BADCRL_FUTURE", \
185 "The CRL is from the future") \
186 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_KEY_USAGE, \
187 "MBEDTLS_X509_BADCERT_KEY_USAGE", \
188 "Usage does not match the keyUsage extension") \
189 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXT_KEY_USAGE, \
190 "MBEDTLS_X509_BADCERT_EXT_KEY_USAGE", \
191 "Usage does not match the extendedKeyUsage extension") \
192 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NS_CERT_TYPE, \
193 "MBEDTLS_X509_BADCERT_NS_CERT_TYPE", \
194 "Usage does not match the nsCertType extension") \
195 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_MD, \
196 "MBEDTLS_X509_BADCERT_BAD_MD", \
197 "The certificate is signed with an unacceptable hash.") \
198 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_PK, \
199 "MBEDTLS_X509_BADCERT_BAD_PK", \
200 "The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \
201 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_KEY, \
202 "MBEDTLS_X509_BADCERT_BAD_KEY", \
203 "The certificate is signed with an unacceptable key (eg bad curve, RSA too short).") \
204 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_MD, \
205 "MBEDTLS_X509_BADCRL_BAD_MD", \
206 "The CRL is signed with an unacceptable hash.") \
207 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_PK, \
208 "MBEDTLS_X509_BADCRL_BAD_PK", \
209 "The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \
210 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_KEY, \
211 "MBEDTLS_X509_BADCRL_BAD_KEY", \
212 "The CRL is signed with an unacceptable key (eg bad curve, RSA too short).")
213
214 /**
215 * Container for writing a certificate (CRT)
216 */
217 typedef struct mbedtls_x509write_cert {
218 int MBEDTLS_PRIVATE(version);
219 unsigned char MBEDTLS_PRIVATE(serial)[MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN];
220 size_t MBEDTLS_PRIVATE(serial_len);
221 mbedtls_pk_context *MBEDTLS_PRIVATE(subject_key);
222 mbedtls_pk_context *MBEDTLS_PRIVATE(issuer_key);
223 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(subject);
224 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(issuer);
225 mbedtls_md_type_t MBEDTLS_PRIVATE(md_alg);
226 char MBEDTLS_PRIVATE(not_before)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
227 char MBEDTLS_PRIVATE(not_after)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
228 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(extensions);
229 }
230 mbedtls_x509write_cert;
231
232 /**
233 * \brief Set Subject Alternative Name
234 *
235 * \param ctx Certificate context to use
236 * \param san_list List of SAN values
237 *
238 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
239 *
240 * \note "dnsName", "uniformResourceIdentifier", "IP address",
241 * "otherName", and "DirectoryName", as defined in RFC 5280,
242 * are supported.
243 */
244 int mbedtls_x509write_crt_set_subject_alternative_name(mbedtls_x509write_cert *ctx,
245 const mbedtls_x509_san_list *san_list);
246
247 /**
248 * Item in a verification chain: cert and flags for it
249 */
250 typedef struct {
251 mbedtls_x509_crt *MBEDTLS_PRIVATE(crt);
252 uint32_t MBEDTLS_PRIVATE(flags);
253 } mbedtls_x509_crt_verify_chain_item;
254
255 /**
256 * Max size of verification chain: end-entity + intermediates + trusted root
257 */
258 #define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE (MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2)
259
260 /**
261 * Verification chain as built by \c mbedtls_crt_verify_chain()
262 */
263 typedef struct {
264 mbedtls_x509_crt_verify_chain_item MBEDTLS_PRIVATE(items)[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE];
265 unsigned MBEDTLS_PRIVATE(len);
266
267 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
268 /* This stores the list of potential trusted signers obtained from
269 * the CA callback used for the CRT verification, if configured.
270 * We must track it somewhere because the callback passes its
271 * ownership to the caller. */
272 mbedtls_x509_crt *MBEDTLS_PRIVATE(trust_ca_cb_result);
273 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
274 } mbedtls_x509_crt_verify_chain;
275
276 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
277
278 /**
279 * \brief Context for resuming X.509 verify operations
280 */
281 typedef struct {
282 /* for check_signature() */
283 mbedtls_pk_restart_ctx MBEDTLS_PRIVATE(pk);
284
285 /* for find_parent_in() */
286 mbedtls_x509_crt *MBEDTLS_PRIVATE(parent); /* non-null iff parent_in in progress */
287 mbedtls_x509_crt *MBEDTLS_PRIVATE(fallback_parent);
288 int MBEDTLS_PRIVATE(fallback_signature_is_good);
289
290 /* for find_parent() */
291 int MBEDTLS_PRIVATE(parent_is_trusted); /* -1 if find_parent is not in progress */
292
293 /* for verify_chain() */
294 enum {
295 x509_crt_rs_none,
296 x509_crt_rs_find_parent,
297 } MBEDTLS_PRIVATE(in_progress); /* none if no operation is in progress */
298 int MBEDTLS_PRIVATE(self_cnt);
299 mbedtls_x509_crt_verify_chain MBEDTLS_PRIVATE(ver_chain);
300
301 } mbedtls_x509_crt_restart_ctx;
302
303 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
304
305 /* Now we can declare functions that take a pointer to that */
306 typedef void mbedtls_x509_crt_restart_ctx;
307
308 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
309
310 #if defined(MBEDTLS_X509_CRT_PARSE_C)
311 /**
312 * Default security profile. Should provide a good balance between security
313 * and compatibility with current deployments.
314 *
315 * This profile permits:
316 * - SHA2 hashes with at least 256 bits: SHA-256, SHA-384, SHA-512.
317 * - Elliptic curves with 255 bits and above except secp256k1.
318 * - RSA with 2048 bits and above.
319 *
320 * New minor versions of Mbed TLS may extend this profile, for example if
321 * new algorithms are added to the library. New minor versions of Mbed TLS will
322 * not reduce this profile unless serious security concerns require it.
323 */
324 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
325
326 /**
327 * Expected next default profile. Recommended for new deployments.
328 * Currently targets a 128-bit security level, except for allowing RSA-2048.
329 * This profile may change at any time.
330 */
331 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
332
333 /**
334 * NSA Suite B profile.
335 */
336 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
337
338 /**
339 * Empty profile that allows nothing. Useful as a basis for constructing
340 * custom profiles.
341 */
342 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_none;
343
344 /**
345 * \brief Parse a single DER formatted certificate and add it
346 * to the end of the provided chained list.
347 *
348 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
349 * subsystem must have been initialized by calling
350 * psa_crypto_init() before calling this function.
351 *
352 * \param chain The pointer to the start of the CRT chain to attach to.
353 * When parsing the first CRT in a chain, this should point
354 * to an instance of ::mbedtls_x509_crt initialized through
355 * mbedtls_x509_crt_init().
356 * \param buf The buffer holding the DER encoded certificate.
357 * \param buflen The size in Bytes of \p buf.
358 *
359 * \note This function makes an internal copy of the CRT buffer
360 * \p buf. In particular, \p buf may be destroyed or reused
361 * after this call returns. To avoid duplicating the CRT
362 * buffer (at the cost of stricter lifetime constraints),
363 * use mbedtls_x509_crt_parse_der_nocopy() instead.
364 *
365 * \return \c 0 if successful.
366 * \return A negative error code on failure.
367 */
368 int mbedtls_x509_crt_parse_der(mbedtls_x509_crt *chain,
369 const unsigned char *buf,
370 size_t buflen);
371
372 /**
373 * \brief The type of certificate extension callbacks.
374 *
375 * Callbacks of this type are passed to and used by the
376 * mbedtls_x509_crt_parse_der_with_ext_cb() routine when
377 * it encounters either an unsupported extension or a
378 * "certificate policies" extension containing any
379 * unsupported certificate policies.
380 * Future versions of the library may invoke the callback
381 * in other cases, if and when the need arises.
382 *
383 * \param p_ctx An opaque context passed to the callback.
384 * \param crt The certificate being parsed.
385 * \param oid The OID of the extension.
386 * \param critical Whether the extension is critical.
387 * \param p Pointer to the start of the extension value
388 * (the content of the OCTET STRING).
389 * \param end End of extension value.
390 *
391 * \note The callback must fail and return a negative error code
392 * if it can not parse or does not support the extension.
393 * When the callback fails to parse a critical extension
394 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails.
395 * When the callback fails to parse a non critical extension
396 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips
397 * the extension and continues parsing.
398 *
399 * \return \c 0 on success.
400 * \return A negative error code on failure.
401 */
402 typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx,
403 mbedtls_x509_crt const *crt,
404 mbedtls_x509_buf const *oid,
405 int critical,
406 const unsigned char *p,
407 const unsigned char *end);
408
409 /**
410 * \brief Parse a single DER formatted certificate and add it
411 * to the end of the provided chained list.
412 *
413 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
414 * subsystem must have been initialized by calling
415 * psa_crypto_init() before calling this function.
416 *
417 * \param chain The pointer to the start of the CRT chain to attach to.
418 * When parsing the first CRT in a chain, this should point
419 * to an instance of ::mbedtls_x509_crt initialized through
420 * mbedtls_x509_crt_init().
421 * \param buf The buffer holding the DER encoded certificate.
422 * \param buflen The size in Bytes of \p buf.
423 * \param make_copy When not zero this function makes an internal copy of the
424 * CRT buffer \p buf. In particular, \p buf may be destroyed
425 * or reused after this call returns.
426 * When zero this function avoids duplicating the CRT buffer
427 * by taking temporary ownership thereof until the CRT
428 * is destroyed (like mbedtls_x509_crt_parse_der_nocopy())
429 * \param cb A callback invoked for every unsupported certificate
430 * extension.
431 * \param p_ctx An opaque context passed to the callback.
432 *
433 * \note This call is functionally equivalent to
434 * mbedtls_x509_crt_parse_der(), and/or
435 * mbedtls_x509_crt_parse_der_nocopy()
436 * but it calls the callback with every unsupported
437 * certificate extension and additionally the
438 * "certificate policies" extension if it contains any
439 * unsupported certificate policies.
440 * The callback must return a negative error code if it
441 * does not know how to handle such an extension.
442 * When the callback fails to parse a critical extension
443 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails.
444 * When the callback fails to parse a non critical extension
445 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips
446 * the extension and continues parsing.
447 * Future versions of the library may invoke the callback
448 * in other cases, if and when the need arises.
449 *
450 * \return \c 0 if successful.
451 * \return A negative error code on failure.
452 */
453 int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain,
454 const unsigned char *buf,
455 size_t buflen,
456 int make_copy,
457 mbedtls_x509_crt_ext_cb_t cb,
458 void *p_ctx);
459
460 /**
461 * \brief Parse a single DER formatted certificate and add it
462 * to the end of the provided chained list. This is a
463 * variant of mbedtls_x509_crt_parse_der() which takes
464 * temporary ownership of the CRT buffer until the CRT
465 * is destroyed.
466 *
467 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
468 * subsystem must have been initialized by calling
469 * psa_crypto_init() before calling this function.
470 *
471 * \param chain The pointer to the start of the CRT chain to attach to.
472 * When parsing the first CRT in a chain, this should point
473 * to an instance of ::mbedtls_x509_crt initialized through
474 * mbedtls_x509_crt_init().
475 * \param buf The address of the readable buffer holding the DER encoded
476 * certificate to use. On success, this buffer must be
477 * retained and not be changed for the lifetime of the
478 * CRT chain \p chain, that is, until \p chain is destroyed
479 * through a call to mbedtls_x509_crt_free().
480 * \param buflen The size in Bytes of \p buf.
481 *
482 * \note This call is functionally equivalent to
483 * mbedtls_x509_crt_parse_der(), but it avoids creating a
484 * copy of the input buffer at the cost of stronger lifetime
485 * constraints. This is useful in constrained environments
486 * where duplication of the CRT cannot be tolerated.
487 *
488 * \return \c 0 if successful.
489 * \return A negative error code on failure.
490 */
491 int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain,
492 const unsigned char *buf,
493 size_t buflen);
494
495 /**
496 * \brief Parse one DER-encoded or one or more concatenated PEM-encoded
497 * certificates and add them to the chained list.
498 *
499 * For CRTs in PEM encoding, the function parses permissively:
500 * if at least one certificate can be parsed, the function
501 * returns the number of certificates for which parsing failed
502 * (hence \c 0 if all certificates were parsed successfully).
503 * If no certificate could be parsed, the function returns
504 * the first (negative) error encountered during parsing.
505 *
506 * PEM encoded certificates may be interleaved by other data
507 * such as human readable descriptions of their content, as
508 * long as the certificates are enclosed in the PEM specific
509 * '-----{BEGIN/END} CERTIFICATE-----' delimiters.
510 *
511 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
512 * subsystem must have been initialized by calling
513 * psa_crypto_init() before calling this function.
514 *
515 * \param chain The chain to which to add the parsed certificates.
516 * \param buf The buffer holding the certificate data in PEM or DER format.
517 * For certificates in PEM encoding, this may be a concatenation
518 * of multiple certificates; for DER encoding, the buffer must
519 * comprise exactly one certificate.
520 * \param buflen The size of \p buf, including the terminating \c NULL byte
521 * in case of PEM encoded data.
522 *
523 * \return \c 0 if all certificates were parsed successfully.
524 * \return The (positive) number of certificates that couldn't
525 * be parsed if parsing was partly successful (see above).
526 * \return A negative X509 or PEM error code otherwise.
527 *
528 */
529 int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen);
530
531 #if defined(MBEDTLS_FS_IO)
532 /**
533 * \brief Load one or more certificates and add them
534 * to the chained list. Parses permissively. If some
535 * certificates can be parsed, the result is the number
536 * of failed certificates it encountered. If none complete
537 * correctly, the first error is returned.
538 *
539 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
540 * subsystem must have been initialized by calling
541 * psa_crypto_init() before calling this function.
542 *
543 * \param chain points to the start of the chain
544 * \param path filename to read the certificates from
545 *
546 * \return 0 if all certificates parsed successfully, a positive number
547 * if partly successful or a specific X509 or PEM error code
548 */
549 int mbedtls_x509_crt_parse_file(mbedtls_x509_crt *chain, const char *path);
550
551 /**
552 * \brief Load one or more certificate files from a path and add them
553 * to the chained list. Parses permissively. If some
554 * certificates can be parsed, the result is the number
555 * of failed certificates it encountered. If none complete
556 * correctly, the first error is returned.
557 *
558 * \param chain points to the start of the chain
559 * \param path directory / folder to read the certificate files from
560 *
561 * \return 0 if all certificates parsed successfully, a positive number
562 * if partly successful or a specific X509 or PEM error code
563 */
564 int mbedtls_x509_crt_parse_path(mbedtls_x509_crt *chain, const char *path);
565
566 #endif /* MBEDTLS_FS_IO */
567
568 #if !defined(MBEDTLS_X509_REMOVE_INFO)
569 /**
570 * \brief Returns an informational string about the
571 * certificate.
572 *
573 * \param buf Buffer to write to
574 * \param size Maximum size of buffer
575 * \param prefix A line prefix
576 * \param crt The X509 certificate to represent
577 *
578 * \return The length of the string written (not including the
579 * terminated nul byte), or a negative error code.
580 */
581 int mbedtls_x509_crt_info(char *buf, size_t size, const char *prefix,
582 const mbedtls_x509_crt *crt);
583
584 /**
585 * \brief Returns an informational string about the
586 * verification status of a certificate.
587 *
588 * \param buf Buffer to write to
589 * \param size Maximum size of buffer
590 * \param prefix A line prefix
591 * \param flags Verification flags created by mbedtls_x509_crt_verify()
592 *
593 * \return The length of the string written (not including the
594 * terminated nul byte), or a negative error code.
595 */
596 int mbedtls_x509_crt_verify_info(char *buf, size_t size, const char *prefix,
597 uint32_t flags);
598 #endif /* !MBEDTLS_X509_REMOVE_INFO */
599
600 /**
601 * \brief Verify a chain of certificates.
602 *
603 * The verify callback is a user-supplied callback that
604 * can clear / modify / add flags for a certificate. If set,
605 * the verification callback is called for each
606 * certificate in the chain (from the trust-ca down to the
607 * presented crt). The parameters for the callback are:
608 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
609 * int *flags). With the flags representing current flags for
610 * that specific certificate and the certificate depth from
611 * the bottom (Peer cert depth = 0).
612 *
613 * All flags left after returning from the callback
614 * are also returned to the application. The function should
615 * return 0 for anything (including invalid certificates)
616 * other than fatal error, as a non-zero return code
617 * immediately aborts the verification process. For fatal
618 * errors, a specific error code should be used (different
619 * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not
620 * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR
621 * can be used if no better code is available.
622 *
623 * \note In case verification failed, the results can be displayed
624 * using \c mbedtls_x509_crt_verify_info()
625 *
626 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
627 * default security profile.
628 *
629 * \note It is your responsibility to provide up-to-date CRLs for
630 * all trusted CAs. If no CRL is provided for the CA that was
631 * used to sign the certificate, CRL verification is skipped
632 * silently, that is *without* setting any flag.
633 *
634 * \note The \c trust_ca list can contain two types of certificates:
635 * (1) those of trusted root CAs, so that certificates
636 * chaining up to those CAs will be trusted, and (2)
637 * self-signed end-entity certificates to be trusted (for
638 * specific peers you know) - in that case, the self-signed
639 * certificate doesn't need to have the CA bit set.
640 *
641 * \param crt The certificate chain to be verified.
642 * \param trust_ca The list of trusted CAs.
643 * \param ca_crl The list of CRLs for trusted CAs.
644 * \param cn The expected Common Name. This will be checked to be
645 * present in the certificate's subjectAltNames extension or,
646 * if this extension is absent, as a CN component in its
647 * Subject name. DNS names and IP addresses are fully
648 * supported, while the URI subtype is partially supported:
649 * only exact matching, without any normalization procedures
650 * described in 7.4 of RFC5280, will result in a positive
651 * URI verification.
652 * This may be \c NULL if the CN need not be verified.
653 * \param flags The address at which to store the result of the verification.
654 * If the verification couldn't be completed, the flag value is
655 * set to (uint32_t) -1.
656 * \param f_vrfy The verification callback to use. See the documentation
657 * of mbedtls_x509_crt_verify() for more information.
658 * \param p_vrfy The context to be passed to \p f_vrfy.
659 *
660 * \return \c 0 if the chain is valid with respect to the
661 * passed CN, CAs, CRLs and security profile.
662 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
663 * certificate chain verification failed. In this case,
664 * \c *flags will have one or more
665 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
666 * flags set.
667 * \return Another negative error code in case of a fatal error
668 * encountered during the verification process.
669 */
670 int mbedtls_x509_crt_verify(mbedtls_x509_crt *crt,
671 mbedtls_x509_crt *trust_ca,
672 mbedtls_x509_crl *ca_crl,
673 const char *cn, uint32_t *flags,
674 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
675 void *p_vrfy);
676
677 /**
678 * \brief Verify a chain of certificates with respect to
679 * a configurable security profile.
680 *
681 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
682 * security profile.
683 *
684 * \note The restrictions on keys (RSA minimum size, allowed curves
685 * for ECDSA) apply to all certificates: trusted root,
686 * intermediate CAs if any, and end entity certificate.
687 *
688 * \param crt The certificate chain to be verified.
689 * \param trust_ca The list of trusted CAs.
690 * \param ca_crl The list of CRLs for trusted CAs.
691 * \param profile The security profile to use for the verification.
692 * \param cn The expected Common Name. This may be \c NULL if the
693 * CN need not be verified.
694 * \param flags The address at which to store the result of the verification.
695 * If the verification couldn't be completed, the flag value is
696 * set to (uint32_t) -1.
697 * \param f_vrfy The verification callback to use. See the documentation
698 * of mbedtls_x509_crt_verify() for more information.
699 * \param p_vrfy The context to be passed to \p f_vrfy.
700 *
701 * \return \c 0 if the chain is valid with respect to the
702 * passed CN, CAs, CRLs and security profile.
703 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
704 * certificate chain verification failed. In this case,
705 * \c *flags will have one or more
706 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
707 * flags set.
708 * \return Another negative error code in case of a fatal error
709 * encountered during the verification process.
710 */
711 int mbedtls_x509_crt_verify_with_profile(mbedtls_x509_crt *crt,
712 mbedtls_x509_crt *trust_ca,
713 mbedtls_x509_crl *ca_crl,
714 const mbedtls_x509_crt_profile *profile,
715 const char *cn, uint32_t *flags,
716 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
717 void *p_vrfy);
718
719 /**
720 * \brief Restartable version of \c mbedtls_crt_verify_with_profile()
721 *
722 * \note Performs the same job as \c mbedtls_crt_verify_with_profile()
723 * but can return early and restart according to the limit
724 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
725 *
726 * \param crt The certificate chain to be verified.
727 * \param trust_ca The list of trusted CAs.
728 * \param ca_crl The list of CRLs for trusted CAs.
729 * \param profile The security profile to use for the verification.
730 * \param cn The expected Common Name. This may be \c NULL if the
731 * CN need not be verified.
732 * \param flags The address at which to store the result of the verification.
733 * If the verification couldn't be completed, the flag value is
734 * set to (uint32_t) -1.
735 * \param f_vrfy The verification callback to use. See the documentation
736 * of mbedtls_x509_crt_verify() for more information.
737 * \param p_vrfy The context to be passed to \p f_vrfy.
738 * \param rs_ctx The restart context to use. This may be set to \c NULL
739 * to disable restartable ECC.
740 *
741 * \return See \c mbedtls_crt_verify_with_profile(), or
742 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
743 * operations was reached: see \c mbedtls_ecp_set_max_ops().
744 */
745 int mbedtls_x509_crt_verify_restartable(mbedtls_x509_crt *crt,
746 mbedtls_x509_crt *trust_ca,
747 mbedtls_x509_crl *ca_crl,
748 const mbedtls_x509_crt_profile *profile,
749 const char *cn, uint32_t *flags,
750 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
751 void *p_vrfy,
752 mbedtls_x509_crt_restart_ctx *rs_ctx);
753
754 /**
755 * \brief The type of trusted certificate callbacks.
756 *
757 * Callbacks of this type are passed to and used by the CRT
758 * verification routine mbedtls_x509_crt_verify_with_ca_cb()
759 * when looking for trusted signers of a given certificate.
760 *
761 * On success, the callback returns a list of trusted
762 * certificates to be considered as potential signers
763 * for the input certificate.
764 *
765 * \param p_ctx An opaque context passed to the callback.
766 * \param child The certificate for which to search a potential signer.
767 * This will point to a readable certificate.
768 * \param candidate_cas The address at which to store the address of the first
769 * entry in the generated linked list of candidate signers.
770 * This will not be \c NULL.
771 *
772 * \note The callback must only return a non-zero value on a
773 * fatal error. If, in contrast, the search for a potential
774 * signer completes without a single candidate, the
775 * callback must return \c 0 and set \c *candidate_cas
776 * to \c NULL.
777 *
778 * \return \c 0 on success. In this case, \c *candidate_cas points
779 * to a heap-allocated linked list of instances of
780 * ::mbedtls_x509_crt, and ownership of this list is passed
781 * to the caller.
782 * \return A negative error code on failure.
783 */
784 typedef int (*mbedtls_x509_crt_ca_cb_t)(void *p_ctx,
785 mbedtls_x509_crt const *child,
786 mbedtls_x509_crt **candidate_cas);
787
788 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
789 /**
790 * \brief Version of \c mbedtls_x509_crt_verify_with_profile() which
791 * uses a callback to acquire the list of trusted CA
792 * certificates.
793 *
794 * \param crt The certificate chain to be verified.
795 * \param f_ca_cb The callback to be used to query for potential signers
796 * of a given child certificate. See the documentation of
797 * ::mbedtls_x509_crt_ca_cb_t for more information.
798 * \param p_ca_cb The opaque context to be passed to \p f_ca_cb.
799 * \param profile The security profile for the verification.
800 * \param cn The expected Common Name. This may be \c NULL if the
801 * CN need not be verified.
802 * \param flags The address at which to store the result of the verification.
803 * If the verification couldn't be completed, the flag value is
804 * set to (uint32_t) -1.
805 * \param f_vrfy The verification callback to use. See the documentation
806 * of mbedtls_x509_crt_verify() for more information.
807 * \param p_vrfy The context to be passed to \p f_vrfy.
808 *
809 * \return See \c mbedtls_crt_verify_with_profile().
810 */
811 int mbedtls_x509_crt_verify_with_ca_cb(mbedtls_x509_crt *crt,
812 mbedtls_x509_crt_ca_cb_t f_ca_cb,
813 void *p_ca_cb,
814 const mbedtls_x509_crt_profile *profile,
815 const char *cn, uint32_t *flags,
816 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
817 void *p_vrfy);
818
819 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
820
821 /**
822 * \brief Check usage of certificate against keyUsage extension.
823 *
824 * \param crt Leaf certificate used.
825 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
826 * before using the certificate to perform an RSA key
827 * exchange).
828 *
829 * \note Except for decipherOnly and encipherOnly, a bit set in the
830 * usage argument means this bit MUST be set in the
831 * certificate. For decipherOnly and encipherOnly, it means
832 * that bit MAY be set.
833 *
834 * \return 0 is these uses of the certificate are allowed,
835 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
836 * is present but does not match the usage argument.
837 *
838 * \note You should only call this function on leaf certificates, on
839 * (intermediate) CAs the keyUsage extension is automatically
840 * checked by \c mbedtls_x509_crt_verify().
841 */
842 int mbedtls_x509_crt_check_key_usage(const mbedtls_x509_crt *crt,
843 unsigned int usage);
844
845 /**
846 * \brief Check usage of certificate against extendedKeyUsage.
847 *
848 * \param crt Leaf certificate used.
849 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
850 * MBEDTLS_OID_CLIENT_AUTH).
851 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
852 *
853 * \return 0 if this use of the certificate is allowed,
854 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
855 *
856 * \note Usually only makes sense on leaf certificates.
857 */
858 int mbedtls_x509_crt_check_extended_key_usage(const mbedtls_x509_crt *crt,
859 const char *usage_oid,
860 size_t usage_len);
861
862 #if defined(MBEDTLS_X509_CRL_PARSE_C)
863 /**
864 * \brief Verify the certificate revocation status
865 *
866 * \param crt a certificate to be verified
867 * \param crl the CRL to verify against
868 *
869 * \return 1 if the certificate is revoked, 0 otherwise
870 *
871 */
872 int mbedtls_x509_crt_is_revoked(const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl);
873 #endif /* MBEDTLS_X509_CRL_PARSE_C */
874
875 /**
876 * \brief Initialize a certificate (chain)
877 *
878 * \param crt Certificate chain to initialize
879 */
880 void mbedtls_x509_crt_init(mbedtls_x509_crt *crt);
881
882 /**
883 * \brief Unallocate all certificate data
884 *
885 * \param crt Certificate chain to free
886 */
887 void mbedtls_x509_crt_free(mbedtls_x509_crt *crt);
888
889 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
890 /**
891 * \brief Initialize a restart context
892 */
893 void mbedtls_x509_crt_restart_init(mbedtls_x509_crt_restart_ctx *ctx);
894
895 /**
896 * \brief Free the components of a restart context
897 */
898 void mbedtls_x509_crt_restart_free(mbedtls_x509_crt_restart_ctx *ctx);
899 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
900 #endif /* MBEDTLS_X509_CRT_PARSE_C */
901
902 /**
903 * \brief Query certificate for given extension type
904 *
905 * \param[in] ctx Certificate context to be queried, must not be \c NULL
906 * \param ext_type Extension type being queried for, must be a valid
907 * extension type. Must be one of the MBEDTLS_X509_EXT_XXX
908 * values
909 *
910 * \return 0 if the given extension type is not present,
911 * non-zero otherwise
912 */
mbedtls_x509_crt_has_ext_type(const mbedtls_x509_crt * ctx,int ext_type)913 static inline int mbedtls_x509_crt_has_ext_type(const mbedtls_x509_crt *ctx,
914 int ext_type)
915 {
916 return ctx->MBEDTLS_PRIVATE(ext_types) & ext_type;
917 }
918
919 /**
920 * \brief Access the ca_istrue field
921 *
922 * \param[in] crt Certificate to be queried, must not be \c NULL
923 *
924 * \return \c 1 if this a CA certificate \c 0 otherwise.
925 * \return MBEDTLS_ERR_X509_INVALID_EXTENSIONS if the certificate does not contain
926 * the Optional Basic Constraint extension.
927 *
928 */
929 int mbedtls_x509_crt_get_ca_istrue(const mbedtls_x509_crt *crt);
930
931 /** \} name Structures and functions for parsing and writing X.509 certificates */
932
933 #if defined(MBEDTLS_X509_CRT_WRITE_C)
934 /**
935 * \brief Initialize a CRT writing context
936 *
937 * \param ctx CRT context to initialize
938 */
939 void mbedtls_x509write_crt_init(mbedtls_x509write_cert *ctx);
940
941 /**
942 * \brief Set the version for a Certificate
943 * Default: MBEDTLS_X509_CRT_VERSION_3
944 *
945 * \param ctx CRT context to use
946 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
947 * MBEDTLS_X509_CRT_VERSION_3)
948 */
949 void mbedtls_x509write_crt_set_version(mbedtls_x509write_cert *ctx, int version);
950
951 #if defined(MBEDTLS_BIGNUM_C) && !defined(MBEDTLS_DEPRECATED_REMOVED)
952 /**
953 * \brief Set the serial number for a Certificate.
954 *
955 * \deprecated This function is deprecated and will be removed in a
956 * future version of the library. Please use
957 * mbedtls_x509write_crt_set_serial_raw() instead.
958 *
959 * \note Even though the MBEDTLS_BIGNUM_C guard looks redundant since
960 * X509 depends on PK and PK depends on BIGNUM, this emphasizes
961 * a direct dependency between X509 and BIGNUM which is going
962 * to be deprecated in the future.
963 *
964 * \param ctx CRT context to use
965 * \param serial serial number to set
966 *
967 * \return 0 if successful
968 */
969 int MBEDTLS_DEPRECATED mbedtls_x509write_crt_set_serial(
970 mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial);
971 #endif // MBEDTLS_BIGNUM_C && !MBEDTLS_DEPRECATED_REMOVED
972
973 /**
974 * \brief Set the serial number for a Certificate.
975 *
976 * \param ctx CRT context to use
977 * \param serial A raw array of bytes containing the serial number in big
978 * endian format
979 * \param serial_len Length of valid bytes (expressed in bytes) in \p serial
980 * input buffer
981 *
982 * \return 0 if successful, or
983 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the provided input buffer
984 * is too big (longer than MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN)
985 */
986 int mbedtls_x509write_crt_set_serial_raw(mbedtls_x509write_cert *ctx,
987 unsigned char *serial, size_t serial_len);
988
989 /**
990 * \brief Set the validity period for a Certificate
991 * Timestamps should be in string format for UTC timezone
992 * i.e. "YYYYMMDDhhmmss"
993 * e.g. "20131231235959" for December 31st 2013
994 * at 23:59:59
995 *
996 * \param ctx CRT context to use
997 * \param not_before not_before timestamp
998 * \param not_after not_after timestamp
999 *
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 */
1209
