blob: 3f9b25075f9773816b78bd597483324c3f3ed2bb [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/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
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é-Gonnard2cf5a7c2015-04-08 12:49:31 +020022#ifndef MBEDTLS_X509_CRT_H
23#define MBEDTLS_X509_CRT_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020024#include "mbedtls/private_access.h"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020025
Bence Szépkútic662b362021-05-27 11:25:03 +020026#include "mbedtls/build_info.h"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020027
Jaeden Amero6609aef2019-07-04 20:01:14 +010028#include "mbedtls/x509.h"
29#include "mbedtls/x509_crl.h"
30#include "mbedtls/bignum.h"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020031
32/**
33 * \addtogroup x509_module
34 * \{
35 */
36
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/**
42 * \name Structures and functions for parsing and writing X.509 certificates
43 * \{
44 */
45
46/**
47 * Container for an X.509 certificate. The certificate may be chained.
Gilles Peskine842edf42021-08-04 21:56:10 +020048 *
49 * Some fields of this structure are publicly readable. Do not modify
50 * them except via Mbed TLS library functions: the effect of modifying
51 * those fields or the data that those fields points to is unspecified.
Paul Bakker7c6b2c32013-09-16 13:49:26 +020052 */
Gilles Peskine449bd832023-01-11 14:50:10 +010053typedef struct mbedtls_x509_crt {
Mateusz Starzyk846f0212021-05-19 19:44:07 +020054 int MBEDTLS_PRIVATE(own_buffer); /**< Indicates if \c raw is owned
Gilles Peskine449bd832023-01-11 14:50:10 +010055 * by the structure or not. */
Gilles Peskine842edf42021-08-04 21:56:10 +020056 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */
57 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020058
Gilles Peskine842edf42021-08-04 21:56:10 +020059 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */
60 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */
61 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020062
Gilles Peskine842edf42021-08-04 21:56:10 +020063 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */
64 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020065
Gilles Peskine842edf42021-08-04 21:56:10 +020066 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */
67 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020068
Gilles Peskine842edf42021-08-04 21:56:10 +020069 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */
70 mbedtls_x509_time valid_to; /**< End time of certificate validity. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020071
Gilles Peskine842edf42021-08-04 21:56:10 +020072 mbedtls_x509_buf pk_raw;
73 mbedtls_pk_context pk; /**< Container for the public key context. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020074
Gilles Peskine842edf42021-08-04 21:56:10 +020075 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */
76 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */
77 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */
Andrzej Kurek17473042023-04-30 14:11:23 -040078 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. */
toth92ga41954d2021-02-12 16:11:17 +010079 mbedtls_x509_buf subject_key_id; /**< Optional X.509 v3 extension subject key identifier. */
80 mbedtls_x509_authority authority_key_id; /**< Optional X.509 v3 extension authority key identifier. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020081
Gilles Peskine842edf42021-08-04 21:56:10 +020082 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). */
Ron Eldor74d9acc2019-03-21 14:00:03 +020083
Mateusz Starzyk846f0212021-05-19 19:44:07 +020084 int MBEDTLS_PRIVATE(ext_types); /**< Bit string containing detected and parsed extensions */
85 int MBEDTLS_PRIVATE(ca_istrue); /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
86 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+ */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020087
Mateusz Starzyk846f0212021-05-19 19:44:07 +020088 unsigned int MBEDTLS_PRIVATE(key_usage); /**< Optional key usage extension value: See the values in x509.h */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020089
Gilles Peskine842edf42021-08-04 21:56:10 +020090 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020091
Mateusz Starzyk846f0212021-05-19 19:44:07 +020092 unsigned char MBEDTLS_PRIVATE(ns_cert_type); /**< Optional Netscape certificate type extension value: See the values in x509.h */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020093
Mateusz Starzyk846f0212021-05-19 19:44:07 +020094 mbedtls_x509_buf MBEDTLS_PRIVATE(sig); /**< Signature: hash of the tbs part signed with the private key. */
95 mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md); /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
96 mbedtls_pk_type_t MBEDTLS_PRIVATE(sig_pk); /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
97 void *MBEDTLS_PRIVATE(sig_opts); /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020098
Gilles Peskineca939952021-08-31 23:18:07 +020099 /** Next certificate in the linked list that constitutes the CA chain.
100 * \p NULL indicates the end of the list.
101 * Do not modify this field directly. */
102 struct mbedtls_x509_crt *next;
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200103}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200104mbedtls_x509_crt;
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200105
Janos Follath5091bec2019-05-08 15:23:08 +0100106/**
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200107 * Build flag from an algorithm/curve identifier (pk, md, ecp)
108 * Since 0 is always XXX_NONE, ignore it.
109 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100110#define MBEDTLS_X509_ID_FLAG(id) (1 << ((id) - 1))
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200111
112/**
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200113 * Security profile for certificate verification.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200114 *
Manuel Pégourié-Gonnardf8ea8562015-06-15 15:33:19 +0200115 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
Manuel Pégourié-Gonnard55a7fb82021-06-17 10:39:39 +0200116 *
117 * The fields of this structure are part of the public API and can be
118 * manipulated directly by applications. Future versions of the library may
119 * add extra fields or reorder existing fields.
Manuel Pégourié-Gonnard9d4c2c42021-06-18 09:48:27 +0200120 *
121 * You can create custom profiles by starting from a copy of
122 * an existing profile, such as mbedtls_x509_crt_profile_default or
123 * mbedtls_x509_ctr_profile_none and then tune it to your needs.
124 *
125 * For example to allow SHA-224 in addition to the default:
126 *
127 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default;
128 * my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 );
129 *
130 * Or to allow only RSA-3072+ with SHA-256:
131 *
132 * mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_none;
133 * my_profile.allowed_mds = MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA256 );
134 * my_profile.allowed_pks = MBEDTLS_X509_ID_FLAG( MBEDTLS_PK_RSA );
135 * my_profile.rsa_min_bitlen = 3072;
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200136 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100137typedef struct mbedtls_x509_crt_profile {
Manuel Pégourié-Gonnard5314e082021-06-17 10:32:01 +0200138 uint32_t allowed_mds; /**< MDs for signatures */
Hanno Becker2b9fb882018-10-11 11:36:29 +0100139 uint32_t allowed_pks; /**< PK algs for public keys;
Manuel Pégourié-Gonnard8ba99e72022-04-25 10:12:01 +0200140 * this applies to all certificates
Hanno Becker2b9fb882018-10-11 11:36:29 +0100141 * in the provided chain. */
Manuel Pégourié-Gonnard5314e082021-06-17 10:32:01 +0200142 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */
143 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200144}
145mbedtls_x509_crt_profile;
146
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200147#define MBEDTLS_X509_CRT_VERSION_1 0
148#define MBEDTLS_X509_CRT_VERSION_2 1
149#define MBEDTLS_X509_CRT_VERSION_3 2
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200150
Valerio Settida0afcc2023-01-05 16:46:59 +0100151#define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 20
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200152#define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200153
Gilles Peskine449bd832023-01-11 14:50:10 +0100154#if !defined(MBEDTLS_X509_MAX_FILE_PATH_LEN)
Andres AGf9113192016-09-02 14:06:04 +0100155#define MBEDTLS_X509_MAX_FILE_PATH_LEN 512
156#endif
157
Hanno Becker7ac83f92020-10-09 10:48:22 +0100158/* This macro unfolds to the concatenation of macro invocations
159 * X509_CRT_ERROR_INFO( error code,
160 * error code as string,
161 * human readable description )
162 * where X509_CRT_ERROR_INFO is defined by the user.
163 * See x509_crt.c for an example of how to use this. */
164#define MBEDTLS_X509_CRT_ERROR_INFO_LIST \
Gilles Peskine449bd832023-01-11 14:50:10 +0100165 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXPIRED, \
166 "MBEDTLS_X509_BADCERT_EXPIRED", \
167 "The certificate validity has expired") \
168 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_REVOKED, \
169 "MBEDTLS_X509_BADCERT_REVOKED", \
170 "The certificate has been revoked (is on a CRL)") \
171 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_CN_MISMATCH, \
172 "MBEDTLS_X509_BADCERT_CN_MISMATCH", \
173 "The certificate Common Name (CN) does not match with the expected CN") \
174 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NOT_TRUSTED, \
175 "MBEDTLS_X509_BADCERT_NOT_TRUSTED", \
176 "The certificate is not correctly signed by the trusted CA") \
177 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_NOT_TRUSTED, \
178 "MBEDTLS_X509_BADCRL_NOT_TRUSTED", \
179 "The CRL is not correctly signed by the trusted CA") \
180 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_EXPIRED, \
181 "MBEDTLS_X509_BADCRL_EXPIRED", \
182 "The CRL is expired") \
183 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_MISSING, \
184 "MBEDTLS_X509_BADCERT_MISSING", \
185 "Certificate was missing") \
186 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_SKIP_VERIFY, \
187 "MBEDTLS_X509_BADCERT_SKIP_VERIFY", \
188 "Certificate verification was skipped") \
189 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_OTHER, \
190 "MBEDTLS_X509_BADCERT_OTHER", \
191 "Other reason (can be used by verify callback)") \
192 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_FUTURE, \
193 "MBEDTLS_X509_BADCERT_FUTURE", \
194 "The certificate validity starts in the future") \
195 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_FUTURE, \
196 "MBEDTLS_X509_BADCRL_FUTURE", \
197 "The CRL is from the future") \
198 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_KEY_USAGE, \
199 "MBEDTLS_X509_BADCERT_KEY_USAGE", \
200 "Usage does not match the keyUsage extension") \
201 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_EXT_KEY_USAGE, \
202 "MBEDTLS_X509_BADCERT_EXT_KEY_USAGE", \
203 "Usage does not match the extendedKeyUsage extension") \
204 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_NS_CERT_TYPE, \
205 "MBEDTLS_X509_BADCERT_NS_CERT_TYPE", \
206 "Usage does not match the nsCertType extension") \
207 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_MD, \
208 "MBEDTLS_X509_BADCERT_BAD_MD", \
209 "The certificate is signed with an unacceptable hash.") \
210 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_PK, \
211 "MBEDTLS_X509_BADCERT_BAD_PK", \
212 "The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \
213 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCERT_BAD_KEY, \
214 "MBEDTLS_X509_BADCERT_BAD_KEY", \
215 "The certificate is signed with an unacceptable key (eg bad curve, RSA too short).") \
216 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_MD, \
217 "MBEDTLS_X509_BADCRL_BAD_MD", \
218 "The CRL is signed with an unacceptable hash.") \
219 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_PK, \
220 "MBEDTLS_X509_BADCRL_BAD_PK", \
221 "The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).") \
222 X509_CRT_ERROR_INFO(MBEDTLS_X509_BADCRL_BAD_KEY, \
223 "MBEDTLS_X509_BADCRL_BAD_KEY", \
224 "The CRL is signed with an unacceptable key (eg bad curve, RSA too short).")
Hanno Becker7ac83f92020-10-09 10:48:22 +0100225
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200226/**
227 * Container for writing a certificate (CRT)
228 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100229typedef struct mbedtls_x509write_cert {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200230 int MBEDTLS_PRIVATE(version);
Valerio Settida0afcc2023-01-05 16:46:59 +0100231 unsigned char MBEDTLS_PRIVATE(serial)[MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN];
232 size_t MBEDTLS_PRIVATE(serial_len);
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200233 mbedtls_pk_context *MBEDTLS_PRIVATE(subject_key);
234 mbedtls_pk_context *MBEDTLS_PRIVATE(issuer_key);
235 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(subject);
236 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(issuer);
237 mbedtls_md_type_t MBEDTLS_PRIVATE(md_alg);
238 char MBEDTLS_PRIVATE(not_before)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
239 char MBEDTLS_PRIVATE(not_after)[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1];
240 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(extensions);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200241}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200242mbedtls_x509write_cert;
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200243
Andrzej Kurek1bc7df22023-04-04 07:09:04 -0400244/**
245 * \brief Set Subject Alternative Name
246 *
247 * \param ctx Certificate context to use
248 * \param san_list List of SAN values
249 *
250 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
251 *
252 * \note "dnsName", "uniformResourceIdentifier", "IP address",
253 * "otherName", and "DirectoryName", as defined in RFC 5280,
254 * are supported.
255 */
Andrzej Kurek67fdb332023-04-04 06:56:14 -0400256int mbedtls_x509write_crt_set_subject_alternative_name(mbedtls_x509write_cert *ctx,
257 const mbedtls_x509_san_list *san_list);
258
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200259/**
260 * Item in a verification chain: cert and flags for it
261 */
262typedef struct {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200263 mbedtls_x509_crt *MBEDTLS_PRIVATE(crt);
264 uint32_t MBEDTLS_PRIVATE(flags);
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200265} mbedtls_x509_crt_verify_chain_item;
266
267/**
268 * Max size of verification chain: end-entity + intermediates + trusted root
269 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100270#define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE (MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2)
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200271
272/**
273 * Verification chain as built by \c mbedtls_crt_verify_chain()
274 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100275typedef struct {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200276 mbedtls_x509_crt_verify_chain_item MBEDTLS_PRIVATE(items)[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE];
277 unsigned MBEDTLS_PRIVATE(len);
Hanno Beckerf53893b2019-03-28 13:45:55 +0000278
279#if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
280 /* This stores the list of potential trusted signers obtained from
281 * the CA callback used for the CRT verification, if configured.
282 * We must track it somewhere because the callback passes its
283 * ownership to the caller. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200284 mbedtls_x509_crt *MBEDTLS_PRIVATE(trust_ca_cb_result);
Hanno Beckerf53893b2019-03-28 13:45:55 +0000285#endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
Manuel Pégourié-Gonnardc11e4ba2017-08-14 17:17:14 +0200286} mbedtls_x509_crt_verify_chain;
287
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200288#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
289
290/**
291 * \brief Context for resuming X.509 verify operations
292 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100293typedef struct {
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200294 /* for check_signature() */
Mateusz Starzyk363eb292021-05-19 17:32:44 +0200295 mbedtls_pk_restart_ctx MBEDTLS_PRIVATE(pk);
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200296
297 /* for find_parent_in() */
Mateusz Starzyk363eb292021-05-19 17:32:44 +0200298 mbedtls_x509_crt *MBEDTLS_PRIVATE(parent); /* non-null iff parent_in in progress */
299 mbedtls_x509_crt *MBEDTLS_PRIVATE(fallback_parent);
300 int MBEDTLS_PRIVATE(fallback_signature_is_good);
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200301
302 /* for find_parent() */
Mateusz Starzyk363eb292021-05-19 17:32:44 +0200303 int MBEDTLS_PRIVATE(parent_is_trusted); /* -1 if find_parent is not in progress */
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200304
305 /* for verify_chain() */
Manuel Pégourié-Gonnarddaf04912017-08-23 12:32:19 +0200306 enum {
307 x509_crt_rs_none,
308 x509_crt_rs_find_parent,
Mateusz Starzyk363eb292021-05-19 17:32:44 +0200309 } MBEDTLS_PRIVATE(in_progress); /* none if no operation is in progress */
310 int MBEDTLS_PRIVATE(self_cnt);
311 mbedtls_x509_crt_verify_chain MBEDTLS_PRIVATE(ver_chain);
Manuel Pégourié-Gonnard8b590492017-08-14 18:04:19 +0200312
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200313} mbedtls_x509_crt_restart_ctx;
314
315#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
316
317/* Now we can declare functions that take a pointer to that */
318typedef void mbedtls_x509_crt_restart_ctx;
319
320#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
321
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200322#if defined(MBEDTLS_X509_CRT_PARSE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200323/**
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200324 * Default security profile. Should provide a good balance between security
325 * and compatibility with current deployments.
Gilles Peskineffb92da2021-06-02 00:03:26 +0200326 *
327 * This profile permits:
328 * - SHA2 hashes with at least 256 bits: SHA-256, SHA-384, SHA-512.
Gilles Peskine39957502021-06-17 23:17:52 +0200329 * - Elliptic curves with 255 bits and above except secp256k1.
Gilles Peskineffb92da2021-06-02 00:03:26 +0200330 * - RSA with 2048 bits and above.
331 *
332 * New minor versions of Mbed TLS may extend this profile, for example if
Gilles Peskine39957502021-06-17 23:17:52 +0200333 * new algorithms are added to the library. New minor versions of Mbed TLS will
Gilles Peskineffb92da2021-06-02 00:03:26 +0200334 * not reduce this profile unless serious security concerns require it.
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200335 */
336extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default;
337
338/**
339 * Expected next default profile. Recommended for new deployments.
Gilles Peskineffb92da2021-06-02 00:03:26 +0200340 * Currently targets a 128-bit security level, except for allowing RSA-2048.
341 * This profile may change at any time.
Manuel Pégourié-Gonnard88db5da2015-06-15 14:34:59 +0200342 */
343extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next;
344
345/**
346 * NSA Suite B profile.
347 */
348extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb;
349
350/**
Manuel Pégourié-Gonnard9d4c2c42021-06-18 09:48:27 +0200351 * Empty profile that allows nothing. Useful as a basis for constructing
352 * custom profiles.
353 */
354extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_none;
355
356/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200357 * \brief Parse a single DER formatted certificate and add it
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000358 * to the end of the provided chained list.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200359 *
Gilles Peskine5b7e1642022-08-04 23:44:59 +0200360 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
361 * subsystem must have been initialized by calling
362 * psa_crypto_init() before calling this function.
363 *
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000364 * \param chain The pointer to the start of the CRT chain to attach to.
365 * When parsing the first CRT in a chain, this should point
366 * to an instance of ::mbedtls_x509_crt initialized through
367 * mbedtls_x509_crt_init().
368 * \param buf The buffer holding the DER encoded certificate.
369 * \param buflen The size in Bytes of \p buf.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200370 *
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000371 * \note This function makes an internal copy of the CRT buffer
372 * \p buf. In particular, \p buf may be destroyed or reused
373 * after this call returns. To avoid duplicating the CRT
374 * buffer (at the cost of stricter lifetime constraints),
375 * use mbedtls_x509_crt_parse_der_nocopy() instead.
376 *
377 * \return \c 0 if successful.
378 * \return A negative error code on failure.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200379 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100380int mbedtls_x509_crt_parse_der(mbedtls_x509_crt *chain,
381 const unsigned char *buf,
382 size_t buflen);
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000383
384/**
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200385 * \brief The type of certificate extension callbacks.
386 *
387 * Callbacks of this type are passed to and used by the
Nicola Di Lietofde98f72020-05-28 08:34:33 +0200388 * mbedtls_x509_crt_parse_der_with_ext_cb() routine when
Nicola Di Lietoc84b1e62020-06-13 11:08:16 +0200389 * it encounters either an unsupported extension or a
390 * "certificate policies" extension containing any
391 * unsupported certificate policies.
Nicola Di Lieto511bc8c2020-06-23 00:15:28 +0200392 * Future versions of the library may invoke the callback
393 * in other cases, if and when the need arises.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200394 *
Nicola Di Lieto5659e7e2020-05-28 23:41:38 +0200395 * \param p_ctx An opaque context passed to the callback.
ndilieto6e249802020-05-28 06:17:38 +0000396 * \param crt The certificate being parsed.
397 * \param oid The OID of the extension.
398 * \param critical Whether the extension is critical.
Nicola Di Lietofae25a12020-05-28 08:55:08 +0200399 * \param p Pointer to the start of the extension value
ndilieto6e249802020-05-28 06:17:38 +0000400 * (the content of the OCTET STRING).
ndilieto6e249802020-05-28 06:17:38 +0000401 * \param end End of extension value.
Nicola Di Lieto565b52b2020-05-29 22:46:56 +0200402 *
403 * \note The callback must fail and return a negative error code
404 * if it can not parse or does not support the extension.
405 * When the callback fails to parse a critical extension
406 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails.
407 * When the callback fails to parse a non critical extension
408 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips
409 * the extension and continues parsing.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200410 *
411 * \return \c 0 on success.
412 * \return A negative error code on failure.
413 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100414typedef int (*mbedtls_x509_crt_ext_cb_t)(void *p_ctx,
415 mbedtls_x509_crt const *crt,
416 mbedtls_x509_buf const *oid,
417 int critical,
418 const unsigned char *p,
419 const unsigned char *end);
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200420
421/**
Nicola Di Lieto4dbe5672020-05-28 09:18:42 +0200422 * \brief Parse a single DER formatted certificate and add it
423 * to the end of the provided chained list.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200424 *
Gilles Peskine5b7e1642022-08-04 23:44:59 +0200425 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
426 * subsystem must have been initialized by calling
427 * psa_crypto_init() before calling this function.
428 *
Nicola Di Lieto4dbe5672020-05-28 09:18:42 +0200429 * \param chain The pointer to the start of the CRT chain to attach to.
430 * When parsing the first CRT in a chain, this should point
431 * to an instance of ::mbedtls_x509_crt initialized through
432 * mbedtls_x509_crt_init().
433 * \param buf The buffer holding the DER encoded certificate.
434 * \param buflen The size in Bytes of \p buf.
435 * \param make_copy When not zero this function makes an internal copy of the
436 * CRT buffer \p buf. In particular, \p buf may be destroyed
437 * or reused after this call returns.
438 * When zero this function avoids duplicating the CRT buffer
439 * by taking temporary ownership thereof until the CRT
440 * is destroyed (like mbedtls_x509_crt_parse_der_nocopy())
441 * \param cb A callback invoked for every unsupported certificate
442 * extension.
Nicola Di Lieto5659e7e2020-05-28 23:41:38 +0200443 * \param p_ctx An opaque context passed to the callback.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200444 *
Nicola Di Lieto4dbe5672020-05-28 09:18:42 +0200445 * \note This call is functionally equivalent to
446 * mbedtls_x509_crt_parse_der(), and/or
447 * mbedtls_x509_crt_parse_der_nocopy()
448 * but it calls the callback with every unsupported
Nicola Di Lietoc84b1e62020-06-13 11:08:16 +0200449 * certificate extension and additionally the
450 * "certificate policies" extension if it contains any
451 * unsupported certificate policies.
Nicola Di Lieto4dbe5672020-05-28 09:18:42 +0200452 * The callback must return a negative error code if it
453 * does not know how to handle such an extension.
Nicola Di Lieto565b52b2020-05-29 22:46:56 +0200454 * When the callback fails to parse a critical extension
455 * mbedtls_x509_crt_parse_der_with_ext_cb() also fails.
456 * When the callback fails to parse a non critical extension
457 * mbedtls_x509_crt_parse_der_with_ext_cb() simply skips
458 * the extension and continues parsing.
Nicola Di Lieto511bc8c2020-06-23 00:15:28 +0200459 * Future versions of the library may invoke the callback
460 * in other cases, if and when the need arises.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200461 *
Nicola Di Lieto4dbe5672020-05-28 09:18:42 +0200462 * \return \c 0 if successful.
463 * \return A negative error code on failure.
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200464 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100465int mbedtls_x509_crt_parse_der_with_ext_cb(mbedtls_x509_crt *chain,
466 const unsigned char *buf,
467 size_t buflen,
468 int make_copy,
469 mbedtls_x509_crt_ext_cb_t cb,
470 void *p_ctx);
Nicola Di Lieto502d4b42020-04-25 14:41:25 +0200471
472/**
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000473 * \brief Parse a single DER formatted certificate and add it
474 * to the end of the provided chained list. This is a
475 * variant of mbedtls_x509_crt_parse_der() which takes
476 * temporary ownership of the CRT buffer until the CRT
477 * is destroyed.
478 *
Gilles Peskine5b7e1642022-08-04 23:44:59 +0200479 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
480 * subsystem must have been initialized by calling
481 * psa_crypto_init() before calling this function.
482 *
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000483 * \param chain The pointer to the start of the CRT chain to attach to.
484 * When parsing the first CRT in a chain, this should point
485 * to an instance of ::mbedtls_x509_crt initialized through
486 * mbedtls_x509_crt_init().
487 * \param buf The address of the readable buffer holding the DER encoded
488 * certificate to use. On success, this buffer must be
Jan Brucknerb33f6e52022-10-06 11:23:49 +0200489 * retained and not be changed for the lifetime of the
Hanno Becker1a65dcd2019-01-31 08:57:44 +0000490 * CRT chain \p chain, that is, until \p chain is destroyed
491 * through a call to mbedtls_x509_crt_free().
492 * \param buflen The size in Bytes of \p buf.
493 *
494 * \note This call is functionally equivalent to
495 * mbedtls_x509_crt_parse_der(), but it avoids creating a
496 * copy of the input buffer at the cost of stronger lifetime
497 * constraints. This is useful in constrained environments
498 * where duplication of the CRT cannot be tolerated.
499 *
500 * \return \c 0 if successful.
501 * \return A negative error code on failure.
502 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100503int mbedtls_x509_crt_parse_der_nocopy(mbedtls_x509_crt *chain,
504 const unsigned char *buf,
505 size_t buflen);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200506
507/**
Hanno Becker89a91122018-08-23 16:14:00 +0100508 * \brief Parse one DER-encoded or one or more concatenated PEM-encoded
Hanno Becker65e619a2018-08-23 15:46:33 +0100509 * certificates and add them to the chained list.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200510 *
Hanno Beckere8658e22018-08-24 10:01:17 +0100511 * For CRTs in PEM encoding, the function parses permissively:
512 * if at least one certificate can be parsed, the function
Hanno Becker65e619a2018-08-23 15:46:33 +0100513 * returns the number of certificates for which parsing failed
514 * (hence \c 0 if all certificates were parsed successfully).
515 * If no certificate could be parsed, the function returns
516 * the first (negative) error encountered during parsing.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200517 *
Hanno Becker65e619a2018-08-23 15:46:33 +0100518 * PEM encoded certificates may be interleaved by other data
519 * such as human readable descriptions of their content, as
520 * long as the certificates are enclosed in the PEM specific
521 * '-----{BEGIN/END} CERTIFICATE-----' delimiters.
522 *
Gilles Peskine5b7e1642022-08-04 23:44:59 +0200523 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
524 * subsystem must have been initialized by calling
525 * psa_crypto_init() before calling this function.
526 *
Hanno Becker65e619a2018-08-23 15:46:33 +0100527 * \param chain The chain to which to add the parsed certificates.
528 * \param buf The buffer holding the certificate data in PEM or DER format.
529 * For certificates in PEM encoding, this may be a concatenation
530 * of multiple certificates; for DER encoding, the buffer must
531 * comprise exactly one certificate.
532 * \param buflen The size of \p buf, including the terminating \c NULL byte
533 * in case of PEM encoded data.
534 *
535 * \return \c 0 if all certificates were parsed successfully.
536 * \return The (positive) number of certificates that couldn't
537 * be parsed if parsing was partly successful (see above).
Hanno Becker89a91122018-08-23 16:14:00 +0100538 * \return A negative X509 or PEM error code otherwise.
Hanno Becker65e619a2018-08-23 15:46:33 +0100539 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200540 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100541int mbedtls_x509_crt_parse(mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200542
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200543#if defined(MBEDTLS_FS_IO)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200544/**
545 * \brief Load one or more certificates and add them
546 * to the chained list. Parses permissively. If some
547 * certificates can be parsed, the result is the number
548 * of failed certificates it encountered. If none complete
549 * correctly, the first error is returned.
550 *
Gilles Peskine5b7e1642022-08-04 23:44:59 +0200551 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
552 * subsystem must have been initialized by calling
553 * psa_crypto_init() before calling this function.
554 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200555 * \param chain points to the start of the chain
556 * \param path filename to read the certificates from
557 *
558 * \return 0 if all certificates parsed successfully, a positive number
559 * if partly successful or a specific X509 or PEM error code
560 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100561int mbedtls_x509_crt_parse_file(mbedtls_x509_crt *chain, const char *path);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200562
563/**
564 * \brief Load one or more certificate files from a path and add them
565 * to the chained list. Parses permissively. If some
566 * certificates can be parsed, the result is the number
567 * of failed certificates it encountered. If none complete
568 * correctly, the first error is returned.
569 *
570 * \param chain points to the start of the chain
571 * \param path directory / folder to read the certificate files from
572 *
573 * \return 0 if all certificates parsed successfully, a positive number
574 * if partly successful or a specific X509 or PEM error code
575 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100576int mbedtls_x509_crt_parse_path(mbedtls_x509_crt *chain, const char *path);
Janos Follath11b41eb2019-05-08 15:26:49 +0100577
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200578#endif /* MBEDTLS_FS_IO */
toth92g8d435a02021-05-10 15:16:33 +0200579
Hanno Becker612a2f12020-10-09 09:19:39 +0100580#if !defined(MBEDTLS_X509_REMOVE_INFO)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200581/**
582 * \brief Returns an informational string about the
583 * certificate.
584 *
585 * \param buf Buffer to write to
586 * \param size Maximum size of buffer
587 * \param prefix A line prefix
588 * \param crt The X509 certificate to represent
589 *
Manuel Pégourié-Gonnarde244f9f2015-06-23 12:10:45 +0200590 * \return The length of the string written (not including the
591 * terminated nul byte), or a negative error code.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200592 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100593int mbedtls_x509_crt_info(char *buf, size_t size, const char *prefix,
594 const mbedtls_x509_crt *crt);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200595
596/**
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100597 * \brief Returns an informational string about the
598 * verification status of a certificate.
599 *
600 * \param buf Buffer to write to
601 * \param size Maximum size of buffer
602 * \param prefix A line prefix
603 * \param flags Verification flags created by mbedtls_x509_crt_verify()
604 *
Manuel Pégourié-Gonnarde244f9f2015-06-23 12:10:45 +0200605 * \return The length of the string written (not including the
606 * terminated nul byte), or a negative error code.
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100607 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100608int mbedtls_x509_crt_verify_info(char *buf, size_t size, const char *prefix,
609 uint32_t flags);
Hanno Becker88c2bf32019-06-14 17:21:24 +0100610#endif /* !MBEDTLS_X509_REMOVE_INFO */
Manuel Pégourié-Gonnard39a183a2015-04-17 16:14:32 +0200611
612/**
Hanno Becker902451d2019-03-27 11:48:40 +0000613 * \brief Verify a chain of certificates.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200614 *
615 * The verify callback is a user-supplied callback that
616 * can clear / modify / add flags for a certificate. If set,
617 * the verification callback is called for each
618 * certificate in the chain (from the trust-ca down to the
619 * presented crt). The parameters for the callback are:
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200620 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth,
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200621 * int *flags). With the flags representing current flags for
622 * that specific certificate and the certificate depth from
623 * the bottom (Peer cert depth = 0).
624 *
625 * All flags left after returning from the callback
626 * are also returned to the application. The function should
Manuel Pégourié-Gonnard31458a12017-06-26 10:11:49 +0200627 * return 0 for anything (including invalid certificates)
628 * other than fatal error, as a non-zero return code
629 * immediately aborts the verification process. For fatal
630 * errors, a specific error code should be used (different
631 * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not
632 * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR
633 * can be used if no better code is available.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200634 *
Manuel Pégourié-Gonnardb5f48ad2015-04-20 10:38:13 +0100635 * \note In case verification failed, the results can be displayed
636 * using \c mbedtls_x509_crt_verify_info()
637 *
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200638 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
639 * default security profile.
640 *
Manuel Pégourié-Gonnardeeef9472016-02-22 11:36:55 +0100641 * \note It is your responsibility to provide up-to-date CRLs for
642 * all trusted CAs. If no CRL is provided for the CA that was
643 * used to sign the certificate, CRL verification is skipped
644 * silently, that is *without* setting any flag.
645 *
Manuel Pégourié-Gonnard08eacec2017-10-18 14:20:24 +0200646 * \note The \c trust_ca list can contain two types of certificates:
Manuel Pégourié-Gonnarda4a206e2017-06-21 09:35:44 +0200647 * (1) those of trusted root CAs, so that certificates
648 * chaining up to those CAs will be trusted, and (2)
649 * self-signed end-entity certificates to be trusted (for
650 * specific peers you know) - in that case, the self-signed
Manuel Pégourié-Gonnard562df402017-08-08 18:09:14 +0200651 * certificate doesn't need to have the CA bit set.
Manuel Pégourié-Gonnarda4a206e2017-06-21 09:35:44 +0200652 *
Hanno Becker902451d2019-03-27 11:48:40 +0000653 * \param crt The certificate chain to be verified.
654 * \param trust_ca The list of trusted CAs.
655 * \param ca_crl The list of CRLs for trusted CAs.
Manuel Pégourié-Gonnardf58e5cc2020-07-24 10:31:37 +0200656 * \param cn The expected Common Name. This will be checked to be
657 * present in the certificate's subjectAltNames extension or,
658 * if this extension is absent, as a CN component in its
Andrzej Kurek199eab92023-05-10 09:57:19 -0400659 * Subject name. DNS names and IP addresses are fully
660 * supported, while the URI subtype is partially supported:
661 * only exact matching, without any normalization procedures
662 * described in 7.4 of RFC5280, will result in a positive
663 * URI verification.
664 * This may be \c NULL if the CN need not be verified.
Hanno Becker902451d2019-03-27 11:48:40 +0000665 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100666 * If the verification couldn't be completed, the flag value is
667 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000668 * \param f_vrfy The verification callback to use. See the documentation
669 * of mbedtls_x509_crt_verify() for more information.
670 * \param p_vrfy The context to be passed to \p f_vrfy.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200671 *
Hanno Becker902451d2019-03-27 11:48:40 +0000672 * \return \c 0 if the chain is valid with respect to the
673 * passed CN, CAs, CRLs and security profile.
674 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
675 * certificate chain verification failed. In this case,
676 * \c *flags will have one or more
677 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
678 * flags set.
679 * \return Another negative error code in case of a fatal error
680 * encountered during the verification process.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200681 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100682int mbedtls_x509_crt_verify(mbedtls_x509_crt *crt,
683 mbedtls_x509_crt *trust_ca,
684 mbedtls_x509_crl *ca_crl,
685 const char *cn, uint32_t *flags,
686 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
687 void *p_vrfy);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200688
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200689/**
Hanno Becker902451d2019-03-27 11:48:40 +0000690 * \brief Verify a chain of certificates with respect to
691 * a configurable security profile.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200692 *
693 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit
694 * security profile.
695 *
Manuel Pégourié-Gonnard27716cc2015-06-17 11:49:39 +0200696 * \note The restrictions on keys (RSA minimum size, allowed curves
Manuel Pégourié-Gonnard65eefc82015-10-23 14:08:48 +0200697 * for ECDSA) apply to all certificates: trusted root,
698 * intermediate CAs if any, and end entity certificate.
Manuel Pégourié-Gonnard27716cc2015-06-17 11:49:39 +0200699 *
Hanno Becker902451d2019-03-27 11:48:40 +0000700 * \param crt The certificate chain to be verified.
701 * \param trust_ca The list of trusted CAs.
702 * \param ca_crl The list of CRLs for trusted CAs.
703 * \param profile The security profile to use for the verification.
704 * \param cn The expected Common Name. This may be \c NULL if the
705 * CN need not be verified.
706 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100707 * If the verification couldn't be completed, the flag value is
708 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000709 * \param f_vrfy The verification callback to use. See the documentation
710 * of mbedtls_x509_crt_verify() for more information.
711 * \param p_vrfy The context to be passed to \p f_vrfy.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200712 *
Hanno Becker902451d2019-03-27 11:48:40 +0000713 * \return \c 0 if the chain is valid with respect to the
714 * passed CN, CAs, CRLs and security profile.
715 * \return #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
716 * certificate chain verification failed. In this case,
717 * \c *flags will have one or more
718 * \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
719 * flags set.
720 * \return Another negative error code in case of a fatal error
721 * encountered during the verification process.
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200722 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100723int mbedtls_x509_crt_verify_with_profile(mbedtls_x509_crt *crt,
724 mbedtls_x509_crt *trust_ca,
725 mbedtls_x509_crl *ca_crl,
726 const mbedtls_x509_crt_profile *profile,
727 const char *cn, uint32_t *flags,
728 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
729 void *p_vrfy);
Manuel Pégourié-Gonnard95051642015-06-15 10:39:46 +0200730
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200731/**
732 * \brief Restartable version of \c mbedtls_crt_verify_with_profile()
733 *
734 * \note Performs the same job as \c mbedtls_crt_verify_with_profile()
735 * but can return early and restart according to the limit
736 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
737 *
Hanno Becker902451d2019-03-27 11:48:40 +0000738 * \param crt The certificate chain to be verified.
739 * \param trust_ca The list of trusted CAs.
740 * \param ca_crl The list of CRLs for trusted CAs.
741 * \param profile The security profile to use for the verification.
742 * \param cn The expected Common Name. This may be \c NULL if the
743 * CN need not be verified.
744 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100745 * If the verification couldn't be completed, the flag value is
746 * set to (uint32_t) -1.
Hanno Becker902451d2019-03-27 11:48:40 +0000747 * \param f_vrfy The verification callback to use. See the documentation
748 * of mbedtls_x509_crt_verify() for more information.
749 * \param p_vrfy The context to be passed to \p f_vrfy.
750 * \param rs_ctx The restart context to use. This may be set to \c NULL
751 * to disable restartable ECC.
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200752 *
753 * \return See \c mbedtls_crt_verify_with_profile(), or
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200754 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200755 * operations was reached: see \c mbedtls_ecp_set_max_ops().
756 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100757int mbedtls_x509_crt_verify_restartable(mbedtls_x509_crt *crt,
758 mbedtls_x509_crt *trust_ca,
759 mbedtls_x509_crl *ca_crl,
760 const mbedtls_x509_crt_profile *profile,
761 const char *cn, uint32_t *flags,
762 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
763 void *p_vrfy,
764 mbedtls_x509_crt_restart_ctx *rs_ctx);
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200765
Hanno Becker5c8df782019-03-27 11:01:17 +0000766/**
767 * \brief The type of trusted certificate callbacks.
768 *
769 * Callbacks of this type are passed to and used by the CRT
Jarno Lamsa31d9db62019-04-01 14:33:49 +0300770 * verification routine mbedtls_x509_crt_verify_with_ca_cb()
Hanno Becker5c8df782019-03-27 11:01:17 +0000771 * when looking for trusted signers of a given certificate.
772 *
773 * On success, the callback returns a list of trusted
774 * certificates to be considered as potential signers
775 * for the input certificate.
776 *
777 * \param p_ctx An opaque context passed to the callback.
778 * \param child The certificate for which to search a potential signer.
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300779 * This will point to a readable certificate.
Hanno Becker5c8df782019-03-27 11:01:17 +0000780 * \param candidate_cas The address at which to store the address of the first
781 * entry in the generated linked list of candidate signers.
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300782 * This will not be \c NULL.
Hanno Becker5c8df782019-03-27 11:01:17 +0000783 *
784 * \note The callback must only return a non-zero value on a
785 * fatal error. If, in contrast, the search for a potential
786 * signer completes without a single candidate, the
Jarno Lamsaf49fedc2019-04-01 14:58:30 +0300787 * callback must return \c 0 and set \c *candidate_cas
Hanno Becker5c8df782019-03-27 11:01:17 +0000788 * to \c NULL.
789 *
790 * \return \c 0 on success. In this case, \c *candidate_cas points
791 * to a heap-allocated linked list of instances of
792 * ::mbedtls_x509_crt, and ownership of this list is passed
793 * to the caller.
794 * \return A negative error code on failure.
795 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100796typedef int (*mbedtls_x509_crt_ca_cb_t)(void *p_ctx,
797 mbedtls_x509_crt const *child,
798 mbedtls_x509_crt **candidate_cas);
Hanno Beckere15dae72019-03-28 13:55:38 +0000799
800#if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
Hanno Becker5c8df782019-03-27 11:01:17 +0000801/**
802 * \brief Version of \c mbedtls_x509_crt_verify_with_profile() which
803 * uses a callback to acquire the list of trusted CA
804 * certificates.
805 *
806 * \param crt The certificate chain to be verified.
807 * \param f_ca_cb The callback to be used to query for potential signers
808 * of a given child certificate. See the documentation of
809 * ::mbedtls_x509_crt_ca_cb_t for more information.
810 * \param p_ca_cb The opaque context to be passed to \p f_ca_cb.
811 * \param profile The security profile for the verification.
812 * \param cn The expected Common Name. This may be \c NULL if the
813 * CN need not be verified.
814 * \param flags The address at which to store the result of the verification.
Janos Follath846ae7a2019-04-05 16:45:01 +0100815 * If the verification couldn't be completed, the flag value is
816 * set to (uint32_t) -1.
Hanno Becker5c8df782019-03-27 11:01:17 +0000817 * \param f_vrfy The verification callback to use. See the documentation
818 * of mbedtls_x509_crt_verify() for more information.
819 * \param p_vrfy The context to be passed to \p f_vrfy.
820 *
821 * \return See \c mbedtls_crt_verify_with_profile().
822 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100823int mbedtls_x509_crt_verify_with_ca_cb(mbedtls_x509_crt *crt,
824 mbedtls_x509_crt_ca_cb_t f_ca_cb,
825 void *p_ca_cb,
826 const mbedtls_x509_crt_profile *profile,
827 const char *cn, uint32_t *flags,
828 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
829 void *p_vrfy);
Hanno Becker5c8df782019-03-27 11:01:17 +0000830
831#endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
832
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200833/**
834 * \brief Check usage of certificate against keyUsage extension.
835 *
836 * \param crt Leaf certificate used.
Manuel Pégourié-Gonnard655a9642015-06-23 10:48:44 +0200837 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT
838 * before using the certificate to perform an RSA key
839 * exchange).
840 *
841 * \note Except for decipherOnly and encipherOnly, a bit set in the
842 * usage argument means this bit MUST be set in the
843 * certificate. For decipherOnly and encipherOnly, it means
844 * that bit MAY be set.
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200845 *
846 * \return 0 is these uses of the certificate are allowed,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200847 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension
Manuel Pégourié-Gonnard655a9642015-06-23 10:48:44 +0200848 * is present but does not match the usage argument.
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200849 *
850 * \note You should only call this function on leaf certificates, on
851 * (intermediate) CAs the keyUsage extension is automatically
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200852 * checked by \c mbedtls_x509_crt_verify().
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200853 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100854int mbedtls_x509_crt_check_key_usage(const mbedtls_x509_crt *crt,
855 unsigned int usage);
Manuel Pégourié-Gonnard603116c2014-04-09 09:50:03 +0200856
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200857/**
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000858 * \brief Check usage of certificate against extendedKeyUsage.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200859 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000860 * \param crt Leaf certificate used.
861 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
862 * MBEDTLS_OID_CLIENT_AUTH).
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200863 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200864 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000865 * \return 0 if this use of the certificate is allowed,
866 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200867 *
Andres Amaya Garcia5a6da632017-11-14 21:40:51 +0000868 * \note Usually only makes sense on leaf certificates.
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200869 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100870int mbedtls_x509_crt_check_extended_key_usage(const mbedtls_x509_crt *crt,
871 const char *usage_oid,
872 size_t usage_len);
Manuel Pégourié-Gonnard7afb8a02014-04-10 17:53:56 +0200873
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200874#if defined(MBEDTLS_X509_CRL_PARSE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200875/**
Manuel Pégourié-Gonnardcbf3ef32013-09-23 12:20:02 +0200876 * \brief Verify the certificate revocation status
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200877 *
878 * \param crt a certificate to be verified
879 * \param crl the CRL to verify against
880 *
881 * \return 1 if the certificate is revoked, 0 otherwise
882 *
883 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100884int mbedtls_x509_crt_is_revoked(const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200885#endif /* MBEDTLS_X509_CRL_PARSE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200886
887/**
Paul Bakker369d2eb2013-09-18 11:58:25 +0200888 * \brief Initialize a certificate (chain)
889 *
890 * \param crt Certificate chain to initialize
891 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100892void mbedtls_x509_crt_init(mbedtls_x509_crt *crt);
Paul Bakker369d2eb2013-09-18 11:58:25 +0200893
894/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200895 * \brief Unallocate all certificate data
896 *
897 * \param crt Certificate chain to free
898 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100899void mbedtls_x509_crt_free(mbedtls_x509_crt *crt);
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200900
901#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
902/**
903 * \brief Initialize a restart context
904 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100905void mbedtls_x509_crt_restart_init(mbedtls_x509_crt_restart_ctx *ctx);
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200906
907/**
908 * \brief Free the components of a restart context
909 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100910void mbedtls_x509_crt_restart_free(mbedtls_x509_crt_restart_ctx *ctx);
Manuel Pégourié-Gonnardbc3f44a2017-07-11 11:02:20 +0200911#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200912#endif /* MBEDTLS_X509_CRT_PARSE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200913
Thomas Daubneya5f39e02022-06-06 15:42:32 +0100914/**
915 * \brief Query certificate for given extension type
916 *
917 * \param[in] ctx Certificate context to be queried, must not be \c NULL
918 * \param ext_type Extension type being queried for, must be a valid
919 * extension type. Must be one of the MBEDTLS_X509_EXT_XXX
920 * values
921 *
922 * \return 0 if the given extension type is not present,
923 * non-zero otherwise
924 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100925static inline int mbedtls_x509_crt_has_ext_type(const mbedtls_x509_crt *ctx,
926 int ext_type)
Thomas Daubneya5f39e02022-06-06 15:42:32 +0100927{
928 return ctx->MBEDTLS_PRIVATE(ext_types) & ext_type;
929}
930
Andrzej Kurek38d4fdd2021-12-28 16:22:52 +0100931/** \} name Structures and functions for parsing and writing X.509 certificates */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200932
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200933#if defined(MBEDTLS_X509_CRT_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200934/**
935 * \brief Initialize a CRT writing context
936 *
937 * \param ctx CRT context to initialize
938 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100939void mbedtls_x509write_crt_init(mbedtls_x509write_cert *ctx);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200940
941/**
Shaun Case8b0ecbc2021-12-20 21:14:10 -0800942 * \brief Set the version for a Certificate
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200943 * Default: MBEDTLS_X509_CRT_VERSION_3
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200944 *
945 * \param ctx CRT context to use
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200946 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or
947 * MBEDTLS_X509_CRT_VERSION_3)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200948 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100949void mbedtls_x509write_crt_set_version(mbedtls_x509write_cert *ctx, int version);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200950
Valerio Setti5d164c42023-01-09 12:19:40 +0100951#if defined(MBEDTLS_BIGNUM_C) && !defined(MBEDTLS_DEPRECATED_REMOVED)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200952/**
953 * \brief Set the serial number for a Certificate.
954 *
Valerio Settida0afcc2023-01-05 16:46:59 +0100955 * \deprecated This function is deprecated and will be removed in a
956 * future version of the library. Please use
Valerio Settiaf4815c2023-01-26 17:43:09 +0100957 * mbedtls_x509write_crt_set_serial_raw() instead.
Valerio Settida0afcc2023-01-05 16:46:59 +0100958 *
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 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200964 * \param ctx CRT context to use
965 * \param serial serial number to set
966 *
967 * \return 0 if successful
968 */
Valerio Setti5d164c42023-01-09 12:19:40 +0100969int MBEDTLS_DEPRECATED mbedtls_x509write_crt_set_serial(
970 mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial);
971#endif // MBEDTLS_BIGNUM_C && !MBEDTLS_DEPRECATED_REMOVED
Valerio Settida0afcc2023-01-05 16:46:59 +0100972
973/**
974 * \brief Set the serial number for a Certificate.
975 *
Valerio Setti746def52023-01-10 11:46:34 +0100976 * \param ctx CRT context to use
977 * \param serial A raw array of bytes containing the serial number in big
978 * endian format
Valerio Setti9b5e1da2023-01-26 17:49:10 +0100979 * \param serial_len Length of valid bytes (expressed in bytes) in \p serial
980 * input buffer
Valerio Settida0afcc2023-01-05 16:46:59 +0100981 *
982 * \return 0 if successful, or
Valerio Settiacf12fb2023-01-09 17:19:26 +0100983 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the provided input buffer
984 * is too big (longer than MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN)
Valerio Settida0afcc2023-01-05 16:46:59 +0100985 */
Valerio Settiaf4815c2023-01-26 17:43:09 +0100986int mbedtls_x509write_crt_set_serial_raw(mbedtls_x509write_cert *ctx,
Valerio Setti746def52023-01-10 11:46:34 +0100987 unsigned char *serial, size_t serial_len);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200988
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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001003int mbedtls_x509write_crt_set_validity(mbedtls_x509write_cert *ctx, const char *not_before,
1004 const char *not_after);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001005
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:
Gilles Peskinee820c0a2023-08-03 17:45:20 +02001010 * e.g. "C=UK,O=ARM,CN=Mbed TLS CA"
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001011 *
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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001018int mbedtls_x509write_crt_set_issuer_name(mbedtls_x509write_cert *ctx,
1019 const char *issuer_name);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001020
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:
Gilles Peskinee820c0a2023-08-03 17:45:20 +02001025 * e.g. "C=UK,O=ARM,CN=Mbed TLS Server 1"
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001026 *
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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001033int mbedtls_x509write_crt_set_subject_name(mbedtls_x509write_cert *ctx,
1034 const char *subject_name);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001035
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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001042void mbedtls_x509write_crt_set_subject_key(mbedtls_x509write_cert *ctx, mbedtls_pk_context *key);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001043
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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001050void mbedtls_x509write_crt_set_issuer_key(mbedtls_x509write_cert *ctx, mbedtls_pk_context *key);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001051
1052/**
1053 * \brief Set the MD algorithm to use for the signature
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001054 * (e.g. MBEDTLS_MD_SHA1)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001055 *
1056 * \param ctx CRT context to use
Paul Bakkera36d23e2013-12-30 17:57:27 +01001057 * \param md_alg MD algorithm to use
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001058 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001059void mbedtls_x509write_crt_set_md_alg(mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001060
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 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001072 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001073 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001074int 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);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001078
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
Tom Cosgrove1e211442022-05-26 11:51:00 +01001086 * unlimited)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001087 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001088 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001089 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001090int mbedtls_x509write_crt_set_basic_constraints(mbedtls_x509write_cert *ctx,
1091 int is_ca, int max_pathlen);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001092
Manuel Pégourié-Gonnarda9464892023-03-17 12:08:50 +01001093#if defined(MBEDTLS_MD_CAN_SHA1)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001094/**
1095 * \brief Set the subjectKeyIdentifier extension for a CRT
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001096 * Requires that mbedtls_x509write_crt_set_subject_key() has been
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001097 * called before
1098 *
1099 * \param ctx CRT context to use
1100 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001101 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001102 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001103int mbedtls_x509write_crt_set_subject_key_identifier(mbedtls_x509write_cert *ctx);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001104
1105/**
1106 * \brief Set the authorityKeyIdentifier extension for a CRT
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001107 * Requires that mbedtls_x509write_crt_set_issuer_key() has been
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001108 * called before
1109 *
1110 * \param ctx CRT context to use
1111 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001112 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001113 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001114int mbedtls_x509write_crt_set_authority_key_identifier(mbedtls_x509write_cert *ctx);
Manuel Pégourié-Gonnarda9464892023-03-17 12:08:50 +01001115#endif /* MBEDTLS_MD_CAN_SHA1 */
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001116
1117/**
1118 * \brief Set the Key Usage Extension flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001119 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001120 *
1121 * \param ctx CRT context to use
1122 * \param key_usage key usage flags to set
1123 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001124 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001125 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001126int mbedtls_x509write_crt_set_key_usage(mbedtls_x509write_cert *ctx,
1127 unsigned int key_usage);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001128
1129/**
Nicholas Wilson8e5bdfb2015-09-09 19:03:34 +01001130 * \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 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001139int mbedtls_x509write_crt_set_ext_key_usage(mbedtls_x509write_cert *ctx,
1140 const mbedtls_asn1_sequence *exts);
Nicholas Wilson8e5bdfb2015-09-09 19:03:34 +01001141
1142/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001143 * \brief Set the Netscape Cert Type flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001144 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001145 *
1146 * \param ctx CRT context to use
1147 * \param ns_cert_type Netscape Cert Type flags to set
1148 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +02001149 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001150 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001151int mbedtls_x509write_crt_set_ns_cert_type(mbedtls_x509write_cert *ctx,
1152 unsigned char ns_cert_type);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001153
1154/**
1155 * \brief Free the contents of a CRT write context
1156 *
1157 * \param ctx CRT context to free
1158 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001159void mbedtls_x509write_crt_free(mbedtls_x509write_cert *ctx);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001160
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 *
Paul Bakkera36d23e2013-12-30 17:57:27 +01001167 * \param ctx certificate to write away
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001168 * \param buf buffer to write to
1169 * \param size size of the buffer
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +02001170 * \param f_rng RNG function. This must not be \c NULL.
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001171 * \param p_rng RNG parameter
1172 *
1173 * \return length of data written if successful, or a specific
1174 * error code
1175 *
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +02001176 * \note \p f_rng is used for the signature operation.
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001177 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001178int 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);
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001181
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001182#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001183/**
1184 * \brief Write a built up certificate to a X509 PEM string
1185 *
Paul Bakkera36d23e2013-12-30 17:57:27 +01001186 * \param ctx certificate to write away
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001187 * \param buf buffer to write to
1188 * \param size size of the buffer
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +02001189 * \param f_rng RNG function. This must not be \c NULL.
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001190 * \param p_rng RNG parameter
1191 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +02001192 * \return 0 if successful, or a specific error code
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001193 *
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +02001194 * \note \p f_rng is used for the signature operation.
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001195 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001196int 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);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001199#endif /* MBEDTLS_PEM_WRITE_C */
1200#endif /* MBEDTLS_X509_CRT_WRITE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001201
Andrzej Kureka0defed2021-12-30 12:33:31 +01001202/** \} addtogroup x509_module */
1203
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001204#ifdef __cplusplus
1205}
1206#endif
1207
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001208#endif /* mbedtls_x509_crt.h */