mbed TLS v2.16.0: x509_crt.h File Reference

mbed TLS v2.16.0

Data Structures | Functions
x509_crt.h File Reference

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

`#include "config.h"`
`#include "x509.h"`
`#include "x509_crl.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_crt_profile
struct | mbedtls_x509write_cert
struct | mbedtls_x509_crt_verify_chain_item
struct | mbedtls_x509_crt_verify_chain

## 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_MAX_VERIFY_CHAIN_SIZE ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 )
typedef struct mbedtls_x509_crt | mbedtls_x509_crt
typedef struct mbedtls_x509_crt_profile | mbedtls_x509_crt_profile
typedef struct mbedtls_x509write_cert | mbedtls_x509write_cert
typedef void | mbedtls_x509_crt_restart_ctx
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
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 chained list. 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_crt_info (char *buf, size_t size, const char *prefix, const mbedtls_x509_crt *crt)
| Returns an informational string about the certificate. More...
int | mbedtls_x509_crt_verify_info (char *buf, size_t size, const char *prefix, uint32_t flags)
| Returns an informational string about the verification status of a certificate. 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 the certificate signature. 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 the certificate signature according to 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_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...

## Detailed Description

X.509 certificate parsing and writing.

Definition in file x509_crt.h.

## Function Documentation

## ◆ mbedtls_x509write_crt_der()

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

  ctx | certificate to write away
  buf | buffer to write to
  size | size of the buffer
  f_rng | RNG function (for signature, see note)
  p_rng | RNG parameter

Returns
  length of data written if successful, or a specific error code

Note
  f_rng may be NULL if RSA is used for signature and the signature is made offline (otherwise f_rng is desirable for countermeasures against timing attacks). ECDSA signatures always require a non-NULL f_rng.

## ◆ mbedtls_x509write_crt_free()

void mbedtls_x509write_crt_free | ( | mbedtls_x509write_cert * | ctx | ) |

Free the contents of a CRT write context.

Parameters

  ctx | CRT context to free

## ◆ mbedtls_x509write_crt_init()

void mbedtls_x509write_crt_init | ( | mbedtls_x509write_cert * | ctx | ) |

Initialize a CRT writing context.

Parameters

  ctx | CRT context to initialize

## ◆ mbedtls_x509write_crt_pem()

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

  ctx | certificate to write away
  buf | buffer to write to
  size | size of the buffer
  f_rng | RNG function (for signature, see note)
  p_rng | RNG parameter

Returns
  0 if successful, or a specific error code

Note
  f_rng may be NULL if RSA is used for signature and the signature is made offline (otherwise f_rng is desirable for countermeasures against timing attacks). ECDSA signatures always require a non-NULL f_rng.

## ◆ mbedtls_x509write_crt_set_authority_key_identifier()

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

  ctx | CRT context to use

Returns
  0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED

## ◆ mbedtls_x509write_crt_set_basic_constraints()

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

  ctx | CRT context to use
  is_ca | is this a CA certificate
  max_pathlen | maximum 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

## ◆ mbedtls_x509write_crt_set_extension()

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

  ctx | CRT context to use
  oid | OID of the extension
  oid_len | length of the OID
  critical | if the extension is critical (per the RFC's definition)
  val | value of the extension OCTET STRING
  val_len | length of the value data

Returns
  0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED

## ◆ mbedtls_x509write_crt_set_issuer_key()

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

  ctx | CRT context to use
  key | private key to sign with

## ◆ mbedtls_x509write_crt_set_issuer_name()

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

  ctx | CRT context to use
  issuer_name | issuer name to set

Returns
  0 if issuer name was parsed successfully, or a specific error code

## ◆ mbedtls_x509write_crt_set_key_usage()

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

  ctx | CRT context to use
  key_usage | key usage flags to set

Returns
  0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED

## ◆ mbedtls_x509write_crt_set_md_alg()

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

  ctx | CRT context to use
  md_alg | MD algorithm to use

## ◆ mbedtls_x509write_crt_set_ns_cert_type()

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

  ctx | CRT context to use
  ns_cert_type | Netscape Cert Type flags to set

Returns
  0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED

## ◆ mbedtls_x509write_crt_set_serial()

int mbedtls_x509write_crt_set_serial | ( | mbedtls_x509write_cert * | ctx,
|  | const mbedtls_mpi * | serial
| ) |  |

Set the serial number for a Certificate.

Parameters

  ctx | CRT context to use
  serial | serial number to set

Returns
  0 if successful

## ◆ mbedtls_x509write_crt_set_subject_key()

void mbedtls_x509write_crt_set_subject_key | ( | mbedtls_x509write_cert * | ctx,
|  | mbedtls_pk_context * | key
| ) |  |

Set the subject public key for the certificate.

Parameters

  ctx | CRT context to use
  key | public key to include

## ◆ mbedtls_x509write_crt_set_subject_key_identifier()

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

  ctx | CRT context to use

Returns
  0 if successful, or a MBEDTLS_ERR_X509_ALLOC_FAILED

## ◆ mbedtls_x509write_crt_set_subject_name()

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

  ctx | CRT context to use
  subject_name | subject name to set

Returns
  0 if subject name was parsed successfully, or a specific error code

## ◆ mbedtls_x509write_crt_set_validity()

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

  ctx | CRT context to use
  not_before | not_before timestamp
  not_after | not_after timestamp

Returns
  0 if timestamp was parsed successfully, or a specific error code

## ◆ mbedtls_x509write_crt_set_version()

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

  ctx | CRT context to use
  version | version to set (MBEDTLS_X509_CRT_VERSION_1, MBEDTLS_X509_CRT_VERSION_2 or MBEDTLS_X509_CRT_VERSION_3)