From e22bc1e730acd3ea00439e934d932769bec1e12a Mon Sep 17 00:00:00 2001 From: John Lamp Date: Tue, 26 Jan 2021 21:35:06 -0500 Subject: [PATCH] doc: add OpenSSL errors to API docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes: https://github.com/nodejs/node/issues/33705 PR-URL: https://github.com/nodejs/node/pull/34213 Reviewed-By: Ben Noordhuis Reviewed-By: Franziska Hinkelmann Reviewed-By: Rich Trott Reviewed-By: Ulises Gascón --- doc/api/errors.md | 211 ++++++++++++++++++++++++++++++++++++ src/crypto/crypto_common.cc | 2 + 2 files changed, 213 insertions(+) diff --git a/doc/api/errors.md b/doc/api/errors.md index d2a74b230db..48dc1f1e392 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -3715,6 +3715,217 @@ removed: v15.0.0 The native call from `process.cpuUsage` could not be processed. + + +## OpenSSL Error Codes + + + +### Time Validity Errors + + + +#### `CERT_NOT_YET_VALID` + +The certificate is not yet valid: the notBefore date is after the current time. + + + +#### `CERT_HAS_EXPIRED` + +The certificate has expired: the notAfter date is before the current time. + + + +#### `CRL_NOT_YET_VALID` + +The certificate revocation list (CRL) has a future issue date. + + + +#### `CRL_HAS_EXPIRED` + +The certificate revocation list (CRL) has expired. + + + +#### `CERT_REVOKED` + +The certificate has been revoked; it is on a certificate revocation list (CRL). + + + +### Trust or Chain Related Errors + + + +#### `UNABLE_TO_GET_ISSUER_CERT` + +The issuer certificate of a looked up certificate could not be found. This +normally means the list of trusted certificates is not complete. + + + +#### `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` + +The certificate’s issuer is not known. This is the case if the issuer is not +included in the trusted certificate list. + + + +#### `DEPTH_ZERO_SELF_SIGNED_CERT` + +The passed certificate is self-signed and the same certificate cannot be found +in the list of trusted certificates. + + + +#### `SELF_SIGNED_CERT_IN_CHAIN` + +The certificate’s issuer is not known. This is the case if the issuer is not +included in the trusted certificate list. + + + +#### `CERT_CHAIN_TOO_LONG` + +The certificate chain length is greater than the maximum depth. + + + +#### `UNABLE_TO_GET_CRL` + +The CRL reference by the certificate could not be found. + + + +#### `UNABLE_TO_VERIFY_LEAF_SIGNATURE` + +No signatures could be verified because the chain contains only one certificate +and it is not self signed. + + + +#### `CERT_UNTRUSTED` + +The root certificate authority (CA) is not marked as trusted for the specified +purpose. + + + +### Basic Extension Errors + + + +#### `INVALID_CA` + +A CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + + + +#### `PATH_LENGTH_EXCEEDED` + +The basicConstraints pathlength parameter has been exceeded. + + + +### Name Related Errors + + + +#### `HOSTNAME_MISMATCH` + +Certificate does not match provided name. + + + +### Usage and Policy Errors + + + +#### `INVALID_PURPOSE` + +The supplied certificate cannot be used for the specified purpose. + + + +#### `CERT_REJECTED` + +The root CA is marked to reject the specified purpose. + + + +### Formatting Errors + + + +#### `CERT_SIGNATURE_FAILURE` + +The signature of the certificate is invalid. + + + +#### `CRL_SIGNATURE_FAILURE` + +The signature of the certificate revocation list (CRL) is invalid. + + + +#### `ERROR_IN_CERT_NOT_BEFORE_FIELD` + +The certificate notBefore field contains an invalid time. + + + +#### `ERROR_IN_CERT_NOT_AFTER_FIELD` + +The certificate notAfter field contains an invalid time. + + + +#### `ERROR_IN_CRL_LAST_UPDATE_FIELD` + +The CRL lastUpdate field contains an invalid time. + + + +#### `ERROR_IN_CRL_NEXT_UPDATE_FIELD` + +The CRL nextUpdate field contains an invalid time. + + + +#### `UNABLE_TO_DECRYPT_CERT_SIGNATURE` + +The certificate signature could not be decrypted. This means that the actual +signature value could not be determined rather than it not matching the expected +value, this is only meaningful for RSA keys. + + + +#### `UNABLE_TO_DECRYPT_CRL_SIGNATURE` + +The certificate revocation list (CRL) signature could not be decrypted: this +means that the actual signature value could not be determined rather than it not +matching the expected value. + + + +#### `UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY` + +The public key in the certificate SubjectPublicKeyInfo could not be read. + + + +### Other OpenSSL Errors + + + +#### `OUT_OF_MEM` + +An error occurred trying to allocate memory. This should never happen. + [ES Module]: esm.md [ICU]: intl.md#internationalization-support [JSON Web Key Elliptic Curve Registry]: https://www.iana.org/assignments/jose/jose.xhtml#web-key-elliptic-curve diff --git a/src/crypto/crypto_common.cc b/src/crypto/crypto_common.cc index 3517c39ad0b..ee1c7931a5c 100644 --- a/src/crypto/crypto_common.cc +++ b/src/crypto/crypto_common.cc @@ -209,6 +209,8 @@ bool SetGroups(SecureContext* sc, const char* groups) { return SSL_CTX_set1_groups_list(sc->ctx().get(), groups) == 1; } +// When adding or removing errors below, please also update the list in the API +// documentation. See the "OpenSSL Error Codes" section of doc/api/errors.md const char* X509ErrorCode(long err) { // NOLINT(runtime/int) const char* code = "UNSPECIFIED"; #define CASE_X509_ERR(CODE) case X509_V_ERR_##CODE: code = #CODE; break;