1 | /**
|
---|
2 | * \file x509_crt.h
|
---|
3 | *
|
---|
4 | * \brief X.509 certificate parsing and writing
|
---|
5 | */
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
|
---|
8 | * SPDX-License-Identifier: Apache-2.0
|
---|
9 | *
|
---|
10 | * Licensed under the Apache License, Version 2.0 (the "License"); you may
|
---|
11 | * not use this file except in compliance with the License.
|
---|
12 | * You may obtain a copy of the License at
|
---|
13 | *
|
---|
14 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
15 | *
|
---|
16 | * Unless required by applicable law or agreed to in writing, software
|
---|
17 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
---|
18 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
19 | * See the License for the specific language governing permissions and
|
---|
20 | * limitations under the License.
|
---|
21 | *
|
---|
22 | * This file is part of mbed TLS (https://tls.mbed.org)
|
---|
23 | */
|
---|
24 | #ifndef MBEDTLS_X509_CRT_H
|
---|
25 | #define MBEDTLS_X509_CRT_H
|
---|
26 |
|
---|
27 | #if !defined(MBEDTLS_CONFIG_FILE)
|
---|
28 | #include "config.h"
|
---|
29 | #else
|
---|
30 | #include MBEDTLS_CONFIG_FILE
|
---|
31 | #endif
|
---|
32 |
|
---|
33 | #include "x509.h"
|
---|
34 | #include "x509_crl.h"
|
---|
35 |
|
---|
36 | /**
|
---|
37 | * \addtogroup x509_module
|
---|
38 | * \{
|
---|
39 | */
|
---|
40 |
|
---|
41 | #ifdef __cplusplus
|
---|
42 | extern "C" {
|
---|
43 | #endif
|
---|
44 |
|
---|
45 | /**
|
---|
46 | * \name Structures and functions for parsing and writing X.509 certificates
|
---|
47 | * \{
|
---|
48 | */
|
---|
49 |
|
---|
50 | /**
|
---|
51 | * Container for an X.509 certificate. The certificate may be chained.
|
---|
52 | */
|
---|
53 | typedef struct mbedtls_x509_crt
|
---|
54 | {
|
---|
55 | mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
|
---|
56 | mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
|
---|
57 |
|
---|
58 | int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
|
---|
59 | mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */
|
---|
60 | mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */
|
---|
61 |
|
---|
62 | mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */
|
---|
63 | mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */
|
---|
64 |
|
---|
65 | mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */
|
---|
66 | mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
|
---|
67 |
|
---|
68 | mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
|
---|
69 | mbedtls_x509_time valid_to; /**< End time of certificate validity. */
|
---|
70 |
|
---|
71 | mbedtls_pk_context pk; /**< Container for the public key context. */
|
---|
72 |
|
---|
73 | mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
|
---|
74 | mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */
|
---|
75 | mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */
|
---|
76 | mbedtls_x509_sequence subject_alt_names; /**< Optional list of Subject Alternative Names (Only dNSName supported). */
|
---|
77 |
|
---|
78 | int ext_types; /**< Bit string containing detected and parsed extensions */
|
---|
79 | int ca_istrue; /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
|
---|
80 | int 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+ */
|
---|
81 |
|
---|
82 | unsigned int key_usage; /**< Optional key usage extension value: See the values in x509.h */
|
---|
83 |
|
---|
84 | mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
|
---|
85 |
|
---|
86 | unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */
|
---|
87 |
|
---|
88 | mbedtls_x509_buf sig; /**< Signature: hash of the tbs part signed with the private key. */
|
---|
89 | mbedtls_md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
|
---|
90 | mbedtls_pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
|
---|
91 | void *sig_opts; /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
|
---|
92 |
|
---|
93 | struct mbedtls_x509_crt *next; /**< Next certificate in the CA-chain. */
|
---|
94 | }
|
---|
95 | mbedtls_x509_crt;
|
---|
96 |
|
---|
97 | /**
|
---|
98 | * Build flag from an algorithm/curve identifier (pk, md, ecp)
|
---|
99 | * Since 0 is always XXX_NONE, ignore it.
|
---|
100 | */
|
---|
101 | #define MBEDTLS_X509_ID_FLAG( id ) ( 1 << ( id - 1 ) )
|
---|
102 |
|
---|
103 | /**
|
---|
104 | * Security profile for certificate verification.
|
---|
105 | *
|
---|
106 | * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
|
---|
107 | */
|
---|
108 | typedef struct mbedtls_x509_crt_profile
|
---|
109 | {
|
---|
110 | uint32_t allowed_mds; /**< MDs for signatures */
|
---|
111 | uint32_t allowed_pks; /**< PK algs for signatures */
|
---|
112 | uint32_t allowed_curves; /**< Elliptic curves for ECDSA */
|
---|
113 | uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */
|
---|
114 | }
|
---|
115 | mbedtls_x509_crt_profile;
|
---|
116 |
|
---|
117 | #define MBEDTLS_X509_CRT_VERSION_1 0
|
---|
118 | #define MBEDTLS_X509_CRT_VERSION_2 1
|
---|
119 | #define MBEDTLS_X509_CRT_VERSION_3 2
|
---|
120 |
|
---|
121 | #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32
|
---|
122 | #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15
|
---|
123 |
|
---|
124 | #if !defined( MBEDTLS_X509_MAX_FILE_PATH_LEN )
|
---|
125 | #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
|
---|
126 | #endif
|
---|
127 |
|
---|
128 | /**
|
---|
129 | * Container for writing a certificate (CRT)
|
---|
130 | */
|
---|
131 | typedef struct mbedtls_x509write_cert
|
---|
132 | {
|
---|
133 | int version;
|
---|
134 | mbedtls_mpi serial;
|
---|
135 | mbedtls_pk_context *subject_key;
|
---|
136 | mbedtls_pk_context *issuer_key;
|
---|
137 | mbedtls_asn1_named_data *subject;
|
---|
138 | mbedtls_asn1_named_data *issuer;
|
---|
139 | mbedtls_md_type_t md_alg;
|
---|
140 | char not_before[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
|
---|
141 | char not_after[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
|
---|
142 | mbedtls_asn1_named_data *extensions;
|
---|
143 | }
|
---|
144 | mbedtls_x509write_cert;
|
---|
145 |
|
---|
146 | /**
|
---|
147 | * Item in a verification chain: cert and flags for it
|
---|
148 | */
|
---|
149 | typedef struct {
|
---|
150 | mbedtls_x509_crt *crt;
|
---|
151 | uint32_t flags;
|
---|
152 | } mbedtls_x509_crt_verify_chain_item;
|
---|
153 |
|
---|
154 | /**
|
---|
155 | * Max size of verification chain: end-entity + intermediates + trusted root
|
---|
156 | */
|
---|
157 | #define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 )
|
---|
158 |
|
---|
159 | /**
|
---|
160 | * Verification chain as built by \c mbedtls_crt_verify_chain()
|
---|
161 | */
|
---|
162 | typedef struct
|
---|
163 | {
|
---|
164 | mbedtls_x509_crt_verify_chain_item items[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE];
|
---|
165 | unsigned len;
|
---|
166 | } mbedtls_x509_crt_verify_chain;
|
---|
167 |
|
---|
168 | #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
|
---|
169 |
|
---|
170 | /**
|
---|
171 | * \brief Context for resuming X.509 verify operations
|
---|
172 | */
|
---|
173 | typedef struct
|
---|
174 | {
|
---|
175 | /* for check_signature() */
|
---|
176 | mbedtls_pk_restart_ctx pk;
|
---|
177 |
|
---|
178 | /* for find_parent_in() */
|
---|
179 | mbedtls_x509_crt *parent; /* non-null iff parent_in in progress */
|
---|
180 | mbedtls_x509_crt *fallback_parent;
|
---|
181 | int fallback_signature_is_good;
|
---|
182 |
|
---|
183 | /* for find_parent() */
|
---|
184 | int parent_is_trusted; /* -1 if find_parent is not in progress */
|
---|
185 |
|
---|
186 | /* for verify_chain() */
|
---|
187 | enum {
|
---|
188 | x509_crt_rs_none,
|
---|
189 | x509_crt_rs_find_parent,
|
---|
190 | } in_progress; /* none if no operation is in progress */
|
---|
191 | int self_cnt;
|
---|
192 | mbedtls_x509_crt_verify_chain ver_chain;
|
---|
193 |
|
---|
194 | } mbedtls_x509_crt_restart_ctx;
|
---|
195 |
|
---|
196 | #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
|
---|
197 |
|
---|
198 | /* Now we can declare functions that take a pointer to that */
|
---|
199 | typedef void mbedtls_x509_crt_restart_ctx;
|
---|
200 |
|
---|
201 | #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
|
---|
202 |
|
---|
203 | #if defined(MBEDTLS_X509_CRT_PARSE_C)
|
---|
204 | /**
|
---|
205 | * Default security profile. Should provide a good balance between security
|
---|
206 | * and compatibility with current deployments.
|
---|
207 | */
|
---|
208 | extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
|
---|
209 |
|
---|
210 | /**
|
---|
211 | * Expected next default profile. Recommended for new deployments.
|
---|
212 | * Currently targets a 128-bit security level, except for RSA-2048.
|
---|
213 | */
|
---|
214 | extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
|
---|
215 |
|
---|
216 | /**
|
---|
217 | * NSA Suite B profile.
|
---|
218 | */
|
---|
219 | extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
|
---|
220 |
|
---|
221 | /**
|
---|
222 | * \brief Parse a single DER formatted certificate and add it
|
---|
223 | * to the chained list.
|
---|
224 | *
|
---|
225 | * \param chain points to the start of the chain
|
---|
226 | * \param buf buffer holding the certificate DER data
|
---|
227 | * \param buflen size of the buffer
|
---|
228 | *
|
---|
229 | * \return 0 if successful, or a specific X509 or PEM error code
|
---|
230 | */
|
---|
231 | int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf,
|
---|
232 | size_t buflen );
|
---|
233 |
|
---|
234 | /**
|
---|
235 | * \brief Parse one DER-encoded or one or more concatenated PEM-encoded
|
---|
236 | * certificates and add them to the chained list.
|
---|
237 | *
|
---|
238 | * For CRTs in PEM encoding, the function parses permissively:
|
---|
239 | * if at least one certificate can be parsed, the function
|
---|
240 | * returns the number of certificates for which parsing failed
|
---|
241 | * (hence \c 0 if all certificates were parsed successfully).
|
---|
242 | * If no certificate could be parsed, the function returns
|
---|
243 | * the first (negative) error encountered during parsing.
|
---|
244 | *
|
---|
245 | * PEM encoded certificates may be interleaved by other data
|
---|
246 | * such as human readable descriptions of their content, as
|
---|
247 | * long as the certificates are enclosed in the PEM specific
|
---|
248 | * '-----{BEGIN/END} CERTIFICATE-----' delimiters.
|
---|
249 | *
|
---|
250 | * \param chain The chain to which to add the parsed certificates.
|
---|
251 | * \param buf The buffer holding the certificate data in PEM or DER format.
|
---|
252 | * For certificates in PEM encoding, this may be a concatenation
|
---|
253 | * of multiple certificates; for DER encoding, the buffer must
|
---|
254 | * comprise exactly one certificate.
|
---|
255 | * \param buflen The size of \p buf, including the terminating \c NULL byte
|
---|
256 | * in case of PEM encoded data.
|
---|
257 | *
|
---|
258 | * \return \c 0 if all certificates were parsed successfully.
|
---|
259 | * \return The (positive) number of certificates that couldn't
|
---|
260 | * be parsed if parsing was partly successful (see above).
|
---|
261 | * \return A negative X509 or PEM error code otherwise.
|
---|
262 | *
|
---|
263 | */
|
---|
264 | int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
|
---|
265 |
|
---|
266 | #if defined(MBEDTLS_FS_IO)
|
---|
267 | /**
|
---|
268 | * \brief Load one or more certificates and add them
|
---|
269 | * to the chained list. Parses permissively. If some
|
---|
270 | * certificates can be parsed, the result is the number
|
---|
271 | * of failed certificates it encountered. If none complete
|
---|
272 | * correctly, the first error is returned.
|
---|
273 | *
|
---|
274 | * \param chain points to the start of the chain
|
---|
275 | * \param path filename to read the certificates from
|
---|
276 | *
|
---|
277 | * \return 0 if all certificates parsed successfully, a positive number
|
---|
278 | * if partly successful or a specific X509 or PEM error code
|
---|
279 | */
|
---|
280 | int mbedtls_x509_crt_parse_file( mbedtls_x509_crt *chain, const char *path );
|
---|
281 |
|
---|
282 | /**
|
---|
283 | * \brief Load one or more certificate files from a path and add them
|
---|
284 | * to the chained list. Parses permissively. If some
|
---|
285 | * certificates can be parsed, the result is the number
|
---|
286 | * of failed certificates it encountered. If none complete
|
---|
287 | * correctly, the first error is returned.
|
---|
288 | *
|
---|
289 | * \param chain points to the start of the chain
|
---|
290 | * \param path directory / folder to read the certificate files from
|
---|
291 | *
|
---|
292 | * \return 0 if all certificates parsed successfully, a positive number
|
---|
293 | * if partly successful or a specific X509 or PEM error code
|
---|
294 | */
|
---|
295 | int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path );
|
---|
296 | #endif /* MBEDTLS_FS_IO */
|
---|
297 |
|
---|
298 | /**
|
---|
299 | * \brief Returns an informational string about the
|
---|
300 | * certificate.
|
---|
301 | *
|
---|
302 | * \param buf Buffer to write to
|
---|
303 | * \param size Maximum size of buffer
|
---|
304 | * \param prefix A line prefix
|
---|
305 | * \param crt The X509 certificate to represent
|
---|
306 | *
|
---|
307 | * \return The length of the string written (not including the
|
---|
308 | * terminated nul byte), or a negative error code.
|
---|
309 | */
|
---|
310 | int mbedtls_x509_crt_info( char *buf, size_t size, const char *prefix,
|
---|
311 | const mbedtls_x509_crt *crt );
|
---|
312 |
|
---|
313 | /**
|
---|
314 | * \brief Returns an informational string about the
|
---|
315 | * verification status of a certificate.
|
---|
316 | *
|
---|
317 | * \param buf Buffer to write to
|
---|
318 | * \param size Maximum size of buffer
|
---|
319 | * \param prefix A line prefix
|
---|
320 | * \param flags Verification flags created by mbedtls_x509_crt_verify()
|
---|
321 | *
|
---|
322 | * \return The length of the string written (not including the
|
---|
323 | * terminated nul byte), or a negative error code.
|
---|
324 | */
|
---|
325 | int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix,
|
---|
326 | uint32_t flags );
|
---|
327 |
|
---|
328 | /**
|
---|
329 | * \brief Verify the certificate signature
|
---|
330 | *
|
---|
331 | * The verify callback is a user-supplied callback that
|
---|
332 | * can clear / modify / add flags for a certificate. If set,
|
---|
333 | * the verification callback is called for each
|
---|
334 | * certificate in the chain (from the trust-ca down to the
|
---|
335 | * presented crt). The parameters for the callback are:
|
---|
336 | * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
|
---|
337 | * int *flags). With the flags representing current flags for
|
---|
338 | * that specific certificate and the certificate depth from
|
---|
339 | * the bottom (Peer cert depth = 0).
|
---|
340 | *
|
---|
341 | * All flags left after returning from the callback
|
---|
342 | * are also returned to the application. The function should
|
---|
343 | * return 0 for anything (including invalid certificates)
|
---|
344 | * other than fatal error, as a non-zero return code
|
---|
345 | * immediately aborts the verification process. For fatal
|
---|
346 | * errors, a specific error code should be used (different
|
---|
347 | * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not
|
---|
348 | * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR
|
---|
349 | * can be used if no better code is available.
|
---|
350 | *
|
---|
351 | * \note In case verification failed, the results can be displayed
|
---|
352 | * using \c mbedtls_x509_crt_verify_info()
|
---|
353 | *
|
---|
354 | * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
|
---|
355 | * default security profile.
|
---|
356 | *
|
---|
357 | * \note It is your responsibility to provide up-to-date CRLs for
|
---|
358 | * all trusted CAs. If no CRL is provided for the CA that was
|
---|
359 | * used to sign the certificate, CRL verification is skipped
|
---|
360 | * silently, that is *without* setting any flag.
|
---|
361 | *
|
---|
362 | * \note The \c trust_ca list can contain two types of certificates:
|
---|
363 | * (1) those of trusted root CAs, so that certificates
|
---|
364 | * chaining up to those CAs will be trusted, and (2)
|
---|
365 | * self-signed end-entity certificates to be trusted (for
|
---|
366 | * specific peers you know) - in that case, the self-signed
|
---|
367 | * certificate doesn't need to have the CA bit set.
|
---|
368 | *
|
---|
369 | * \param crt a certificate (chain) to be verified
|
---|
370 | * \param trust_ca the list of trusted CAs (see note above)
|
---|
371 | * \param ca_crl the list of CRLs for trusted CAs (see note above)
|
---|
372 | * \param cn expected Common Name (can be set to
|
---|
373 | * NULL if the CN must not be verified)
|
---|
374 | * \param flags result of the verification
|
---|
375 | * \param f_vrfy verification function
|
---|
376 | * \param p_vrfy verification parameter
|
---|
377 | *
|
---|
378 | * \return 0 (and flags set to 0) if the chain was verified and valid,
|
---|
379 | * MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified
|
---|
380 | * but found to be invalid, in which case *flags will have one
|
---|
381 | * or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX
|
---|
382 | * flags set, or another error (and flags set to 0xffffffff)
|
---|
383 | * in case of a fatal error encountered during the
|
---|
384 | * verification process.
|
---|
385 | */
|
---|
386 | int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
|
---|
387 | mbedtls_x509_crt *trust_ca,
|
---|
388 | mbedtls_x509_crl *ca_crl,
|
---|
389 | const char *cn, uint32_t *flags,
|
---|
390 | int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
|
---|
391 | void *p_vrfy );
|
---|
392 |
|
---|
393 | /**
|
---|
394 | * \brief Verify the certificate signature according to profile
|
---|
395 | *
|
---|
396 | * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
|
---|
397 | * security profile.
|
---|
398 | *
|
---|
399 | * \note The restrictions on keys (RSA minimum size, allowed curves
|
---|
400 | * for ECDSA) apply to all certificates: trusted root,
|
---|
401 | * intermediate CAs if any, and end entity certificate.
|
---|
402 | *
|
---|
403 | * \param crt a certificate (chain) to be verified
|
---|
404 | * \param trust_ca the list of trusted CAs
|
---|
405 | * \param ca_crl the list of CRLs for trusted CAs
|
---|
406 | * \param profile security profile for verification
|
---|
407 | * \param cn expected Common Name (can be set to
|
---|
408 | * NULL if the CN must not be verified)
|
---|
409 | * \param flags result of the verification
|
---|
410 | * \param f_vrfy verification function
|
---|
411 | * \param p_vrfy verification parameter
|
---|
412 | *
|
---|
413 | * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED
|
---|
414 | * in which case *flags will have one or more
|
---|
415 | * MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags
|
---|
416 | * set,
|
---|
417 | * or another error in case of a fatal error encountered
|
---|
418 | * during the verification process.
|
---|
419 | */
|
---|
420 | int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
|
---|
421 | mbedtls_x509_crt *trust_ca,
|
---|
422 | mbedtls_x509_crl *ca_crl,
|
---|
423 | const mbedtls_x509_crt_profile *profile,
|
---|
424 | const char *cn, uint32_t *flags,
|
---|
425 | int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
|
---|
426 | void *p_vrfy );
|
---|
427 |
|
---|
428 | /**
|
---|
429 | * \brief Restartable version of \c mbedtls_crt_verify_with_profile()
|
---|
430 | *
|
---|
431 | * \note Performs the same job as \c mbedtls_crt_verify_with_profile()
|
---|
432 | * but can return early and restart according to the limit
|
---|
433 | * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
|
---|
434 | *
|
---|
435 | * \param crt a certificate (chain) to be verified
|
---|
436 | * \param trust_ca the list of trusted CAs
|
---|
437 | * \param ca_crl the list of CRLs for trusted CAs
|
---|
438 | * \param profile security profile for verification
|
---|
439 | * \param cn expected Common Name (can be set to
|
---|
440 | * NULL if the CN must not be verified)
|
---|
441 | * \param flags result of the verification
|
---|
442 | * \param f_vrfy verification function
|
---|
443 | * \param p_vrfy verification parameter
|
---|
444 | * \param rs_ctx restart context (NULL to disable restart)
|
---|
445 | *
|
---|
446 | * \return See \c mbedtls_crt_verify_with_profile(), or
|
---|
447 | * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
|
---|
448 | * operations was reached: see \c mbedtls_ecp_set_max_ops().
|
---|
449 | */
|
---|
450 | int mbedtls_x509_crt_verify_restartable( mbedtls_x509_crt *crt,
|
---|
451 | mbedtls_x509_crt *trust_ca,
|
---|
452 | mbedtls_x509_crl *ca_crl,
|
---|
453 | const mbedtls_x509_crt_profile *profile,
|
---|
454 | const char *cn, uint32_t *flags,
|
---|
455 | int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
|
---|
456 | void *p_vrfy,
|
---|
457 | mbedtls_x509_crt_restart_ctx *rs_ctx );
|
---|
458 |
|
---|
459 | #if defined(MBEDTLS_X509_CHECK_KEY_USAGE)
|
---|
460 | /**
|
---|
461 | * \brief Check usage of certificate against keyUsage extension.
|
---|
462 | *
|
---|
463 | * \param crt Leaf certificate used.
|
---|
464 | * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
|
---|
465 | * before using the certificate to perform an RSA key
|
---|
466 | * exchange).
|
---|
467 | *
|
---|
468 | * \note Except for decipherOnly and encipherOnly, a bit set in the
|
---|
469 | * usage argument means this bit MUST be set in the
|
---|
470 | * certificate. For decipherOnly and encipherOnly, it means
|
---|
471 | * that bit MAY be set.
|
---|
472 | *
|
---|
473 | * \return 0 is these uses of the certificate are allowed,
|
---|
474 | * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
|
---|
475 | * is present but does not match the usage argument.
|
---|
476 | *
|
---|
477 | * \note You should only call this function on leaf certificates, on
|
---|
478 | * (intermediate) CAs the keyUsage extension is automatically
|
---|
479 | * checked by \c mbedtls_x509_crt_verify().
|
---|
480 | */
|
---|
481 | int mbedtls_x509_crt_check_key_usage( const mbedtls_x509_crt *crt,
|
---|
482 | unsigned int usage );
|
---|
483 | #endif /* MBEDTLS_X509_CHECK_KEY_USAGE) */
|
---|
484 |
|
---|
485 | #if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
|
---|
486 | /**
|
---|
487 | * \brief Check usage of certificate against extendedKeyUsage.
|
---|
488 | *
|
---|
489 | * \param crt Leaf certificate used.
|
---|
490 | * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
|
---|
491 | * MBEDTLS_OID_CLIENT_AUTH).
|
---|
492 | * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
|
---|
493 | *
|
---|
494 | * \return 0 if this use of the certificate is allowed,
|
---|
495 | * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
|
---|
496 | *
|
---|
497 | * \note Usually only makes sense on leaf certificates.
|
---|
498 | */
|
---|
499 | int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
|
---|
500 | const char *usage_oid,
|
---|
501 | size_t usage_len );
|
---|
502 | #endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */
|
---|
503 |
|
---|
504 | #if defined(MBEDTLS_X509_CRL_PARSE_C)
|
---|
505 | /**
|
---|
506 | * \brief Verify the certificate revocation status
|
---|
507 | *
|
---|
508 | * \param crt a certificate to be verified
|
---|
509 | * \param crl the CRL to verify against
|
---|
510 | *
|
---|
511 | * \return 1 if the certificate is revoked, 0 otherwise
|
---|
512 | *
|
---|
513 | */
|
---|
514 | int mbedtls_x509_crt_is_revoked( const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl );
|
---|
515 | #endif /* MBEDTLS_X509_CRL_PARSE_C */
|
---|
516 |
|
---|
517 | /**
|
---|
518 | * \brief Initialize a certificate (chain)
|
---|
519 | *
|
---|
520 | * \param crt Certificate chain to initialize
|
---|
521 | */
|
---|
522 | void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );
|
---|
523 |
|
---|
524 | /**
|
---|
525 | * \brief Unallocate all certificate data
|
---|
526 | *
|
---|
527 | * \param crt Certificate chain to free
|
---|
528 | */
|
---|
529 | void mbedtls_x509_crt_free( mbedtls_x509_crt *crt );
|
---|
530 |
|
---|
531 | #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
|
---|
532 | /**
|
---|
533 | * \brief Initialize a restart context
|
---|
534 | */
|
---|
535 | void mbedtls_x509_crt_restart_init( mbedtls_x509_crt_restart_ctx *ctx );
|
---|
536 |
|
---|
537 | /**
|
---|
538 | * \brief Free the components of a restart context
|
---|
539 | */
|
---|
540 | void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx );
|
---|
541 | #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
|
---|
542 | #endif /* MBEDTLS_X509_CRT_PARSE_C */
|
---|
543 |
|
---|
544 | /* \} name */
|
---|
545 | /* \} addtogroup x509_module */
|
---|
546 |
|
---|
547 | #if defined(MBEDTLS_X509_CRT_WRITE_C)
|
---|
548 | /**
|
---|
549 | * \brief Initialize a CRT writing context
|
---|
550 | *
|
---|
551 | * \param ctx CRT context to initialize
|
---|
552 | */
|
---|
553 | void mbedtls_x509write_crt_init( mbedtls_x509write_cert *ctx );
|
---|
554 |
|
---|
555 | /**
|
---|
556 | * \brief Set the verion for a Certificate
|
---|
557 | * Default: MBEDTLS_X509_CRT_VERSION_3
|
---|
558 | *
|
---|
559 | * \param ctx CRT context to use
|
---|
560 | * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
|
---|
561 | * MBEDTLS_X509_CRT_VERSION_3)
|
---|
562 | */
|
---|
563 | void mbedtls_x509write_crt_set_version( mbedtls_x509write_cert *ctx, int version );
|
---|
564 |
|
---|
565 | /**
|
---|
566 | * \brief Set the serial number for a Certificate.
|
---|
567 | *
|
---|
568 | * \param ctx CRT context to use
|
---|
569 | * \param serial serial number to set
|
---|
570 | *
|
---|
571 | * \return 0 if successful
|
---|
572 | */
|
---|
573 | int mbedtls_x509write_crt_set_serial( mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial );
|
---|
574 |
|
---|
575 | /**
|
---|
576 | * \brief Set the validity period for a Certificate
|
---|
577 | * Timestamps should be in string format for UTC timezone
|
---|
578 | * i.e. "YYYYMMDDhhmmss"
|
---|
579 | * e.g. "20131231235959" for December 31st 2013
|
---|
580 | * at 23:59:59
|
---|
581 | *
|
---|
582 | * \param ctx CRT context to use
|
---|
583 | * \param not_before not_before timestamp
|
---|
584 | * \param not_after not_after timestamp
|
---|
585 | *
|
---|
586 | * \return 0 if timestamp was parsed successfully, or
|
---|
587 | * a specific error code
|
---|
588 | */
|
---|
589 | int mbedtls_x509write_crt_set_validity( mbedtls_x509write_cert *ctx, const char *not_before,
|
---|
590 | const char *not_after );
|
---|
591 |
|
---|
592 | /**
|
---|
593 | * \brief Set the issuer name for a Certificate
|
---|
594 | * Issuer names should contain a comma-separated list
|
---|
595 | * of OID types and values:
|
---|
596 | * e.g. "C=UK,O=ARM,CN=mbed TLS CA"
|
---|
597 | *
|
---|
598 | * \param ctx CRT context to use
|
---|
599 | * \param issuer_name issuer name to set
|
---|
600 | *
|
---|
601 | * \return 0 if issuer name was parsed successfully, or
|
---|
602 | * a specific error code
|
---|
603 | */
|
---|
604 | int mbedtls_x509write_crt_set_issuer_name( mbedtls_x509write_cert *ctx,
|
---|
605 | const char *issuer_name );
|
---|
606 |
|
---|
607 | /**
|
---|
608 | * \brief Set the subject name for a Certificate
|
---|
609 | * Subject names should contain a comma-separated list
|
---|
610 | * of OID types and values:
|
---|
611 | * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
|
---|
612 | *
|
---|
613 | * \param ctx CRT context to use
|
---|
614 | * \param subject_name subject name to set
|
---|
615 | *
|
---|
616 | * \return 0 if subject name was parsed successfully, or
|
---|
617 | * a specific error code
|
---|
618 | */
|
---|
619 | int mbedtls_x509write_crt_set_subject_name( mbedtls_x509write_cert *ctx,
|
---|
620 | const char *subject_name );
|
---|
621 |
|
---|
622 | /**
|
---|
623 | * \brief Set the subject public key for the certificate
|
---|
624 | *
|
---|
625 | * \param ctx CRT context to use
|
---|
626 | * \param key public key to include
|
---|
627 | */
|
---|
628 | void mbedtls_x509write_crt_set_subject_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
|
---|
629 |
|
---|
630 | /**
|
---|
631 | * \brief Set the issuer key used for signing the certificate
|
---|
632 | *
|
---|
633 | * \param ctx CRT context to use
|
---|
634 | * \param key private key to sign with
|
---|
635 | */
|
---|
636 | void mbedtls_x509write_crt_set_issuer_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
|
---|
637 |
|
---|
638 | /**
|
---|
639 | * \brief Set the MD algorithm to use for the signature
|
---|
640 | * (e.g. MBEDTLS_MD_SHA1)
|
---|
641 | *
|
---|
642 | * \param ctx CRT context to use
|
---|
643 | * \param md_alg MD algorithm to use
|
---|
644 | */
|
---|
645 | void mbedtls_x509write_crt_set_md_alg( mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg );
|
---|
646 |
|
---|
647 | /**
|
---|
648 | * \brief Generic function to add to or replace an extension in the
|
---|
649 | * CRT
|
---|
650 | *
|
---|
651 | * \param ctx CRT context to use
|
---|
652 | * \param oid OID of the extension
|
---|
653 | * \param oid_len length of the OID
|
---|
654 | * \param critical if the extension is critical (per the RFC's definition)
|
---|
655 | * \param val value of the extension OCTET STRING
|
---|
656 | * \param val_len length of the value data
|
---|
657 | *
|
---|
658 | * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
659 | */
|
---|
660 | int mbedtls_x509write_crt_set_extension( mbedtls_x509write_cert *ctx,
|
---|
661 | const char *oid, size_t oid_len,
|
---|
662 | int critical,
|
---|
663 | const unsigned char *val, size_t val_len );
|
---|
664 |
|
---|
665 | /**
|
---|
666 | * \brief Set the basicConstraints extension for a CRT
|
---|
667 | *
|
---|
668 | * \param ctx CRT context to use
|
---|
669 | * \param is_ca is this a CA certificate
|
---|
670 | * \param max_pathlen maximum length of certificate chains below this
|
---|
671 | * certificate (only for CA certificates, -1 is
|
---|
672 | * inlimited)
|
---|
673 | *
|
---|
674 | * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
675 | */
|
---|
676 | int mbedtls_x509write_crt_set_basic_constraints( mbedtls_x509write_cert *ctx,
|
---|
677 | int is_ca, int max_pathlen );
|
---|
678 |
|
---|
679 | #if defined(MBEDTLS_SHA1_C)
|
---|
680 | /**
|
---|
681 | * \brief Set the subjectKeyIdentifier extension for a CRT
|
---|
682 | * Requires that mbedtls_x509write_crt_set_subject_key() has been
|
---|
683 | * called before
|
---|
684 | *
|
---|
685 | * \param ctx CRT context to use
|
---|
686 | *
|
---|
687 | * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
688 | */
|
---|
689 | int mbedtls_x509write_crt_set_subject_key_identifier( mbedtls_x509write_cert *ctx );
|
---|
690 |
|
---|
691 | /**
|
---|
692 | * \brief Set the authorityKeyIdentifier extension for a CRT
|
---|
693 | * Requires that mbedtls_x509write_crt_set_issuer_key() has been
|
---|
694 | * called before
|
---|
695 | *
|
---|
696 | * \param ctx CRT context to use
|
---|
697 | *
|
---|
698 | * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
699 | */
|
---|
700 | int mbedtls_x509write_crt_set_authority_key_identifier( mbedtls_x509write_cert *ctx );
|
---|
701 | #endif /* MBEDTLS_SHA1_C */
|
---|
702 |
|
---|
703 | /**
|
---|
704 | * \brief Set the Key Usage Extension flags
|
---|
705 | * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
|
---|
706 | *
|
---|
707 | * \param ctx CRT context to use
|
---|
708 | * \param key_usage key usage flags to set
|
---|
709 | *
|
---|
710 | * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
711 | */
|
---|
712 | int mbedtls_x509write_crt_set_key_usage( mbedtls_x509write_cert *ctx,
|
---|
713 | unsigned int key_usage );
|
---|
714 |
|
---|
715 | /**
|
---|
716 | * \brief Set the Netscape Cert Type flags
|
---|
717 | * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
|
---|
718 | *
|
---|
719 | * \param ctx CRT context to use
|
---|
720 | * \param ns_cert_type Netscape Cert Type flags to set
|
---|
721 | *
|
---|
722 | * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
|
---|
723 | */
|
---|
724 | int mbedtls_x509write_crt_set_ns_cert_type( mbedtls_x509write_cert *ctx,
|
---|
725 | unsigned char ns_cert_type );
|
---|
726 |
|
---|
727 | /**
|
---|
728 | * \brief Free the contents of a CRT write context
|
---|
729 | *
|
---|
730 | * \param ctx CRT context to free
|
---|
731 | */
|
---|
732 | void mbedtls_x509write_crt_free( mbedtls_x509write_cert *ctx );
|
---|
733 |
|
---|
734 | /**
|
---|
735 | * \brief Write a built up certificate to a X509 DER structure
|
---|
736 | * Note: data is written at the end of the buffer! Use the
|
---|
737 | * return value to determine where you should start
|
---|
738 | * using the buffer
|
---|
739 | *
|
---|
740 | * \param ctx certificate to write away
|
---|
741 | * \param buf buffer to write to
|
---|
742 | * \param size size of the buffer
|
---|
743 | * \param f_rng RNG function (for signature, see note)
|
---|
744 | * \param p_rng RNG parameter
|
---|
745 | *
|
---|
746 | * \return length of data written if successful, or a specific
|
---|
747 | * error code
|
---|
748 | *
|
---|
749 | * \note f_rng may be NULL if RSA is used for signature and the
|
---|
750 | * signature is made offline (otherwise f_rng is desirable
|
---|
751 | * for countermeasures against timing attacks).
|
---|
752 | * ECDSA signatures always require a non-NULL f_rng.
|
---|
753 | */
|
---|
754 | int mbedtls_x509write_crt_der( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
|
---|
755 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
756 | void *p_rng );
|
---|
757 |
|
---|
758 | #if defined(MBEDTLS_PEM_WRITE_C)
|
---|
759 | /**
|
---|
760 | * \brief Write a built up certificate to a X509 PEM string
|
---|
761 | *
|
---|
762 | * \param ctx certificate to write away
|
---|
763 | * \param buf buffer to write to
|
---|
764 | * \param size size of the buffer
|
---|
765 | * \param f_rng RNG function (for signature, see note)
|
---|
766 | * \param p_rng RNG parameter
|
---|
767 | *
|
---|
768 | * \return 0 if successful, or a specific error code
|
---|
769 | *
|
---|
770 | * \note f_rng may be NULL if RSA is used for signature and the
|
---|
771 | * signature is made offline (otherwise f_rng is desirable
|
---|
772 | * for countermeasures against timing attacks).
|
---|
773 | * ECDSA signatures always require a non-NULL f_rng.
|
---|
774 | */
|
---|
775 | int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
|
---|
776 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
777 | void *p_rng );
|
---|
778 | #endif /* MBEDTLS_PEM_WRITE_C */
|
---|
779 | #endif /* MBEDTLS_X509_CRT_WRITE_C */
|
---|
780 |
|
---|
781 | #ifdef __cplusplus
|
---|
782 | }
|
---|
783 | #endif
|
---|
784 |
|
---|
785 | #endif /* mbedtls_x509_crt.h */
|
---|