1 /** 2 * \file x509_crt.h 3 * 4 * \brief X.509 certificate parsing and writing 5 */ 6 /* 7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 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 * This file is part of mbed TLS (https://tls.mbed.org) 23 */ 24 #ifndef MBEDTLS_X509_CRT_H 25 #define MBEDTLS_X509_CRT_H 26 27 #if !defined(MBEDTLS_CONFIG_FILE) 28 #include "config.h" 29 #else 30 #include MBEDTLS_CONFIG_FILE 31 #endif 32 33 #include "x509.h" 34 #include "x509_crl.h" 35 36 /** 37 * \addtogroup x509_module 38 * \{ 39 */ 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * \name Structures and functions for parsing and writing X.509 certificates 47 * \{ 48 */ 49 50 /** 51 * Container for an X.509 certificate. The certificate may be chained. 52 */ 53 typedef struct mbedtls_x509_crt 54 { 55 mbedtls_x509_buf raw; /**< The raw certificate data (DER). */ 56 mbedtls_x509_buf tbs; /**< The raw certificate body (DER). The part that is To Be Signed. */ 57 58 int version; /**< The X.509 version. (1=v1, 2=v2, 3=v3) */ 59 mbedtls_x509_buf serial; /**< Unique id for certificate issued by a specific CA. */ 60 mbedtls_x509_buf sig_oid; /**< Signature algorithm, e.g. sha1RSA */ 61 62 mbedtls_x509_buf issuer_raw; /**< The raw issuer data (DER). Used for quick comparison. */ 63 mbedtls_x509_buf subject_raw; /**< The raw subject data (DER). Used for quick comparison. */ 64 65 mbedtls_x509_name issuer; /**< The parsed issuer data (named information object). */ 66 mbedtls_x509_name subject; /**< The parsed subject data (named information object). */ 67 68 mbedtls_x509_time valid_from; /**< Start time of certificate validity. */ 69 mbedtls_x509_time valid_to; /**< End time of certificate validity. */ 70 71 mbedtls_pk_context pk; /**< Container for the public key context. */ 72 73 mbedtls_x509_buf issuer_id; /**< Optional X.509 v2/v3 issuer unique identifier. */ 74 mbedtls_x509_buf subject_id; /**< Optional X.509 v2/v3 subject unique identifier. */ 75 mbedtls_x509_buf v3_ext; /**< Optional X.509 v3 extensions. */ 76 mbedtls_x509_sequence subject_alt_names; /**< Optional list of Subject Alternative Names (Only dNSName supported). */ 77 78 int ext_types; /**< Bit string containing detected and parsed extensions */ 79 int ca_istrue; /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */ 80 int max_pathlen; /**< Optional Basic Constraint extension value: The maximum path length to the root certificate. Path length is 1 higher than RFC 5280 'meaning', so 1+ */ 81 82 unsigned int key_usage; /**< Optional key usage extension value: See the values in x509.h */ 83 84 mbedtls_x509_sequence ext_key_usage; /**< Optional list of extended key usage OIDs. */ 85 86 unsigned char ns_cert_type; /**< Optional Netscape certificate type extension value: See the values in x509.h */ 87 88 mbedtls_x509_buf sig; /**< Signature: hash of the tbs part signed with the private key. */ 89 mbedtls_md_type_t sig_md; /**< Internal representation of the MD algorithm of the signature algorithm, e.g. MBEDTLS_MD_SHA256 */ 90 mbedtls_pk_type_t sig_pk; /**< Internal representation of the Public Key algorithm of the signature algorithm, e.g. MBEDTLS_PK_RSA */ 91 void *sig_opts; /**< Signature options to be passed to mbedtls_pk_verify_ext(), e.g. for RSASSA-PSS */ 92 93 struct mbedtls_x509_crt *next; /**< Next certificate in the CA-chain. */ 94 } 95 mbedtls_x509_crt; 96 97 /** 98 * Build flag from an algorithm/curve identifier (pk, md, ecp) 99 * Since 0 is always XXX_NONE, ignore it. 100 */ 101 #define MBEDTLS_X509_ID_FLAG( id ) ( 1 << ( (id) - 1 ) ) 102 103 /** 104 * Security profile for certificate verification. 105 * 106 * All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG(). 107 */ 108 typedef struct mbedtls_x509_crt_profile 109 { 110 uint32_t allowed_mds; /**< MDs for signatures */ 111 uint32_t allowed_pks; /**< PK algs for signatures */ 112 uint32_t allowed_curves; /**< Elliptic curves for ECDSA */ 113 uint32_t rsa_min_bitlen; /**< Minimum size for RSA keys */ 114 } 115 mbedtls_x509_crt_profile; 116 117 #define MBEDTLS_X509_CRT_VERSION_1 0 118 #define MBEDTLS_X509_CRT_VERSION_2 1 119 #define MBEDTLS_X509_CRT_VERSION_3 2 120 121 #define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32 122 #define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15 123 124 #if !defined( MBEDTLS_X509_MAX_FILE_PATH_LEN ) 125 #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 126 #endif 127 128 /** 129 * Container for writing a certificate (CRT) 130 */ 131 typedef struct mbedtls_x509write_cert 132 { 133 int version; 134 mbedtls_mpi serial; 135 mbedtls_pk_context *subject_key; 136 mbedtls_pk_context *issuer_key; 137 mbedtls_asn1_named_data *subject; 138 mbedtls_asn1_named_data *issuer; 139 mbedtls_md_type_t md_alg; 140 char not_before[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1]; 141 char not_after[MBEDTLS_X509_RFC5280_UTC_TIME_LEN + 1]; 142 mbedtls_asn1_named_data *extensions; 143 } 144 mbedtls_x509write_cert; 145 146 /** 147 * Item in a verification chain: cert and flags for it 148 */ 149 typedef struct { 150 mbedtls_x509_crt *crt; 151 uint32_t flags; 152 } mbedtls_x509_crt_verify_chain_item; 153 154 /** 155 * Max size of verification chain: end-entity + intermediates + trusted root 156 */ 157 #define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 ) 158 159 /** 160 * Verification chain as built by \c mbedtls_crt_verify_chain() 161 */ 162 typedef struct 163 { 164 mbedtls_x509_crt_verify_chain_item items[MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE]; 165 unsigned len; 166 } mbedtls_x509_crt_verify_chain; 167 168 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE) 169 170 /** 171 * \brief Context for resuming X.509 verify operations 172 */ 173 typedef struct 174 { 175 /* for check_signature() */ 176 mbedtls_pk_restart_ctx pk; 177 178 /* for find_parent_in() */ 179 mbedtls_x509_crt *parent; /* non-null iff parent_in in progress */ 180 mbedtls_x509_crt *fallback_parent; 181 int fallback_signature_is_good; 182 183 /* for find_parent() */ 184 int parent_is_trusted; /* -1 if find_parent is not in progress */ 185 186 /* for verify_chain() */ 187 enum { 188 x509_crt_rs_none, 189 x509_crt_rs_find_parent, 190 } in_progress; /* none if no operation is in progress */ 191 int self_cnt; 192 mbedtls_x509_crt_verify_chain ver_chain; 193 194 } mbedtls_x509_crt_restart_ctx; 195 196 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 197 198 /* Now we can declare functions that take a pointer to that */ 199 typedef void mbedtls_x509_crt_restart_ctx; 200 201 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 202 203 #if defined(MBEDTLS_X509_CRT_PARSE_C) 204 /** 205 * Default security profile. Should provide a good balance between security 206 * and compatibility with current deployments. 207 */ 208 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default; 209 210 /** 211 * Expected next default profile. Recommended for new deployments. 212 * Currently targets a 128-bit security level, except for RSA-2048. 213 */ 214 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next; 215 216 /** 217 * NSA Suite B profile. 218 */ 219 extern const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb; 220 221 /** 222 * \brief Parse a single DER formatted certificate and add it 223 * to the chained list. 224 * 225 * \param chain points to the start of the chain 226 * \param buf buffer holding the certificate DER data 227 * \param buflen size of the buffer 228 * 229 * \return 0 if successful, or a specific X509 or PEM error code 230 */ 231 int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf, 232 size_t buflen ); 233 234 /** 235 * \brief Parse one DER-encoded or one or more concatenated PEM-encoded 236 * certificates and add them to the chained list. 237 * 238 * For CRTs in PEM encoding, the function parses permissively: 239 * if at least one certificate can be parsed, the function 240 * returns the number of certificates for which parsing failed 241 * (hence \c 0 if all certificates were parsed successfully). 242 * If no certificate could be parsed, the function returns 243 * the first (negative) error encountered during parsing. 244 * 245 * PEM encoded certificates may be interleaved by other data 246 * such as human readable descriptions of their content, as 247 * long as the certificates are enclosed in the PEM specific 248 * '-----{BEGIN/END} CERTIFICATE-----' delimiters. 249 * 250 * \param chain The chain to which to add the parsed certificates. 251 * \param buf The buffer holding the certificate data in PEM or DER format. 252 * For certificates in PEM encoding, this may be a concatenation 253 * of multiple certificates; for DER encoding, the buffer must 254 * comprise exactly one certificate. 255 * \param buflen The size of \p buf, including the terminating \c NULL byte 256 * in case of PEM encoded data. 257 * 258 * \return \c 0 if all certificates were parsed successfully. 259 * \return The (positive) number of certificates that couldn't 260 * be parsed if parsing was partly successful (see above). 261 * \return A negative X509 or PEM error code otherwise. 262 * 263 */ 264 int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen ); 265 266 #if defined(MBEDTLS_FS_IO) 267 /** 268 * \brief Load one or more certificates and add them 269 * to the chained list. Parses permissively. If some 270 * certificates can be parsed, the result is the number 271 * of failed certificates it encountered. If none complete 272 * correctly, the first error is returned. 273 * 274 * \param chain points to the start of the chain 275 * \param path filename to read the certificates from 276 * 277 * \return 0 if all certificates parsed successfully, a positive number 278 * if partly successful or a specific X509 or PEM error code 279 */ 280 int mbedtls_x509_crt_parse_file( mbedtls_x509_crt *chain, const char *path ); 281 282 /** 283 * \brief Load one or more certificate files from a path and add them 284 * to the chained list. Parses permissively. If some 285 * certificates can be parsed, the result is the number 286 * of failed certificates it encountered. If none complete 287 * correctly, the first error is returned. 288 * 289 * \param chain points to the start of the chain 290 * \param path directory / folder to read the certificate files from 291 * 292 * \return 0 if all certificates parsed successfully, a positive number 293 * if partly successful or a specific X509 or PEM error code 294 */ 295 int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path ); 296 #endif /* MBEDTLS_FS_IO */ 297 298 /** 299 * \brief Returns an informational string about the 300 * certificate. 301 * 302 * \param buf Buffer to write to 303 * \param size Maximum size of buffer 304 * \param prefix A line prefix 305 * \param crt The X509 certificate to represent 306 * 307 * \return The length of the string written (not including the 308 * terminated nul byte), or a negative error code. 309 */ 310 int mbedtls_x509_crt_info( char *buf, size_t size, const char *prefix, 311 const mbedtls_x509_crt *crt ); 312 313 /** 314 * \brief Returns an informational string about the 315 * verification status of a certificate. 316 * 317 * \param buf Buffer to write to 318 * \param size Maximum size of buffer 319 * \param prefix A line prefix 320 * \param flags Verification flags created by mbedtls_x509_crt_verify() 321 * 322 * \return The length of the string written (not including the 323 * terminated nul byte), or a negative error code. 324 */ 325 int mbedtls_x509_crt_verify_info( char *buf, size_t size, const char *prefix, 326 uint32_t flags ); 327 328 /** 329 * \brief Verify the certificate signature 330 * 331 * The verify callback is a user-supplied callback that 332 * can clear / modify / add flags for a certificate. If set, 333 * the verification callback is called for each 334 * certificate in the chain (from the trust-ca down to the 335 * presented crt). The parameters for the callback are: 336 * (void *parameter, mbedtls_x509_crt *crt, int certificate_depth, 337 * int *flags). With the flags representing current flags for 338 * that specific certificate and the certificate depth from 339 * the bottom (Peer cert depth = 0). 340 * 341 * All flags left after returning from the callback 342 * are also returned to the application. The function should 343 * return 0 for anything (including invalid certificates) 344 * other than fatal error, as a non-zero return code 345 * immediately aborts the verification process. For fatal 346 * errors, a specific error code should be used (different 347 * from MBEDTLS_ERR_X509_CERT_VERIFY_FAILED which should not 348 * be returned at this point), or MBEDTLS_ERR_X509_FATAL_ERROR 349 * can be used if no better code is available. 350 * 351 * \note In case verification failed, the results can be displayed 352 * using \c mbedtls_x509_crt_verify_info() 353 * 354 * \note Same as \c mbedtls_x509_crt_verify_with_profile() with the 355 * default security profile. 356 * 357 * \note It is your responsibility to provide up-to-date CRLs for 358 * all trusted CAs. If no CRL is provided for the CA that was 359 * used to sign the certificate, CRL verification is skipped 360 * silently, that is *without* setting any flag. 361 * 362 * \note The \c trust_ca list can contain two types of certificates: 363 * (1) those of trusted root CAs, so that certificates 364 * chaining up to those CAs will be trusted, and (2) 365 * self-signed end-entity certificates to be trusted (for 366 * specific peers you know) - in that case, the self-signed 367 * certificate doesn't need to have the CA bit set. 368 * 369 * \param crt a certificate (chain) to be verified 370 * \param trust_ca the list of trusted CAs (see note above) 371 * \param ca_crl the list of CRLs for trusted CAs (see note above) 372 * \param cn expected Common Name (can be set to 373 * NULL if the CN must not be verified) 374 * \param flags result of the verification 375 * \param f_vrfy verification function 376 * \param p_vrfy verification parameter 377 * 378 * \return 0 (and flags set to 0) if the chain was verified and valid, 379 * MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified 380 * but found to be invalid, in which case *flags will have one 381 * or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX 382 * flags set, or another error (and flags set to 0xffffffff) 383 * in case of a fatal error encountered during the 384 * verification process. 385 */ 386 int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt, 387 mbedtls_x509_crt *trust_ca, 388 mbedtls_x509_crl *ca_crl, 389 const char *cn, uint32_t *flags, 390 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 391 void *p_vrfy ); 392 393 /** 394 * \brief Verify the certificate signature according to profile 395 * 396 * \note Same as \c mbedtls_x509_crt_verify(), but with explicit 397 * security profile. 398 * 399 * \note The restrictions on keys (RSA minimum size, allowed curves 400 * for ECDSA) apply to all certificates: trusted root, 401 * intermediate CAs if any, and end entity certificate. 402 * 403 * \param crt a certificate (chain) to be verified 404 * \param trust_ca the list of trusted CAs 405 * \param ca_crl the list of CRLs for trusted CAs 406 * \param profile security profile for verification 407 * \param cn expected Common Name (can be set to 408 * NULL if the CN must not be verified) 409 * \param flags result of the verification 410 * \param f_vrfy verification function 411 * \param p_vrfy verification parameter 412 * 413 * \return 0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED 414 * in which case *flags will have one or more 415 * MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags 416 * set, 417 * or another error in case of a fatal error encountered 418 * during the verification process. 419 */ 420 int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt, 421 mbedtls_x509_crt *trust_ca, 422 mbedtls_x509_crl *ca_crl, 423 const mbedtls_x509_crt_profile *profile, 424 const char *cn, uint32_t *flags, 425 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 426 void *p_vrfy ); 427 428 /** 429 * \brief Restartable version of \c mbedtls_crt_verify_with_profile() 430 * 431 * \note Performs the same job as \c mbedtls_crt_verify_with_profile() 432 * but can return early and restart according to the limit 433 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 434 * 435 * \param crt a certificate (chain) to be verified 436 * \param trust_ca the list of trusted CAs 437 * \param ca_crl the list of CRLs for trusted CAs 438 * \param profile security profile for verification 439 * \param cn expected Common Name (can be set to 440 * NULL if the CN must not be verified) 441 * \param flags result of the verification 442 * \param f_vrfy verification function 443 * \param p_vrfy verification parameter 444 * \param rs_ctx restart context (NULL to disable restart) 445 * 446 * \return See \c mbedtls_crt_verify_with_profile(), or 447 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 448 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 449 */ 450 int mbedtls_x509_crt_verify_restartable( mbedtls_x509_crt *crt, 451 mbedtls_x509_crt *trust_ca, 452 mbedtls_x509_crl *ca_crl, 453 const mbedtls_x509_crt_profile *profile, 454 const char *cn, uint32_t *flags, 455 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 456 void *p_vrfy, 457 mbedtls_x509_crt_restart_ctx *rs_ctx ); 458 459 #if defined(MBEDTLS_X509_CHECK_KEY_USAGE) 460 /** 461 * \brief Check usage of certificate against keyUsage extension. 462 * 463 * \param crt Leaf certificate used. 464 * \param usage Intended usage(s) (eg MBEDTLS_X509_KU_KEY_ENCIPHERMENT 465 * before using the certificate to perform an RSA key 466 * exchange). 467 * 468 * \note Except for decipherOnly and encipherOnly, a bit set in the 469 * usage argument means this bit MUST be set in the 470 * certificate. For decipherOnly and encipherOnly, it means 471 * that bit MAY be set. 472 * 473 * \return 0 is these uses of the certificate are allowed, 474 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if the keyUsage extension 475 * is present but does not match the usage argument. 476 * 477 * \note You should only call this function on leaf certificates, on 478 * (intermediate) CAs the keyUsage extension is automatically 479 * checked by \c mbedtls_x509_crt_verify(). 480 */ 481 int mbedtls_x509_crt_check_key_usage( const mbedtls_x509_crt *crt, 482 unsigned int usage ); 483 #endif /* MBEDTLS_X509_CHECK_KEY_USAGE) */ 484 485 #if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE) 486 /** 487 * \brief Check usage of certificate against extendedKeyUsage. 488 * 489 * \param crt Leaf certificate used. 490 * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or 491 * MBEDTLS_OID_CLIENT_AUTH). 492 * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()). 493 * 494 * \return 0 if this use of the certificate is allowed, 495 * MBEDTLS_ERR_X509_BAD_INPUT_DATA if not. 496 * 497 * \note Usually only makes sense on leaf certificates. 498 */ 499 int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt, 500 const char *usage_oid, 501 size_t usage_len ); 502 #endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */ 503 504 #if defined(MBEDTLS_X509_CRL_PARSE_C) 505 /** 506 * \brief Verify the certificate revocation status 507 * 508 * \param crt a certificate to be verified 509 * \param crl the CRL to verify against 510 * 511 * \return 1 if the certificate is revoked, 0 otherwise 512 * 513 */ 514 int mbedtls_x509_crt_is_revoked( const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl ); 515 #endif /* MBEDTLS_X509_CRL_PARSE_C */ 516 517 /** 518 * \brief Initialize a certificate (chain) 519 * 520 * \param crt Certificate chain to initialize 521 */ 522 void mbedtls_x509_crt_init( mbedtls_x509_crt *crt ); 523 524 /** 525 * \brief Unallocate all certificate data 526 * 527 * \param crt Certificate chain to free 528 */ 529 void mbedtls_x509_crt_free( mbedtls_x509_crt *crt ); 530 531 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE) 532 /** 533 * \brief Initialize a restart context 534 */ 535 void mbedtls_x509_crt_restart_init( mbedtls_x509_crt_restart_ctx *ctx ); 536 537 /** 538 * \brief Free the components of a restart context 539 */ 540 void mbedtls_x509_crt_restart_free( mbedtls_x509_crt_restart_ctx *ctx ); 541 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ 542 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 543 544 /* \} name */ 545 /* \} addtogroup x509_module */ 546 547 #if defined(MBEDTLS_X509_CRT_WRITE_C) 548 /** 549 * \brief Initialize a CRT writing context 550 * 551 * \param ctx CRT context to initialize 552 */ 553 void mbedtls_x509write_crt_init( mbedtls_x509write_cert *ctx ); 554 555 /** 556 * \brief Set the verion for a Certificate 557 * Default: MBEDTLS_X509_CRT_VERSION_3 558 * 559 * \param ctx CRT context to use 560 * \param version version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or 561 * MBEDTLS_X509_CRT_VERSION_3) 562 */ 563 void mbedtls_x509write_crt_set_version( mbedtls_x509write_cert *ctx, int version ); 564 565 /** 566 * \brief Set the serial number for a Certificate. 567 * 568 * \param ctx CRT context to use 569 * \param serial serial number to set 570 * 571 * \return 0 if successful 572 */ 573 int mbedtls_x509write_crt_set_serial( mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial ); 574 575 /** 576 * \brief Set the validity period for a Certificate 577 * Timestamps should be in string format for UTC timezone 578 * i.e. "YYYYMMDDhhmmss" 579 * e.g. "20131231235959" for December 31st 2013 580 * at 23:59:59 581 * 582 * \param ctx CRT context to use 583 * \param not_before not_before timestamp 584 * \param not_after not_after timestamp 585 * 586 * \return 0 if timestamp was parsed successfully, or 587 * a specific error code 588 */ 589 int mbedtls_x509write_crt_set_validity( mbedtls_x509write_cert *ctx, const char *not_before, 590 const char *not_after ); 591 592 /** 593 * \brief Set the issuer name for a Certificate 594 * Issuer names should contain a comma-separated list 595 * of OID types and values: 596 * e.g. "C=UK,O=ARM,CN=mbed TLS CA" 597 * 598 * \param ctx CRT context to use 599 * \param issuer_name issuer name to set 600 * 601 * \return 0 if issuer name was parsed successfully, or 602 * a specific error code 603 */ 604 int mbedtls_x509write_crt_set_issuer_name( mbedtls_x509write_cert *ctx, 605 const char *issuer_name ); 606 607 /** 608 * \brief Set the subject name for a Certificate 609 * Subject names should contain a comma-separated list 610 * of OID types and values: 611 * e.g. "C=UK,O=ARM,CN=mbed TLS Server 1" 612 * 613 * \param ctx CRT context to use 614 * \param subject_name subject name to set 615 * 616 * \return 0 if subject name was parsed successfully, or 617 * a specific error code 618 */ 619 int mbedtls_x509write_crt_set_subject_name( mbedtls_x509write_cert *ctx, 620 const char *subject_name ); 621 622 /** 623 * \brief Set the subject public key for the certificate 624 * 625 * \param ctx CRT context to use 626 * \param key public key to include 627 */ 628 void mbedtls_x509write_crt_set_subject_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key ); 629 630 /** 631 * \brief Set the issuer key used for signing the certificate 632 * 633 * \param ctx CRT context to use 634 * \param key private key to sign with 635 */ 636 void mbedtls_x509write_crt_set_issuer_key( mbedtls_x509write_cert *ctx, mbedtls_pk_context *key ); 637 638 /** 639 * \brief Set the MD algorithm to use for the signature 640 * (e.g. MBEDTLS_MD_SHA1) 641 * 642 * \param ctx CRT context to use 643 * \param md_alg MD algorithm to use 644 */ 645 void mbedtls_x509write_crt_set_md_alg( mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg ); 646 647 /** 648 * \brief Generic function to add to or replace an extension in the 649 * CRT 650 * 651 * \param ctx CRT context to use 652 * \param oid OID of the extension 653 * \param oid_len length of the OID 654 * \param critical if the extension is critical (per the RFC's definition) 655 * \param val value of the extension OCTET STRING 656 * \param val_len length of the value data 657 * 658 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 659 */ 660 int mbedtls_x509write_crt_set_extension( mbedtls_x509write_cert *ctx, 661 const char *oid, size_t oid_len, 662 int critical, 663 const unsigned char *val, size_t val_len ); 664 665 /** 666 * \brief Set the basicConstraints extension for a CRT 667 * 668 * \param ctx CRT context to use 669 * \param is_ca is this a CA certificate 670 * \param max_pathlen maximum length of certificate chains below this 671 * certificate (only for CA certificates, -1 is 672 * inlimited) 673 * 674 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 675 */ 676 int mbedtls_x509write_crt_set_basic_constraints( mbedtls_x509write_cert *ctx, 677 int is_ca, int max_pathlen ); 678 679 #if defined(MBEDTLS_SHA1_C) 680 /** 681 * \brief Set the subjectKeyIdentifier extension for a CRT 682 * Requires that mbedtls_x509write_crt_set_subject_key() has been 683 * called before 684 * 685 * \param ctx CRT context to use 686 * 687 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 688 */ 689 int mbedtls_x509write_crt_set_subject_key_identifier( mbedtls_x509write_cert *ctx ); 690 691 /** 692 * \brief Set the authorityKeyIdentifier extension for a CRT 693 * Requires that mbedtls_x509write_crt_set_issuer_key() has been 694 * called before 695 * 696 * \param ctx CRT context to use 697 * 698 * \return 0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED 699 */ 700 int mbedtls_x509write_crt_set_authority_key_identifier( mbedtls_x509write_cert *ctx ); 701 #endif /* MBEDTLS_SHA1_C */ 702 703 /** 704 * \brief Set the Key Usage Extension flags 705 * (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN) 706 * 707 * \param ctx CRT context to use 708 * \param key_usage key usage flags to set 709 * 710 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 711 */ 712 int mbedtls_x509write_crt_set_key_usage( mbedtls_x509write_cert *ctx, 713 unsigned int key_usage ); 714 715 /** 716 * \brief Set the Netscape Cert Type flags 717 * (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL) 718 * 719 * \param ctx CRT context to use 720 * \param ns_cert_type Netscape Cert Type flags to set 721 * 722 * \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED 723 */ 724 int mbedtls_x509write_crt_set_ns_cert_type( mbedtls_x509write_cert *ctx, 725 unsigned char ns_cert_type ); 726 727 /** 728 * \brief Free the contents of a CRT write context 729 * 730 * \param ctx CRT context to free 731 */ 732 void mbedtls_x509write_crt_free( mbedtls_x509write_cert *ctx ); 733 734 /** 735 * \brief Write a built up certificate to a X509 DER structure 736 * Note: data is written at the end of the buffer! Use the 737 * return value to determine where you should start 738 * using the buffer 739 * 740 * \param ctx certificate to write away 741 * \param buf buffer to write to 742 * \param size size of the buffer 743 * \param f_rng RNG function (for signature, see note) 744 * \param p_rng RNG parameter 745 * 746 * \return length of data written if successful, or a specific 747 * error code 748 * 749 * \note f_rng may be NULL if RSA is used for signature and the 750 * signature is made offline (otherwise f_rng is desirable 751 * for countermeasures against timing attacks). 752 * ECDSA signatures always require a non-NULL f_rng. 753 */ 754 int mbedtls_x509write_crt_der( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, 755 int (*f_rng)(void *, unsigned char *, size_t), 756 void *p_rng ); 757 758 #if defined(MBEDTLS_PEM_WRITE_C) 759 /** 760 * \brief Write a built up certificate to a X509 PEM string 761 * 762 * \param ctx certificate to write away 763 * \param buf buffer to write to 764 * \param size size of the buffer 765 * \param f_rng RNG function (for signature, see note) 766 * \param p_rng RNG parameter 767 * 768 * \return 0 if successful, or a specific error code 769 * 770 * \note f_rng may be NULL if RSA is used for signature and the 771 * signature is made offline (otherwise f_rng is desirable 772 * for countermeasures against timing attacks). 773 * ECDSA signatures always require a non-NULL f_rng. 774 */ 775 int mbedtls_x509write_crt_pem( mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, 776 int (*f_rng)(void *, unsigned char *, size_t), 777 void *p_rng ); 778 #endif /* MBEDTLS_PEM_WRITE_C */ 779 #endif /* MBEDTLS_X509_CRT_WRITE_C */ 780 781 #ifdef __cplusplus 782 } 783 #endif 784 785 #endif /* mbedtls_x509_crt.h */ 786