blob: 9509e814f244a8eecb3e34dec5397dea5b906a60 [file] [log] [blame]
QUICHE teama6ef0a62019-03-07 20:34:33 -05001// Copyright (c) 2017 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_TLS_HANDSHAKER_H_
6#define QUICHE_QUIC_CORE_TLS_HANDSHAKER_H_
7
vasilvvc872ee42020-10-07 19:50:22 -07008#include "absl/strings/string_view.h"
QUICHE teama6ef0a62019-03-07 20:34:33 -05009#include "third_party/boringssl/src/include/openssl/base.h"
10#include "third_party/boringssl/src/include/openssl/ssl.h"
QUICHE team5be974e2020-12-29 18:35:24 -050011#include "quic/core/crypto/crypto_handshake.h"
12#include "quic/core/crypto/crypto_message_parser.h"
13#include "quic/core/crypto/proof_verifier.h"
14#include "quic/core/crypto/quic_decrypter.h"
15#include "quic/core/crypto/quic_encrypter.h"
16#include "quic/core/crypto/tls_connection.h"
17#include "quic/core/quic_session.h"
18#include "quic/platform/api/quic_export.h"
wubfa47a6d2021-04-16 08:56:26 -070019#include "quic/platform/api/quic_flags.h"
QUICHE teama6ef0a62019-03-07 20:34:33 -050020
21namespace quic {
22
23class QuicCryptoStream;
24
25// Base class for TlsClientHandshaker and TlsServerHandshaker. TlsHandshaker
26// provides functionality common to both the client and server, such as moving
27// messages between the TLS stack and the QUIC crypto stream, and handling
28// derivation of secrets.
nharper6ebe83b2019-06-13 17:43:52 -070029class QUIC_EXPORT_PRIVATE TlsHandshaker : public TlsConnection::Delegate,
30 public CryptoMessageParser {
QUICHE teama6ef0a62019-03-07 20:34:33 -050031 public:
32 // TlsHandshaker does not take ownership of any of its arguments; they must
33 // outlive the TlsHandshaker.
nharper80d3b172020-01-17 11:43:39 -080034 TlsHandshaker(QuicCryptoStream* stream, QuicSession* session);
QUICHE teama6ef0a62019-03-07 20:34:33 -050035 TlsHandshaker(const TlsHandshaker&) = delete;
36 TlsHandshaker& operator=(const TlsHandshaker&) = delete;
37
38 ~TlsHandshaker() override;
39
40 // From CryptoMessageParser
vasilvvc872ee42020-10-07 19:50:22 -070041 bool ProcessInput(absl::string_view input, EncryptionLevel level) override;
QUICHE teama6ef0a62019-03-07 20:34:33 -050042 size_t InputBytesRemaining() const override { return 0; }
43 QuicErrorCode error() const override { return parser_error_; }
vasilvvc48c8712019-03-11 13:38:16 -070044 const std::string& error_detail() const override {
QUICHE teama6ef0a62019-03-07 20:34:33 -050045 return parser_error_detail_;
46 }
47
nharper82bea252020-09-16 16:18:49 -070048 // The following methods provide implementations to subclasses of
49 // TlsHandshaker which use them to implement methods of QuicCryptoStream.
50 CryptoMessageParser* crypto_message_parser() { return this; }
nharper486a8a92019-08-28 16:25:10 -070051 size_t BufferSizeLimitForLevel(EncryptionLevel level) const;
nharper6a6bd312020-09-17 13:20:53 -070052 ssl_early_data_reason_t EarlyDataReason() const;
mattm072a7e32020-10-09 16:16:56 -070053 std::unique_ptr<QuicDecrypter> AdvanceKeysAndCreateCurrentOneRttDecrypter();
54 std::unique_ptr<QuicEncrypter> CreateCurrentOneRttEncrypter();
nharper0ab1c662020-11-02 17:05:32 -080055 virtual HandshakeState GetHandshakeState() const = 0;
haoyuewangf88c4a52021-10-04 15:21:37 -070056 bool ExportKeyingMaterialForLabel(absl::string_view label,
57 absl::string_view context,
58 size_t result_len, std::string* result);
QUICHE teama6ef0a62019-03-07 20:34:33 -050059
60 protected:
nharper0ab1c662020-11-02 17:05:32 -080061 // Called when a new message is received on the crypto stream and is available
62 // for the TLS stack to read.
QUICHE team4f1e2f92021-06-14 15:18:50 -070063 virtual void AdvanceHandshake();
QUICHE teama6ef0a62019-03-07 20:34:33 -050064
nharper0ab1c662020-11-02 17:05:32 -080065 void CloseConnection(QuicErrorCode error, const std::string& reason_phrase);
mattm55006b02021-01-14 15:09:54 -080066 // Closes the connection, specifying the wire error code |ietf_error|
67 // explicitly.
68 void CloseConnection(QuicErrorCode error,
69 QuicIetfTransportErrorCodes ietf_error,
70 const std::string& reason_phrase);
nharper0ab1c662020-11-02 17:05:32 -080071
72 void OnConnectionClosed(QuicErrorCode error, ConnectionCloseSource source);
73
74 bool is_connection_closed() const { return is_connection_closed_; }
75
76 // Called when |SSL_do_handshake| returns 1, indicating that the handshake has
wubbebae4a2021-06-28 09:41:11 -070077 // finished. Note that a handshake only finishes once, entering early data
78 // does not count.
nharper0ab1c662020-11-02 17:05:32 -080079 virtual void FinishHandshake() = 0;
80
wub48b16812021-04-30 10:22:22 -070081 // Called when |SSL_do_handshake| returns 1 and the connection is in early
82 // data. In that case, |AdvanceHandshake| will call |OnEnterEarlyData| and
83 // retry |SSL_do_handshake| once.
84 virtual void OnEnterEarlyData() {
85 // By default, do nothing but check the preconditions.
wub48b16812021-04-30 10:22:22 -070086 QUICHE_DCHECK(SSL_in_early_data(ssl()));
87 }
88
nharper0ab1c662020-11-02 17:05:32 -080089 // Called when a handshake message is received after the handshake is
90 // complete.
91 virtual void ProcessPostHandshakeMessage() = 0;
92
93 // Called when an unexpected error code is received from |SSL_get_error|. If a
94 // subclass can expect more than just a single error (as provided by
95 // |set_expected_ssl_error|), it can override this method to handle that case.
96 virtual bool ShouldCloseConnectionOnUnexpectedError(int ssl_error);
97
98 void set_expected_ssl_error(int ssl_error) {
99 expected_ssl_error_ = ssl_error;
100 }
101 int expected_ssl_error() const { return expected_ssl_error_; }
QUICHE teama6ef0a62019-03-07 20:34:33 -0500102
wub5b786df2021-12-01 15:11:38 -0800103 // Called to verify a cert chain. This can be implemented as a simple wrapper
104 // around ProofVerifier, which optionally gathers additional arguments to pass
105 // into their VerifyCertChain method. This class retains a non-owning pointer
106 // to |callback|; the callback must live until this function returns
107 // QUIC_SUCCESS or QUIC_FAILURE, or until the callback is run.
nharper54fc9ab2020-11-12 11:07:39 -0800108 //
109 // If certificate verification fails, |*out_alert| may be set to a TLS alert
110 // that will be sent when closing the connection; it defaults to
111 // certificate_unknown. Implementations of VerifyCertChain may retain the
112 // |out_alert| pointer while performing an async operation.
nharpere62aab72020-11-04 16:32:09 -0800113 virtual QuicAsyncStatus VerifyCertChain(
114 const std::vector<std::string>& certs,
115 std::string* error_details,
116 std::unique_ptr<ProofVerifyDetails>* details,
nharper54fc9ab2020-11-12 11:07:39 -0800117 uint8_t* out_alert,
nharpere62aab72020-11-04 16:32:09 -0800118 std::unique_ptr<ProofVerifierCallback> callback) = 0;
119 // Called when certificate verification is completed.
120 virtual void OnProofVerifyDetailsAvailable(
121 const ProofVerifyDetails& verify_details) = 0;
122
QUICHE teama6ef0a62019-03-07 20:34:33 -0500123 // Returns the PRF used by the cipher suite negotiated in the TLS handshake.
nharper8d4ff5c2020-02-27 11:43:44 -0800124 const EVP_MD* Prf(const SSL_CIPHER* cipher);
QUICHE teama6ef0a62019-03-07 20:34:33 -0500125
nharper486a8a92019-08-28 16:25:10 -0700126 virtual const TlsConnection* tls_connection() const = 0;
nharper6ebe83b2019-06-13 17:43:52 -0700127
nharper486a8a92019-08-28 16:25:10 -0700128 SSL* ssl() const { return tls_connection()->ssl(); }
nharper6ebe83b2019-06-13 17:43:52 -0700129
QUICHE teama6ef0a62019-03-07 20:34:33 -0500130 QuicCryptoStream* stream() { return stream_; }
renjietangbd33b622020-02-12 16:52:30 -0800131 HandshakerDelegateInterface* handshaker_delegate() {
132 return handshaker_delegate_;
133 }
QUICHE teama6ef0a62019-03-07 20:34:33 -0500134
nharpere62aab72020-11-04 16:32:09 -0800135 enum ssl_verify_result_t VerifyCert(uint8_t* out_alert) override;
136
nharperd08b82c2020-02-26 12:10:25 -0800137 // SetWriteSecret provides the encryption secret used to encrypt messages at
138 // encryption level |level|. The secret provided here is the one from the TLS
139 // 1.3 key schedule (RFC 8446 section 7.1), in particular the handshake
140 // traffic secrets and application traffic secrets. The provided write secret
141 // must be used with the provided cipher suite |cipher|.
142 void SetWriteSecret(EncryptionLevel level,
143 const SSL_CIPHER* cipher,
144 const std::vector<uint8_t>& write_secret) override;
145
146 // SetReadSecret is similar to SetWriteSecret, except that it is used for
147 // decrypting messages. SetReadSecret at a particular level is always called
148 // after SetWriteSecret for that level, except for ENCRYPTION_ZERO_RTT, where
149 // the EncryptionLevel for SetWriteSecret is ENCRYPTION_FORWARD_SECURE.
150 bool SetReadSecret(EncryptionLevel level,
151 const SSL_CIPHER* cipher,
152 const std::vector<uint8_t>& read_secret) override;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500153
154 // WriteMessage is called when there is |data| from the TLS stack ready for
155 // the QUIC stack to write in a crypto frame. The data must be transmitted at
156 // encryption level |level|.
vasilvvc872ee42020-10-07 19:50:22 -0700157 void WriteMessage(EncryptionLevel level, absl::string_view data) override;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500158
159 // FlushFlight is called to signal that the current flight of
160 // messages have all been written (via calls to WriteMessage) and can be
161 // flushed to the underlying transport.
nharper6ebe83b2019-06-13 17:43:52 -0700162 void FlushFlight() override;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500163
164 // SendAlert causes this TlsHandshaker to close the QUIC connection with an
165 // error code corresponding to the TLS alert description |desc|.
nharper6ebe83b2019-06-13 17:43:52 -0700166 void SendAlert(EncryptionLevel level, uint8_t desc) override;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500167
wubd9036e42021-08-02 20:59:15 -0700168 // Informational callback from BoringSSL. Subclasses can override it to do
169 // logging, tracing, etc.
170 // See |SSL_CTX_set_info_callback| for the meaning of |type| and |value|.
171 void InfoCallback(int /*type*/, int /*value*/) override {}
172
nharper6ebe83b2019-06-13 17:43:52 -0700173 private:
nharpere62aab72020-11-04 16:32:09 -0800174 // ProofVerifierCallbackImpl handles the result of an asynchronous certificate
175 // verification operation.
176 class QUIC_EXPORT_PRIVATE ProofVerifierCallbackImpl
177 : public ProofVerifierCallback {
178 public:
179 explicit ProofVerifierCallbackImpl(TlsHandshaker* parent);
180 ~ProofVerifierCallbackImpl() override;
181
182 // ProofVerifierCallback interface.
183 void Run(bool ok,
184 const std::string& error_details,
185 std::unique_ptr<ProofVerifyDetails>* details) override;
186
187 // If called, Cancel causes the pending callback to be a no-op.
188 void Cancel();
189
190 private:
191 // Non-owning pointer to the TlsHandshaker responsible for this callback.
192 // |parent_| must be valid for the life of this callback or until |Cancel|
193 // is called.
194 TlsHandshaker* parent_;
195 };
196
197 // ProofVerifierCallback used for async certificate verification. Ownership of
198 // this object is transferred to |VerifyCertChain|;
199 ProofVerifierCallbackImpl* proof_verify_callback_ = nullptr;
200 std::unique_ptr<ProofVerifyDetails> verify_details_;
201 enum ssl_verify_result_t verify_result_ = ssl_verify_retry;
nharper54fc9ab2020-11-12 11:07:39 -0800202 uint8_t cert_verify_tls_alert_ = SSL_AD_CERTIFICATE_UNKNOWN;
nharpere62aab72020-11-04 16:32:09 -0800203 std::string cert_verify_error_details_;
204
nharper0ab1c662020-11-02 17:05:32 -0800205 int expected_ssl_error_ = SSL_ERROR_WANT_READ;
206 bool is_connection_closed_ = false;
207
QUICHE teama6ef0a62019-03-07 20:34:33 -0500208 QuicCryptoStream* stream_;
renjietangbd33b622020-02-12 16:52:30 -0800209 HandshakerDelegateInterface* handshaker_delegate_;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500210
211 QuicErrorCode parser_error_ = QUIC_NO_ERROR;
vasilvvc48c8712019-03-11 13:38:16 -0700212 std::string parser_error_detail_;
mattm072a7e32020-10-09 16:16:56 -0700213
214 // The most recently derived 1-RTT read and write secrets, which are updated
215 // on each key update.
216 std::vector<uint8_t> latest_read_secret_;
217 std::vector<uint8_t> latest_write_secret_;
218 // 1-RTT header protection keys, which are not changed during key update.
219 std::vector<uint8_t> one_rtt_read_header_protection_key_;
220 std::vector<uint8_t> one_rtt_write_header_protection_key_;
QUICHE teama6ef0a62019-03-07 20:34:33 -0500221};
222
223} // namespace quic
224
225#endif // QUICHE_QUIC_CORE_TLS_HANDSHAKER_H_