X.509 module
Detailed Description
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.
Data Structures | |
struct | mbedtls_x509_time |
struct | mbedtls_x509_crl_entry |
struct | mbedtls_x509_crl |
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_csr |
struct | mbedtls_x509write_csr |
Macros | |
#define | MBEDTLS_X509_MAX_INTERMEDIATE_CA 8 |
X509 Error codes | |
#define | MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE -0x2080 |
#define | MBEDTLS_ERR_X509_UNKNOWN_OID -0x2100 |
#define | MBEDTLS_ERR_X509_INVALID_FORMAT -0x2180 |
#define | MBEDTLS_ERR_X509_INVALID_VERSION -0x2200 |
#define | MBEDTLS_ERR_X509_INVALID_SERIAL -0x2280 |
#define | MBEDTLS_ERR_X509_INVALID_ALG -0x2300 |
#define | MBEDTLS_ERR_X509_INVALID_NAME -0x2380 |
#define | MBEDTLS_ERR_X509_INVALID_DATE -0x2400 |
#define | MBEDTLS_ERR_X509_INVALID_SIGNATURE -0x2480 |
#define | MBEDTLS_ERR_X509_INVALID_EXTENSIONS -0x2500 |
#define | MBEDTLS_ERR_X509_UNKNOWN_VERSION -0x2580 |
#define | MBEDTLS_ERR_X509_UNKNOWN_SIG_ALG -0x2600 |
#define | MBEDTLS_ERR_X509_SIG_MISMATCH -0x2680 |
#define | MBEDTLS_ERR_X509_CERT_VERIFY_FAILED -0x2700 |
#define | MBEDTLS_ERR_X509_CERT_UNKNOWN_FORMAT -0x2780 |
#define | MBEDTLS_ERR_X509_BAD_INPUT_DATA -0x2800 |
#define | MBEDTLS_ERR_X509_ALLOC_FAILED -0x2880 |
#define | MBEDTLS_ERR_X509_FILE_IO_ERROR -0x2900 |
#define | MBEDTLS_ERR_X509_BUFFER_TOO_SMALL -0x2980 |
#define | MBEDTLS_ERR_X509_FATAL_ERROR -0x3000 |
X509 Verify codes | |
#define | MBEDTLS_X509_BADCERT_EXPIRED 0x01 |
#define | MBEDTLS_X509_BADCERT_REVOKED 0x02 |
#define | MBEDTLS_X509_BADCERT_CN_MISMATCH 0x04 |
#define | MBEDTLS_X509_BADCERT_NOT_TRUSTED 0x08 |
#define | MBEDTLS_X509_BADCRL_NOT_TRUSTED 0x10 |
#define | MBEDTLS_X509_BADCRL_EXPIRED 0x20 |
#define | MBEDTLS_X509_BADCERT_MISSING 0x40 |
#define | MBEDTLS_X509_BADCERT_SKIP_VERIFY 0x80 |
#define | MBEDTLS_X509_BADCERT_OTHER 0x0100 |
#define | MBEDTLS_X509_BADCERT_FUTURE 0x0200 |
#define | MBEDTLS_X509_BADCRL_FUTURE 0x0400 |
#define | MBEDTLS_X509_BADCERT_KEY_USAGE 0x0800 |
#define | MBEDTLS_X509_BADCERT_EXT_KEY_USAGE 0x1000 |
#define | MBEDTLS_X509_BADCERT_NS_CERT_TYPE 0x2000 |
#define | MBEDTLS_X509_BADCERT_BAD_MD 0x4000 |
#define | MBEDTLS_X509_BADCERT_BAD_PK 0x8000 |
#define | MBEDTLS_X509_BADCERT_BAD_KEY 0x010000 |
#define | MBEDTLS_X509_BADCRL_BAD_MD 0x020000 |
#define | MBEDTLS_X509_BADCRL_BAD_PK 0x040000 |
#define | MBEDTLS_X509_BADCRL_BAD_KEY 0x080000 |
Structures for parsing X.509 certificates, CRLs and CSRs | |
typedef mbedtls_asn1_buf | mbedtls_x509_buf |
typedef mbedtls_asn1_bitstring | mbedtls_x509_bitstring |
typedef mbedtls_asn1_named_data | mbedtls_x509_name |
typedef mbedtls_asn1_sequence | mbedtls_x509_sequence |
typedef struct mbedtls_x509_time | mbedtls_x509_time |
Structures and functions for parsing CRLs | |
typedef struct mbedtls_x509_crl_entry | mbedtls_x509_crl_entry |
typedef struct mbedtls_x509_crl | mbedtls_x509_crl |
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. | |
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. | |
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. | |
void | mbedtls_x509_crl_init (mbedtls_x509_crl *crl) |
Initialize a CRL (chain) | |
void | mbedtls_x509_crl_free (mbedtls_x509_crl *crl) |
Unallocate all CRL data. | |
Structures and functions for parsing and writing X.509 certificates | |
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 void | mbedtls_x509_crt_restart_ctx |
#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 ) |
Structures and functions for X.509 Certificate Signing Requests (CSR) | |
typedef struct mbedtls_x509_csr | mbedtls_x509_csr |
typedef struct mbedtls_x509write_csr | mbedtls_x509write_csr |
Macro Definition Documentation
#define MBEDTLS_ERR_X509_ALLOC_FAILED -0x2880 |
Allocation of memory failed.
Definition at line 75
of file x509.h
.
#define MBEDTLS_ERR_X509_BAD_INPUT_DATA -0x2800 |
Input invalid.
Definition at line 74
of file x509.h
.
#define MBEDTLS_ERR_X509_BUFFER_TOO_SMALL -0x2980 |
Destination buffer is too small.
Definition at line 77
of file x509.h
.
#define MBEDTLS_ERR_X509_CERT_UNKNOWN_FORMAT -0x2780 |
Format not recognized as DER or PEM.
Definition at line 73
of file x509.h
.
#define MBEDTLS_ERR_X509_CERT_VERIFY_FAILED -0x2700 |
Certificate verification failed, e.g. CRL, CA or signature check failed.
Definition at line 72
of file x509.h
.
#define MBEDTLS_ERR_X509_FATAL_ERROR -0x3000 |
A fatal error occurred, eg the chain is too long or the vrfy callback failed.
Definition at line 78
of file x509.h
.
#define MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE -0x2080 |
Unavailable feature, e.g. RSA hashing/encryption combination.
Definition at line 59
of file x509.h
.
#define MBEDTLS_ERR_X509_FILE_IO_ERROR -0x2900 |
Read/write of file failed.
Definition at line 76
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_ALG -0x2300 |
The algorithm tag or value is invalid.
Definition at line 64
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_DATE -0x2400 |
The date tag or value is invalid.
Definition at line 66
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_EXTENSIONS -0x2500 |
The extension tag or value is invalid.
Definition at line 68
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_FORMAT -0x2180 |
The CRT/CRL/CSR format is invalid, e.g. different type expected.
Definition at line 61
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_NAME -0x2380 |
The name tag or value is invalid.
Definition at line 65
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_SERIAL -0x2280 |
The serial tag or value is invalid.
Definition at line 63
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_SIGNATURE -0x2480 |
The signature tag or value invalid.
Definition at line 67
of file x509.h
.
#define MBEDTLS_ERR_X509_INVALID_VERSION -0x2200 |
The CRT/CRL/CSR version element is invalid.
Definition at line 62
of file x509.h
.
#define MBEDTLS_ERR_X509_SIG_MISMATCH -0x2680 |
Signature algorithms do not match. (see mbedtls_x509_crt
sig_oid)
Definition at line 71
of file x509.h
.
#define MBEDTLS_ERR_X509_UNKNOWN_OID -0x2100 |
Requested OID is unknown.
Definition at line 60
of file x509.h
.
#define MBEDTLS_ERR_X509_UNKNOWN_SIG_ALG -0x2600 |
Signature algorithm (oid) is unsupported.
Definition at line 70
of file x509.h
.
#define MBEDTLS_ERR_X509_UNKNOWN_VERSION -0x2580 |
CRT/CRL/CSR has an unsupported version number.
Definition at line 69
of file x509.h
.
#define MBEDTLS_X509_BADCERT_BAD_KEY 0x010000 |
The certificate is signed with an unacceptable key (eg bad curve, RSA too short).
Definition at line 102
of file x509.h
.
#define MBEDTLS_X509_BADCERT_BAD_MD 0x4000 |
The certificate is signed with an unacceptable hash.
Definition at line 100
of file x509.h
.
#define MBEDTLS_X509_BADCERT_BAD_PK 0x8000 |
The certificate is signed with an unacceptable PK alg (eg RSA vs ECDSA).
Definition at line 101
of file x509.h
.
#define MBEDTLS_X509_BADCERT_CN_MISMATCH 0x04 |
The certificate Common Name (CN) does not match with the expected CN.
Definition at line 88
of file x509.h
.
#define MBEDTLS_X509_BADCERT_EXPIRED 0x01 |
The certificate validity has expired.
Definition at line 86
of file x509.h
.
#define MBEDTLS_X509_BADCERT_EXT_KEY_USAGE 0x1000 |
Usage does not match the extendedKeyUsage extension.
Definition at line 98
of file x509.h
.
#define MBEDTLS_X509_BADCERT_FUTURE 0x0200 |
The certificate validity starts in the future.
Definition at line 95
of file x509.h
.
#define MBEDTLS_X509_BADCERT_KEY_USAGE 0x0800 |
Usage does not match the keyUsage extension.
Definition at line 97
of file x509.h
.
#define MBEDTLS_X509_BADCERT_MISSING 0x40 |
Certificate was missing.
Definition at line 92
of file x509.h
.
#define MBEDTLS_X509_BADCERT_NOT_TRUSTED 0x08 |
The certificate is not correctly signed by the trusted CA.
Definition at line 89
of file x509.h
.
#define MBEDTLS_X509_BADCERT_NS_CERT_TYPE 0x2000 |
Usage does not match the nsCertType extension.
Definition at line 99
of file x509.h
.
#define MBEDTLS_X509_BADCERT_OTHER 0x0100 |
Other reason (can be used by verify callback)
Definition at line 94
of file x509.h
.
#define MBEDTLS_X509_BADCERT_REVOKED 0x02 |
The certificate has been revoked (is on a CRL).
Definition at line 87
of file x509.h
.
#define MBEDTLS_X509_BADCERT_SKIP_VERIFY 0x80 |
Certificate verification was skipped.
Definition at line 93
of file x509.h
.
#define MBEDTLS_X509_BADCRL_BAD_KEY 0x080000 |
The CRL is signed with an unacceptable key (eg bad curve, RSA too short).
Definition at line 105
of file x509.h
.
#define MBEDTLS_X509_BADCRL_BAD_MD 0x020000 |
The CRL is signed with an unacceptable hash.
Definition at line 103
of file x509.h
.
#define MBEDTLS_X509_BADCRL_BAD_PK 0x040000 |
The CRL is signed with an unacceptable PK alg (eg RSA vs ECDSA).
Definition at line 104
of file x509.h
.
#define MBEDTLS_X509_BADCRL_EXPIRED 0x20 |
The CRL is expired.
Definition at line 91
of file x509.h
.
#define MBEDTLS_X509_BADCRL_FUTURE 0x0400 |
The CRL is from the future
Definition at line 96
of file x509.h
.
#define MBEDTLS_X509_BADCRL_NOT_TRUSTED 0x10 |
The CRL is not correctly signed by the trusted CA.
Definition at line 90
of file x509.h
.
#define MBEDTLS_X509_CRT_VERSION_1 0 |
Definition at line 168
of file x509_crt.h
.
#define MBEDTLS_X509_CRT_VERSION_2 1 |
Definition at line 169
of file x509_crt.h
.
#define MBEDTLS_X509_CRT_VERSION_3 2 |
Definition at line 170
of file x509_crt.h
.
#define MBEDTLS_X509_ID_FLAG | ( | id | ) | ( 1 << ( (id) - 1 ) ) |
Build flag from an algorithm/curve identifier (pk, md, ecp) Since 0 is always XXX_NONE, ignore it.
Definition at line 152
of file x509_crt.h
.
#define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 |
Definition at line 176
of file x509_crt.h
.
#define MBEDTLS_X509_MAX_INTERMEDIATE_CA 8 |
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.
Definition at line 52
of file x509.h
.
#define MBEDTLS_X509_MAX_VERIFY_CHAIN_SIZE ( MBEDTLS_X509_MAX_INTERMEDIATE_CA + 2 ) |
Max size of verification chain: end-entity + intermediates + trusted root
Definition at line 208
of file x509_crt.h
.
#define MBEDTLS_X509_RFC5280_MAX_SERIAL_LEN 32 |
Definition at line 172
of file x509_crt.h
.
#define MBEDTLS_X509_RFC5280_UTC_TIME_LEN 15 |
Definition at line 173
of file x509_crt.h
.
Typedef Documentation
Container for ASN1 bit strings.
Definition at line 216
of file x509.h
.
typedef mbedtls_asn1_buf mbedtls_x509_buf |
Type-length-value structure that allows for ASN1 using DER.
Definition at line 211
of file x509.h
.
typedef struct mbedtls_x509_crl mbedtls_x509_crl |
Certificate revocation list structure. Every CRL may have multiple entries.
typedef struct mbedtls_x509_crl_entry mbedtls_x509_crl_entry |
Certificate revocation list entry. Contains the CA-specific serial numbers and revocation dates.
typedef struct mbedtls_x509_crt mbedtls_x509_crt |
Container for an X.509 certificate. The certificate may be chained.
typedef struct mbedtls_x509_crt_profile mbedtls_x509_crt_profile |
Security profile for certificate verification.
All lists are bitfields, built by ORing flags from MBEDTLS_X509_ID_FLAG().
typedef void mbedtls_x509_crt_restart_ctx |
Definition at line 258
of file x509_crt.h
.
typedef struct mbedtls_x509_csr mbedtls_x509_csr |
Certificate Signing Request (CSR) structure.
Container for ASN1 named information objects. It allows for Relative Distinguished Names (e.g. cn=localhost,ou=code,etc.).
Definition at line 222
of file x509.h
.
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 }
Container for a sequence of ASN.1 items
Definition at line 227
of file x509.h
.
A structure for holding the parsed Subject Alternative Name, according to type
typedef struct mbedtls_x509_time mbedtls_x509_time |
Container for date and time (precision in seconds).
typedef struct mbedtls_x509write_cert mbedtls_x509write_cert |
Container for writing a certificate (CRT)
typedef struct mbedtls_x509write_csr mbedtls_x509write_csr |
Container for writing a CSR
Function Documentation
void mbedtls_x509_crl_free | ( | mbedtls_x509_crl * | crl | ) |
Unallocate all CRL data.
- Parameters
-
crl
CRL chain to free
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.
- Parameters
-
buf
Buffer to write to size
Maximum size of buffer prefix
A line prefix crl
The X509 CRL to represent
- Returns
- The length of the string written (not including the terminated nul byte), or a negative error code.
void mbedtls_x509_crl_init | ( | mbedtls_x509_crl * | crl | ) |
Initialize a CRL (chain)
- Parameters
-
crl
CRL chain to initialize
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.
- Note
- Multiple CRLs are accepted only if using PEM format
- Parameters
-
chain
points to the start of the chain buf
buffer holding the CRL data in PEM or DER format 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
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.
- Parameters
-
chain
points to the start of the chain buf
buffer holding the CRL data in DER format 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