Usable X.509 errors: Botan
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:
Certificate is not yet valid (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_CERT_NOT_YET_VALID
- GnuTLS/GNUTLS_CERT_NOT_ACTIVATED
- mbedTLS/MBEDTLS_X509_BADCERT_FUTURE
Original documentation:
Certificate has expired (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_CERT_HAS_EXPIRED
- GnuTLS/GNUTLS_CERT_EXPIRED
- mbedTLS/MBEDTLS_X509_BADCERT_EXPIRED
Original documentation:
CRL response is not yet valid (source)
Original documentation:
CRL has expired (source)
Original documentation:
OCSP is not yet valid (source)
Original documentation:
OCSP response has expired (source)
Original documentation:
OCSP response is too old (source)
Original documentation:
Certificate is revoked (source)
Corresponding errors:
- OpenSSL/X509_V_ERR_CERT_REVOKED
- GnuTLS/GNUTLS_CERT_REVOKED
- mbedTLS/MBEDTLS_X509_BADCERT_REVOKED
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:
Cannot establish trust (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify chain.crt
Corresponding errors:
Original documentation:
Certificate chain does not end in a CA certificate (source)
Original documentation:
Certificate public key invalid, no HTTP support compiled in (source)
Original documentation:
Certificate issuer not found (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt
Corresponding errors:
Original documentation:
Loop in certificate chain (source)
Original documentation:
Certificate chain too long (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt subca1.crt subca2.crt ca.crt
Corresponding errors:
Original documentation:
Unable to find certificate issusing OCSP response (source)
Original documentation:
OCSP signature error (source)
Original documentation:
OCSP bad status (source)
Original documentation:
OCSP parsing valid (source)
Original documentation:
OCSP URL not available (source)
(No detailed documentation provided by the library.)
Unused: Deprecated due to a typo - will be removed in future major release
Original documentation:
OCSP server not available (source)
(No detailed documentation provided by the library.)
Unused: Deprecated due to a typo - will be removed in future major release
Original documentation:
No revocation data (source)
Basic extension errors
Errors related to extensions in general or to the BasicConstraints standard extension.
Relevant links: Certificate Extensions (RFC 5280), BasicConstraints Extension (RFC 5280)
Original documentation:
Unknown critical extension encountered (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
Original documentation:
CA certificate not allowed to issue certs (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt subca.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_INVALID_CA
- GnuTLS/GNUTLS_CERT_SIGNER_NOT_CA
- mbedTLS/MBEDTLS_X509_BADCERT_NOT_TRUSTED
Original documentation:
Duplicate certificate extension encountered (source)
Original documentation:
Encountered extension in certificate with version < 3 (source)
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:
Certificate does not match provided name (source)
Corresponding errors:
- OpenSSL/X509_V_ERR_HOSTNAME_MISMATCH
- mbedTLS/MBEDTLS_X509_BADCERT_CN_MISMATCH
Original documentation:
Certificate issuer does not match subject of issuing cert (source)
Original documentation:
Certificate does not pass name constraint (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_PERMITTED_VIOLATION
- GnuTLS/GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE
- mbedTLS/MBEDTLS_X509_BADCERT_NOT_TRUSTED
Original documentation:
Distinguished name too long (source)
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:
Certificate does not allow the requested usage (source)
Original documentation:
Certificate policy error (source)
Original documentation:
Certificate contains duplicate policy (source)
Original documentation:
CA certificate not allowed to issue CRLs (source)
Original documentation:
OCSP issuer's keyusage prohibits OCSP (source)
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:
Signature method too weak (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_CA_KEY_TOO_SMALL
- mbedTLS/MBEDTLS_X509_BADCERT_BAD_KEY
Original documentation:
Certificate signed with unknown/unavailable algorithm (source)
Original documentation:
Certificate signature has invalid parameters (source)
Original documentation:
Hash function used is considered too weak for security (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_CA_MD_TOO_WEAK
- mbedTLS/MBEDTLS_X509_BADCERT_BAD_MD
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 error (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_ERR_CERT_SIGNATURE_FAILURE
- GnuTLS/GNUTLS_CERT_SIGNATURE_FAILURE
- mbedTLS/MBEDTLS_X509_BADCERT_NOT_TRUSTED
Original documentation:
CRL bad signature (source)
Original documentation:
Certificate serial number is negative (source)
Uncategorized errors
These errors are not yet categorized, deprecated or not used at all.
Original documentation:
No CRL with matching distribution point for certificate (source)
Original documentation:
OCSP cert not listed (source)
Original documentation:
OCSP requests not available (source)
Original documentation:
Signature on OCSP response was found valid (source)
Original documentation:
OCSP response accepted as affirming unrevoked status for certificate (source)
Original documentation:
Valid CRL examined (source)
Original documentation:
Verified (source)
Example certificate
Download the certificate archive and validate the contents using a command indicated below. If you are interested in generating such certificate yourself, see the generating script for this case on the project GitHub.
Validate with: botan cert_verify endpoint.crt ca.crt
Corresponding errors:
- OpenSSL/X509_V_OK
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, 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 and Red Hat Czech and Kiwi.com.