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_CRYPTO_HANDSHAKE_H_
6 #define QUICHE_QUIC_CORE_CRYPTO_CRYPTO_HANDSHAKE_H_
7 
8 #include <memory>
9 #include <string>
10 #include <vector>
11 
12 #include "net/third_party/quiche/src/quic/core/quic_packets.h"
13 #include "net/third_party/quiche/src/quic/platform/api/quic_export.h"
14 
15 namespace quic {
16 
17 class CommonCertSets;
18 class SynchronousKeyExchange;
19 class QuicDecrypter;
20 class QuicEncrypter;
21 
22 // HandshakeFailureReason enum values are uploaded to UMA, they cannot be
23 // changed.
24 enum HandshakeFailureReason {
25   HANDSHAKE_OK = 0,
26 
27   // Failure reasons for an invalid client nonce in CHLO.
28   //
29   // The default error value for nonce verification failures from strike
30   // register (covers old strike registers and unknown failures).
31   CLIENT_NONCE_UNKNOWN_FAILURE = 1,
32   // Client nonce had incorrect length.
33   CLIENT_NONCE_INVALID_FAILURE = 2,
34   // Client nonce is not unique.
35   CLIENT_NONCE_NOT_UNIQUE_FAILURE = 3,
36   // Client orbit is invalid or incorrect.
37   CLIENT_NONCE_INVALID_ORBIT_FAILURE = 4,
38   // Client nonce's timestamp is not in the strike register's valid time range.
39   CLIENT_NONCE_INVALID_TIME_FAILURE = 5,
40   // Strike register's RPC call timed out, client nonce couldn't be verified.
41   CLIENT_NONCE_STRIKE_REGISTER_TIMEOUT = 6,
42   // Strike register is down, client nonce couldn't be verified.
43   CLIENT_NONCE_STRIKE_REGISTER_FAILURE = 7,
44 
45   // Failure reasons for an invalid server nonce in CHLO.
46   //
47   // Unbox of server nonce failed.
48   SERVER_NONCE_DECRYPTION_FAILURE = 8,
49   // Decrypted server nonce had incorrect length.
50   SERVER_NONCE_INVALID_FAILURE = 9,
51   // Server nonce is not unique.
52   SERVER_NONCE_NOT_UNIQUE_FAILURE = 10,
53   // Server nonce's timestamp is not in the strike register's valid time range.
54   SERVER_NONCE_INVALID_TIME_FAILURE = 11,
55   // The server requires handshake confirmation.
56   SERVER_NONCE_REQUIRED_FAILURE = 20,
57 
58   // Failure reasons for an invalid server config in CHLO.
59   //
60   // Missing Server config id (kSCID) tag.
61   SERVER_CONFIG_INCHOATE_HELLO_FAILURE = 12,
62   // Couldn't find the Server config id (kSCID).
63   SERVER_CONFIG_UNKNOWN_CONFIG_FAILURE = 13,
64 
65   // Failure reasons for an invalid source-address token.
66   //
67   // Missing Source-address token (kSourceAddressTokenTag) tag.
68   SOURCE_ADDRESS_TOKEN_INVALID_FAILURE = 14,
69   // Unbox of Source-address token failed.
70   SOURCE_ADDRESS_TOKEN_DECRYPTION_FAILURE = 15,
71   // Couldn't parse the unbox'ed Source-address token.
72   SOURCE_ADDRESS_TOKEN_PARSE_FAILURE = 16,
73   // Source-address token is for a different IP address.
74   SOURCE_ADDRESS_TOKEN_DIFFERENT_IP_ADDRESS_FAILURE = 17,
75   // The source-address token has a timestamp in the future.
76   SOURCE_ADDRESS_TOKEN_CLOCK_SKEW_FAILURE = 18,
77   // The source-address token has expired.
78   SOURCE_ADDRESS_TOKEN_EXPIRED_FAILURE = 19,
79 
80   // The expected leaf certificate hash could not be validated.
81   INVALID_EXPECTED_LEAF_CERTIFICATE = 21,
82 
83   MAX_FAILURE_REASON = 22,
84 };
85 
86 // These errors will be packed into an uint32_t and we don't want to set the
87 // most significant bit, which may be misinterpreted as the sign bit.
88 static_assert(MAX_FAILURE_REASON <= 32, "failure reason out of sync");
89 
90 // A CrypterPair contains the encrypter and decrypter for an encryption level.
91 struct QUIC_EXPORT_PRIVATE CrypterPair {
92   CrypterPair();
93   CrypterPair(CrypterPair&&) = default;
94   ~CrypterPair();
95 
96   std::unique_ptr<QuicEncrypter> encrypter;
97   std::unique_ptr<QuicDecrypter> decrypter;
98 };
99 
100 // Parameters negotiated by the crypto handshake.
101 struct QUIC_EXPORT_PRIVATE QuicCryptoNegotiatedParameters
102     : public QuicReferenceCounted {
103   // Initializes the members to 0 or empty values.
104   QuicCryptoNegotiatedParameters();
105 
106   QuicTag key_exchange;
107   QuicTag aead;
108   std::string initial_premaster_secret;
109   std::string forward_secure_premaster_secret;
110   // initial_subkey_secret is used as the PRK input to the HKDF used when
111   // performing key extraction that needs to happen before forward-secure keys
112   // are available.
113   std::string initial_subkey_secret;
114   // subkey_secret is used as the PRK input to the HKDF used for key extraction.
115   std::string subkey_secret;
116   CrypterPair initial_crypters;
117   CrypterPair forward_secure_crypters;
118   // Normalized SNI: converted to lower case and trailing '.' removed.
119   std::string sni;
120   std::string client_nonce;
121   std::string server_nonce;
122   // hkdf_input_suffix contains the HKDF input following the label: the
123   // ConnectionId, client hello and server config. This is only populated in the
124   // client because only the client needs to derive the forward secure keys at a
125   // later time from the initial keys.
126   std::string hkdf_input_suffix;
127   // cached_certs contains the cached certificates that a client used when
128   // sending a client hello.
129   std::vector<std::string> cached_certs;
130   // client_key_exchange is used by clients to store the ephemeral KeyExchange
131   // for the connection.
132   std::unique_ptr<SynchronousKeyExchange> client_key_exchange;
133   // channel_id is set by servers to a ChannelID key when the client correctly
134   // proves possession of the corresponding private key. It consists of 32
135   // bytes of x coordinate, followed by 32 bytes of y coordinate. Both values
136   // are big-endian and the pair is a P-256 public key.
137   std::string channel_id;
138   QuicTag token_binding_key_param;
139 
140   // Used when generating proof signature when sending server config updates.
141 
142   // Used to generate cert chain when sending server config updates.
143   std::string client_common_set_hashes;
144   std::string client_cached_cert_hashes;
145 
146   // Default to false; set to true if the client indicates that it supports sct
147   // by sending CSCT tag with an empty value in client hello.
148   bool sct_supported_by_client;
149 
150   // Parameters only populated for TLS handshakes. These will be 0 for
151   // connections not using TLS, or if the TLS handshake is not finished yet.
152   uint16_t cipher_suite = 0;
153   uint16_t key_exchange_group = 0;
154   uint16_t peer_signature_algorithm = 0;
155 
156  protected:
157   ~QuicCryptoNegotiatedParameters() override;
158 };
159 
160 // QuicCryptoConfig contains common configuration between clients and servers.
161 class QUIC_EXPORT_PRIVATE QuicCryptoConfig {
162  public:
163   // kInitialLabel is a constant that is used when deriving the initial
164   // (non-forward secure) keys for the connection in order to tie the resulting
165   // key to this protocol.
166   static const char kInitialLabel[];
167 
168   // kCETVLabel is a constant that is used when deriving the keys for the
169   // encrypted tag/value block in the client hello.
170   static const char kCETVLabel[];
171 
172   // kForwardSecureLabel is a constant that is used when deriving the forward
173   // secure keys for the connection in order to tie the resulting key to this
174   // protocol.
175   static const char kForwardSecureLabel[];
176 
177   QuicCryptoConfig();
178   QuicCryptoConfig(const QuicCryptoConfig&) = delete;
179   QuicCryptoConfig& operator=(const QuicCryptoConfig&) = delete;
180   ~QuicCryptoConfig();
181 
182   // Key exchange methods. The following two members' values correspond by
183   // index.
184   QuicTagVector kexs;
185   // Authenticated encryption with associated data (AEAD) algorithms.
186   QuicTagVector aead;
187 
188   const CommonCertSets* common_cert_sets;
189 };
190 
191 }  // namespace quic
192 
193 #endif  // QUICHE_QUIC_CORE_CRYPTO_CRYPTO_HANDSHAKE_H_
194