git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/x509_csr.h

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