verify.h (6885B)
1 #ifndef BSSL_VERIFY_H_ 2 #define BSSL_VERIFY_H_ 3 4 #include <chrono> 5 #include <optional> 6 #include <string> 7 #include <string_view> 8 #include <vector> 9 10 #include <openssl/pki/signature_verify_cache.h> 11 #include <openssl/pki/verify_error.h> 12 13 BSSL_NAMESPACE_BEGIN 14 15 class CertIssuerSourceStatic; 16 class TrustStoreInMemory; 17 class CertificateVerifyOptions; 18 class CertificateVerifyStatus; 19 20 class OPENSSL_EXPORT VerifyTrustStore { 21 public: 22 std::unique_ptr<TrustStoreInMemory> trust_store; 23 24 ~VerifyTrustStore(); 25 26 // FromDER returns a |TrustStore| derived from interpreting the |der_certs| as 27 // a bunch of DER-encoded certs, concatenated. In the event of a failure nullptr 28 // e is returned and a diagnostic string is placed in |out_diagnostic| 29 static std::unique_ptr<VerifyTrustStore> FromDER( 30 std::string_view der_certs, std::string *out_diagnostic); 31 32 // FromDER returns a |TrustStore| consisting of the supplied DER-encoded 33 // certs in |der_certs|. In the event of a failure nullptr is returned and a 34 // diagnostic string is placed in |out_diagnostic| 35 static std::unique_ptr<VerifyTrustStore> FromDER( 36 const std::vector<std::string_view> &der_certs, 37 std::string *out_diagnostic); 38 }; 39 40 class OPENSSL_EXPORT CertPool { 41 public: 42 CertPool(); 43 CertPool(const CertPool &) = delete; 44 CertPool &operator=(const CertPool &) = delete; 45 virtual ~CertPool(); 46 47 // FromCerts returns a |CertPool| consisting of the supplied DER-encoded 48 // certs in |der_certs|. In the event of a failure nullptr is returned and a 49 // diagnostic string is placed in |out_diagnostic| 50 static std::unique_ptr<CertPool> FromCerts( 51 const std::vector<std::string_view> &der_certs, 52 std::string *out_diagnostic); 53 54 private: 55 friend std::optional<std::vector<std::vector<std::string>>> 56 CertificateVerifyInternal(const CertificateVerifyOptions &opts, 57 VerifyError *out_error, 58 CertificateVerifyStatus *out_status, 59 bool all_paths); 60 std::unique_ptr<CertIssuerSourceStatic> impl_; 61 }; 62 63 // CertificateVerifyOptions contains all the options for a certificate verification. 64 class OPENSSL_EXPORT CertificateVerifyOptions { 65 public: 66 // The key purpose (extended key usage) to check for during verification. 67 enum class KeyPurpose { 68 ANY_EKU, 69 SERVER_AUTH, 70 CLIENT_AUTH, 71 SERVER_AUTH_STRICT, 72 CLIENT_AUTH_STRICT, 73 SERVER_AUTH_STRICT_LEAF, 74 CLIENT_AUTH_STRICT_LEAF, 75 RCS_MLS_CLIENT_AUTH, 76 C2PA_TIMESTAMPING, 77 C2PA_MANIFEST 78 }; 79 80 CertificateVerifyOptions(); 81 CertificateVerifyOptions(const CertificateVerifyOptions &) = delete; 82 CertificateVerifyOptions &operator=(const CertificateVerifyOptions &) = 83 delete; 84 85 KeyPurpose key_purpose = KeyPurpose::SERVER_AUTH; 86 std::string_view leaf_cert; 87 std::vector<std::string_view> intermediates; 88 89 // extra_intermediates optionally points to a pool of common intermediates. 90 const CertPool *extra_intermediates = nullptr; 91 // trust_store points to the set of root certificates to trust. 92 const VerifyTrustStore *trust_store = nullptr; 93 // min_rsa_modulus_length is the minimum acceptable RSA key size in a chain. 94 size_t min_rsa_modulus_length = 1024; 95 // time is the time in POSIX seconds since the POSIX epoch at which to 96 // validate the chain. It defaults to the current time if not set. 97 std::optional<int64_t> time; 98 // insecurely_allow_sha1 allows verification of signatures that use SHA-1 99 // message digests. This option is insecure and should not be used. 100 bool insecurely_allow_sha1 = false; 101 102 // max_iteration_count, if not zero, limits the number of times path building 103 // will try to append an intermediate to a potential path. This bounds the 104 // amount of time that a verification attempt can take, at the risk of 105 // rejecting cases that would be solved if only more effort were used. 106 uint32_t max_iteration_count = 0; 107 108 // Sets an optional deadline for completing path building. It defaults 109 // to std::chrono::time_point::max() if it not set. If |deadline| has a 110 // value that has passed based on comparison to 111 // std::chrono::steady_clock::now(), and path building has not completed, 112 // path building will stop. Note that this is not a hard limit, there is no 113 // guarantee how far past |deadline| time will be when path building is 114 // aborted. 115 std::optional<std::chrono::time_point<std::chrono::steady_clock>> deadline; 116 117 // max_path_building_depth, if not zero, limits the depth of the path that the 118 // path building algorithm attempts to build between leafs and roots. Using 119 // this comes at the risk of rejecting cases that would be solved if only one 120 // more certificate is added to the path. 121 uint32_t max_path_building_depth = 0; 122 123 // signature_verify_cache, if not nullptr, points to an object implementing a 124 // signature verification cache derived from 125 // <openssl/pki/signature_verify_cache.h> 126 SignatureVerifyCache *signature_verify_cache = nullptr; 127 }; 128 129 // CertificateVerifyStatus describes the status of a certificate verification 130 // attempt. 131 class OPENSSL_EXPORT CertificateVerifyStatus { 132 public: 133 CertificateVerifyStatus(); 134 135 // IterationCount returns the total number of attempted certificate additions 136 // to any potential path while performing path building for verification. It 137 // is the same value which may be bound by max_iteration_count in 138 // CertificateVerifyOptions. 139 size_t IterationCount() const; 140 141 // MaxDepthSeen returns the maximum path depth seen during path building. 142 size_t MaxDepthSeen() const; 143 144 private: 145 friend std::optional<std::vector<std::vector<std::string>>> 146 CertificateVerifyInternal(const CertificateVerifyOptions &opts, 147 VerifyError *out_error, 148 CertificateVerifyStatus *out_status, 149 bool all_paths); 150 size_t iteration_count_ = 0; 151 size_t max_depth_seen_ = 0; 152 }; 153 154 // Verify verifies |opts.leaf_cert| using the other values in |opts|. It 155 // returns either an error, or else a validated chain from leaf to root. 156 // 157 // In the event of an error return, |out_error| will be updated with information 158 // about the error. It may be |nullptr|. 159 // 160 // Status information about the verification will be returned in |out_status|. 161 // It may be |nullptr|. 162 OPENSSL_EXPORT std::optional<std::vector<std::string>> CertificateVerify( 163 const CertificateVerifyOptions &opts, VerifyError *out_error = nullptr, 164 CertificateVerifyStatus *out_status = nullptr); 165 166 // VerifyAllPaths verifies |opts.leaf_cert| using the other values in |opts|, 167 // and returns all possible valid chains from the leaf to a root. If no chains 168 // exist, it returns an error. 169 OPENSSL_EXPORT std::optional<std::vector<std::vector<std::string>>> 170 CertificateVerifyAllPaths(const CertificateVerifyOptions &opts); 171 172 BSSL_NAMESPACE_END 173 174 #endif // BSSL_VERIFY_H_