1/**
2 * \file x509_csr.h
3 *
4 * \brief X.509 certificate signing request parsing and writing
5 */
6/*
7 * Copyright The Mbed TLS Contributors
8 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 */
22#ifndef MBEDTLS_X509_CSR_H
23#define MBEDTLS_X509_CSR_H
24
25#if !defined(MBEDTLS_CONFIG_FILE)
26#include "mbedtls/config.h"
27#else
28#include MBEDTLS_CONFIG_FILE
29#endif
30
31#include "mbedtls/x509.h"
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/**
38 * \addtogroup x509_module
39 * \{ */
40
41/**
42 * \name Structures and functions for X.509 Certificate Signing Requests (CSR)
43 * \{
44 */
45
46/**
47 * Certificate Signing Request (CSR) structure.
48 */
49typedef struct mbedtls_x509_csr {
50 mbedtls_x509_buf raw; /**< The raw CSR data (DER). */
51 mbedtls_x509_buf cri; /**< The raw CertificateRequestInfo body (DER). */
52
53 int version; /**< CSR version (1=v1). */
54
55 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). */
56 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */
57
58 mbedtls_pk_context pk; /**< Container for the public key context. */
59
60 mbedtls_x509_buf sig_oid;
61 mbedtls_x509_buf sig;
62 mbedtls_md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
63 mbedtls_pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
64 void *sig_opts; /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
65}
66mbedtls_x509_csr;
67
68/**
69 * Container for writing a CSR
70 */
71typedef struct mbedtls_x509write_csr {
72 mbedtls_pk_context *key;
73 mbedtls_asn1_named_data *subject;
74 mbedtls_md_type_t md_alg;
75 mbedtls_asn1_named_data *extensions;
76}
77mbedtls_x509write_csr;
78
79#if defined(MBEDTLS_X509_CSR_PARSE_C)
80/**
81 * \brief Load a Certificate Signing Request (CSR) in DER format
82 *
83 * \note CSR attributes (if any) are currently silently ignored.
84 *
85 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
86 * subsystem must have been initialized by calling
87 * psa_crypto_init() before calling this function.
88 *
89 * \param csr CSR context to fill
90 * \param buf buffer holding the CRL data
91 * \param buflen size of the buffer
92 *
93 * \return 0 if successful, or a specific X509 error code
94 */
95int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr,
96 const unsigned char *buf, size_t buflen);
97
98/**
99 * \brief Load a Certificate Signing Request (CSR), DER or PEM format
100 *
101 * \note See notes for \c mbedtls_x509_csr_parse_der()
102 *
103 * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
104 * subsystem must have been initialized by calling
105 * psa_crypto_init() before calling this function.
106 *
107 * \param csr CSR context to fill
108 * \param buf buffer holding the CRL data
109 * \param buflen size of the buffer
110 * (including the terminating null byte for PEM data)
111 *
112 * \return 0 if successful, or a specific X509 or PEM error code
113 */
114int mbedtls_x509_csr_parse(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen);
115
116#if defined(MBEDTLS_FS_IO)
117/**
118 * \brief Load a Certificate Signing Request (CSR)
119 *
120 * \note See notes for \c mbedtls_x509_csr_parse()
121 *
122 * \param csr CSR context to fill
123 * \param path filename to read the CSR from
124 *
125 * \return 0 if successful, or a specific X509 or PEM error code
126 */
127int mbedtls_x509_csr_parse_file(mbedtls_x509_csr *csr, const char *path);
128#endif /* MBEDTLS_FS_IO */
129
130/**
131 * \brief Returns an informational string about the
132 * CSR.
133 *
134 * \param buf Buffer to write to
135 * \param size Maximum size of buffer
136 * \param prefix A line prefix
137 * \param csr The X509 CSR to represent
138 *
139 * \return The length of the string written (not including the
140 * terminated nul byte), or a negative error code.
141 */
142int mbedtls_x509_csr_info(char *buf, size_t size, const char *prefix,
143 const mbedtls_x509_csr *csr);
144
145/**
146 * \brief Initialize a CSR
147 *
148 * \param csr CSR to initialize
149 */
150void mbedtls_x509_csr_init(mbedtls_x509_csr *csr);
151
152/**
153 * \brief Unallocate all CSR data
154 *
155 * \param csr CSR to free
156 */
157void mbedtls_x509_csr_free(mbedtls_x509_csr *csr);
158#endif /* MBEDTLS_X509_CSR_PARSE_C */
159
160/** \} name Structures and functions for X.509 Certificate Signing Requests (CSR) */
161
162#if defined(MBEDTLS_X509_CSR_WRITE_C)
163/**
164 * \brief Initialize a CSR context
165 *
166 * \param ctx CSR context to initialize
167 */
168void mbedtls_x509write_csr_init(mbedtls_x509write_csr *ctx);
169
170/**
171 * \brief Set the subject name for a CSR
172 * Subject names should contain a comma-separated list
173 * of OID types and values:
174 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
175 *
176 * \param ctx CSR context to use
177 * \param subject_name subject name to set
178 *
179 * \return 0 if subject name was parsed successfully, or
180 * a specific error code
181 */
182int mbedtls_x509write_csr_set_subject_name(mbedtls_x509write_csr *ctx,
183 const char *subject_name);
184
185/**
186 * \brief Set the key for a CSR (public key will be included,
187 * private key used to sign the CSR when writing it)
188 *
189 * \param ctx CSR context to use
190 * \param key Asymmetric key to include
191 */
192void mbedtls_x509write_csr_set_key(mbedtls_x509write_csr *ctx, mbedtls_pk_context *key);
193
194/**
195 * \brief Set the MD algorithm to use for the signature
196 * (e.g. MBEDTLS_MD_SHA1)
197 *
198 * \param ctx CSR context to use
199 * \param md_alg MD algorithm to use
200 */
201void mbedtls_x509write_csr_set_md_alg(mbedtls_x509write_csr *ctx, mbedtls_md_type_t md_alg);
202
203/**
204 * \brief Set the Key Usage Extension flags
205 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
206 *
207 * \param ctx CSR context to use
208 * \param key_usage key usage flags to set
209 *
210 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
211 *
212 * \note The <code>decipherOnly</code> flag from the Key Usage
213 * extension is represented by bit 8 (i.e.
214 * <code>0x8000</code>), which cannot typically be represented
215 * in an unsigned char. Therefore, the flag
216 * <code>decipherOnly</code> (i.e.
217 * #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
218 * function.
219 */
220int mbedtls_x509write_csr_set_key_usage(mbedtls_x509write_csr *ctx, unsigned char key_usage);
221
222/**
223 * \brief Set the Netscape Cert Type flags
224 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
225 *
226 * \param ctx CSR context to use
227 * \param ns_cert_type Netscape Cert Type flags to set
228 *
229 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
230 */
231int mbedtls_x509write_csr_set_ns_cert_type(mbedtls_x509write_csr *ctx,
232 unsigned char ns_cert_type);
233
234/**
235 * \brief Generic function to add to or replace an extension in the
236 * CSR
237 *
238 * \param ctx CSR context to use
239 * \param oid OID of the extension
240 * \param oid_len length of the OID
241 * \param val value of the extension OCTET STRING
242 * \param val_len length of the value data
243 *
244 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
245 */
246int mbedtls_x509write_csr_set_extension(mbedtls_x509write_csr *ctx,
247 const char *oid, size_t oid_len,
248 const unsigned char *val, size_t val_len);
249
250/**
251 * \brief Free the contents of a CSR context
252 *
253 * \param ctx CSR context to free
254 */
255void mbedtls_x509write_csr_free(mbedtls_x509write_csr *ctx);
256
257/**
258 * \brief Write a CSR (Certificate Signing Request) to a
259 * DER structure
260 * Note: data is written at the end of the buffer! Use the
261 * return value to determine where you should start
262 * using the buffer
263 *
264 * \param ctx CSR to write away
265 * \param buf buffer to write to
266 * \param size size of the buffer
267 * \param f_rng RNG function (for signature, see note)
268 * \param p_rng RNG parameter
269 *
270 * \return length of data written if successful, or a specific
271 * error code
272 *
273 * \note f_rng may be NULL if RSA is used for signature and the
274 * signature is made offline (otherwise f_rng is desirable
275 * for countermeasures against timing attacks).
276 * ECDSA signatures always require a non-NULL f_rng.
277 */
278int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
279 int (*f_rng)(void *, unsigned char *, size_t),
280 void *p_rng);
281
282#if defined(MBEDTLS_PEM_WRITE_C)
283/**
284 * \brief Write a CSR (Certificate Signing Request) to a
285 * PEM string
286 *
287 * \param ctx CSR to write away
288 * \param buf buffer to write to
289 * \param size size of the buffer
290 * \param f_rng RNG function (for signature, see note)
291 * \param p_rng RNG parameter
292 *
293 * \return 0 if successful, or a specific error code
294 *
295 * \note f_rng may be NULL if RSA is used for signature and the
296 * signature is made offline (otherwise f_rng is desirable
297 * for countermeasures against timing attacks).
298 * ECDSA signatures always require a non-NULL f_rng.
299 */
300int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
301 int (*f_rng)(void *, unsigned char *, size_t),
302 void *p_rng);
303#endif /* MBEDTLS_PEM_WRITE_C */
304#endif /* MBEDTLS_X509_CSR_WRITE_C */
305
306/** \} addtogroup x509_module */
307
308#ifdef __cplusplus
309}
310#endif
311
312#endif /* mbedtls_x509_csr.h */
313