File x509.h

X.509 generic defines and structures.

X509 Error codes

MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE: Unavailable feature, e.g. RSA hashing/encryption combination.

MBEDTLS_ERR_X509_UNKNOWN_OID: Requested OID is unknown.

MBEDTLS_ERR_X509_INVALID_FORMAT: The CRT/CRL/CSR format is invalid, e.g. different type expected.

MBEDTLS_ERR_X509_INVALID_VERSION: The CRT/CRL/CSR version element is invalid.

MBEDTLS_ERR_X509_INVALID_SERIAL: The serial tag or value is invalid.

MBEDTLS_ERR_X509_INVALID_ALG: The algorithm tag or value is invalid.

MBEDTLS_ERR_X509_INVALID_NAME: The name tag or value is invalid.

MBEDTLS_ERR_X509_INVALID_DATE: The date tag or value is invalid.

MBEDTLS_ERR_X509_INVALID_SIGNATURE: The signature tag or value invalid.

MBEDTLS_ERR_X509_INVALID_EXTENSIONS: The extension tag or value is invalid.

MBEDTLS_ERR_X509_UNKNOWN_VERSION: CRT/CRL/CSR has an unsupported version number.

MBEDTLS_ERR_X509_UNKNOWN_SIG_ALG: Signature algorithm (oid) is unsupported.

MBEDTLS_ERR_X509_SIG_MISMATCH: Signature algorithms do not match. (see mbedtls_x509_crt sig_oid)

MBEDTLS_ERR_X509_CERT_VERIFY_FAILED: Certificate verification failed, e.g. CRL, CA or signature check failed.

MBEDTLS_ERR_X509_CERT_UNKNOWN_FORMAT: Format not recognized as DER or PEM.

MBEDTLS_ERR_X509_BAD_INPUT_DATA: Input invalid.

MBEDTLS_ERR_X509_ALLOC_FAILED: Allocation of memory failed.

MBEDTLS_ERR_X509_FILE_IO_ERROR: Read/write of file failed.

MBEDTLS_ERR_X509_BUFFER_TOO_SMALL: Destination buffer is too small.

MBEDTLS_ERR_X509_FATAL_ERROR: A fatal error occurred, eg the chain is too long or the vrfy callback failed.

X509 Verify codes

MBEDTLS_X509_BADCERT_EXPIRED: The certificate validity has expired.

MBEDTLS_X509_BADCERT_REVOKED: The certificate has been revoked (is on a CRL).

MBEDTLS_X509_BADCERT_CN_MISMATCH: The certificate Common Name (CN) does not match with the expected CN.

MBEDTLS_X509_BADCERT_NOT_TRUSTED: The certificate is not correctly signed by the trusted CA.

MBEDTLS_X509_BADCRL_NOT_TRUSTED: The CRL is not correctly signed by the trusted CA.

MBEDTLS_X509_BADCRL_EXPIRED: The CRL is expired.

MBEDTLS_X509_BADCERT_MISSING: Certificate was missing.

MBEDTLS_X509_BADCERT_SKIP_VERIFY: Certificate verification was skipped.

MBEDTLS_X509_BADCERT_OTHER: Other reason (can be used by verify callback)

MBEDTLS_X509_BADCERT_FUTURE: The certificate validity starts in the future.

MBEDTLS_X509_BADCRL_FUTURE: The CRL is from the future

MBEDTLS_X509_BADCERT_KEY_USAGE: Usage does not match the keyUsage extension.

MBEDTLS_X509_BADCERT_EXT_KEY_USAGE: Usage does not match the extendedKeyUsage extension.

MBEDTLS_X509_BADCERT_NS_CERT_TYPE: Usage does not match the nsCertType extension.

MBEDTLS_X509_BADCERT_BAD_MD: The certificate is signed with an unacceptable hash.

MBEDTLS_X509_BADCERT_BAD_PK: The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).

MBEDTLS_X509_BADCERT_BAD_KEY: The certificate is signed with an unacceptable key (eg bad curve, RSA too short).

