1 /* Copyright 2024 The BoringSSL Authors 2 * 3 * Permission to use, copy, modify, and/or distribute this software for any 4 * purpose with or without fee is hereby granted, provided that the above 5 * copyright notice and this permission notice appear in all copies. 6 * 7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ 14 15 #if !defined(OPENSSL_HEADER_BSSL_PKI_VERIFY_ERROR_H_) && defined(__cplusplus) 16 #define OPENSSL_HEADER_BSSL_PKI_VERIFY_ERROR_H_ 17 18 #include <openssl/base.h> 19 20 #include <string> 21 22 BSSL_NAMESPACE_BEGIN 23 24 // VerifyError describes certificate chain validation result. 25 class OPENSSL_EXPORT VerifyError { 26 public: 27 VerifyError() = default; 28 VerifyError(const VerifyError &other) = default; 29 VerifyError &operator=(const VerifyError &other) = default; 30 31 // Code is the representation of a single error that we could 32 // find. 33 enum class StatusCode { 34 // PATH_VERIFIED means there were no errors, the certificate chain is valid. 35 PATH_VERIFIED, 36 37 // CERTIFICATE_INVALID_SIGNATURE means that the certificate's signature 38 // failed to verify. 39 CERTIFICATE_INVALID_SIGNATURE, 40 41 // CERTIFICATE_UNSUPPORTED_KEY means that the certificate's key type and/or 42 // size is not supported. 43 CERTIFICATE_UNSUPPORTED_KEY, 44 45 // CERTIFICATE_UNSUPPORTED_SIGNATURE ALGORITHM means that the signature 46 // algorithm is not supported. 47 CERTIFICATE_UNSUPPORTED_SIGNATURE_ALGORITHM, 48 49 // CERTIFICATE_REVOKED means that the certificate has been revoked. 50 CERTIFICATE_REVOKED, 51 52 // CERTIFICATE_NO_REVOCATION_MECHANISM means that revocation checking was 53 // required and no revocation mechanism was given for the certificate 54 CERTIFICATE_NO_REVOCATION_MECHANISM, 55 56 // CERTIFICATE_UNABLE_TO_CHECK_REVOCATION means that revocation checking was 57 // required and we were unable to check if the certificate was revoked via 58 // any revocation mechanism. 59 CERTIFICATE_UNABLE_TO_CHECK_REVOCATION, 60 61 // CERTIFICATE_EXPIRED means that the validation time is after the 62 // certificate's |notAfter| timestamp. 63 CERTIFICATE_EXPIRED, 64 65 // CERTIFICATE_NOT_YET_VALID means that the validation time is before the 66 // certificate's |notBefore| timestamp. 67 CERTIFICATE_NOT_YET_VALID, 68 69 // CERTIFICATE_NO_MATCHING_EKU means that the certificate's EKU does not 70 // allow the certificate to be used for the intended purpose. 71 CERTIFICATE_NO_MATCHING_EKU, 72 73 // CERTIFICATE_INVALID means that the certificate was structurally 74 // invalid, or invalid for some different reason than the above. 75 CERTIFICATE_INVALID, 76 77 // PATH_NOT_FOUND means that no path could be found from the leaf 78 // certificate to any trust anchor. 79 PATH_NOT_FOUND, 80 81 // PATH_ITERATION_COUNT_EXCEEDED means that the iteration limit for path 82 // building was hit and so the search for a valid path terminated early. 83 PATH_ITERATION_COUNT_EXCEEDED, 84 85 // PATH_DEADLINE_EXCEEDED means that the time limit for path building 86 // was hit and so the search for a valid path terminated early. 87 PATH_DEADLINE_EXCEEDED, 88 89 // PATH_DEPTH_LIMIT_REACHED means that path building was not able to find a 90 // path within the configured depth limit for verification. 91 PATH_DEPTH_LIMIT_REACHED, 92 93 // PATH_MULTIPLE_ERRORS indicates that there are multiple fatal 94 // errors present on the certificate chain, so that a single error could 95 // not be reported. 96 PATH_MULTIPLE_ERRORS, 97 98 // VERIFICATION_FAILURE means that something is wrong with the returned path 99 // that is not specific to a single certificate. There are many possible 100 // reasons for a verification to fail. 101 VERIFICATION_FAILURE, 102 }; 103 104 VerifyError(StatusCode code, ptrdiff_t offset, std::string diagnostic); 105 106 // Code returns the indicated error code for the certificate path. 107 StatusCode Code() const; 108 109 // Index returns the certificate in the chain for which the error first 110 // occured, starting with 0 for the leaf certificate. Later certificates in 111 // the chain may also exhibit the same error. If the error is not specific to 112 // a certificate, -1 is returned. 113 ptrdiff_t Index() const; 114 115 // DiagnosticString returns a string of diagnostic information related to this 116 // verification attempt. The string aims to be useful to debugging, but it is 117 // not stable and may not be processed programmatically or asserted on in 118 // tests. The string may be empty if no diagnostic information was available. 119 // 120 // The DiagnosticString is specifically not guaranteed to be unchanging for 121 // any given error code, as the diagnostic error message can contain 122 // information specific to the verification attempt and chain presented, due 123 // to there being multiple possible ways for, as an example, a certificate to 124 // be invalid, or that we are unable to build a path to a trust anchor. 125 // 126 // Needless to say, one should not attempt to parse the string that is 127 // returned. 128 const std::string &DiagnosticString() const; 129 130 private: 131 ptrdiff_t offset_ = -1; 132 StatusCode code_ = StatusCode::VERIFICATION_FAILURE; 133 std::string diagnostic_; 134 }; 135 136 BSSL_NAMESPACE_END 137 138 #endif // OPENSSL_HEADER_BSSL_PKI_VERIFY_ERROR_H_ 139