mbed TLS v3.1.0
Data Structures | Functions
x509_crt.h File Reference

X.509 certificate parsing and writing. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/x509.h"
#include "mbedtls/x509_crl.h"
#include "mbedtls/bignum.h"
Include dependency graph for x509_crt.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_x509_crt
 
struct  mbedtls_x509_san_other_name
 
struct  mbedtls_x509_subject_alternative_name
 
struct  mbedtls_x509_crt_profile
 
struct  mbedtls_x509write_cert
 
struct  mbedtls_x509_crt_verify_chain_item
 
struct  mbedtls_x509_crt_verify_chain
 
struct  mbedtls_x509_crt_restart_ctx
 Context for resuming X.509 verify operations. More...
 

Functions

void mbedtls_x509write_crt_init (mbedtls_x509write_cert *ctx)
 Initialize a CRT writing context. More...
 
void mbedtls_x509write_crt_set_version (mbedtls_x509write_cert *ctx, int version)
 Set the verion for a Certificate Default: MBEDTLS_X509_CRT_VERSION_3. More...
 
int mbedtls_x509write_crt_set_serial (mbedtls_x509write_cert *ctx, const mbedtls_mpi *serial)
 Set the serial number for a Certificate. More...
 
int mbedtls_x509write_crt_set_validity (mbedtls_x509write_cert *ctx, const char *not_before, const char *not_after)
 Set the validity period for a Certificate Timestamps should be in string format for UTC timezone i.e. "YYYYMMDDhhmmss" e.g. "20131231235959" for December 31st 2013 at 23:59:59. More...
 
int mbedtls_x509write_crt_set_issuer_name (mbedtls_x509write_cert *ctx, const char *issuer_name)
 Set the issuer name for a Certificate Issuer names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=mbed TLS CA". More...
 
int mbedtls_x509write_crt_set_subject_name (mbedtls_x509write_cert *ctx, const char *subject_name)
 Set the subject name for a Certificate Subject names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=mbed TLS Server 1". More...
 
void mbedtls_x509write_crt_set_subject_key (mbedtls_x509write_cert *ctx, mbedtls_pk_context *key)
 Set the subject public key for the certificate. More...
 
void mbedtls_x509write_crt_set_issuer_key (mbedtls_x509write_cert *ctx, mbedtls_pk_context *key)
 Set the issuer key used for signing the certificate. More...
 
void mbedtls_x509write_crt_set_md_alg (mbedtls_x509write_cert *ctx, mbedtls_md_type_t md_alg)
 Set the MD algorithm to use for the signature (e.g. MBEDTLS_MD_SHA1) More...
 
int mbedtls_x509write_crt_set_extension (mbedtls_x509write_cert *ctx, const char *oid, size_t oid_len, int critical, const unsigned char *val, size_t val_len)
 Generic function to add to or replace an extension in the CRT. More...
 
int mbedtls_x509write_crt_set_basic_constraints (mbedtls_x509write_cert *ctx, int is_ca, int max_pathlen)
 Set the basicConstraints extension for a CRT. More...
 
int mbedtls_x509write_crt_set_subject_key_identifier (mbedtls_x509write_cert *ctx)
 Set the subjectKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_subject_key() has been called before. More...
 
int mbedtls_x509write_crt_set_authority_key_identifier (mbedtls_x509write_cert *ctx)
 Set the authorityKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_issuer_key() has been called before. More...
 
int mbedtls_x509write_crt_set_key_usage (mbedtls_x509write_cert *ctx, unsigned int key_usage)
 Set the Key Usage Extension flags (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN) More...
 
int mbedtls_x509write_crt_set_ns_cert_type (mbedtls_x509write_cert *ctx, unsigned char ns_cert_type)
 Set the Netscape Cert Type flags (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL) More...
 
void mbedtls_x509write_crt_free (mbedtls_x509write_cert *ctx)
 Free the contents of a CRT write context. More...
 