MBEDTLS_X509_BADCRL_BAD_MD: The CRL is signed with an unacceptable hash.

MBEDTLS_X509_BADCRL_BAD_PK: The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).

MBEDTLS_X509_BADCRL_BAD_KEY: The CRL is signed with an unacceptable key (eg bad curve, RSA too short).

Structures for parsing X.509 certificates, CRLs and CSRs

typedef mbedtls_asn1_buf mbedtls_x509_buf: Type-length-value structure that allows for ASN1 using DER.

typedef mbedtls_asn1_bitstring mbedtls_x509_bitstring: Container for ASN1 bit strings.

typedef mbedtls_asn1_named_data mbedtls_x509_name: Container for ASN1 named information objects. It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).

typedef mbedtls_asn1_sequence mbedtls_x509_sequence: Container for a sequence of ASN.1 items

typedef struct mbedtls_x509_authority mbedtls_x509_authority

typedef struct mbedtls_x509_time mbedtls_x509_time: Container for date and time (precision in seconds).

typedef struct mbedtls_x509_san_other_name mbedtls_x509_san_other_name

From RFC 5280 section 4.2.1.6: OtherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY DEFINED BY type-id }

Future versions of the library may add new fields to this structure or to its embedded union and structure.

typedef struct mbedtls_x509_subject_alternative_name mbedtls_x509_subject_alternative_name

A structure for holding the parsed Subject Alternative Name, according to type.

Future versions of the library may add new fields to this structure or to its embedded union and structure.

typedef struct mbedtls_x509_san_list mbedtls_x509_san_list

Defines

MBEDTLS_X509_MAX_INTERMEDIATE_CA

Maximum number of intermediate CAs in a verification chain. That is, maximum length of the chain, excluding the end-entity certificate and the trusted root certificate.

Set this to a low value to prevent an adversary from making you waste resources verifying an overlong certificate chain.

MBEDTLS_X509_SAN_OTHER_NAME

MBEDTLS_X509_SAN_RFC822_NAME

MBEDTLS_X509_SAN_DNS_NAME

MBEDTLS_X509_SAN_X400_ADDRESS_NAME

MBEDTLS_X509_SAN_DIRECTORY_NAME

MBEDTLS_X509_SAN_EDI_PARTY_NAME

MBEDTLS_X509_SAN_UNIFORM_RESOURCE_IDENTIFIER

MBEDTLS_X509_SAN_IP_ADDRESS

MBEDTLS_X509_SAN_REGISTERED_ID

MBEDTLS_X509_KU_DIGITAL_SIGNATURE

MBEDTLS_X509_KU_NON_REPUDIATION

MBEDTLS_X509_KU_KEY_ENCIPHERMENT

MBEDTLS_X509_KU_DATA_ENCIPHERMENT

MBEDTLS_X509_KU_KEY_AGREEMENT

MBEDTLS_X509_KU_KEY_CERT_SIGN

MBEDTLS_X509_KU_CRL_SIGN

MBEDTLS_X509_KU_ENCIPHER_ONLY

MBEDTLS_X509_KU_DECIPHER_ONLY

MBEDTLS_X509_NS_CERT_TYPE_SSL_CLIENT

MBEDTLS_X509_NS_CERT_TYPE_SSL_SERVER

MBEDTLS_X509_NS_CERT_TYPE_EMAIL

MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING

MBEDTLS_X509_NS_CERT_TYPE_RESERVED

MBEDTLS_X509_NS_CERT_TYPE_SSL_CA

MBEDTLS_X509_NS_CERT_TYPE_EMAIL_CA

MBEDTLS_X509_NS_CERT_TYPE_OBJECT_SIGNING_CA

MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER

MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER

MBEDTLS_X509_EXT_KEY_USAGE

MBEDTLS_X509_EXT_CERTIFICATE_POLICIES

MBEDTLS_X509_EXT_POLICY_MAPPINGS

