common/mbedtls/x509_csr.h

   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
  34 extern "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  */
  49 typedef 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 }
  66 mbedtls_x509_csr;
  67
  68 /**
  69  * Container for writing a CSR
  70  */
  71 typedef 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 }
  77 mbedtls_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  * \param csr      CSR context to fill
  86  * \param buf      buffer holding the CRL data
  87  * \param buflen   size of the buffer
  88  *
  89  * \return         0 if successful, or a specific X509 error code
  90  */
  91 int mbedtls_x509_csr_parse_der(mbedtls_x509_csr *csr,
  92                                const unsigned char *buf, size_t buflen);
  93
  94 /**
  95  * \brief          Load a Certificate Signing Request (CSR), DER or PEM format
  96  *
  97  * \note           See notes for \c mbedtls_x509_csr_parse_der()
  98  *
  99  * \param csr      CSR context to fill
 100  * \param buf      buffer holding the CRL data
 101  * \param buflen   size of the buffer
 102  *                 (including the terminating null byte for PEM data)
 103  *
 104  * \return         0 if successful, or a specific X509 or PEM error code
 105  */
 106 int mbedtls_x509_csr_parse(mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen);
 107
 108 #if defined(MBEDTLS_FS_IO)
 109 /**
 110  * \brief          Load a Certificate Signing Request (CSR)
 111  *
 112  * \note           See notes for \c mbedtls_x509_csr_parse()
 113  *
 114  * \param csr      CSR context to fill
 115  * \param path     filename to read the CSR from
 116  *
 117  * \return         0 if successful, or a specific X509 or PEM error code
 118  */
 119 int mbedtls_x509_csr_parse_file(mbedtls_x509_csr *csr, const char *path);
 120 #endif /* MBEDTLS_FS_IO */
 121
 122 /**
 123  * \brief          Returns an informational string about the
 124  *                 CSR.
 125  *
 126  * \param buf      Buffer to write to
 127  * \param size     Maximum size of buffer
 128  * \param prefix   A line prefix
 129  * \param csr      The X509 CSR to represent
 130  *
 131  * \return         The length of the string written (not including the
 132  *                 terminated nul byte), or a negative error code.
 133  */
 134 int mbedtls_x509_csr_info(char *buf, size_t size, const char *prefix,
 135                           const mbedtls_x509_csr *csr);
 136
 137 /**
 138  * \brief          Initialize a CSR
 139  *
 140  * \param csr      CSR to initialize
 141  */
 142 void mbedtls_x509_csr_init(mbedtls_x509_csr *csr);
 143
 144 /**
 145  * \brief          Unallocate all CSR data
 146  *
 147  * \param csr      CSR to free
 148  */
 149 void mbedtls_x509_csr_free(mbedtls_x509_csr *csr);
 150 #endif /* MBEDTLS_X509_CSR_PARSE_C */
 151
 152 /* \} name */
 153 /* \} addtogroup x509_module */
 154
 155 #if defined(MBEDTLS_X509_CSR_WRITE_C)
 156 /**
 157  * \brief           Initialize a CSR context
 158  *
 159  * \param ctx       CSR context to initialize
 160  */
 161 void mbedtls_x509write_csr_init(mbedtls_x509write_csr *ctx);
 162
 163 /**
 164  * \brief           Set the subject name for a CSR
 165  *                  Subject names should contain a comma-separated list
 166  *                  of OID types and values:
 167  *                  e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
 168  *
 169  * \param ctx           CSR context to use
 170  * \param subject_name  subject name to set
 171  *
 172  * \return          0 if subject name was parsed successfully, or
 173  *                  a specific error code
 174  */
 175 int mbedtls_x509write_csr_set_subject_name(mbedtls_x509write_csr *ctx,
 176                                            const char *subject_name);
 177
 178 /**
 179  * \brief           Set the key for a CSR (public key will be included,
 180  *                  private key used to sign the CSR when writing it)
 181  *
 182  * \param ctx       CSR context to use
 183  * \param key       Asymetric key to include
 184  */
 185 void mbedtls_x509write_csr_set_key(mbedtls_x509write_csr *ctx, mbedtls_pk_context *key);
 186
 187 /**
 188  * \brief           Set the MD algorithm to use for the signature
 189  *                  (e.g. MBEDTLS_MD_SHA1)
 190  *
 191  * \param ctx       CSR context to use
 192  * \param md_alg    MD algorithm to use
 193  */
 194 void mbedtls_x509write_csr_set_md_alg(mbedtls_x509write_csr *ctx, mbedtls_md_type_t md_alg);
 195
 196 /**
 197  * \brief           Set the Key Usage Extension flags
 198  *                  (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
 199  *
 200  * \param ctx       CSR context to use
 201  * \param key_usage key usage flags to set
 202  *
 203  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
 204  *
 205  * \note            The <code>decipherOnly</code> flag from the Key Usage
 206  *                  extension is represented by bit 8 (i.e.
 207  *                  <code>0x8000</code>), which cannot typically be represented
 208  *                  in an unsigned char. Therefore, the flag
 209  *                  <code>decipherOnly</code> (i.e.
 210  *                  #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
 211  *                  function.
 212  */
 213 int mbedtls_x509write_csr_set_key_usage(mbedtls_x509write_csr *ctx, unsigned char key_usage);
 214
 215 /**
 216  * \brief           Set the Netscape Cert Type flags
 217  *                  (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
 218  *
 219  * \param ctx           CSR context to use
 220  * \param ns_cert_type  Netscape Cert Type flags to set
 221  *
 222  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
 223  */
 224 int mbedtls_x509write_csr_set_ns_cert_type(mbedtls_x509write_csr *ctx,
 225                                            unsigned char ns_cert_type);
 226
 227 /**
 228  * \brief           Generic function to add to or replace an extension in the
 229  *                  CSR
 230  *
 231  * \param ctx       CSR context to use
 232  * \param oid       OID of the extension
 233  * \param oid_len   length of the OID
 234  * \param val       value of the extension OCTET STRING
 235  * \param val_len   length of the value data
 236  *
 237  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
 238  */
 239 int mbedtls_x509write_csr_set_extension(mbedtls_x509write_csr *ctx,
 240                                         const char *oid, size_t oid_len,
 241                                         const unsigned char *val, size_t val_len);
 242
 243 /**
 244  * \brief           Free the contents of a CSR context
 245  *
 246  * \param ctx       CSR context to free
 247  */
 248 void mbedtls_x509write_csr_free(mbedtls_x509write_csr *ctx);
 249
 250 /**
 251  * \brief           Write a CSR (Certificate Signing Request) to a
 252  *                  DER structure
 253  *                  Note: data is written at the end of the buffer! Use the
 254  *                        return value to determine where you should start
 255  *                        using the buffer
 256  *
 257  * \param ctx       CSR to write away
 258  * \param buf       buffer to write to
 259  * \param size      size of the buffer
 260  * \param f_rng     RNG function (for signature, see note)
 261  * \param p_rng     RNG parameter
 262  *
 263  * \return          length of data written if successful, or a specific
 264  *                  error code
 265  *
 266  * \note            f_rng may be NULL if RSA is used for signature and the
 267  *                  signature is made offline (otherwise f_rng is desirable
 268  *                  for countermeasures against timing attacks).
 269  *                  ECDSA signatures always require a non-NULL f_rng.
 270  */
 271 int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
 272                               int (*f_rng)(void *, unsigned char *, size_t),
 273                               void *p_rng);
 274
 275 #if defined(MBEDTLS_PEM_WRITE_C)
 276 /**
 277  * \brief           Write a CSR (Certificate Signing Request) to a
 278  *                  PEM string
 279  *
 280  * \param ctx       CSR to write away
 281  * \param buf       buffer to write to
 282  * \param size      size of the buffer
 283  * \param f_rng     RNG function (for signature, see note)
 284  * \param p_rng     RNG parameter
 285  *
 286  * \return          0 if successful, or a specific error code
 287  *
 288  * \note            f_rng may be NULL if RSA is used for signature and the
 289  *                  signature is made offline (otherwise f_rng is desirable
 290  *                  for countermeasures against timing attacks).
 291  *                  ECDSA signatures always require a non-NULL f_rng.
 292  */
 293 int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
 294                               int (*f_rng)(void *, unsigned char *, size_t),
 295                               void *p_rng);
 296 #endif /* MBEDTLS_PEM_WRITE_C */
 297 #endif /* MBEDTLS_X509_CSR_WRITE_C */
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif
 302
 303 #endif /* mbedtls_x509_csr.h */