1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef QUICHE_QUIC_CORE_CRYPTO_PROOF_VERIFIER_H_ 6 #define QUICHE_QUIC_CORE_CRYPTO_PROOF_VERIFIER_H_ 7 8 #include <memory> 9 #include <string> 10 #include <vector> 11 12 #include "absl/strings/string_view.h" 13 #include "quiche/quic/core/quic_types.h" 14 #include "quiche/quic/core/quic_versions.h" 15 #include "quiche/quic/platform/api/quic_export.h" 16 17 namespace quic { 18 19 // ProofVerifyDetails is an abstract class that acts as a container for any 20 // implementation specific details that a ProofVerifier wishes to return. These 21 // details are saved in the CachedState for the origin in question. 22 class QUICHE_EXPORT ProofVerifyDetails { 23 public: ~ProofVerifyDetails()24 virtual ~ProofVerifyDetails() {} 25 26 // Returns an new ProofVerifyDetails object with the same contents 27 // as this one. 28 virtual ProofVerifyDetails* Clone() const = 0; 29 }; 30 31 // ProofVerifyContext is an abstract class that acts as a container for any 32 // implementation specific context that a ProofVerifier needs. 33 class QUICHE_EXPORT ProofVerifyContext { 34 public: ~ProofVerifyContext()35 virtual ~ProofVerifyContext() {} 36 }; 37 38 // ProofVerifierCallback provides a generic mechanism for a ProofVerifier to 39 // call back after an asynchronous verification. 40 class QUICHE_EXPORT ProofVerifierCallback { 41 public: ~ProofVerifierCallback()42 virtual ~ProofVerifierCallback() {} 43 44 // Run is called on the original thread to mark the completion of an 45 // asynchonous verification. If |ok| is true then the certificate is valid 46 // and |error_details| is unused. Otherwise, |error_details| contains a 47 // description of the error. |details| contains implementation-specific 48 // details of the verification. |Run| may take ownership of |details| by 49 // calling |release| on it. 50 virtual void Run(bool ok, const std::string& error_details, 51 std::unique_ptr<ProofVerifyDetails>* details) = 0; 52 }; 53 54 // A ProofVerifier checks the signature on a server config, and the certificate 55 // chain that backs the public key. 56 class QUICHE_EXPORT ProofVerifier { 57 public: ~ProofVerifier()58 virtual ~ProofVerifier() {} 59 60 // VerifyProof checks that |signature| is a valid signature of 61 // |server_config| by the public key in the leaf certificate of |certs|, and 62 // that |certs| is a valid chain for |hostname|. On success, it returns 63 // QUIC_SUCCESS. On failure, it returns QUIC_FAILURE and sets |*error_details| 64 // to a description of the problem. In either case it may set |*details|, 65 // which the caller takes ownership of. 66 // 67 // |context| specifies an implementation specific struct (which may be nullptr 68 // for some implementations) that provides useful information for the 69 // verifier, e.g. logging handles. 70 // 71 // This function may also return QUIC_PENDING, in which case the ProofVerifier 72 // will call back, on the original thread, via |callback| when complete. 73 // 74 // The signature uses SHA-256 as the hash function and PSS padding in the 75 // case of RSA. 76 virtual QuicAsyncStatus VerifyProof( 77 const std::string& hostname, const uint16_t port, 78 const std::string& server_config, QuicTransportVersion transport_version, 79 absl::string_view chlo_hash, const std::vector<std::string>& certs, 80 const std::string& cert_sct, const std::string& signature, 81 const ProofVerifyContext* context, std::string* error_details, 82 std::unique_ptr<ProofVerifyDetails>* details, 83 std::unique_ptr<ProofVerifierCallback> callback) = 0; 84 85 // VerifyCertChain checks that |certs| is a valid chain for |hostname|. On 86 // success, it returns QUIC_SUCCESS. On failure, it returns QUIC_FAILURE and 87 // sets |*error_details| to a description of the problem. In either case it 88 // may set |*details|, which the caller takes ownership of. 89 // 90 // |context| specifies an implementation specific struct (which may be nullptr 91 // for some implementations) that provides useful information for the 92 // verifier, e.g. logging handles. 93 // 94 // If certificate verification fails, a TLS alert will be sent when closing 95 // the connection. This alert defaults to certificate_unknown. By setting 96 // |*out_alert|, a different alert can be sent to provide a more specific 97 // reason why verification failed. 98 // 99 // This function may also return QUIC_PENDING, in which case the ProofVerifier 100 // will call back, on the original thread, via |callback| when complete. 101 // In this case, the ProofVerifier will take ownership of |callback|. 102 virtual QuicAsyncStatus VerifyCertChain( 103 const std::string& hostname, const uint16_t port, 104 const std::vector<std::string>& certs, const std::string& ocsp_response, 105 const std::string& cert_sct, const ProofVerifyContext* context, 106 std::string* error_details, std::unique_ptr<ProofVerifyDetails>* details, 107 uint8_t* out_alert, std::unique_ptr<ProofVerifierCallback> callback) = 0; 108 109 // Returns a ProofVerifyContext instance which can be use for subsequent 110 // verifications. Applications may chose create a different context and 111 // supply it for verifications instead. 112 virtual std::unique_ptr<ProofVerifyContext> CreateDefaultContext() = 0; 113 }; 114 115 } // namespace quic 116 117 #endif // QUICHE_QUIC_CORE_CRYPTO_PROOF_VERIFIER_H_ 118