MBEDTLS_X509_EXT_SUBJECT_ALT_NAME

MBEDTLS_X509_EXT_ISSUER_ALT_NAME

MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS

MBEDTLS_X509_EXT_BASIC_CONSTRAINTS

MBEDTLS_X509_EXT_NAME_CONSTRAINTS

MBEDTLS_X509_EXT_POLICY_CONSTRAINTS

MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE

MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS

MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY

MBEDTLS_X509_EXT_FRESHEST_CRL

MBEDTLS_X509_EXT_NS_CERT_TYPE

MBEDTLS_X509_FORMAT_DER

MBEDTLS_X509_FORMAT_PEM

MBEDTLS_X509_MAX_DN_NAME_SIZE: Maximum value size of a DN entry

MBEDTLS_X509_SAFE_SNPRINTF

Functions

int mbedtls_x509_dn_gets(char *buf, size_t size, const mbedtls_x509_name *dn)

Store the certificate DN in printable form into buf; no more than size characters will be written.

Parameters

buf – Buffer to write to
size – Maximum size of buffer
dn – The X509 name to represent

Returns

The length of the string written (not including the terminated nul byte), or a negative error code.

int mbedtls_x509_string_to_names(mbedtls_asn1_named_data **head, const char *name)

Convert the certificate DN string name into a linked list of mbedtls_x509_name (equivalent to mbedtls_asn1_named_data).

Note

This function allocates a linked list, and places the head pointer in head. This list must later be freed by a call to mbedtls_asn1_free_named_data_list().

Parameters

head – [out] Address in which to store the pointer to the head of the allocated list of mbedtls_x509_name
name – [in] The string representation of a DN to convert

Returns

0 on success, or a negative error code.

static inline mbedtls_x509_name *mbedtls_x509_dn_get_next(mbedtls_x509_name *dn)

Return the next relative DN in an X509 name.

Note

Intended use is to compare function result to dn->next in order to detect boundaries of multi-valued RDNs.

Parameters: dn – Current node in the X509 name
Returns: Pointer to the first attribute-value pair of the next RDN in sequence, or NULL if end is reached.

int mbedtls_x509_serial_gets(char *buf, size_t size, const mbedtls_x509_buf *serial)

Store the certificate serial in printable form into buf; no more than size characters will be written.

Parameters

buf – Buffer to write to
size – Maximum size of buffer
serial – The X509 serial to represent

Returns

The length of the string written (not including the terminated nul byte), or a negative error code.

int mbedtls_x509_time_cmp(const mbedtls_x509_time *t1, const mbedtls_x509_time *t2)

Compare pair of mbedtls_x509_time.

Parameters

t1 – mbedtls_x509_time to compare
t2 – mbedtls_x509_time to compare

Returns

< 0 if t1 is before t2 0 if t1 equals t2 > 0 if t1 is after t2

int mbedtls_x509_time_gmtime(mbedtls_time_t tt, mbedtls_x509_time *now)

Fill mbedtls_x509_time with provided mbedtls_time_t.

Parameters

tt – mbedtls_time_t to convert
now – mbedtls_x509_time to fill with converted mbedtls_time_t

Returns

0 on success

Returns

A non-zero return value on failure.

int mbedtls_x509_time_is_past(const mbedtls_x509_time *to)

Check a given mbedtls_x509_time against the system time and tell if it’s in the past.

Note

Intended usage is “if( is_past( valid_to ) ) ERROR”. Hence the return value of 1 if on internal errors.

Parameters: to – mbedtls_x509_time to check
Returns: 1 if the given time is in the past or an error occurred, 0 otherwise.

int mbedtls_x509_time_is_future(const mbedtls_x509_time *from)

Check a given mbedtls_x509_time against the system time and tell if it’s in the future.

Note

Intended usage is “if( is_future( valid_from ) ) ERROR”. Hence the return value of 1 if on internal errors.