int mbedtls_x509write_crt_der (mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Write a built up certificate to a X509 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer. More...
 
int mbedtls_x509write_crt_pem (mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Write a built up certificate to a X509 PEM string. More...
 

Structures and functions for parsing and writing X.509 certificates

#define MBEDTLS_X509_ID_FLAG(id)   ( 1 << ( (id) - 1 ) )
 
#define MBEDTLS_X509_CRT_VERSION_1   0
 
#define MBEDTLS_X509_CRT_VERSION_2   1
 
#define MBEDTLS_X509_CRT_VERSION_3   2
 
#define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN   32
 
#define MBEDTLS_X509_RFC5280_UTC_TIME_LEN   15
 
#define MBEDTLS_X509_MAX_FILE_PATH_LEN   512
 
#define MBEDTLS_X509_CRT_ERROR_INFO_LIST
 
#define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE   ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 )
 
typedef struct mbedtls_x509_crt mbedtls_x509_crt
 
typedef struct
mbedtls_x509_san_other_name 
mbedtls_x509_san_other_name
 
typedef struct
mbedtls_x509_subject_alternative_name 
mbedtls_x509_subject_alternative_name
 
typedef struct
mbedtls_x509_crt_profile 
mbedtls_x509_crt_profile
 
typedef struct
mbedtls_x509write_cert 
mbedtls_x509write_cert
 
typedef int(* mbedtls_x509_crt_ext_cb_t )(void *p_ctx, mbedtls_x509_crt const *crt, mbedtls_x509_buf const *oid, int critical, const unsigned char *p, const unsigned char *end)
 The type of certificate extension callbacks. More...
 
typedef int(* mbedtls_x509_crt_ca_cb_t )(void *p_ctx, mbedtls_x509_crt const *child, mbedtls_x509_crt **candidate_cas)
 The type of trusted certificate callbacks. More...
 
const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_default
 
const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_next
 
const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_suiteb
 
const mbedtls_x509_crt_profile mbedtls_x509_crt_profile_none
 
int mbedtls_x509_crt_parse_der (mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen)
 Parse a single DER formatted certificate and add it to the end of the provided chained list. More...
 
int mbedtls_x509_crt_parse_der_with_ext_cb (mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen, int make_copy, mbedtls_x509_crt_ext_cb_t cb, void *p_ctx)
 Parse a single DER formatted certificate and add it to the end of the provided chained list. More...
 
int mbedtls_x509_crt_parse_der_nocopy (mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen)
 Parse a single DER formatted certificate and add it to the end of the provided chained list. This is a variant of mbedtls_x509_crt_parse_der() which takes temporary ownership of the CRT buffer until the CRT is destroyed. More...
 
int mbedtls_x509_crt_parse (mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen)
 Parse one DER-encoded or one or more concatenated PEM-encoded certificates and add them to the chained list. More...
 
int mbedtls_x509_crt_parse_file (mbedtls_x509_crt *chain, const char *path)
 Load one or more certificates and add them to the chained list. Parses permissively. If some certificates can be parsed, the result is the number of failed certificates it encountered. If none complete correctly, the first error is returned. More...
 
int mbedtls_x509_crt_parse_path (mbedtls_x509_crt *chain, const char *path)
 Load one or more certificate files from a path and add them to the chained list. Parses permissively. If some certificates can be parsed, the result is the number of failed certificates it encountered. If none complete correctly, the first error is returned. More...
 
int mbedtls_x509_parse_subject_alt_name (const mbedtls_x509_buf *san_buf, mbedtls_x509_subject_alternative_name *san)
 This function parses an item in the SubjectAlternativeNames extension. More...
 
int mbedtls_x509_crt_verify (mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, mbedtls_x509_crl *ca_crl, const char *cn, uint32_t *flags, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy)
 Verify a chain of certificates. More...
 
int mbedtls_x509_crt_verify_with_profile (mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, mbedtls_x509_crl *ca_crl, const mbedtls_x509_crt_profile *profile, const char *cn, uint32_t *flags, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy)
 Verify a chain of certificates with respect to a configurable security profile. More...
 
int mbedtls_x509_crt_verify_restartable (mbedtls_x509_crt *crt, mbedtls_x509_crt *trust_ca, mbedtls_x509_crl *ca_crl, const mbedtls_x509_crt_profile *profile, const char *cn, uint32_t *flags, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy, mbedtls_x509_crt_restart_ctx *rs_ctx)
 Restartable version of mbedtls_crt_verify_with_profile() More...
 
int mbedtls_x509_crt_verify_with_ca_cb (mbedtls_x509_crt *crt, mbedtls_x509_crt_ca_cb_t f_ca_cb, void *p_ca_cb, const mbedtls_x509_crt_profile *profile, const char *cn, uint32_t *flags, int(*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), void *p_vrfy)
 Version of mbedtls_x509_crt_verify_with_profile() which uses a callback to acquire the list of trusted CA certificates. More...
 
int mbedtls_x509_crt_check_key_usage (const mbedtls_x509_crt *crt, unsigned int usage)
 Check usage of certificate against keyUsage extension. More...
 
int mbedtls_x509_crt_check_extended_key_usage (const mbedtls_x509_crt *crt, const char *usage_oid, size_t usage_len)
 Check usage of certificate against extendedKeyUsage. More...
 
int mbedtls_x509_crt_is_revoked (const mbedtls_x509_crt *crt, const mbedtls_x509_crl *crl)
 Verify the certificate revocation status. More...
 
void mbedtls_x509_crt_init (mbedtls_x509_crt *crt)
 Initialize a certificate (chain) More...
 
void mbedtls_x509_crt_free (mbedtls_x509_crt *crt)
 Unallocate all certificate data. More...
 
void mbedtls_x509_crt_restart_init (mbedtls_x509_crt_restart_ctx *ctx)
 Initialize a restart context. More...
 
void mbedtls_x509_crt_restart_free (mbedtls_x509_crt_restart_ctx *ctx)
 Free the components of a restart context. More...
 

Detailed Description

X.509 certificate parsing and writing.

Definition in file x509_crt.h.

Function Documentation

int mbedtls_x509write_crt_der ( mbedtls_x509write_cert ctx,
unsigned char *  buf,
size_t  size,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Write a built up certificate to a X509 DER structure Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer.

Parameters
ctxcertificate to write away
bufbuffer to write to
sizesize of the buffer
f_rngRNG function. This must not be NULL.
p_rngRNG parameter
Returns
length of data written if successful, or a specific error code
Note
f_rng is used for the signature operation.
void mbedtls_x509write_crt_free ( mbedtls_x509write_cert ctx)

Free the contents of a CRT write context.

Parameters
ctxCRT context to free
void mbedtls_x509write_crt_init ( mbedtls_x509write_cert ctx)

Initialize a CRT writing context.

Parameters
ctxCRT context to initialize
int mbedtls_x509write_crt_pem ( mbedtls_x509write_cert ctx,
unsigned char *  buf,
size_t  size,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

Write a built up certificate to a X509 PEM string.

Parameters
ctxcertificate to write away
bufbuffer to write to
sizesize of the buffer
f_rngRNG function. This must not be NULL.
p_rngRNG parameter
Returns
0 if successful, or a specific error code
Note
f_rng is used for the signature operation.
int mbedtls_x509write_crt_set_authority_key_identifier ( mbedtls_x509write_cert ctx)

Set the authorityKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_issuer_key() has been called before.

Parameters
ctxCRT context to use
Returns
0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
int mbedtls_x509write_crt_set_basic_constraints ( mbedtls_x509write_cert ctx,
int  is_ca,
int  max_pathlen 
)

Set the basicConstraints extension for a CRT.

Parameters
ctxCRT context to use
is_cais this a CA certificate
max_pathlenmaximum length of certificate chains below this certificate (only for CA certificates, -1 is inlimited)
Returns
0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
int mbedtls_x509write_crt_set_extension ( mbedtls_x509write_cert ctx,
const char *  oid,
size_t  oid_len,
int  critical,
const unsigned char *  val,
size_t  val_len 
)

Generic function to add to or replace an extension in the CRT.

Parameters
ctxCRT context to use
oidOID of the extension
oid_lenlength of the OID
criticalif the extension is critical (per the RFC's definition)
valvalue of the extension OCTET STRING
val_lenlength of the value data
Returns
0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
void mbedtls_x509write_crt_set_issuer_key ( mbedtls_x509write_cert ctx,
mbedtls_pk_context key 
)

Set the issuer key used for signing the certificate.

Parameters
ctxCRT context to use
keyprivate key to sign with
int mbedtls_x509write_crt_set_issuer_name ( mbedtls_x509write_cert ctx,
const char *  issuer_name 
)

Set the issuer name for a Certificate Issuer names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=mbed TLS CA".

Parameters
ctxCRT context to use
issuer_nameissuer name to set
Returns
0 if issuer name was parsed successfully, or a specific error code
int mbedtls_x509write_crt_set_key_usage ( mbedtls_x509write_cert ctx,
unsigned int  key_usage 
)

Set the Key Usage Extension flags (e.g. MBEDTLS_X509_KU_DIGITAL_SIGNATURE | MBEDTLS_X509_KU_KEY_CERT_SIGN)

Parameters
ctxCRT context to use
key_usagekey usage flags to set
Returns
0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
void mbedtls_x509write_crt_set_md_alg ( mbedtls_x509write_cert ctx,
mbedtls_md_type_t  md_alg 
)

Set the MD algorithm to use for the signature (e.g. MBEDTLS_MD_SHA1)

Parameters
ctxCRT context to use
md_algMD algorithm to use
int mbedtls_x509write_crt_set_ns_cert_type ( mbedtls_x509write_cert ctx,
unsigned char  ns_cert_type 
)

Set the Netscape Cert Type flags (e.g. MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT | MBEDTLS_X509_NS_CERT_TYPE_EMAIL)

Parameters
ctxCRT context to use
ns_cert_typeNetscape Cert Type flags to set
Returns
0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
int mbedtls_x509write_crt_set_serial ( mbedtls_x509write_cert ctx,
const mbedtls_mpi serial 
)

Set the serial number for a Certificate.

Parameters
ctxCRT context to use
serialserial number to set
Returns
0 if successful
void mbedtls_x509write_crt_set_subject_key ( mbedtls_x509write_cert ctx,
mbedtls_pk_context key 
)

Set the subject public key for the certificate.

Parameters
ctxCRT context to use
keypublic key to include
int mbedtls_x509write_crt_set_subject_key_identifier ( mbedtls_x509write_cert ctx)

Set the subjectKeyIdentifier extension for a CRT Requires that mbedtls_x509write_crt_set_subject_key() has been called before.

Parameters
ctxCRT context to use
Returns
0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED
int mbedtls_x509write_crt_set_subject_name ( mbedtls_x509write_cert ctx,
const char *  subject_name 
)

Set the subject name for a Certificate Subject names should contain a comma-separated list of OID types and values: e.g. "C=UK,O=ARM,CN=mbed TLS Server 1".

Parameters
ctxCRT context to use
subject_namesubject name to set
Returns
0 if subject name was parsed successfully, or a specific error code
int mbedtls_x509write_crt_set_validity ( mbedtls_x509write_cert ctx,
const char *  not_before,
const char *  not_after 
)

Set the validity period for a Certificate Timestamps should be in string format for UTC timezone i.e. "YYYYMMDDhhmmss" e.g. "20131231235959" for December 31st 2013 at 23:59:59.

Parameters
ctxCRT context to use
not_beforenot_before timestamp
not_afternot_after timestamp
Returns
0 if timestamp was parsed successfully, or a specific error code
void mbedtls_x509write_crt_set_version ( mbedtls_x509write_cert ctx,
int  version 
)

Set the verion for a Certificate Default: MBEDTLS_X509_CRT_VERSION_3.

Parameters
ctxCRT context to use
versionversion to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or MBEDTLS_X509_CRT_VERSION_3)