x509_csr.h

00001 /**
00002  * \file x509_csr.h
00003  *
00004  * \brief X.509 certificate signing request parsing and writing
00005  *
00006  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00007  *  SPDX-License-Identifier: Apache-2.0
00008  *
00009  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  *  not use this file except in compliance with the License.
00011  *  You may obtain a copy of the License at
00012  *
00013  *  http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  *  Unless required by applicable law or agreed to in writing, software
00016  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  *  See the License for the specific language governing permissions and
00019  *  limitations under the License.
00020  *
00021  *  This file is part of mbed TLS (https://tls.mbed.org)
00022  */
00023 #ifndef MBEDTLS_X509_CSR_H
00024 #define MBEDTLS_X509_CSR_H
00025 
00026 #if !defined(MBEDTLS_CONFIG_FILE)
00027 #include "config.h"
00028 #else
00029 #include MBEDTLS_CONFIG_FILE
00030 #endif
00031 
00032 #include "x509.h"
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif
00037 
00038 /**
00039  * \addtogroup x509_module
00040  * \{ */
00041 
00042 /**
00043  * \name Structures and functions for X.509 Certificate Signing Requests (CSR)
00044  * \{
00045  */
00046 
00047 /**
00048  * Certificate Signing Request (CSR) structure.
00049  */
00050 typedef struct mbedtls_x509_csr
00051 {
00052     mbedtls_x509_buf raw;           /**< The raw CSR data (DER). */
00053     mbedtls_x509_buf cri;           /**< The raw CertificateRequestInfo body (DER). */
00054 
00055     int version;            /**< CSR version (1=v1). */
00056 
00057     mbedtls_x509_buf  subject_raw;  /**< The raw subject data (DER). */
00058     mbedtls_x509_name subject;      /**< The parsed subject data (named information object). */
00059 
00060     mbedtls_pk_context pk;          /**< Container for the public key context. */
00061 
00062     mbedtls_x509_buf sig_oid;
00063     mbedtls_x509_buf sig;
00064     mbedtls_md_type_t sig_md;       /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */
00065     mbedtls_pk_type_t sig_pk;       /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */
00066     void *sig_opts;         /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */
00067 }
00068 mbedtls_x509_csr;
00069 
00070 /**
00071  * Container for writing a CSR
00072  */
00073 typedef struct mbedtls_x509write_csr
00074 {
00075     mbedtls_pk_context *key;
00076     mbedtls_asn1_named_data *subject;
00077     mbedtls_md_type_t md_alg;
00078     mbedtls_asn1_named_data *extensions;
00079 }
00080 mbedtls_x509write_csr;
00081 
00082 #if defined(MBEDTLS_X509_CSR_PARSE_C)
00083 /**
00084  * \brief          Load a Certificate Signing Request (CSR) in DER format
00085  *
00086  * \note           CSR attributes (if any) are currently silently ignored.
00087  *
00088  * \param csr      CSR context to fill
00089  * \param buf      buffer holding the CRL data
00090  * \param buflen   size of the buffer
00091  *
00092  * \return         0 if successful, or a specific X509 error code
00093  */
00094 int mbedtls_x509_csr_parse_der( mbedtls_x509_csr *csr,
00095                         const unsigned char *buf, size_t buflen );
00096 
00097 /**
00098  * \brief          Load a Certificate Signing Request (CSR), DER or PEM format
00099  *
00100  * \note           See notes for \c mbedtls_x509_csr_parse_der()
00101  *
00102  * \param csr      CSR context to fill
00103  * \param buf      buffer holding the CRL data
00104  * \param buflen   size of the buffer
00105  *                 (including the terminating null byte for PEM data)
00106  *
00107  * \return         0 if successful, or a specific X509 or PEM error code
00108  */
00109 int mbedtls_x509_csr_parse( mbedtls_x509_csr *csr, const unsigned char *buf, size_t buflen );
00110 
00111 #if defined(MBEDTLS_FS_IO)
00112 /**
00113  * \brief          Load a Certificate Signing Request (CSR)
00114  *
00115  * \note           See notes for \c mbedtls_x509_csr_parse()
00116  *
00117  * \param csr      CSR context to fill
00118  * \param path     filename to read the CSR from
00119  *
00120  * \return         0 if successful, or a specific X509 or PEM error code
00121  */
00122 int mbedtls_x509_csr_parse_file( mbedtls_x509_csr *csr, const char *path );
00123 #endif /* MBEDTLS_FS_IO */
00124 
00125 /**
00126  * \brief          Returns an informational string about the
00127  *                 CSR.
00128  *
00129  * \param buf      Buffer to write to
00130  * \param size     Maximum size of buffer
00131  * \param prefix   A line prefix
00132  * \param csr      The X509 CSR to represent
00133  *
00134  * \return         The length of the string written (not including the
00135  *                 terminated nul byte), or a negative error code.
00136  */
00137 int mbedtls_x509_csr_info( char *buf, size_t size, const char *prefix,
00138                    const mbedtls_x509_csr *csr );
00139 
00140 /**
00141  * \brief          Initialize a CSR
00142  *
00143  * \param csr      CSR to initialize
00144  */
00145 void mbedtls_x509_csr_init( mbedtls_x509_csr *csr );
00146 
00147 /**
00148  * \brief          Unallocate all CSR data
00149  *
00150  * \param csr      CSR to free
00151  */
00152 void mbedtls_x509_csr_free( mbedtls_x509_csr *csr );
00153 #endif /* MBEDTLS_X509_CSR_PARSE_C */
00154 
00155 /* \} name */
00156 /* \} addtogroup x509_module */
00157 
00158 #if defined(MBEDTLS_X509_CSR_WRITE_C)
00159 /**
00160  * \brief           Initialize a CSR context
00161  *
00162  * \param ctx       CSR context to initialize
00163  */
00164 void mbedtls_x509write_csr_init( mbedtls_x509write_csr *ctx );
00165 
00166 /**
00167  * \brief           Set the subject name for a CSR
00168  *                  Subject names should contain a comma-separated list
00169  *                  of OID types and values:
00170  *                  e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
00171  *
00172  * \param ctx           CSR context to use
00173  * \param subject_name  subject name to set
00174  *
00175  * \return          0 if subject name was parsed successfully, or
00176  *                  a specific error code
00177  */
00178 int mbedtls_x509write_csr_set_subject_name( mbedtls_x509write_csr *ctx,
00179                                     const char *subject_name );
00180 
00181 /**
00182  * \brief           Set the key for a CSR (public key will be included,
00183  *                  private key used to sign the CSR when writing it)
00184  *
00185  * \param ctx       CSR context to use
00186  * \param key       Asymetric key to include
00187  */
00188 void mbedtls_x509write_csr_set_key( mbedtls_x509write_csr *ctx, mbedtls_pk_context *key );
00189 
00190 /**
00191  * \brief           Set the MD algorithm to use for the signature
00192  *                  (e.g. MBEDTLS_MD_SHA1)
00193  *
00194  * \param ctx       CSR context to use
00195  * \param md_alg    MD algorithm to use
00196  */
00197 void mbedtls_x509write_csr_set_md_alg( mbedtls_x509write_csr *ctx, mbedtls_md_type_t md_alg );
00198 
00199 /**
00200  * \brief           Set the Key Usage Extension flags
00201  *                  (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)
00202  *
00203  * \param ctx       CSR context to use
00204  * \param key_usage key usage flags to set
00205  *
00206  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
00207  */
00208 int mbedtls_x509write_csr_set_key_usage( mbedtls_x509write_csr *ctx, unsigned char key_usage );
00209 
00210 /**
00211  * \brief           Set the Netscape Cert Type flags
00212  *                  (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)
00213  *
00214  * \param ctx           CSR context to use
00215  * \param ns_cert_type  Netscape Cert Type flags to set
00216  *
00217  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
00218  */
00219 int mbedtls_x509write_csr_set_ns_cert_type( mbedtls_x509write_csr *ctx,
00220                                     unsigned char ns_cert_type );
00221 
00222 /**
00223  * \brief           Generic function to add to or replace an extension in the
00224  *                  CSR
00225  *
00226  * \param ctx       CSR context to use
00227  * \param oid       OID of the extension
00228  * \param oid_len   length of the OID
00229  * \param val       value of the extension OCTET STRING
00230  * \param val_len   length of the value data
00231  *
00232  * \return          0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
00233  */
00234 int mbedtls_x509write_csr_set_extension( mbedtls_x509write_csr *ctx,
00235                                  const char *oid, size_t oid_len,
00236                                  const unsigned char *val, size_t val_len );
00237 
00238 /**
00239  * \brief           Free the contents of a CSR context
00240  *
00241  * \param ctx       CSR context to free
00242  */
00243 void mbedtls_x509write_csr_free( mbedtls_x509write_csr *ctx );
00244 
00245 /**
00246  * \brief           Write a CSR (Certificate Signing Request) to a
00247  *                  DER structure
00248  *                  Note: data is written at the end of the buffer! Use the
00249  *                        return value to determine where you should start
00250  *                        using the buffer
00251  *
00252  * \param ctx       CSR to write away
00253  * \param buf       buffer to write to
00254  * \param size      size of the buffer
00255  * \param f_rng     RNG function (for signature, see note)
00256  * \param p_rng     RNG parameter
00257  *
00258  * \return          length of data written if successful, or a specific
00259  *                  error code
00260  *
00261  * \note            f_rng may be NULL if RSA is used for signature and the
00262  *                  signature is made offline (otherwise f_rng is desirable
00263  *                  for countermeasures against timing attacks).
00264  *                  ECDSA signatures always require a non-NULL f_rng.
00265  */
00266 int mbedtls_x509write_csr_der( mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
00267                        int (*f_rng)(void *, unsigned char *, size_t),
00268                        void *p_rng );
00269 
00270 #if defined(MBEDTLS_PEM_WRITE_C)
00271 /**
00272  * \brief           Write a CSR (Certificate Signing Request) to a
00273  *                  PEM string
00274  *
00275  * \param ctx       CSR to write away
00276  * \param buf       buffer to write to
00277  * \param size      size of the buffer
00278  * \param f_rng     RNG function (for signature, see note)
00279  * \param p_rng     RNG parameter
00280  *
00281  * \return          0 if successful, or a specific error code
00282  *
00283  * \note            f_rng may be NULL if RSA is used for signature and the
00284  *                  signature is made offline (otherwise f_rng is desirable
00285  *                  for countermeasures against timing attacks).
00286  *                  ECDSA signatures always require a non-NULL f_rng.
00287  */
00288 int mbedtls_x509write_csr_pem( mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
00289                        int (*f_rng)(void *, unsigned char *, size_t),
00290                        void *p_rng );
00291 #endif /* MBEDTLS_PEM_WRITE_C */
00292 #endif /* MBEDTLS_X509_CSR_WRITE_C */
00293 
00294 #ifdef __cplusplus
00295 }
00296 #endif
00297 
00298 #endif /* mbedtls_x509_csr.h */