Parameters: from – mbedtls_x509_time to check
Returns: 1 if the given time is in the future or an error occurred, 0 otherwise.

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. Please note that this function might allocate additional memory for a subject alternative name, thus mbedtls_x509_free_subject_alt_name has to be called to dispose of this additional memory afterwards.

Note

Supported GeneralName types, as defined in RFC 5280: “rfc822Name”, “dnsName”, “directoryName”, “uniformResourceIdentifier” and “hardware_module_name” of type “otherName”, as defined in RFC 4108.

Note

This function should be called on a single raw data of subject alternative name. For example, after successful certificate parsing, one must iterate on every item in the crt->subject_alt_names sequence, and pass it to this function.

Warning

The target structure contains pointers to the raw data of the parsed certificate, and its lifetime is restricted by the lifetime of the certificate.

Parameters

san_buf – The buffer holding the raw data item of the subject alternative name.
san – The target structure to populate with the parsed presentation of the subject alternative name encoded in san_buf.

Returns

0 on success

Returns

MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE for an unsupported SAN type.

Returns

Another negative value for any other failure.

void mbedtls_x509_free_subject_alt_name(mbedtls_x509_subject_alternative_name *san)

Unallocate all data related to subject alternative name.

Parameters: san – SAN structure - extra memory owned by this structure will be freed

size_t mbedtls_x509_crt_parse_cn_inet_pton(const char *cn, void *dst)

This function parses a CN string as an IP address.

Note

cn is parsed as an IPv6 address if string contains ‘:’, else cn is parsed as an IPv4 address.

Parameters

cn – The CN string to parse. CN string MUST be null-terminated.
dst – The target buffer to populate with the binary IP address. The buffer MUST be 16 bytes to save IPv6, and should be 4-byte aligned if the result will be used as struct in_addr. e.g. uint32_t dst[4]

Returns

Length of binary IP address; num bytes written to target.

Returns

0 on failure to parse CN string as an IP address.

struct mbedtls_x509_authority

#include <x509.h>

Public Members

mbedtls_x509_buf keyIdentifier

mbedtls_x509_sequence authorityCertIssuer

mbedtls_x509_buf authorityCertSerialNumber

mbedtls_x509_buf raw

struct mbedtls_x509_time

#include <x509.h>

Container for date and time (precision in seconds).

Public Members

int year

int mon

int day: Date.

int hour

int min

int sec: Time.

struct mbedtls_x509_san_other_name

#include <x509.h>

From RFC 5280 section 4.2.1.6: OtherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY DEFINED BY type-id }

Future versions of the library may add new fields to this structure or to its embedded union and structure.

Public Members

mbedtls_x509_buf type_id: The type_id is an OID as defined in RFC 5280. To check the value of the type id, you should use MBEDTLS_OID_CMP with a known OID mbedtls_x509_buf. The type id.

mbedtls_x509_buf oid: The object identifier.

mbedtls_x509_buf val: The named value.

struct mbedtls_x509_san_other_name::[anonymous]::[anonymous] hardware_module_name: From RFC 4108 section 5: HardwareModuleName ::= SEQUENCE { hwType OBJECT IDENTIFIER, hwSerialNum OCTET STRING }

union mbedtls_x509_san_other_name::[anonymous] value

struct mbedtls_x509_subject_alternative_name

#include <x509.h>

A structure for holding the parsed Subject Alternative Name, according to type.

Future versions of the library may add new fields to this structure or to its embedded union and structure.

Public Members

int type: The SAN type, value of MBEDTLS_X509_SAN_XXX.

mbedtls_x509_san_other_name other_name

mbedtls_x509_name directory_name

mbedtls_x509_buf unstructured_name: The buffer for the unstructured types. rfc822Name, dnsName and uniformResourceIdentifier are currently supported.

union mbedtls_x509_subject_alternative_name::[anonymous] san: A union of the supported SAN types

struct mbedtls_x509_san_list

#include <x509.h>

Public Members

mbedtls_x509_subject_alternative_name node

struct mbedtls_x509_san_list *next