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