blob: 40db9e76776feccc302798e83c0786dd0e043ea5 [file] [log] [blame]
Paul Bakkerbdb912d2012-02-13 23:11:30 +00001/**
2 * \file x509write.h
3 *
4 * \brief X509 buffer writing functionality
5 *
Paul Bakker407a0da2013-06-27 14:29:21 +02006 * Copyright (C) 2006-2013, Brainspark B.V.
Paul Bakkerbdb912d2012-02-13 23:11:30 +00007 *
8 * This file is part of PolarSSL (http://www.polarssl.org)
9 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License along
24 * with this program; if not, write to the Free Software Foundation, Inc.,
25 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 */
27#ifndef POLARSSL_X509_WRITE_H
28#define POLARSSL_X509_WRITE_H
29
Paul Bakkerbc956d92013-04-19 14:51:29 +020030#include "config.h"
31
Paul Bakkerfde42702013-08-25 14:47:27 +020032#include "x509.h"
Paul Bakkerbdb912d2012-02-13 23:11:30 +000033
Paul Bakkerf6774662013-08-25 11:47:51 +020034/**
35 * \addtogroup x509_module
36 * \{
37 */
38
39/**
40 * \name X509 Write Error codes
41 * \{
42 */
Paul Bakker0e06c0f2013-08-25 11:21:30 +020043#define POLARSSL_ERR_X509WRITE_UNKNOWN_OID -0x5F80 /**< Requested OID is unknown. */
44#define POLARSSL_ERR_X509WRITE_BAD_INPUT_DATA -0x5F00 /**< Failed to allocate memory. */
45#define POLARSSL_ERR_X509WRITE_MALLOC_FAILED -0x5E80 /**< Failed to allocate memory. */
Paul Bakkerf6774662013-08-25 11:47:51 +020046/* \} name */
47/* \} addtogroup x509_module */
Paul Bakker8eabfc12013-08-25 10:18:25 +020048
Paul Bakker407a0da2013-06-27 14:29:21 +020049#ifdef __cplusplus
50extern "C" {
51#endif
52
Paul Bakkerf6774662013-08-25 11:47:51 +020053/**
54 * \addtogroup x509_module
55 * \{
56 */
57
58/**
59 * \name Structures for writing X.509 CSRs (Certificate Signing Request)
60 * \{
61 */
62
63/**
Paul Bakkerf6774662013-08-25 11:47:51 +020064 * Container for a CSR
65 */
Paul Bakkercd358032013-09-09 12:08:11 +020066typedef struct _x509write_csr
Paul Bakker8eabfc12013-08-25 10:18:25 +020067{
Manuel Pégourié-Gonnard5353a032013-09-11 12:14:26 +020068 pk_context *key;
Paul Bakker5f45e622013-09-09 12:02:36 +020069 asn1_named_data *subject;
Paul Bakker8eabfc12013-08-25 10:18:25 +020070 md_type_t md_alg;
Paul Bakkere5eae762013-08-26 12:05:14 +020071 asn1_named_data *extensions;
Paul Bakker8eabfc12013-08-25 10:18:25 +020072}
Paul Bakkercd358032013-09-09 12:08:11 +020073x509write_csr;
Paul Bakker8eabfc12013-08-25 10:18:25 +020074
Paul Bakker9397dcb2013-09-06 09:55:26 +020075#define X509_CRT_VERSION_1 0
76#define X509_CRT_VERSION_2 1
77#define X509_CRT_VERSION_3 2
78
79#define X509_RFC5280_MAX_SERIAL_LEN 32
80#define X509_RFC5280_UTC_TIME_LEN 15
81
82/**
83 * Container for writing a certificate (CRT)
84 */
85typedef struct _x509write_cert
86{
87 int version;
88 mpi serial;
89 rsa_context *subject_key;
90 rsa_context *issuer_key;
Paul Bakker5f45e622013-09-09 12:02:36 +020091 asn1_named_data *subject;
92 asn1_named_data *issuer;
Paul Bakker9397dcb2013-09-06 09:55:26 +020093 md_type_t md_alg;
94 char not_before[X509_RFC5280_UTC_TIME_LEN + 1];
95 char not_after[X509_RFC5280_UTC_TIME_LEN + 1];
96 asn1_named_data *extensions;
97}
98x509write_cert;
99
Paul Bakkerf6774662013-08-25 11:47:51 +0200100/* \} addtogroup x509_module */
101
102/**
103 * \brief Initialize a CSR context
104 *
105 * \param ctx CSR context to initialize
106 */
Paul Bakkercd358032013-09-09 12:08:11 +0200107void x509write_csr_init( x509write_csr *ctx );
Paul Bakkerf6774662013-08-25 11:47:51 +0200108
109/**
110 * \brief Set the subject name for a CSR
111 * Subject names should contain a comma-separated list
112 * of OID types and values:
113 * e.g. "C=NL,O=Offspark,CN=PolarSSL Server 1"
114 *
115 * \param ctx CSR context to use
116 * \param subject_name subject name to set
117 *
118 * \return 0 if subject name was parsed successfully, or
119 * a specific error code
120 */
Paul Bakkercd358032013-09-09 12:08:11 +0200121int x509write_csr_set_subject_name( x509write_csr *ctx, char *subject_name );
Paul Bakkerf6774662013-08-25 11:47:51 +0200122
123/**
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200124 * \brief Set the key for a CSR (public key will be included,
Paul Bakkerf6774662013-08-25 11:47:51 +0200125 * private key used to sign the CSR when writing it)
126 *
127 * \param ctx CSR context to use
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200128 * \param key Asymetric key to include
Paul Bakkerf6774662013-08-25 11:47:51 +0200129 */
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200130void x509write_csr_set_key( x509write_csr *ctx, pk_context *key );
Paul Bakkerf6774662013-08-25 11:47:51 +0200131
132/**
133 * \brief Set the MD algorithm to use for the signature
134 * (e.g. POLARSSL_MD_SHA1)
135 *
136 * \param ctx CSR context to use
137 * \param md_ald MD algorithm to use
138 */
Paul Bakkercd358032013-09-09 12:08:11 +0200139void x509write_csr_set_md_alg( x509write_csr *ctx, md_type_t md_alg );
Paul Bakkerf6774662013-08-25 11:47:51 +0200140
141/**
Paul Bakkerfde42702013-08-25 14:47:27 +0200142 * \brief Set the Key Usage Extension flags
143 * (e.g. KU_DIGITAL_SIGNATURE | KU_KEY_CERT_SIGN)
144 *
145 * \param ctx CSR context to use
Paul Bakker1c0e5502013-08-26 13:41:01 +0200146 * \param key_usage key usage flags to set
Paul Bakkere5eae762013-08-26 12:05:14 +0200147 *
148 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
Paul Bakkerfde42702013-08-25 14:47:27 +0200149 */
Paul Bakkercd358032013-09-09 12:08:11 +0200150int x509write_csr_set_key_usage( x509write_csr *ctx, unsigned char key_usage );
Paul Bakkerfde42702013-08-25 14:47:27 +0200151
152/**
Paul Bakker1c0e5502013-08-26 13:41:01 +0200153 * \brief Set the Netscape Cert Type flags
154 * (e.g. NS_CERT_TYPE_SSL_CLIENT | NS_CERT_TYPE_EMAIL)
155 *
156 * \param ctx CSR context to use
157 * \param ns_cert_type Netscape Cert Type flags to set
158 *
159 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
160 */
Paul Bakkercd358032013-09-09 12:08:11 +0200161int x509write_csr_set_ns_cert_type( x509write_csr *ctx,
162 unsigned char ns_cert_type );
Paul Bakker1c0e5502013-08-26 13:41:01 +0200163
164/**
165 * \brief Generic function to add to or replace an extension in the CSR
166 *
167 * \param ctx CSR context to use
168 * \param oid OID of the extension
169 * \param oid_len length of the OID
170 * \param val value of the extension OCTET STRING
171 * \param val_len length of the value data
172 *
173 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
174 */
Paul Bakkercd358032013-09-09 12:08:11 +0200175int x509write_csr_set_extension( x509write_csr *ctx,
Paul Bakker1c0e5502013-08-26 13:41:01 +0200176 const char *oid, size_t oid_len,
177 const unsigned char *val, size_t val_len );
178
179/**
Paul Bakkerf6774662013-08-25 11:47:51 +0200180 * \brief Free the contents of a CSR context
181 *
182 * \param ctx CSR context to free
183 */
Paul Bakkercd358032013-09-09 12:08:11 +0200184void x509write_csr_free( x509write_csr *ctx );
Paul Bakker8eabfc12013-08-25 10:18:25 +0200185
Paul Bakkerf6774662013-08-25 11:47:51 +0200186/**
Paul Bakker9397dcb2013-09-06 09:55:26 +0200187 * \brief Initialize a CRT writing context
188 *
189 * \param ctx CRT context to initialize
190 */
191void x509write_crt_init( x509write_cert *ctx );
192
193/**
194 * \brief Set the verion for a Certificate
195 * Default: X509_CRT_VERSION_3
196 *
197 * \param ctx CRT context to use
198 * \param version version to set (X509_CRT_VERSION_1, X509_CRT_VERSION_2 or
199 * X509_CRT_VERSION_3)
200 */
201void x509write_crt_set_version( x509write_cert *ctx, int version );
202
203/**
204 * \brief Set the serial number for a Certificate.
205 *
206 * \param ctx CRT context to use
207 * \param serial serial number to set
208 *
209 * \return 0 if successful
210 */
211int x509write_crt_set_serial( x509write_cert *ctx, const mpi *serial );
212
213/**
214 * \brief Set the validity period for a Certificate
215 * Timestamps should be in string format for UTC timezone
216 * i.e. "YYYYMMDDhhmmss"
217 * e.g. "20131231235959" for December 31st 2013
218 * at 23:59:59
219 *
220 * \param ctx CRT context to use
221 * \param not_before not_before timestamp
222 * \param not_after not_after timestamp
223 *
224 * \return 0 if timestamp was parsed successfully, or
225 * a specific error code
226 */
227int x509write_crt_set_validity( x509write_cert *ctx, char *not_before,
228 char *not_after );
229
230/**
231 * \brief Set the issuer name for a Certificate
232 * Issuer names should contain a comma-separated list
233 * of OID types and values:
234 * e.g. "C=NL,O=Offspark,CN=PolarSSL CA"
235 *
236 * \param ctx CRT context to use
237 * \param issuer_name issuer name to set
238 *
239 * \return 0 if issuer name was parsed successfully, or
240 * a specific error code
241 */
242int x509write_crt_set_issuer_name( x509write_cert *ctx, char *issuer_name );
243
244/**
245 * \brief Set the subject name for a Certificate
246 * Subject names should contain a comma-separated list
247 * of OID types and values:
248 * e.g. "C=NL,O=Offspark,CN=PolarSSL Server 1"
249 *
250 * \param ctx CRT context to use
251 * \param subject_name subject name to set
252 *
253 * \return 0 if subject name was parsed successfully, or
254 * a specific error code
255 */
256int x509write_crt_set_subject_name( x509write_cert *ctx, char *subject_name );
257
258/**
259 * \brief Set the subject public key for the certificate
260 *
261 * \param ctx CRT context to use
Manuel Pégourié-Gonnardf38e71a2013-09-12 05:21:54 +0200262 * \param key public key to include
Paul Bakker9397dcb2013-09-06 09:55:26 +0200263 */
Manuel Pégourié-Gonnardf38e71a2013-09-12 05:21:54 +0200264void x509write_crt_set_subject_key( x509write_cert *ctx, pk_context *key );
Paul Bakker9397dcb2013-09-06 09:55:26 +0200265
266/**
267 * \brief Set the issuer key used for signing the certificate
268 *
269 * \param ctx CRT context to use
Manuel Pégourié-Gonnardf38e71a2013-09-12 05:21:54 +0200270 * \param key private key to sign with
Paul Bakker9397dcb2013-09-06 09:55:26 +0200271 */
Manuel Pégourié-Gonnardf38e71a2013-09-12 05:21:54 +0200272void x509write_crt_set_issuer_key( x509write_cert *ctx, pk_context *key );
Paul Bakker9397dcb2013-09-06 09:55:26 +0200273
274/**
275 * \brief Set the MD algorithm to use for the signature
276 * (e.g. POLARSSL_MD_SHA1)
277 *
278 * \param ctx CRT context to use
279 * \param md_ald MD algorithm to use
280 */
281void x509write_crt_set_md_alg( x509write_cert *ctx, md_type_t md_alg );
282
283/**
Paul Bakker15162a02013-09-06 19:27:21 +0200284 * \brief Generic function to add to or replace an extension in the
285 * CRT
286 *
287 * \param ctx CRT context to use
288 * \param oid OID of the extension
289 * \param oid_len length of the OID
290 * \param critical if the extension is critical (per the RFC's definition)
291 * \param val value of the extension OCTET STRING
292 * \param val_len length of the value data
293 *
294 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
295 */
296int x509write_crt_set_extension( x509write_cert *ctx,
297 const char *oid, size_t oid_len,
298 int critical,
299 const unsigned char *val, size_t val_len );
300
301/**
302 * \brief Set the basicConstraints extension for a CRT
303 *
304 * \param ctx CRT context to use
305 * \param is_ca is this a CA certificate
306 * \param max_pathlen maximum length of certificate chains below this
307 * certificate (only for CA certificates, -1 is
308 * inlimited)
309 *
310 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
311 */
312int x509write_crt_set_basic_constraints( x509write_cert *ctx,
313 int is_ca, int max_pathlen );
314
315/**
316 * \brief Set the subjectKeyIdentifier extension for a CRT
317 * Requires that x509write_crt_set_subject_key() has been
318 * called before
319 *
320 * \param ctx CRT context to use
321 *
322 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
323 */
324int x509write_crt_set_subject_key_identifier( x509write_cert *ctx );
325
326/**
327 * \brief Set the authorityKeyIdentifier extension for a CRT
328 * Requires that x509write_crt_set_issuer_key() has been
329 * called before
330 *
331 * \param ctx CRT context to use
332 *
333 * \return 0 if successful, or a POLARSSL_ERR_X509WRITE_MALLOC_FAILED
334 */
335int x509write_crt_set_authority_key_identifier( x509write_cert *ctx );
336
337/**
Paul Bakker52be08c2013-09-09 12:37:54 +0200338 * \brief Set the Key Usage Extension flags
339 * (e.g. KU_DIGITAL_SIGNATURE | KU_KEY_CERT_SIGN)
340 *
341 * \param ctx CRT context to use
342 * \param key_usage key usage flags to set
343 *
344 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
345 */
346int x509write_crt_set_key_usage( x509write_cert *ctx, unsigned char key_usage );
347
348/**
349 * \brief Set the Netscape Cert Type flags
350 * (e.g. NS_CERT_TYPE_SSL_CLIENT | NS_CERT_TYPE_EMAIL)
351 *
352 * \param ctx CRT context to use
353 * \param ns_cert_type Netscape Cert Type flags to set
354 *
355 * \return 0 if successful, or POLARSSL_ERR_X509WRITE_MALLOC_FAILED
356 */
357int x509write_crt_set_ns_cert_type( x509write_cert *ctx,
358 unsigned char ns_cert_type );
359
360/**
Paul Bakker9397dcb2013-09-06 09:55:26 +0200361 * \brief Free the contents of a CRT write context
362 *
363 * \param ctx CRT context to free
364 */
365void x509write_crt_free( x509write_cert *ctx );
366
367/**
368 * \brief Write a built up certificate to a X509 DER structure
369 * Note: data is written at the end of the buffer! Use the
370 * return value to determine where you should start
371 * using the buffer
372 *
373 * \param crt certificate to write away
374 * \param buf buffer to write to
375 * \param size size of the buffer
376 *
377 * \return length of data written if successful, or a specific
378 * error code
379 */
380int x509write_crt_der( x509write_cert *ctx, unsigned char *buf, size_t size );
381
382/**
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200383 * \brief Write a public key to a DER structure
Paul Bakkerf6774662013-08-25 11:47:51 +0200384 * Note: data is written at the end of the buffer! Use the
385 * return value to determine where you should start
386 * using the buffer
387 *
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200388 * \param key public key to write away
Paul Bakkerf6774662013-08-25 11:47:51 +0200389 * \param buf buffer to write to
390 * \param size size of the buffer
391 *
392 * \return length of data written if successful, or a specific
393 * error code
394 */
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200395int x509write_pubkey_der( pk_context *key, unsigned char *buf, size_t size );
Paul Bakkerf6774662013-08-25 11:47:51 +0200396
397/**
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200398 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
Paul Bakkerf6774662013-08-25 11:47:51 +0200399 * Note: data is written at the end of the buffer! Use the
400 * return value to determine where you should start
401 * using the buffer
402 *
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200403 * \param key private to write away
Paul Bakkerf6774662013-08-25 11:47:51 +0200404 * \param buf buffer to write to
405 * \param size size of the buffer
406 *
407 * \return length of data written if successful, or a specific
408 * error code
409 */
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200410int x509write_key_der( pk_context *pk, unsigned char *buf, size_t size );
Paul Bakkerf6774662013-08-25 11:47:51 +0200411
412/**
413 * \brief Write a CSR (Certificate Signing Request) to a
414 * DER structure
415 * Note: data is written at the end of the buffer! Use the
416 * return value to determine where you should start
417 * using the buffer
418 *
419 * \param rsa CSR to write away
420 * \param buf buffer to write to
421 * \param size size of the buffer
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200422 * \param f_rng RNG function (for signature, see note)
423 * \param p_rng RNG parameter
Paul Bakkerf6774662013-08-25 11:47:51 +0200424 *
425 * \return length of data written if successful, or a specific
426 * error code
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200427 *
428 * \note f_rng may be NULL if RSA is used for signature and the
429 * signature is made offline (otherwise f_rng is desirable
430 * for countermeasures against timing attacks).
431 * ECDSA signatures always require a non-NULL f_rng.
Paul Bakkerf6774662013-08-25 11:47:51 +0200432 */
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200433int x509write_csr_der( x509write_csr *ctx, unsigned char *buf, size_t size,
434 int (*f_rng)(void *, unsigned char *, size_t),
435 void *p_rng );
Paul Bakkerbdb912d2012-02-13 23:11:30 +0000436
Paul Bakker135f1e92013-08-26 16:54:13 +0200437#if defined(POLARSSL_BASE64_C)
438/**
Paul Bakker9397dcb2013-09-06 09:55:26 +0200439 * \brief Write a built up certificate to a X509 PEM string
440 *
441 * \param crt certificate to write away
442 * \param buf buffer to write to
443 * \param size size of the buffer
444 *
445 * \return 0 successful, or a specific error code
446 */
447int x509write_crt_pem( x509write_cert *ctx, unsigned char *buf, size_t size );
448
449/**
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200450 * \brief Write a public key to a PEM string
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200451 *
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200452 * \param key public key to write away
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200453 * \param buf buffer to write to
454 * \param size size of the buffer
455 *
456 * \return 0 successful, or a specific error code
457 */
Manuel Pégourié-Gonnarde1f821a2013-09-12 00:59:40 +0200458int x509write_pubkey_pem( pk_context *key, unsigned char *buf, size_t size );
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200459
460/**
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200461 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200462 *
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200463 * \param key private to write away
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200464 * \param buf buffer to write to
465 * \param size size of the buffer
466 *
467 * \return 0 successful, or a specific error code
468 */
Manuel Pégourié-Gonnard6de63e42013-09-12 04:59:34 +0200469int x509write_key_pem( pk_context *key, unsigned char *buf, size_t size );
Paul Bakkerf3df61a2013-08-26 17:22:23 +0200470
471/**
Paul Bakker135f1e92013-08-26 16:54:13 +0200472 * \brief Write a CSR (Certificate Signing Request) to a
473 * PEM string
474 *
475 * \param rsa CSR to write away
476 * \param buf buffer to write to
477 * \param size size of the buffer
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200478 * \param f_rng RNG function (for signature, see note)
479 * \param p_rng RNG parameter
Paul Bakker135f1e92013-08-26 16:54:13 +0200480 *
481 * \return 0 successful, or a specific error code
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200482 *
483 * \note f_rng may be NULL if RSA is used for signature and the
484 * signature is made offline (otherwise f_rng is desirable
485 * for couermeasures against timing attacks).
486 * ECDSA signatures always require a non-NULL f_rng.
Paul Bakker135f1e92013-08-26 16:54:13 +0200487 */
Manuel Pégourié-Gonnardee731792013-09-11 22:48:40 +0200488int x509write_csr_pem( x509write_csr *ctx, unsigned char *buf, size_t size,
489 int (*f_rng)(void *, unsigned char *, size_t),
490 void *p_rng );
Paul Bakker135f1e92013-08-26 16:54:13 +0200491#endif /* POLARSSL_BASE64_C */
492
Paul Bakker407a0da2013-06-27 14:29:21 +0200493#ifdef __cplusplus
494}
495#endif
496
Paul Bakkerbdb912d2012-02-13 23:11:30 +0000497#endif /* POLARSSL_X509_WRITE_H */