1 // Copyright (c) 2012 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_QUIC_CRYPTER_H_ 6 #define QUICHE_QUIC_CORE_CRYPTO_QUIC_CRYPTER_H_ 7 8 #include "absl/strings/string_view.h" 9 #include "quiche/quic/core/quic_versions.h" 10 #include "quiche/quic/platform/api/quic_export.h" 11 12 namespace quic { 13 14 // QuicCrypter is the parent class for QuicEncrypter and QuicDecrypter. 15 // Its purpose is to provide an interface for using methods that are common to 16 // both classes when operations are being done that apply to both encrypters and 17 // decrypters. 18 class QUICHE_EXPORT QuicCrypter { 19 public: ~QuicCrypter()20 virtual ~QuicCrypter() {} 21 22 // Sets the symmetric encryption/decryption key. Returns true on success, 23 // false on failure. 24 // 25 // NOTE: The key is the client_write_key or server_write_key derived from 26 // the master secret. 27 virtual bool SetKey(absl::string_view key) = 0; 28 29 // Sets the fixed initial bytes of the nonce. Returns true on success, 30 // false on failure. This method must only be used with Google QUIC crypters. 31 // 32 // NOTE: The nonce prefix is the client_write_iv or server_write_iv 33 // derived from the master secret. A 64-bit packet number will 34 // be appended to form the nonce. 35 // 36 // <------------ 64 bits -----------> 37 // +---------------------+----------------------------------+ 38 // | Fixed prefix | packet number | 39 // +---------------------+----------------------------------+ 40 // Nonce format 41 // 42 // The security of the nonce format requires that QUIC never reuse a 43 // packet number, even when retransmitting a lost packet. 44 virtual bool SetNoncePrefix(absl::string_view nonce_prefix) = 0; 45 46 // Sets |iv| as the initialization vector to use when constructing the nonce. 47 // Returns true on success, false on failure. This method must only be used 48 // with IETF QUIC crypters. 49 // 50 // Google QUIC and IETF QUIC use different nonce constructions. This method 51 // must be used when using IETF QUIC; SetNoncePrefix must be used when using 52 // Google QUIC. 53 // 54 // The nonce is constructed as follows (draft-ietf-quic-tls-14 section 5.2): 55 // 56 // <---------------- max(8, N_MIN) bytes -----------------> 57 // +--------------------------------------------------------+ 58 // | packet protection IV | 59 // +--------------------------------------------------------+ 60 // XOR 61 // <------------ 64 bits -----------> 62 // +---------------------+----------------------------------+ 63 // | zeroes | reconstructed packet number | 64 // +---------------------+----------------------------------+ 65 // 66 // The nonce is the packet protection IV (|iv|) XOR'd with the left-padded 67 // reconstructed packet number. 68 // 69 // The security of the nonce format requires that QUIC never reuse a 70 // packet number, even when retransmitting a lost packet. 71 virtual bool SetIV(absl::string_view iv) = 0; 72 73 // Calls SetNoncePrefix or SetIV depending on whether |version| uses the 74 // Google QUIC crypto or IETF QUIC nonce construction. 75 virtual bool SetNoncePrefixOrIV(const ParsedQuicVersion& version, 76 absl::string_view nonce_prefix_or_iv); 77 78 // Sets the key to use for header protection. 79 virtual bool SetHeaderProtectionKey(absl::string_view key) = 0; 80 81 // GetKeySize, GetIVSize, and GetNoncePrefixSize are used to know how many 82 // bytes of key material needs to be derived from the master secret. 83 84 // Returns the size in bytes of a key for the algorithm. 85 virtual size_t GetKeySize() const = 0; 86 // Returns the size in bytes of an IV to use with the algorithm. 87 virtual size_t GetIVSize() const = 0; 88 // Returns the size in bytes of the fixed initial part of the nonce. 89 virtual size_t GetNoncePrefixSize() const = 0; 90 }; 91 92 } // namespace quic 93 94 #endif // QUICHE_QUIC_CORE_CRYPTO_QUIC_CRYPTER_H_ 95