blob: 0ac844fc9e52af3ec113aefdb870a163069ceeab [file] [log] [blame]
Paul Bakker7c6b2c32013-09-16 13:49:26 +02001/**
Simon Butcher5b331b92016-01-03 16:14:14 +00002 * \file x509_csr.h
Paul Bakker7c6b2c32013-09-16 13:49:26 +02003 *
4 * \brief X.509 certificate signing request 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_CSR_H
23#define MBEDTLS_X509_CSR_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"
Paul Bakker7c6b2c32013-09-16 13:49:26 +020029
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/**
35 * \addtogroup x509_module
36 * \{ */
37
38/**
39 * \name Structures and functions for X.509 Certificate Signing Requests (CSR)
40 * \{
41 */
42
43/**
44 * Certificate Signing Request (CSR) structure.
Gilles Peskine842edf42021-08-04 21:56:10 +020045 *
46 * Some fields of this structure are publicly readable. Do not modify
47 * them except via Mbed TLS library functions: the effect of modifying
Gilles Peskine44ffc792021-08-31 22:59:35 +020048 * those fields or the data that those fields point to is unspecified.
Paul Bakker7c6b2c32013-09-16 13:49:26 +020049 */
Gilles Peskine449bd832023-01-11 14:50:10 +010050typedef struct mbedtls_x509_csr {
Gilles Peskine842edf42021-08-04 21:56:10 +020051 mbedtls_x509_buf raw; /**< The raw CSR data (DER). */
52 mbedtls_x509_buf cri; /**< The raw CertificateRequestInfo body (DER). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020053
Gilles Peskine842edf42021-08-04 21:56:10 +020054 int version; /**< CSR version (1=v1). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020055
Gilles Peskine842edf42021-08-04 21:56:10 +020056 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). */
57 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020058
Gilles Peskine842edf42021-08-04 21:56:10 +020059 mbedtls_pk_context pk; /**< Container for the public key context. */
Paul Bakker7c6b2c32013-09-16 13:49:26 +020060
Jens Alfke2d9e3592019-10-29 15:03:37 -070061 unsigned int key_usage; /**< Optional key usage extension value: See the values in x509.h */
62 unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */
63 mbedtls_x509_sequence subject_alt_names; /**< Optional list of raw entries of Subject Alternative Names extension (currently only dNSName and OtherName are listed). */
64
Przemek Stekielcbaf3162023-01-12 12:58:02 +010065 int MBEDTLS_PRIVATE(ext_types); /**< Bit string containing detected and parsed extensions */
66
Gilles Peskine842edf42021-08-04 21:56:10 +020067 mbedtls_x509_buf sig_oid;
Mateusz Starzyk846f0212021-05-19 19:44:07 +020068 mbedtls_x509_buf MBEDTLS_PRIVATE(sig);
69 mbedtls_md_type_t MBEDTLS_PRIVATE(sig_md); /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
70 mbedtls_pk_type_t MBEDTLS_PRIVATE(sig_pk); /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
71 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 +020072}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020073mbedtls_x509_csr;
Paul Bakker7c6b2c32013-09-16 13:49:26 +020074
75/**
76 * Container for writing a CSR
77 */
Gilles Peskine449bd832023-01-11 14:50:10 +010078typedef struct mbedtls_x509write_csr {
Mateusz Starzyk846f0212021-05-19 19:44:07 +020079 mbedtls_pk_context *MBEDTLS_PRIVATE(key);
80 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(subject);
81 mbedtls_md_type_t MBEDTLS_PRIVATE(md_alg);
82 mbedtls_asn1_named_data *MBEDTLS_PRIVATE(extensions);
Paul Bakker7c6b2c32013-09-16 13:49:26 +020083}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020084mbedtls_x509write_csr;
Paul Bakker7c6b2c32013-09-16 13:49:26 +020085
Hannes Tschofenig6b108602022-12-28 18:38:53 +010086typedef struct mbedtls_x509_san_list {
Przemek Stekiel5a49d3c2023-02-24 13:12:55 +010087 mbedtls_x509_subject_alternative_name node;
Hannes Tschofenig6b108602022-12-28 18:38:53 +010088 struct mbedtls_x509_san_list *next;
89}
90mbedtls_x509_san_list;
91
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020092#if defined(MBEDTLS_X509_CSR_PARSE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +020093/**
Manuel Pégourié-Gonnardf3b47242014-06-16 18:06:48 +020094 * \brief Load a Certificate Signing Request (CSR) in DER format
95 *
Manuel Pégourié-Gonnard986bbf22016-02-24 14:36:05 +000096 * \note CSR attributes (if any) are currently silently ignored.
97 *
Manuel Pégourié-Gonnardf3b47242014-06-16 18:06:48 +020098 * \param csr CSR context to fill
99 * \param buf buffer holding the CRL data
100 * \param buflen size of the buffer
101 *
102 * \return 0 if successful, or a specific X509 error code
103 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100104int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr,
105 const unsigned char *buf, size_t buflen);
Manuel Pégourié-Gonnardf3b47242014-06-16 18:06:48 +0200106
107/**
108 * \brief Load a Certificate Signing Request (CSR), DER or PEM format
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200109 *
Manuel Pégourié-Gonnard986bbf22016-02-24 14:36:05 +0000110 * \note See notes for \c mbedtls_x509_csr_parse_der()
111 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200112 * \param csr CSR context to fill
113 * \param buf buffer holding the CRL data
114 * \param buflen size of the buffer
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200115 * (including the terminating null byte for PEM data)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200116 *
117 * \return 0 if successful, or a specific X509 or PEM error code
118 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100119int mbedtls_x509_csr_parse(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200120
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200121#if defined(MBEDTLS_FS_IO)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200122/**
123 * \brief Load a Certificate Signing Request (CSR)
124 *
Manuel Pégourié-Gonnard986bbf22016-02-24 14:36:05 +0000125 * \note See notes for \c mbedtls_x509_csr_parse()
126 *
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200127 * \param csr CSR context to fill
128 * \param path filename to read the CSR from
129 *
130 * \return 0 if successful, or a specific X509 or PEM error code
131 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100132int mbedtls_x509_csr_parse_file(mbedtls_x509_csr *csr, const char *path);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200133#endif /* MBEDTLS_FS_IO */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200134
Hanno Becker612a2f12020-10-09 09:19:39 +0100135#if !defined(MBEDTLS_X509_REMOVE_INFO)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200136/**
137 * \brief Returns an informational string about the
138 * CSR.
139 *
140 * \param buf Buffer to write to
141 * \param size Maximum size of buffer
142 * \param prefix A line prefix
143 * \param csr The X509 CSR to represent
144 *
Manuel Pégourié-Gonnarde244f9f2015-06-23 12:10:45 +0200145 * \return The length of the string written (not including the
146 * terminated nul byte), or a negative error code.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200147 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100148int mbedtls_x509_csr_info(char *buf, size_t size, const char *prefix,
149 const mbedtls_x509_csr *csr);
Hanno Becker88c2bf32019-06-14 17:21:24 +0100150#endif /* !MBEDTLS_X509_REMOVE_INFO */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200151
152/**
Paul Bakker369d2eb2013-09-18 11:58:25 +0200153 * \brief Initialize a CSR
154 *
155 * \param csr CSR to initialize
156 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100157void mbedtls_x509_csr_init(mbedtls_x509_csr *csr);
Paul Bakker369d2eb2013-09-18 11:58:25 +0200158
159/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200160 * \brief Unallocate all CSR data
161 *
162 * \param csr CSR to free
163 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100164void mbedtls_x509_csr_free(mbedtls_x509_csr *csr);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200165#endif /* MBEDTLS_X509_CSR_PARSE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200166
Andrzej Kurek38d4fdd2021-12-28 16:22:52 +0100167/** \} name Structures and functions for X.509 Certificate Signing Requests (CSR) */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200168
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200169#if defined(MBEDTLS_X509_CSR_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200170/**
171 * \brief Initialize a CSR context
172 *
173 * \param ctx CSR context to initialize
174 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100175void mbedtls_x509write_csr_init(mbedtls_x509write_csr *ctx);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200176
177/**
178 * \brief Set the subject name for a CSR
179 * Subject names should contain a comma-separated list
180 * of OID types and values:
Manuel Pégourié-Gonnardb4fe3cb2015-01-22 16:11:05 +0000181 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200182 *
183 * \param ctx CSR context to use
184 * \param subject_name subject name to set
185 *
186 * \return 0 if subject name was parsed successfully, or
187 * a specific error code
188 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100189int mbedtls_x509write_csr_set_subject_name(mbedtls_x509write_csr *ctx,
190 const char *subject_name);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200191
192/**
193 * \brief Set the key for a CSR (public key will be included,
194 * private key used to sign the CSR when writing it)
195 *
196 * \param ctx CSR context to use
Shaun Case8b0ecbc2021-12-20 21:14:10 -0800197 * \param key Asymmetric key to include
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200198 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100199void mbedtls_x509write_csr_set_key(mbedtls_x509write_csr *ctx, mbedtls_pk_context *key);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200200
201/**
202 * \brief Set the MD algorithm to use for the signature
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200203 * (e.g. MBEDTLS_MD_SHA1)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200204 *
205 * \param ctx CSR context to use
206 * \param md_alg MD algorithm to use
207 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100208void mbedtls_x509write_csr_set_md_alg(mbedtls_x509write_csr *ctx, mbedtls_md_type_t md_alg);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200209
210/**
211 * \brief Set the Key Usage Extension flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200212 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200213 *
214 * \param ctx CSR context to use
215 * \param key_usage key usage flags to set
216 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200217 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Andres Amaya Garciad8233f72018-10-08 19:44:55 +0100218 *
219 * \note The <code>decipherOnly</code> flag from the Key Usage
220 * extension is represented by bit 8 (i.e.
221 * <code>0x8000</code>), which cannot typically be represented
222 * in an unsigned char. Therefore, the flag
223 * <code>decipherOnly</code> (i.e.
224 * #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
225 * function.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200226 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100227int mbedtls_x509write_csr_set_key_usage(mbedtls_x509write_csr *ctx, unsigned char key_usage);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200228
229/**
Hannes Tschofenig6b108602022-12-28 18:38:53 +0100230 * \brief Set Subject Alternative Name
231 *
232 * \param ctx CSR context to use
233 * \param san_list List of SAN values
234 *
235 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
236 *
237 * \note Only "dnsName", "uniformResourceIdentifier" and "otherName",
238 * as defined in RFC 5280, are supported.
239 */
240int mbedtls_x509write_csr_set_subject_alternative_name(mbedtls_x509write_csr *ctx,
241 const mbedtls_x509_san_list *san_list);
242
243/**
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200244 * \brief Set the Netscape Cert Type flags
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200245 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200246 *
247 * \param ctx CSR context to use
248 * \param ns_cert_type Netscape Cert Type flags to set
249 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200250 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200251 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100252int mbedtls_x509write_csr_set_ns_cert_type(mbedtls_x509write_csr *ctx,
253 unsigned char ns_cert_type);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200254
255/**
Paul Bakkerb9e4e2c2014-05-01 14:18:25 +0200256 * \brief Generic function to add to or replace an extension in the
257 * CSR
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200258 *
259 * \param ctx CSR context to use
260 * \param oid OID of the extension
261 * \param oid_len length of the OID
Christoph Reiter95273f42021-01-21 13:31:23 +0100262 * \param critical Set to 1 to mark the extension as critical, 0 otherwise.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200263 * \param val value of the extension OCTET STRING
264 * \param val_len length of the value data
265 *
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200266 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200267 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100268int mbedtls_x509write_csr_set_extension(mbedtls_x509write_csr *ctx,
269 const char *oid, size_t oid_len,
270 int critical,
271 const unsigned char *val, size_t val_len);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200272
273/**
274 * \brief Free the contents of a CSR context
275 *
276 * \param ctx CSR context to free
277 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100278void mbedtls_x509write_csr_free(mbedtls_x509write_csr *ctx);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200279
280/**
281 * \brief Write a CSR (Certificate Signing Request) to a
282 * DER structure
283 * Note: data is written at the end of the buffer! Use the
284 * return value to determine where you should start
285 * using the buffer
286 *
287 * \param ctx CSR to write away
288 * \param buf buffer to write to
289 * \param size size of the buffer
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +0200290 * \param f_rng RNG function. This must not be \c NULL.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200291 * \param p_rng RNG parameter
292 *
293 * \return length of data written if successful, or a specific
294 * error code
295 *
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +0200296 * \note \p f_rng is used for the signature operation.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200297 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100298int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
299 int (*f_rng)(void *, unsigned char *, size_t),
300 void *p_rng);
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200301
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200302#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200303/**
304 * \brief Write a CSR (Certificate Signing Request) to a
305 * PEM string
306 *
307 * \param ctx CSR to write away
308 * \param buf buffer to write to
309 * \param size size of the buffer
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +0200310 * \param f_rng RNG function. This must not be \c NULL.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200311 * \param p_rng RNG parameter
312 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200313 * \return 0 if successful, or a specific error code
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200314 *
Manuel Pégourié-Gonnardc305b722021-06-15 11:29:26 +0200315 * \note \p f_rng is used for the signature operation.
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200316 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100317int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
318 int (*f_rng)(void *, unsigned char *, size_t),
319 void *p_rng);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200320#endif /* MBEDTLS_PEM_WRITE_C */
321#endif /* MBEDTLS_X509_CSR_WRITE_C */
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200322
Andrzej Kureka0defed2021-12-30 12:33:31 +0100323/** \} addtogroup x509_module */
324
Paul Bakker7c6b2c32013-09-16 13:49:26 +0200325#ifdef __cplusplus
326}
327#endif
328
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200329#endif /* mbedtls_x509_csr.h */