blob: a0f32cb304fe4eef809357bfa00f61fe0a5a46ef [file] [log] [blame]
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001/**
Simon Butcher5b331b92016-01-03 16:14:14 +00002 * \file x509_crt.h
Paul Bakker7c6b2c32013-09-16 13:49:26 +02003 *
4 * \brief X.509 certificate parsing and writing
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Manuel Pégourié-Gonnard6fb81872015-07-27 11:11:48 +02007 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02008 * 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.
Paul Bakker7c6b2c32013-09-16 13:49:26 +020021 *
Manuel Pégourié-Gonnardfe446432015-03-06 13:17:10 +000022 * This file is part of mbed TLS (https://tls.mbed.org)
Paul Bakker7c6b2c32013-09-16 13:49:26 +020023 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020024#ifndef MBEDTLS_X509_CRT_H
25#define MBEDTLS_X509_CRT_H
Paul Bakker7c6b2c32013-09-16 13:49:26 +020026
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020027#if !defined(MBEDTLS_CONFIG_FILE)
Paul Bakker7c6b2c32013-09-16 13:49:26 +020028#include "config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020029#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020030#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020031#endif
Paul Bakker7c6b2c32013-09-16 13:49:26 +020032
33#include "x509.h"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020034#include "x509_crl.h"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020035
36/**
37 * \addtogroup x509_module
38 * \{
39 */
40
41#ifdef __cplusplus
42extern "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 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020053typedef struct mbedtls_x509_crt
Paul Bakker7c6b2c32013-09-16 13:49:26 +020054{
Hanno Becker1a65dcd2019-01-31 08:57:44 +000055 int own_buffer; /**< Indicates if \c raw is owned
56 * by the structure or not. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020057 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
58 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020059
Manuel Pégourié-Gonnardf4e1b642014-06-19 11:39:46 +020060 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020061 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */
62 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020063
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020064 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */
65 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020066
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020067 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */
68 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020069
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020070 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
71 mbedtls_x509_time valid_to; /**< End time of certificate validity. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020072
Hanno Becker494dd7a2019-02-06 16:13:41 +000073 mbedtls_x509_buf pk_raw;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020074 mbedtls_pk_context pk; /**< Container for the public key context. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020075
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020076 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
77 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */
78 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */
79 mbedtls_x509_sequence subject_alt_names; /**< Optional list of Subject Alternative Names (Only dNSName supported). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020080
81 int ext_types; /**< Bit string containing detected and parsed extensions */
82 int ca_istrue; /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
83 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+ */
84
Manuel Pégourié-Gonnard1d0ca1a2015-03-27 16:50:00 +010085 unsigned int key_usage; /**< Optional key usage extension value: See the values in x509.h */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020086
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020087 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020088
Manuel Pégourié-Gonnardb28487d2014-04-01 12:19:09 +020089 unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020090
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020091 mbedtls_x509_buf sig; /**< Signature: hash of the tbs part signed with the private key. */
92 mbedtls_md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
93 mbedtls_pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
94 void *sig_opts; /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020095
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020096 struct mbedtls_x509_crt *next; /**< Next certificate in the CA-chain. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020097}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020098mbedtls_x509_crt;
Paul Bakker7c6b2c32013-09-16 13:49:26 +020099
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200100/**
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200101 * Build flag from an algorithm/curve identifier (pk, md, ecp)
102 * Since 0 is always XXX_NONE, ignore it.
103 */
Hanno Becker1eeca412018-10-15 12:01:35 +0100104#define MBEDTLS_X509_ID_FLAG( id ) ( 1 << ( (id) - 1 ) )
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200105
106/**
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200107 * Security profile for certificate verification.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200108 *
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200109 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200110 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200111typedef struct mbedtls_x509_crt_profile
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200112{
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200113 uint32_t allowed_mds; /**< MDs for signatures */
114 uint32_t allowed_pks; /**< PK algs for signatures */
115 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */
116 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200117}
118mbedtls_x509_crt_profile;
119
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200120#define MBEDTLS_X509_CRT_VERSION_1 0
121#define MBEDTLS_X509_CRT_VERSION_2 1
122#define MBEDTLS_X509_CRT_VERSION_3 2
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200123
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200124#define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32
125#define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200126
Andres AGf9113192016-09-02 14:06:04 +0100127#if !defined( MBEDTLS_X509_MAX_FILE_PATH_LEN )
128#define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
129#endif
130
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200131/**
132 * Container for writing a certificate (CRT)
133 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200134typedef struct mbedtls_x509write_cert
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200135{
136 int version;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200137 mbedtls_mpi serial;
138 mbedtls_pk_context *subject_key;
139 mbedtls_pk_context *issuer_key;
140 mbedtls_asn1_named_data *subject;
141 mbedtls_asn1_named_data *issuer;
142 mbedtls_md_type_t md_alg;
143 char not_before[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
144 char not_after[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
145 mbedtls_asn1_named_data *extensions;
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200146}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200147mbedtls_x509write_cert;
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200148
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200149/**
150 * Item in a verification chain: cert and flags for it
151 */
152typedef struct {
153 mbedtls_x509_crt *crt;
154 uint32_t flags;
155} mbedtls_x509_crt_verify_chain_item;
156
157/**
158 * Max size of verification chain: end-entity + intermediates + trusted root
159 */
160#define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 )
161
162/**
163 * Verification chain as built by \c mbedtls_crt_verify_chain()
164 */
165typedef struct
166{
167 mbedtls_x509_crt_verify_chain_item items[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE];
Manuel Pégourié-Gonnardbb216bd2017-08-28 13:25:55 +0200168 unsigned len;
Hanno Beckerf53893b2019-03-28 13:45:55 +0000169
170#if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
171 /* This stores the list of potential trusted signers obtained from
172 * the CA callback used for the CRT verification, if configured.
173 * We must track it somewhere because the callback passes its
174 * ownership to the caller. */
175 mbedtls_x509_crt *trust_ca_cb_result;
176#endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200177} mbedtls_x509_crt_verify_chain;
178
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200179#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
180
181/**
182 * \brief Context for resuming X.509 verify operations
183 */
184typedef struct
185{
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200186 /* for check_signature() */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200187 mbedtls_pk_restart_ctx pk;
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200188
189 /* for find_parent_in() */
190 mbedtls_x509_crt *parent; /* non-null iff parent_in in progress */
191 mbedtls_x509_crt *fallback_parent;
Manuel Pégourié-Gonnard78d7e8c2018-07-02 12:33:14 +0200192 int fallback_signature_is_good;
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200193
194 /* for find_parent() */
195 int parent_is_trusted; /* -1 if find_parent is not in progress */
196
197 /* for verify_chain() */
Manuel Pégourié-Gonnarddaf04912017-08-23 12:32:19 +0200198 enum {
199 x509_crt_rs_none,
200 x509_crt_rs_find_parent,
201 } in_progress; /* none if no operation is in progress */
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200202 int self_cnt;
203 mbedtls_x509_crt_verify_chain ver_chain;
204
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200205} mbedtls_x509_crt_restart_ctx;
206
207#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
208
209/* Now we can declare functions that take a pointer to that */
210typedef void mbedtls_x509_crt_restart_ctx;
211
212#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
213
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200214#if defined(MBEDTLS_X509_CRT_PARSE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200215/**
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200216 * Default security profile. Should provide a good balance between security
217 * and compatibility with current deployments.
218 */
219extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
220
221/**
222 * Expected next default profile. Recommended for new deployments.
223 * Currently targets a 128-bit security level, except for RSA-2048.
224 */
225extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
226
227/**
228 * NSA Suite B profile.
229 */
230extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
231
232/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200233 * \brief Parse a single DER formatted certificate and add it
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000234 * to the end of the provided chained list.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200235 *
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000236 * \param chain The pointer to the start of the CRT chain to attach to.
237 * When parsing the first CRT in a chain, this should point
238 * to an instance of ::mbedtls_x509_crt initialized through
239 * mbedtls_x509_crt_init().
240 * \param buf The buffer holding the DER encoded certificate.
241 * \param buflen The size in Bytes of \p buf.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200242 *
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000243 * \note This function makes an internal copy of the CRT buffer
244 * \p buf. In particular, \p buf may be destroyed or reused
245 * after this call returns. To avoid duplicating the CRT
246 * buffer (at the cost of stricter lifetime constraints),
247 * use mbedtls_x509_crt_parse_der_nocopy() instead.
248 *
249 * \return \c 0 if successful.
250 * \return A negative error code on failure.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200251 */
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000252int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain,
253 const unsigned char *buf,
254 size_t buflen );
255
256/**
257 * \brief Parse a single DER formatted certificate and add it
258 * to the end of the provided chained list. This is a
259 * variant of mbedtls_x509_crt_parse_der() which takes
260 * temporary ownership of the CRT buffer until the CRT
261 * is destroyed.
262 *
263 * \param chain The pointer to the start of the CRT chain to attach to.
264 * When parsing the first CRT in a chain, this should point
265 * to an instance of ::mbedtls_x509_crt initialized through
266 * mbedtls_x509_crt_init().
267 * \param buf The address of the readable buffer holding the DER encoded
268 * certificate to use. On success, this buffer must be
269 * retained and not be changed for the liftetime of the
270 * CRT chain \p chain, that is, until \p chain is destroyed
271 * through a call to mbedtls_x509_crt_free().
272 * \param buflen The size in Bytes of \p buf.
273 *
274 * \note This call is functionally equivalent to
275 * mbedtls_x509_crt_parse_der(), but it avoids creating a
276 * copy of the input buffer at the cost of stronger lifetime
277 * constraints. This is useful in constrained environments
278 * where duplication of the CRT cannot be tolerated.
279 *
280 * \return \c 0 if successful.
281 * \return A negative error code on failure.
282 */
283int mbedtls_x509_crt_parse_der_nocopy( mbedtls_x509_crt *chain,
284 const unsigned char *buf,
285 size_t buflen );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200286
287/**
Hanno Becker89a91122018-08-23 16:14:00 +0100288 * \brief Parse one DER-encoded or one or more concatenated PEM-encoded
Hanno Becker65e619a2018-08-23 15:46:33 +0100289 * certificates and add them to the chained list.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200290 *
Hanno Beckere8658e22018-08-24 10:01:17 +0100291 * For CRTs in PEM encoding, the function parses permissively:
292 * if at least one certificate can be parsed, the function
Hanno Becker65e619a2018-08-23 15:46:33 +0100293 * returns the number of certificates for which parsing failed
294 * (hence \c 0 if all certificates were parsed successfully).
295 * If no certificate could be parsed, the function returns
296 * the first (negative) error encountered during parsing.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200297 *
Hanno Becker65e619a2018-08-23 15:46:33 +0100298 * PEM encoded certificates may be interleaved by other data
299 * such as human readable descriptions of their content, as
300 * long as the certificates are enclosed in the PEM specific
301 * '-----{BEGIN/END} CERTIFICATE-----' delimiters.
302 *
303 * \param chain The chain to which to add the parsed certificates.
304 * \param buf The buffer holding the certificate data in PEM or DER format.
305 * For certificates in PEM encoding, this may be a concatenation
306 * of multiple certificates; for DER encoding, the buffer must
307 * comprise exactly one certificate.
308 * \param buflen The size of \p buf, including the terminating \c NULL byte
309 * in case of PEM encoded data.
310 *
311 * \return \c 0 if all certificates were parsed successfully.
312 * \return The (positive) number of certificates that couldn't
313 * be parsed if parsing was partly successful (see above).
Hanno Becker89a91122018-08-23 16:14:00 +0100314 * \return A negative X509 or PEM error code otherwise.
Hanno Becker65e619a2018-08-23 15:46:33 +0100315 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200316 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200317int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200318
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200319#if defined(MBEDTLS_FS_IO)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200320/**
321 * \brief Load one or more certificates and add them
322 * to the chained list. Parses permissively. If some
323 * certificates can be parsed, the result is the number
324 * of failed certificates it encountered. If none complete
325 * correctly, the first error is returned.
326 *
327 * \param chain points to the start of the chain
328 * \param path filename to read the certificates from
329 *
330 * \return 0 if all certificates parsed successfully, a positive number
331 * if partly successful or a specific X509 or PEM error code
332 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200333int mbedtls_x509_crt_parse_file( mbedtls_x509_crt *chain, const char *path );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200334
335/**
336 * \brief Load one or more certificate files from a path and add them
337 * to the chained list. Parses permissively. If some
338 * certificates can be parsed, the result is the number
339 * of failed certificates it encountered. If none complete
340 * correctly, the first error is returned.
341 *
342 * \param chain points to the start of the chain
343 * \param path directory / folder to read the certificate files from
344 *
345 * \return 0 if all certificates parsed successfully, a positive number
346 * if partly successful or a specific X509 or PEM error code
347 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200348int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path );
349#endif /* MBEDTLS_FS_IO */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200350
351/**
352 * \brief Returns an informational string about the
353 * certificate.
354 *
355 * \param buf Buffer to write to
356 * \param size Maximum size of buffer
357 * \param prefix A line prefix
358 * \param crt The X509 certificate to represent
359 *
Manuel Pégourié-Gonnarde244f9f2015-06-23 12:10:45 +0200360 * \return The length of the string written (not including the
361 * terminated nul byte), or a negative error code.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200362 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200363int mbedtls_x509_crt_info( char *buf, size_t size, const char *prefix,
364 const mbedtls_x509_crt *crt );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200365
366/**
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100367 * \brief Returns an informational string about the
368 * verification status of a certificate.
369 *
370 * \param buf Buffer to write to
371 * \param size Maximum size of buffer
372 * \param prefix A line prefix
373 * \param flags Verification flags created by mbedtls_x509_crt_verify()
374 *
Manuel Pégourié-Gonnarde244f9f2015-06-23 12:10:45 +0200375 * \return The length of the string written (not including the
376 * terminated nul byte), or a negative error code.
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100377 */
378int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix,
Manuel Pégourié-Gonnarde6ef16f2015-05-11 19:54:43 +0200379 uint32_t flags );
Manuel Pégourié-Gonnard39a183a2015-04-17 16:14:32 +0200380
381/**
Hanno Becker902451d2019-03-27 11:48:40 +0000382 * \brief Verify a chain of certificates.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200383 *
384 * The verify callback is a user-supplied callback that
385 * can clear / modify / add flags for a certificate. If set,
386 * the verification callback is called for each
387 * certificate in the chain (from the trust-ca down to the
388 * presented crt). The parameters for the callback are:
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200389 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200390 * int *flags). With the flags representing current flags for
391 * that specific certificate and the certificate depth from
392 * the bottom (Peer cert depth = 0).
393 *
394 * All flags left after returning from the callback
395 * are also returned to the application. The function should
Manuel Pégourié-Gonnard31458a12017-06-26 10:11:49 +0200396 * return 0 for anything (including invalid certificates)
397 * other than fatal error, as a non-zero return code
398 * immediately aborts the verification process. For fatal
399 * errors, a specific error code should be used (different
400 * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not
401 * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR
402 * can be used if no better code is available.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200403 *
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100404 * \note In case verification failed, the results can be displayed
405 * using \c mbedtls_x509_crt_verify_info()
406 *
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200407 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
408 * default security profile.
409 *
Manuel Pégourié-Gonnardeeef9472016-02-22 11:36:55 +0100410 * \note It is your responsibility to provide up-to-date CRLs for
411 * all trusted CAs. If no CRL is provided for the CA that was
412 * used to sign the certificate, CRL verification is skipped
413 * silently, that is *without* setting any flag.
414 *
Manuel Pégourié-Gonnard08eacec2017-10-18 14:20:24 +0200415 * \note The \c trust_ca list can contain two types of certificates:
Manuel Pégourié-Gonnarda4a206e2017-06-21 09:35:44 +0200416 * (1) those of trusted root CAs, so that certificates
417 * chaining up to those CAs will be trusted, and (2)
418 * self-signed end-entity certificates to be trusted (for
419 * specific peers you know) - in that case, the self-signed
Manuel Pégourié-Gonnard562df402017-08-08 18:09:14 +0200420 * certificate doesn't need to have the CA bit set.
Manuel Pégourié-Gonnarda4a206e2017-06-21 09:35:44 +0200421 *
Hanno Becker902451d2019-03-27 11:48:40 +0000422 * \param crt The certificate chain to be verified.
423 * \param trust_ca The list of trusted CAs.
424 * \param ca_crl The list of CRLs for trusted CAs.
425 * \param cn The expected Common Name. This may be \c NULL if the
426 * CN need not be verified.
427 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100428 * If the verification couldn't be completed, the flag value is
429 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000430 * \param f_vrfy The verification callback to use. See the documentation
431 * of mbedtls_x509_crt_verify() for more information.
432 * \param p_vrfy The context to be passed to \p f_vrfy.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200433 *
Hanno Becker902451d2019-03-27 11:48:40 +0000434 * \return \c 0 if the chain is valid with respect to the
435 * passed CN, CAs, CRLs and security profile.
436 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
437 * certificate chain verification failed. In this case,
438 * \c *flags will have one or more
439 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
440 * flags set.
441 * \return Another negative error code in case of a fatal error
442 * encountered during the verification process.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200443 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200444int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
445 mbedtls_x509_crt *trust_ca,
446 mbedtls_x509_crl *ca_crl,
Manuel Pégourié-Gonnarde6ef16f2015-05-11 19:54:43 +0200447 const char *cn, uint32_t *flags,
448 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
Paul Bakkerddf26b42013-09-18 13:46:23 +0200449 void *p_vrfy );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200450
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200451/**
Hanno Becker902451d2019-03-27 11:48:40 +0000452 * \brief Verify a chain of certificates with respect to
453 * a configurable security profile.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200454 *
455 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
456 * security profile.
457 *
Manuel Pégourié-Gonnard27716cc2015-06-17 11:49:39 +0200458 * \note The restrictions on keys (RSA minimum size, allowed curves
Manuel Pégourié-Gonnard65eefc82015-10-23 14:08:48 +0200459 * for ECDSA) apply to all certificates: trusted root,
460 * intermediate CAs if any, and end entity certificate.
Manuel Pégourié-Gonnard27716cc2015-06-17 11:49:39 +0200461 *
Hanno Becker902451d2019-03-27 11:48:40 +0000462 * \param crt The certificate chain to be verified.
463 * \param trust_ca The list of trusted CAs.
464 * \param ca_crl The list of CRLs for trusted CAs.
465 * \param profile The security profile to use for the verification.
466 * \param cn The expected Common Name. This may be \c NULL if the
467 * CN need not be verified.
468 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100469 * If the verification couldn't be completed, the flag value is
470 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000471 * \param f_vrfy The verification callback to use. See the documentation
472 * of mbedtls_x509_crt_verify() for more information.
473 * \param p_vrfy The context to be passed to \p f_vrfy.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200474 *
Hanno Becker902451d2019-03-27 11:48:40 +0000475 * \return \c 0 if the chain is valid with respect to the
476 * passed CN, CAs, CRLs and security profile.
477 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
478 * certificate chain verification failed. In this case,
479 * \c *flags will have one or more
480 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
481 * flags set.
482 * \return Another negative error code in case of a fatal error
483 * encountered during the verification process.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200484 */
485int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
486 mbedtls_x509_crt *trust_ca,
487 mbedtls_x509_crl *ca_crl,
488 const mbedtls_x509_crt_profile *profile,
489 const char *cn, uint32_t *flags,
490 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
491 void *p_vrfy );
492
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200493/**
494 * \brief Restartable version of \c mbedtls_crt_verify_with_profile()
495 *
496 * \note Performs the same job as \c mbedtls_crt_verify_with_profile()
497 * but can return early and restart according to the limit
498 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
499 *
Hanno Becker902451d2019-03-27 11:48:40 +0000500 * \param crt The certificate chain to be verified.
501 * \param trust_ca The list of trusted CAs.
502 * \param ca_crl The list of CRLs for trusted CAs.
503 * \param profile The security profile to use for the verification.
504 * \param cn The expected Common Name. This may be \c NULL if the
505 * CN need not be verified.
506 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100507 * If the verification couldn't be completed, the flag value is
508 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000509 * \param f_vrfy The verification callback to use. See the documentation
510 * of mbedtls_x509_crt_verify() for more information.
511 * \param p_vrfy The context to be passed to \p f_vrfy.
512 * \param rs_ctx The restart context to use. This may be set to \c NULL
513 * to disable restartable ECC.
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200514 *
515 * \return See \c mbedtls_crt_verify_with_profile(), or
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200516 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200517 * operations was reached: see \c mbedtls_ecp_set_max_ops().
518 */
519int mbedtls_x509_crt_verify_restartable( mbedtls_x509_crt *crt,
520 mbedtls_x509_crt *trust_ca,
521 mbedtls_x509_crl *ca_crl,
522 const mbedtls_x509_crt_profile *profile,
523 const char *cn, uint32_t *flags,
524 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
525 void *p_vrfy,
526 mbedtls_x509_crt_restart_ctx *rs_ctx );
527
Hanno Becker5c8df782019-03-27 11:01:17 +0000528/**
529 * \brief The type of trusted certificate callbacks.
530 *
531 * Callbacks of this type are passed to and used by the CRT
Jarno Lamsa31d9db62019-04-01 14:33:49 +0300532 * verification routine mbedtls_x509_crt_verify_with_ca_cb()
Hanno Becker5c8df782019-03-27 11:01:17 +0000533 * when looking for trusted signers of a given certificate.
534 *
535 * On success, the callback returns a list of trusted
536 * certificates to be considered as potential signers
537 * for the input certificate.
538 *
539 * \param p_ctx An opaque context passed to the callback.
540 * \param child The certificate for which to search a potential signer.
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300541 * This will point to a readable certificate.
Hanno Becker5c8df782019-03-27 11:01:17 +0000542 * \param candidate_cas The address at which to store the address of the first
543 * entry in the generated linked list of candidate signers.
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300544 * This will not be \c NULL.
Hanno Becker5c8df782019-03-27 11:01:17 +0000545 *
546 * \note The callback must only return a non-zero value on a
547 * fatal error. If, in contrast, the search for a potential
548 * signer completes without a single candidate, the
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300549 * callback must return \c 0 and set \c *candidate_cas
Hanno Becker5c8df782019-03-27 11:01:17 +0000550 * to \c NULL.
551 *
552 * \return \c 0 on success. In this case, \c *candidate_cas points
553 * to a heap-allocated linked list of instances of
554 * ::mbedtls_x509_crt, and ownership of this list is passed
555 * to the caller.
556 * \return A negative error code on failure.
557 */
558typedef int (*mbedtls_x509_crt_ca_cb_t)( void *p_ctx,
559 mbedtls_x509_crt const *child,
560 mbedtls_x509_crt **candidate_cas );
Hanno Beckere15dae72019-03-28 13:55:38 +0000561
562#if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
Hanno Becker5c8df782019-03-27 11:01:17 +0000563/**
564 * \brief Version of \c mbedtls_x509_crt_verify_with_profile() which
565 * uses a callback to acquire the list of trusted CA
566 * certificates.
567 *
568 * \param crt The certificate chain to be verified.
569 * \param f_ca_cb The callback to be used to query for potential signers
570 * of a given child certificate. See the documentation of
571 * ::mbedtls_x509_crt_ca_cb_t for more information.
572 * \param p_ca_cb The opaque context to be passed to \p f_ca_cb.
573 * \param profile The security profile for the verification.
574 * \param cn The expected Common Name. This may be \c NULL if the
575 * CN need not be verified.
576 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100577 * If the verification couldn't be completed, the flag value is
578 * set to (uint32_t) -1.
Hanno Becker5c8df782019-03-27 11:01:17 +0000579 * \param f_vrfy The verification callback to use. See the documentation
580 * of mbedtls_x509_crt_verify() for more information.
581 * \param p_vrfy The context to be passed to \p f_vrfy.
582 *
583 * \return See \c mbedtls_crt_verify_with_profile().
584 */
Jarno Lamsa31d9db62019-04-01 14:33:49 +0300585int mbedtls_x509_crt_verify_with_ca_cb( mbedtls_x509_crt *crt,
Hanno Becker5c8df782019-03-27 11:01:17 +0000586 mbedtls_x509_crt_ca_cb_t f_ca_cb,
587 void *p_ca_cb,
588 const mbedtls_x509_crt_profile *profile,
589 const char *cn, uint32_t *flags,
590 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
591 void *p_vrfy );
592
593#endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
594
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200595#if defined(MBEDTLS_X509_CHECK_KEY_USAGE)
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200596/**
597 * \brief Check usage of certificate against keyUsage extension.
598 *
599 * \param crt Leaf certificate used.
Manuel Pégourié-Gonnard655a9642015-06-23 10:48:44 +0200600 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
601 * before using the certificate to perform an RSA key
602 * exchange).
603 *
604 * \note Except for decipherOnly and encipherOnly, a bit set in the
605 * usage argument means this bit MUST be set in the
606 * certificate. For decipherOnly and encipherOnly, it means
607 * that bit MAY be set.
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200608 *
609 * \return 0 is these uses of the certificate are allowed,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200610 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
Manuel Pégourié-Gonnard655a9642015-06-23 10:48:44 +0200611 * is present but does not match the usage argument.
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200612 *
613 * \note You should only call this function on leaf certificates, on
614 * (intermediate) CAs the keyUsage extension is automatically
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200615 * checked by \c mbedtls_x509_crt_verify().
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200616 */
Manuel Pégourié-Gonnard655a9642015-06-23 10:48:44 +0200617int mbedtls_x509_crt_check_key_usage( const mbedtls_x509_crt *crt,
618 unsigned int usage );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200619#endif /* MBEDTLS_X509_CHECK_KEY_USAGE) */
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200620
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200621#if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200622/**
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000623 * \brief Check usage of certificate against extendedKeyUsage.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200624 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000625 * \param crt Leaf certificate used.
626 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
627 * MBEDTLS_OID_CLIENT_AUTH).
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200628 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200629 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000630 * \return 0 if this use of the certificate is allowed,
631 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200632 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000633 * \note Usually only makes sense on leaf certificates.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200634 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200635int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000636 const char *usage_oid,
637 size_t usage_len );
Andres Amaya Garciac81fcb92017-11-14 21:40:02 +0000638#endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200639
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200640#if defined(MBEDTLS_X509_CRL_PARSE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200641/**
Manuel Pégourié-Gonnardcbf3ef32013-09-23 12:20:02 +0200642 * \brief Verify the certificate revocation status
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200643 *
644 * \param crt a certificate to be verified
645 * \param crl the CRL to verify against
646 *
647 * \return 1 if the certificate is revoked, 0 otherwise
648 *
649 */
Manuel Pégourié-Gonnardc730ed32015-06-02 10:38:50 +0100650int mbedtls_x509_crt_is_revoked( const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200651#endif /* MBEDTLS_X509_CRL_PARSE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200652
653/**
Paul Bakker369d2eb2013-09-18 11:58:25 +0200654 * \brief Initialize a certificate (chain)
655 *
656 * \param crt Certificate chain to initialize
657 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200658void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );
Paul Bakker369d2eb2013-09-18 11:58:25 +0200659
660/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200661 * \brief Unallocate all certificate data
662 *
663 * \param crt Certificate chain to free
664 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200665void mbedtls_x509_crt_free( mbedtls_x509_crt *crt );
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200666
667#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
668/**
669 * \brief Initialize a restart context
670 */
671void mbedtls_x509_crt_restart_init( mbedtls_x509_crt_restart_ctx *ctx );
672
673/**
674 * \brief Free the components of a restart context
675 */
676void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx );
677#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200678#endif /* MBEDTLS_X509_CRT_PARSE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200679
680/* \} name */
681/* \} addtogroup x509_module */
682
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200683#if defined(MBEDTLS_X509_CRT_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200684/**
685 * \brief Initialize a CRT writing context
686 *
687 * \param ctx CRT context to initialize
688 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200689void mbedtls_x509write_crt_init( mbedtls_x509write_cert *ctx );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200690
691/**
692 * \brief Set the verion for a Certificate
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200693 * Default: MBEDTLS_X509_CRT_VERSION_3
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200694 *
695 * \param ctx CRT context to use
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200696 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
697 * MBEDTLS_X509_CRT_VERSION_3)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200698 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200699void mbedtls_x509write_crt_set_version( mbedtls_x509write_cert *ctx, int version );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200700
701/**
702 * \brief Set the serial number for a Certificate.
703 *
704 * \param ctx CRT context to use
705 * \param serial serial number to set
706 *
707 * \return 0 if successful
708 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200709int mbedtls_x509write_crt_set_serial( mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200710
711/**
712 * \brief Set the validity period for a Certificate
713 * Timestamps should be in string format for UTC timezone
714 * i.e. "YYYYMMDDhhmmss"
715 * e.g. "20131231235959" for December 31st 2013
716 * at 23:59:59
717 *
718 * \param ctx CRT context to use
719 * \param not_before not_before timestamp
720 * \param not_after not_after timestamp
721 *
722 * \return 0 if timestamp was parsed successfully, or
723 * a specific error code
724 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200725int mbedtls_x509write_crt_set_validity( mbedtls_x509write_cert *ctx, const char *not_before,
Paul Bakker50dc8502013-10-28 21:19:10 +0100726 const char *not_after );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200727
728/**
729 * \brief Set the issuer name for a Certificate
730 * Issuer names should contain a comma-separated list
731 * of OID types and values:
Manuel Pégourié-Gonnardb4fe3cb2015-01-22 16:11:05 +0000732 * e.g. "C=UK,O=ARM,CN=mbed TLS CA"
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200733 *
734 * \param ctx CRT context to use
735 * \param issuer_name issuer name to set
736 *
737 * \return 0 if issuer name was parsed successfully, or
738 * a specific error code
739 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200740int mbedtls_x509write_crt_set_issuer_name( mbedtls_x509write_cert *ctx,
Paul Bakker50dc8502013-10-28 21:19:10 +0100741 const char *issuer_name );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200742
743/**
744 * \brief Set the subject name for a Certificate
745 * Subject names should contain a comma-separated list
746 * of OID types and values:
Manuel Pégourié-Gonnardb4fe3cb2015-01-22 16:11:05 +0000747 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200748 *
749 * \param ctx CRT context to use
750 * \param subject_name subject name to set
751 *
752 * \return 0 if subject name was parsed successfully, or
753 * a specific error code
754 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200755int mbedtls_x509write_crt_set_subject_name( mbedtls_x509write_cert *ctx,
Paul Bakker50dc8502013-10-28 21:19:10 +0100756 const char *subject_name );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200757
758/**
759 * \brief Set the subject public key for the certificate
760 *
761 * \param ctx CRT context to use
762 * \param key public key to include
763 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200764void mbedtls_x509write_crt_set_subject_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200765
766/**
767 * \brief Set the issuer key used for signing the certificate
768 *
769 * \param ctx CRT context to use
770 * \param key private key to sign with
771 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200772void mbedtls_x509write_crt_set_issuer_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200773
774/**
775 * \brief Set the MD algorithm to use for the signature
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200776 * (e.g. MBEDTLS_MD_SHA1)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200777 *
778 * \param ctx CRT context to use
Paul Bakkera36d23e2013-12-30 17:57:27 +0100779 * \param md_alg MD algorithm to use
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200780 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200781void mbedtls_x509write_crt_set_md_alg( mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200782
783/**
784 * \brief Generic function to add to or replace an extension in the
785 * CRT
786 *
787 * \param ctx CRT context to use
788 * \param oid OID of the extension
789 * \param oid_len length of the OID
790 * \param critical if the extension is critical (per the RFC's definition)
791 * \param val value of the extension OCTET STRING
792 * \param val_len length of the value data
793 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200794 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200795 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200796int mbedtls_x509write_crt_set_extension( mbedtls_x509write_cert *ctx,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200797 const char *oid, size_t oid_len,
798 int critical,
799 const unsigned char *val, size_t val_len );
800
801/**
802 * \brief Set the basicConstraints extension for a CRT
803 *
804 * \param ctx CRT context to use
805 * \param is_ca is this a CA certificate
806 * \param max_pathlen maximum length of certificate chains below this
807 * certificate (only for CA certificates, -1 is
808 * inlimited)
809 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200810 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200811 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200812int mbedtls_x509write_crt_set_basic_constraints( mbedtls_x509write_cert *ctx,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200813 int is_ca, int max_pathlen );
814
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200815#if defined(MBEDTLS_SHA1_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200816/**
817 * \brief Set the subjectKeyIdentifier extension for a CRT
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200818 * Requires that mbedtls_x509write_crt_set_subject_key() has been
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200819 * called before
820 *
821 * \param ctx CRT context to use
822 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200823 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200824 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200825int mbedtls_x509write_crt_set_subject_key_identifier( mbedtls_x509write_cert *ctx );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200826
827/**
828 * \brief Set the authorityKeyIdentifier extension for a CRT
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200829 * Requires that mbedtls_x509write_crt_set_issuer_key() has been
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200830 * called before
831 *
832 * \param ctx CRT context to use
833 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200834 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200835 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200836int mbedtls_x509write_crt_set_authority_key_identifier( mbedtls_x509write_cert *ctx );
837#endif /* MBEDTLS_SHA1_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200838
839/**
840 * \brief Set the Key Usage Extension flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200841 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200842 *
843 * \param ctx CRT context to use
844 * \param key_usage key usage flags to set
845 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200846 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200847 */
Manuel Pégourié-Gonnard1cd10ad2015-06-23 11:07:37 +0200848int mbedtls_x509write_crt_set_key_usage( mbedtls_x509write_cert *ctx,
849 unsigned int key_usage );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200850
851/**
852 * \brief Set the Netscape Cert Type flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200853 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200854 *
855 * \param ctx CRT context to use
856 * \param ns_cert_type Netscape Cert Type flags to set
857 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200858 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200859 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200860int mbedtls_x509write_crt_set_ns_cert_type( mbedtls_x509write_cert *ctx,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200861 unsigned char ns_cert_type );
862
863/**
864 * \brief Free the contents of a CRT write context
865 *
866 * \param ctx CRT context to free
867 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200868void mbedtls_x509write_crt_free( mbedtls_x509write_cert *ctx );
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200869
870/**
871 * \brief Write a built up certificate to a X509 DER structure
872 * Note: data is written at the end of the buffer! Use the
873 * return value to determine where you should start
874 * using the buffer
875 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100876 * \param ctx certificate to write away
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200877 * \param buf buffer to write to
878 * \param size size of the buffer
879 * \param f_rng RNG function (for signature, see note)
880 * \param p_rng RNG parameter
881 *
882 * \return length of data written if successful, or a specific
883 * error code
884 *
885 * \note f_rng may be NULL if RSA is used for signature and the
886 * signature is made offline (otherwise f_rng is desirable
887 * for countermeasures against timing attacks).
888 * ECDSA signatures always require a non-NULL f_rng.
889 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200890int mbedtls_x509write_crt_der( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200891 int (*f_rng)(void *, unsigned char *, size_t),
892 void *p_rng );
893
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200894#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200895/**
896 * \brief Write a built up certificate to a X509 PEM string
897 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100898 * \param ctx certificate to write away
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200899 * \param buf buffer to write to
900 * \param size size of the buffer
901 * \param f_rng RNG function (for signature, see note)
902 * \param p_rng RNG parameter
903 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200904 * \return 0 if successful, or a specific error code
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200905 *
906 * \note f_rng may be NULL if RSA is used for signature and the
907 * signature is made offline (otherwise f_rng is desirable
908 * for countermeasures against timing attacks).
909 * ECDSA signatures always require a non-NULL f_rng.
910 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200911int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200912 int (*f_rng)(void *, unsigned char *, size_t),
913 void *p_rng );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200914#endif /* MBEDTLS_PEM_WRITE_C */
915#endif /* MBEDTLS_X509_CRT_WRITE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200916
917#ifdef __cplusplus
918}
919#endif
920
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200921#endif /* mbedtls_x509_crt.h */