X.509 module#
The X.509 module provides X.509 support for reading, writing and verification of certificates.
In summary:
X.509 certificate (CRT) reading (see
mbedtls_x509_crt_parse(),mbedtls_x509_crt_parse_der(),mbedtls_x509_crt_parse_file()).X.509 certificate revocation list (CRL) reading (see
mbedtls_x509_crl_parse(),mbedtls_x509_crl_parse_der(), andmbedtls_x509_crl_parse_file()).X.509 certificate signature verification (see
mbedtls_x509_crt_verify()andmbedtls_x509_crt_verify_with_profile().X.509 certificate writing and certificate request writing (see
mbedtls_x509write_crt_der()andmbedtls_x509write_csr_der()).
This module can be used to build a certificate authority (CA) chain and verify its signature. It is also used to generate Certificate Signing Requests and X.509 certificates just as a CA would do.
Modules#
mbedtls_x509_subject_alternative_name
mbedtls_x509_crt_verify_chain_item
Structures for parsing X.509 certificates, CRLs and CSRs#
Type-length-value structure that allows for ASN1 using DER.
Container for ASN1 bit strings.
Container for ASN1 named information objects.
Container for a sequence of ASN.1 items.
Structures and functions for parsing and writing X.509 certificates#
Query certificate for given extension type.
Build flag from an algorithm/curve identifier (pk, md, ecp) Since 0 is always XXX_NONE, ignore it.
Max size of verification chain: end-entity + intermediates + trusted root.
Structures and functions for parsing CRLs#
Parse a DER-encoded CRL and append it to the chained list.
Parse one or more CRLs and append them to the chained list.
Returns an informational string about the CRL.
Initialize a CRL (chain)
Unallocate all CRL data.
X509 Error codes#
Unavailable feature, e.g.
Requested OID is unknown.
The CRT/CRL/CSR format is invalid, e.g.
The CRT/CRL/CSR version element is invalid.
The serial tag or value is invalid.
The algorithm tag or value is invalid.
The name tag or value is invalid.
The date tag or value is invalid.
The signature tag or value invalid.
The extension tag or value is invalid.
CRT/CRL/CSR has an unsupported version number.
Signature algorithm (oid) is unsupported.
Signature algorithms do not match.
Certificate verification failed, e.g.
Format not recognized as DER or PEM.
Input invalid.
Allocation of memory failed.
Read/write of file failed.
Destination buffer is too small.
A fatal error occurred, eg the chain is too long or the vrfy callback failed.
X509 Verify codes#
The certificate validity has expired.
The certificate has been revoked (is on a CRL).
The certificate Common Name (CN) does not match with the expected CN.
The certificate is not correctly signed by the trusted CA.
The CRL is not correctly signed by the trusted CA.
The CRL is expired.
Certificate was missing.
Certificate verification was skipped.
Other reason (can be used by verify callback)
The certificate validity starts in the future.
The CRL is from the future.
Usage does not match the keyUsage extension.
Usage does not match the extendedKeyUsage extension.
Usage does not match the nsCertType extension.
The certificate is signed with an unacceptable hash.
The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).
The certificate is signed with an unacceptable key (eg bad curve, RSA too short).
The CRL is signed with an unacceptable hash.
The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).
The CRL is signed with an unacceptable key (eg bad curve, RSA too short).
Functions#
Store the certificate DN in printable form into buf; no more than size characters will be written.
Return the next relative DN in an X509 name.
Store the certificate serial in printable form into buf; no more than size characters will be written.
Check a given mbedtls_x509_time against the system time and tell if it's in the past.
Check a given mbedtls_x509_time against the system time and tell if it's in the future.
Macros#
Maximum number of intermediate CAs in a verification chain.
Structures for parsing X.509 certificates, CRLs and CSRs Documentation#
mbedtls_x509_buf#
typedef mbedtls_asn1_buf mbedtls_x509_buf
Type-length-value structure that allows for ASN1 using DER.
mbedtls_x509_bitstring#
typedef mbedtls_asn1_bitstring mbedtls_x509_bitstring
Container for ASN1 bit strings.
mbedtls_x509_name#
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.).
mbedtls_x509_sequence#
typedef mbedtls_asn1_sequence mbedtls_x509_sequence
Container for a sequence of ASN.1 items.
Structures and functions for parsing and writing X.509 certificates Documentation#
mbedtls_x509_crt_has_ext_type#
static int mbedtls_x509_crt_has_ext_type (const mbedtls_x509_crt * ctx, int ext_type)
Query certificate for given extension type.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const mbedtls_x509_crt * | [in] | ctx | Certificate context to be queried, must not be |
| int | N/A | ext_type | Extension type being queried for, must be a valid extension type. Must be one of the MBEDTLS_X509_EXT_XXX values |
Returns
0 if the given extension type is not present, non-zero otherwise
Structures and functions for parsing CRLs Documentation#
mbedtls_x509_crl_parse_der#
int mbedtls_x509_crl_parse_der (mbedtls_x509_crl * chain, const unsigned char * buf, size_t buflen)
Parse a DER-encoded CRL and append it to the chained list.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| mbedtls_x509_crl * | N/A | chain | points to the start of the chain |
| const unsigned char * | N/A | buf | buffer holding the CRL data in DER format |
| size_t | N/A | buflen | size of the buffer (including the terminating null byte for PEM data) |
Returns
0 if successful, or a specific X509 or PEM error code
mbedtls_x509_crl_parse#
int mbedtls_x509_crl_parse (mbedtls_x509_crl * chain, const unsigned char * buf, size_t buflen)
Parse one or more CRLs and append them to the chained list.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| mbedtls_x509_crl * | N/A | chain | points to the start of the chain |
| const unsigned char * | N/A | buf | buffer holding the CRL data in PEM or DER format |
| size_t | N/A | buflen | size of the buffer (including the terminating null byte for PEM data) |
Note
Multiple CRLs are accepted only if using PEM format
Returns
0 if successful, or a specific X509 or PEM error code
mbedtls_x509_crl_info#
int mbedtls_x509_crl_info (char * buf, size_t size, const char * prefix, const mbedtls_x509_crl * crl)
Returns an informational string about the CRL.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| char * | N/A | buf | Buffer to write to |
| size_t | N/A | size | Maximum size of buffer |
| const char * | N/A | prefix | A line prefix |
| const mbedtls_x509_crl * | N/A | crl | The X509 CRL to represent |
Returns
The length of the string written (not including the terminated nul byte), or a negative error code.
mbedtls_x509_crl_init#
void mbedtls_x509_crl_init (mbedtls_x509_crl * crl)
Initialize a CRL (chain)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| mbedtls_x509_crl * | N/A | crl | CRL chain to initialize |
mbedtls_x509_crl_free#
void mbedtls_x509_crl_free (mbedtls_x509_crl * crl)
Unallocate all CRL data.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| mbedtls_x509_crl * | N/A | crl | CRL chain to free |
X509 Error codes Documentation#
X509 Verify codes Documentation#
Function Documentation#
mbedtls_x509_dn_gets#
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| char * | N/A | buf | Buffer to write to |
| size_t | N/A | size | Maximum size of buffer |
| const mbedtls_x509_name * | N/A | dn | The X509 name to represent |
Returns
The length of the string written (not including the terminated nul byte), or a negative error code.
mbedtls_x509_dn_get_next#
static mbedtls_x509_name * mbedtls_x509_dn_get_next (mbedtls_x509_name * dn)
Return the next relative DN in an X509 name.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| mbedtls_x509_name * | N/A | dn | Current node in the X509 name |
Note
Intended use is to compare function result to dn->next in order to detect boundaries of multi-valued RDNs.
Returns
Pointer to the first attribute-value pair of the next RDN in sequence, or NULL if end is reached.
mbedtls_x509_serial_gets#
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| char * | N/A | buf | Buffer to write to |
| size_t | N/A | size | Maximum size of buffer |
| const mbedtls_x509_buf * | N/A | serial | The X509 serial to represent |
Returns
The length of the string written (not including the terminated nul byte), or a negative error code.
mbedtls_x509_time_is_past#
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const mbedtls_x509_time * | N/A | to | mbedtls_x509_time to check |
Note
Intended usage is "if( is_past( valid_to ) ) ERROR". Hence the return value of 1 if on internal errors.
Returns
1 if the given time is in the past or an error occurred, 0 otherwise.
mbedtls_x509_time_is_future#
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const mbedtls_x509_time * | N/A | from | mbedtls_x509_time to check |
Note
Intended usage is "if( is_future( valid_from ) ) ERROR". Hence the return value of 1 if on internal errors.
Returns
1 if the given time is in the future or an error occurred, 0 otherwise.