Mbed TLS: X.509 errors
Our goal is to simplify the ecosystem by consolidating the errors and their documentation (similarly to web documentation) and better explaining what the validation errors mean.
Correctly validating X.509 certificates turns out to be pretty complicated (e.g., Georgiev2012, Ukrop2019). Yet certificate validation is crucial for secure communication on the Internet (think TLS).
For every error, we aim to provide our redesigned documentation ( ), an example certificate ( ), original documentation provided by the library ( , unused or deprecated errors denoted by ). Furthermore, we provide links to corresponding errors from other libraries ( ). In the future, we plan on adding error frequencies based on IP-wide scans and elaborating on the consequences of individual errors.
Time validity errors
Errors occuring when a certificate is outside its validity period or when it is revoked by its CA.
Relevant links: Certificate Validity (RFC 5280), Certificate Revocation (RFC 5280)
Original documentation:
The certificate validity starts in the future. (source)
Original error message:
The certificate validity starts in the future (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_FUTURE in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case not-yet-valid (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_FUTURE in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_CERT_NOT_YET_VALID
- GnuTLS: GNUTLS_CERT_NOT_ACTIVATED
- Botan: CERT_NOT_YET_VALID
Original documentation:
The certificate validity has expired. (source)
Original error message:
The certificate validity has expired (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_EXPIRED in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case expired (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_EXPIRED in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_CERT_HAS_EXPIRED
- GnuTLS: GNUTLS_CERT_EXPIRED
- Botan: CERT_HAS_EXPIRED
Trust or chain related errors
These errors occur when the trust chain to the root certificate is not built correctly or fails.
Relevant links: Certificate Paths (RFC 5280), Certificate Revocation Lists (RFC 5280), OCSP (RFC 2560)
Original documentation:
The certificate is not correctly signed by the trusted CA. (source)
Original error message:
The certificate is not correctly signed by the trusted CA (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_NOT_TRUSTED in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case bc-path-len-exceeded (see the generation script)
- Case chain-loop (see the generation script)
- Case invalid-signature (see the generation script)
- Case issuer-ca-false (see the generation script)
- Case issuer-no-match-subject (see the generation script)
- Case no-certsign-in-keyusage (see the generation script)
- Case self-signed-end-entity (see the generation script)
- Case self-signed-intermediate (see the generation script)
- Case unknown-root-cn (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_NOT_TRUSTED in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_PATH_LENGTH_EXCEEDED, X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY, X509_V_ERR_CERT_SIGNATURE_FAILURE, X509_V_ERR_INVALID_CA
- GnuTLS: GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE, GNUTLS_CERT_SIGNER_NOT_FOUND, GNUTLS_E_KEY_USAGE_VIOLATION, GNUTLS_CERT_SIGNATURE_FAILURE, GNUTLS_CERT_SIGNER_NOT_CA
- Botan: CERT_CHAIN_TOO_LONG, TLS_EXCEPTION, SIGNATURE_ERROR, CA_CERT_NOT_FOR_CERT_ISSUER, CERT_ISSUER_NOT_FOUND, CANNOT_ESTABLISH_TRUST
Name related errors
Errors signalizing problems with either hostname verification, NameConstaints standard extension or IP Address Delegation extension.
Relevant links: NameConstaints extension (RFC 5280), IP Address Delegation extension (RFC 3779), Certificate Common Name (RFC 5280)
Original documentation:
The certificate Common Name (CN) does not match with the expected CN. (source)
Original error message:
The certificate Common Name (CN) does not match with the expected CN (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_CN_MISMATCH in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case empty-subject-and-no-san (see the generation script)
- Case host-no-match-cn (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_CN_MISMATCH in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- GnuTLS: GNUTLS_CERT_UNEXPECTED_OWNER
- Botan: CERT_NAME_NOMATCH
Usage and policy errors
Errors related to standard extensions CertificatePolicies, KeyUsage and ExtendedKeyUsage.
Relevant links: KeyUsage extension (RFC5280), ExtendedKeyUsage extension (RFC5280), CertificatePolicies extension (RFC5280)
Original documentation:
Usage does not match the keyUsage extension. (source)
Original error message:
Usage does not match the keyUsage extension (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_KEY_USAGE in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case chain-loop (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_KEY_USAGE in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
Original documentation:
Usage does not match the extendedKeyUsage extension. (source)
Original error message:
Usage does not match the extendedKeyUsage extension (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_EXT_KEY_USAGE in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case unknown-ext-key-usage (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_EXT_KEY_USAGE in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- GnuTLS: GNUTLS_CERT_UNEXPECTED_OWNER
- Botan: INVALID_USAGE
Algorithm related errors
Various errors signalizing usage of invalid or deprecated algorithms.
Relevant links: Algorithm and Key Size Profile for PKI (RFC 7935), Suite B Profile for TLS (RFC 6460)
Original documentation:
The certificate is signed with an unacceptable key (eg bad curve, RSA too short). (source)
Original error message:
The certificate is signed with an unacceptable key (eg bad curve, RSA too short). (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_BAD_KEY in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case end-entity-rsa-key-1024 (see the generation script)
- Case issuer-rsa-key-1024 (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_BAD_KEY in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
Original documentation:
The certificate is signed with an unacceptable hash. (source)
Original error message:
The certificate is signed with an unacceptable hash. (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_X509_BADCERT_BAD_MD in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case issuer-hash-md5 (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_X509_BADCERT_BAD_MD in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_CA_MD_TOO_WEAK
- GnuTLS: GNUTLS_CERT_INSECURE_ALGORITHM
- Botan: UNTRUSTED_HASH
Formatting errors
These errors occur when a field of the certificate/CRL contains invalid values or is badly formatted.
Relevant links: Certificate Signature (RFC 5280), Certificate Time formatting (RFC 5280), Certificate Signature Algorithm (RFC 5280)
Original documentation:
Signature algorithms do not match. (source)
Original error message:
X509 - Signature algorithms do not match. (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_ERR_X509_SIG_MISMATCH in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case wrong-signature-algorithm (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_ERR_X509_SIG_MISMATCH in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_CERT_SIGNATURE_FAILURE
- GnuTLS: GNUTLS_E_CERTIFICATE_ERROR
- Botan: DECODING_ERROR
Original documentation:
The CRT/CRL/CSR format is invalid, e.g. different type expected. (source)
Original error message:
X509 - The CRT/CRL/CSR format is invalid, e.g. different type expected (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_ERR_X509_INVALID_FORMAT in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case v1-cert-with-extensions (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_ERR_X509_INVALID_FORMAT in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_EXTENSIONS_REQUIRE_VERSION_3
- GnuTLS: GNUTLS_E_CERTIFICATE_ERROR
- Botan: TLS_EXCEPTION
Original documentation:
The extension tag or value is invalid. (source)
Original error message:
X509 - The extension tag or value is invalid (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_ERR_X509_INVALID_EXTENSIONS in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case bc-path-len-negative (see the generation script)
- Case duplicate-bc-extension (see the generation script)
- Case empty-ext-key-usage (see the generation script)
- Case empty-ip-addr-blocks (see the generation script)
- Case ip-addr-blocks-no-subset (see the generation script)
- Case nc-empty (see the generation script)
- Case nc-excluded-violation (see the generation script)
- Case nc-maximum-present (see the generation script)
- Case nc-minimum-not-zero (see the generation script)
- Case nc-permitted-violation (see the generation script)
- Case nc-unknown-name-type (see the generation script)
- Case proxy-ca (see the generation script)
- Case proxy-length-exceeded (see the generation script)
- Case proxy-name-no-match-issuer (see the generation script)
- Case proxy-with-san (see the generation script)
- Case san-empty-email (see the generation script)
- Case san-null-byte-in-email (see the generation script)
- Case unknown-critical-extension (see the generation script)
- Case valid-proxy (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_ERR_X509_INVALID_EXTENSIONS in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY, X509_V_ERR_INVALID_EXTENSION, X509_V_ERR_UNNESTED_RESOURCE, X509_V_OK, X509_V_ERR_EXCLUDED_VIOLATION, X509_V_ERR_SUBTREE_MINMAX, X509_V_ERR_PERMITTED_VIOLATION, X509_V_ERR_INVALID_NON_CA, X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED, X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION, X509_V_ERR_UNSUPPORTED_NAME_SYNTAX, X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION
- GnuTLS: GNUTLS_E_SUCCESS, GNUTLS_E_CERTIFICATE_ERROR, GNUTLS_CERT_UNKNOWN_CRIT_EXTENSIONS, GNUTLS_CERT_UNEXPECTED_OWNER, GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE, GNUTLS_CERT_SIGNER_NOT_CA
- Botan: UNKNOWN_CRITICAL_EXTENSION, DUPLICATE_CERT_EXTENSION, VERIFIED, ENCODING_ERROR, NAME_CONSTRAINT_ERROR
Original documentation:
The date tag or value is invalid. (source)
Original error message:
X509 - The date tag or value is invalid (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_ERR_X509_INVALID_DATE in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case notafter-field-invalid (see the generation script)
- Case notbefore-field-invalid (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_ERR_X509_INVALID_DATE in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
Uncategorized errors
These errors are not yet categorized, deprecated or not used at all.
(No detailed documentation provided by the library.)
Original error message:
ok (source)
Example certificates
Below you can download one or more example malformed certificates causing MBEDTLS_OK in Mbed TLS. If you are interested in generating these certificates yourself, see the corresponding generating script for each case on the project Github.
- Case any-ext-key-usage (see the generation script)
- Case bc-not-critical-ca (see the generation script)
- Case bc-path-len-in-non-ca (see the generation script)
- Case cert_revoked (see the generation script)
- Case crl_has_expired (see the generation script)
- Case crl_not_yet_valid (see the generation script)
- Case crl_path_validation_error (see the generation script)
- Case crl_signature_failure (see the generation script)
- Case different_crl_scope (see the generation script)
- Case error_in_crl_last_update_field (see the generation script)
- Case error_in_crl_next_update_field (see the generation script)
- Case keyusage_no_crl_sign (see the generation script)
- Case negative-serial-number (see the generation script)
- Case no-key-usage-in-ca (see the generation script)
- Case trusted-only-intermediate (see the generation script)
- Case unable_to_get_crl (see the generation script)
- Case unhandled_critical_crl_extension (see the generation script)
- Case valid-with-aia (see the generation script)
- Case valid-with-crldp (see the generation script)
- Case valid (see the generation script)
Corresponding errors
What validation errors do other libraries give for certificates causing MBEDTLS_OK in Mbed TLS? Below, you can see the basic overview based on the example certificates from the previous section. (The list may be incomplete.)
- OpenSSL: X509_V_ERR_CA_BCONS_NOT_CRITICAL, X509_V_ERR_PATHLEN_WITHOUT_KU_KEY_CERT_SIGN, X509_V_ERR_CERT_REVOKED, X509_V_ERR_CRL_HAS_EXPIRED, X509_V_ERR_CRL_NOT_YET_VALID, X509_V_ERR_CRL_PATH_VALIDATION_ERROR, X509_V_ERR_CRL_SIGNATURE_FAILURE, X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD, X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD, X509_V_ERR_KEYUSAGE_NO_CRL_SIGN, X509_V_OK, X509_V_ERR_CA_CERT_MISSING_KEY_USAGE, X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT, X509_V_ERR_UNABLE_TO_GET_CRL, X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION
- GnuTLS: GNUTLS_E_SUCCESS
- Botan: INVALID_USAGE, VERIFIED, CERT_ISSUER_NOT_FOUND
About the project
The project is developed at the Centre for Research on Cryptography and Security (CRoCS) at Masaryk University, Brno, Czech Republic by Martin Ukrop, Pavol Žáčik, Marián Svitek, Eric Valčík with the help of Michaela Balážová and Matěj Grabovský. For more details, see the ReadMe file in the project repository on GitHub.
The authors are grateful for the financial support by Red Hat Czech and Kiwi.com.