Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/x509_csr.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file x509_csr.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief X.509 certificate signing request parsing and writing
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24 #ifndef POLARSSL_X509_CSR_H
ansond 0:137634ff4186 25 #define POLARSSL_X509_CSR_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 28 #include "config.h"
ansond 0:137634ff4186 29 #else
ansond 0:137634ff4186 30 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 31 #endif
ansond 0:137634ff4186 32
ansond 0:137634ff4186 33 #include "x509.h"
ansond 0:137634ff4186 34
ansond 0:137634ff4186 35 #ifdef __cplusplus
ansond 0:137634ff4186 36 extern "C" {
ansond 0:137634ff4186 37 #endif
ansond 0:137634ff4186 38
ansond 0:137634ff4186 39 /**
ansond 0:137634ff4186 40 * \addtogroup x509_module
ansond 0:137634ff4186 41 * \{ */
ansond 0:137634ff4186 42
ansond 0:137634ff4186 43 /**
ansond 0:137634ff4186 44 * \name Structures and functions for X.509 Certificate Signing Requests (CSR)
ansond 0:137634ff4186 45 * \{
ansond 0:137634ff4186 46 */
ansond 0:137634ff4186 47
ansond 0:137634ff4186 48 /**
ansond 0:137634ff4186 49 * Certificate Signing Request (CSR) structure.
ansond 0:137634ff4186 50 */
ansond 0:137634ff4186 51 typedef struct _x509_csr
ansond 0:137634ff4186 52 {
ansond 0:137634ff4186 53 x509_buf raw; /**< The raw CSR data (DER). */
ansond 0:137634ff4186 54 x509_buf cri; /**< The raw CertificateRequestInfo body (DER). */
ansond 0:137634ff4186 55
ansond 0:137634ff4186 56 int version; /**< CSR version (1=v1). */
ansond 0:137634ff4186 57
ansond 0:137634ff4186 58 x509_buf subject_raw; /**< The raw subject data (DER). */
ansond 0:137634ff4186 59 x509_name subject; /**< The parsed subject data (named information object). */
ansond 0:137634ff4186 60
ansond 0:137634ff4186 61 pk_context pk; /**< Container for the public key context. */
ansond 0:137634ff4186 62
ansond 0:137634ff4186 63 x509_buf sig_oid;
ansond 0:137634ff4186 64 x509_buf sig;
ansond 0:137634ff4186 65 md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. POLARSSL_MD_SHA256 */
ansond 0:137634ff4186 66 pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. POLARSSL_PK_RSA */
ansond 0:137634ff4186 67 void *sig_opts; /**< Signature options to be passed to pk_verify_ext(), e.g. for RSASSA-PSS */
ansond 0:137634ff4186 68 }
ansond 0:137634ff4186 69 x509_csr;
ansond 0:137634ff4186 70
ansond 0:137634ff4186 71 /**
ansond 0:137634ff4186 72 * Container for writing a CSR
ansond 0:137634ff4186 73 */
ansond 0:137634ff4186 74 typedef struct _x509write_csr
ansond 0:137634ff4186 75 {
ansond 0:137634ff4186 76 pk_context *key;
ansond 0:137634ff4186 77 asn1_named_data *subject;
ansond 0:137634ff4186 78 md_type_t md_alg;
ansond 0:137634ff4186 79 asn1_named_data *extensions;
ansond 0:137634ff4186 80 }
ansond 0:137634ff4186 81 x509write_csr;
ansond 0:137634ff4186 82
ansond 0:137634ff4186 83 #if defined(POLARSSL_X509_CSR_PARSE_C)
ansond 0:137634ff4186 84 /**
ansond 0:137634ff4186 85 * \brief Load a Certificate Signing Request (CSR) in DER format
ansond 0:137634ff4186 86 *
ansond 0:137634ff4186 87 * \param csr CSR context to fill
ansond 0:137634ff4186 88 * \param buf buffer holding the CRL data
ansond 0:137634ff4186 89 * \param buflen size of the buffer
ansond 0:137634ff4186 90 *
ansond 0:137634ff4186 91 * \return 0 if successful, or a specific X509 error code
ansond 0:137634ff4186 92 */
ansond 0:137634ff4186 93 int x509_csr_parse_der( x509_csr *csr,
ansond 0:137634ff4186 94 const unsigned char *buf, size_t buflen );
ansond 0:137634ff4186 95
ansond 0:137634ff4186 96 /**
ansond 0:137634ff4186 97 * \brief Load a Certificate Signing Request (CSR), DER or PEM format
ansond 0:137634ff4186 98 *
ansond 0:137634ff4186 99 * \param csr CSR context to fill
ansond 0:137634ff4186 100 * \param buf buffer holding the CRL data
ansond 0:137634ff4186 101 * \param buflen size of the buffer
ansond 0:137634ff4186 102 *
ansond 0:137634ff4186 103 * \return 0 if successful, or a specific X509 or PEM error code
ansond 0:137634ff4186 104 */
ansond 0:137634ff4186 105 int x509_csr_parse( x509_csr *csr, const unsigned char *buf, size_t buflen );
ansond 0:137634ff4186 106
ansond 0:137634ff4186 107 #if defined(POLARSSL_FS_IO)
ansond 0:137634ff4186 108 /**
ansond 0:137634ff4186 109 * \brief Load a Certificate Signing Request (CSR)
ansond 0:137634ff4186 110 *
ansond 0:137634ff4186 111 * \param csr CSR context to fill
ansond 0:137634ff4186 112 * \param path filename to read the CSR from
ansond 0:137634ff4186 113 *
ansond 0:137634ff4186 114 * \return 0 if successful, or a specific X509 or PEM error code
ansond 0:137634ff4186 115 */
ansond 0:137634ff4186 116 int x509_csr_parse_file( x509_csr *csr, const char *path );
ansond 0:137634ff4186 117 #endif /* POLARSSL_FS_IO */
ansond 0:137634ff4186 118
ansond 0:137634ff4186 119 /**
ansond 0:137634ff4186 120 * \brief Returns an informational string about the
ansond 0:137634ff4186 121 * CSR.
ansond 0:137634ff4186 122 *
ansond 0:137634ff4186 123 * \param buf Buffer to write to
ansond 0:137634ff4186 124 * \param size Maximum size of buffer
ansond 0:137634ff4186 125 * \param prefix A line prefix
ansond 0:137634ff4186 126 * \param csr The X509 CSR to represent
ansond 0:137634ff4186 127 *
ansond 0:137634ff4186 128 * \return The length of the string written (exluding the terminating
ansond 0:137634ff4186 129 * null byte), or a negative value in case of an error.
ansond 0:137634ff4186 130 */
ansond 0:137634ff4186 131 int x509_csr_info( char *buf, size_t size, const char *prefix,
ansond 0:137634ff4186 132 const x509_csr *csr );
ansond 0:137634ff4186 133
ansond 0:137634ff4186 134 /**
ansond 0:137634ff4186 135 * \brief Initialize a CSR
ansond 0:137634ff4186 136 *
ansond 0:137634ff4186 137 * \param csr CSR to initialize
ansond 0:137634ff4186 138 */
ansond 0:137634ff4186 139 void x509_csr_init( x509_csr *csr );
ansond 0:137634ff4186 140
ansond 0:137634ff4186 141 /**
ansond 0:137634ff4186 142 * \brief Unallocate all CSR data
ansond 0:137634ff4186 143 *
ansond 0:137634ff4186 144 * \param csr CSR to free
ansond 0:137634ff4186 145 */
ansond 0:137634ff4186 146 void x509_csr_free( x509_csr *csr );
ansond 0:137634ff4186 147 #endif /* POLARSSL_X509_CSR_PARSE_C */
ansond 0:137634ff4186 148
ansond 0:137634ff4186 149 /* \} name */
ansond 0:137634ff4186 150 /* \} addtogroup x509_module */
ansond 0:137634ff4186 151
ansond 0:137634ff4186 152 #if defined(POLARSSL_X509_CSR_WRITE_C)
ansond 0:137634ff4186 153 /**
ansond 0:137634ff4186 154 * \brief Initialize a CSR context
ansond 0:137634ff4186 155 *
ansond 0:137634ff4186 156 * \param ctx CSR context to initialize
ansond 0:137634ff4186 157 */
ansond 0:137634ff4186 158 void x509write_csr_init( x509write_csr *ctx );
ansond 0:137634ff4186 159
ansond 0:137634ff4186 160 /**
ansond 0:137634ff4186 161 * \brief Set the subject name for a CSR
ansond 0:137634ff4186 162 * Subject names should contain a comma-separated list
ansond 0:137634ff4186 163 * of OID types and values:
ansond 0:137634ff4186 164 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1"
ansond 0:137634ff4186 165 *
ansond 0:137634ff4186 166 * \param ctx CSR context to use
ansond 0:137634ff4186 167 * \param subject_name subject name to set
ansond 0:137634ff4186 168 *
ansond 0:137634ff4186 169 * \return 0 if subject name was parsed successfully, or
ansond 0:137634ff4186 170 * a specific error code
ansond 0:137634ff4186 171 */
ansond 0:137634ff4186 172 int x509write_csr_set_subject_name( x509write_csr *ctx,
ansond 0:137634ff4186 173 const char *subject_name );
ansond 0:137634ff4186 174
ansond 0:137634ff4186 175 /**
ansond 0:137634ff4186 176 * \brief Set the key for a CSR (public key will be included,
ansond 0:137634ff4186 177 * private key used to sign the CSR when writing it)
ansond 0:137634ff4186 178 *
ansond 0:137634ff4186 179 * \param ctx CSR context to use
ansond 0:137634ff4186 180 * \param key Asymetric key to include
ansond 0:137634ff4186 181 */
ansond 0:137634ff4186 182 void x509write_csr_set_key( x509write_csr *ctx, pk_context *key );
ansond 0:137634ff4186 183
ansond 0:137634ff4186 184 /**
ansond 0:137634ff4186 185 * \brief Set the MD algorithm to use for the signature
ansond 0:137634ff4186 186 * (e.g. POLARSSL_MD_SHA1)
ansond 0:137634ff4186 187 *
ansond 0:137634ff4186 188 * \param ctx CSR context to use
ansond 0:137634ff4186 189 * \param md_alg MD algorithm to use
ansond 0:137634ff4186 190 */
ansond 0:137634ff4186 191 void x509write_csr_set_md_alg( x509write_csr *ctx, md_type_t md_alg );
ansond 0:137634ff4186 192
ansond 0:137634ff4186 193 /**
ansond 0:137634ff4186 194 * \brief Set the Key Usage Extension flags
ansond 0:137634ff4186 195 * (e.g. KU_DIGITAL_SIGNATURE | KU_KEY_CERT_SIGN)
ansond 0:137634ff4186 196 *
ansond 0:137634ff4186 197 * \param ctx CSR context to use
ansond 0:137634ff4186 198 * \param key_usage key usage flags to set
ansond 0:137634ff4186 199 *
ansond 0:137634ff4186 200 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
ansond 0:137634ff4186 201 */
ansond 0:137634ff4186 202 int x509write_csr_set_key_usage( x509write_csr *ctx, unsigned char key_usage );
ansond 0:137634ff4186 203
ansond 0:137634ff4186 204 /**
ansond 0:137634ff4186 205 * \brief Set the Netscape Cert Type flags
ansond 0:137634ff4186 206 * (e.g. NS_CERT_TYPE_SSL_CLIENT | NS_CERT_TYPE_EMAIL)
ansond 0:137634ff4186 207 *
ansond 0:137634ff4186 208 * \param ctx CSR context to use
ansond 0:137634ff4186 209 * \param ns_cert_type Netscape Cert Type flags to set
ansond 0:137634ff4186 210 *
ansond 0:137634ff4186 211 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
ansond 0:137634ff4186 212 */
ansond 0:137634ff4186 213 int x509write_csr_set_ns_cert_type( x509write_csr *ctx,
ansond 0:137634ff4186 214 unsigned char ns_cert_type );
ansond 0:137634ff4186 215
ansond 0:137634ff4186 216 /**
ansond 0:137634ff4186 217 * \brief Generic function to add to or replace an extension in the
ansond 0:137634ff4186 218 * CSR
ansond 0:137634ff4186 219 *
ansond 0:137634ff4186 220 * \param ctx CSR context to use
ansond 0:137634ff4186 221 * \param oid OID of the extension
ansond 0:137634ff4186 222 * \param oid_len length of the OID
ansond 0:137634ff4186 223 * \param val value of the extension OCTET STRING
ansond 0:137634ff4186 224 * \param val_len length of the value data
ansond 0:137634ff4186 225 *
ansond 0:137634ff4186 226 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
ansond 0:137634ff4186 227 */
ansond 0:137634ff4186 228 int x509write_csr_set_extension( x509write_csr *ctx,
ansond 0:137634ff4186 229 const char *oid, size_t oid_len,
ansond 0:137634ff4186 230 const unsigned char *val, size_t val_len );
ansond 0:137634ff4186 231
ansond 0:137634ff4186 232 /**
ansond 0:137634ff4186 233 * \brief Free the contents of a CSR context
ansond 0:137634ff4186 234 *
ansond 0:137634ff4186 235 * \param ctx CSR context to free
ansond 0:137634ff4186 236 */
ansond 0:137634ff4186 237 void x509write_csr_free( x509write_csr *ctx );
ansond 0:137634ff4186 238
ansond 0:137634ff4186 239 /**
ansond 0:137634ff4186 240 * \brief Write a CSR (Certificate Signing Request) to a
ansond 0:137634ff4186 241 * DER structure
ansond 0:137634ff4186 242 * Note: data is written at the end of the buffer! Use the
ansond 0:137634ff4186 243 * return value to determine where you should start
ansond 0:137634ff4186 244 * using the buffer
ansond 0:137634ff4186 245 *
ansond 0:137634ff4186 246 * \param ctx CSR to write away
ansond 0:137634ff4186 247 * \param buf buffer to write to
ansond 0:137634ff4186 248 * \param size size of the buffer
ansond 0:137634ff4186 249 * \param f_rng RNG function (for signature, see note)
ansond 0:137634ff4186 250 * \param p_rng RNG parameter
ansond 0:137634ff4186 251 *
ansond 0:137634ff4186 252 * \return length of data written if successful, or a specific
ansond 0:137634ff4186 253 * error code
ansond 0:137634ff4186 254 *
ansond 0:137634ff4186 255 * \note f_rng may be NULL if RSA is used for signature and the
ansond 0:137634ff4186 256 * signature is made offline (otherwise f_rng is desirable
ansond 0:137634ff4186 257 * for countermeasures against timing attacks).
ansond 0:137634ff4186 258 * ECDSA signatures always require a non-NULL f_rng.
ansond 0:137634ff4186 259 */
ansond 0:137634ff4186 260 int x509write_csr_der( x509write_csr *ctx, unsigned char *buf, size_t size,
ansond 0:137634ff4186 261 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 262 void *p_rng );
ansond 0:137634ff4186 263
ansond 0:137634ff4186 264 #if defined(POLARSSL_PEM_WRITE_C)
ansond 0:137634ff4186 265 /**
ansond 0:137634ff4186 266 * \brief Write a CSR (Certificate Signing Request) to a
ansond 0:137634ff4186 267 * PEM string
ansond 0:137634ff4186 268 *
ansond 0:137634ff4186 269 * \param ctx CSR to write away
ansond 0:137634ff4186 270 * \param buf buffer to write to
ansond 0:137634ff4186 271 * \param size size of the buffer
ansond 0:137634ff4186 272 * \param f_rng RNG function (for signature, see note)
ansond 0:137634ff4186 273 * \param p_rng RNG parameter
ansond 0:137634ff4186 274 *
ansond 0:137634ff4186 275 * \return 0 successful, or a specific error code
ansond 0:137634ff4186 276 *
ansond 0:137634ff4186 277 * \note f_rng may be NULL if RSA is used for signature and the
ansond 0:137634ff4186 278 * signature is made offline (otherwise f_rng is desirable
ansond 0:137634ff4186 279 * for couermeasures against timing attacks).
ansond 0:137634ff4186 280 * ECDSA signatures always require a non-NULL f_rng.
ansond 0:137634ff4186 281 */
ansond 0:137634ff4186 282 int x509write_csr_pem( x509write_csr *ctx, unsigned char *buf, size_t size,
ansond 0:137634ff4186 283 int (*f_rng)(void *, unsigned char *, size_t),
ansond 0:137634ff4186 284 void *p_rng );
ansond 0:137634ff4186 285 #endif /* POLARSSL_PEM_WRITE_C */
ansond 0:137634ff4186 286 #endif /* POLARSSL_X509_CSR_WRITE_C */
ansond 0:137634ff4186 287
ansond 0:137634ff4186 288 #ifdef __cplusplus
ansond 0:137634ff4186 289 }
ansond 0:137634ff4186 290 #endif
ansond 0:137634ff4186 291
ansond 0:137634ff4186 292 #endif /* x509_csr.h */
ansond 0:137634ff4186 293