quic_framer.h revision 1e9bf3e0803691d0a228da41fc608347b6db4340
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 NET_QUIC_QUIC_FRAMER_H_ 6#define NET_QUIC_QUIC_FRAMER_H_ 7 8#include <vector> 9 10#include "base/basictypes.h" 11#include "base/logging.h" 12#include "base/memory/scoped_ptr.h" 13#include "base/strings/string_piece.h" 14#include "net/base/net_export.h" 15#include "net/quic/quic_protocol.h" 16 17namespace net { 18 19namespace test { 20class QuicFramerPeer; 21} // namespace test 22 23class QuicDataReader; 24class QuicDataWriter; 25class QuicDecrypter; 26class QuicEncrypter; 27class QuicFramer; 28 29// Number of bytes reserved for the frame type preceding each frame. 30const size_t kQuicFrameTypeSize = 1; 31// Number of bytes reserved for error code. 32const size_t kQuicErrorCodeSize = 4; 33// Number of bytes reserved to denote the length of error details field. 34const size_t kQuicErrorDetailsLengthSize = 2; 35 36// Maximum number of bytes reserved for stream id. 37const size_t kQuicMaxStreamIdSize = 4; 38// Maximum number of bytes reserved for byte offset in stream frame. 39const size_t kQuicMaxStreamOffsetSize = 8; 40// Number of bytes reserved to store payload length in stream frame. 41const size_t kQuicStreamPayloadLengthSize = 2; 42 43// Size in bytes of the entropy hash sent in ack frames. 44const size_t kQuicEntropyHashSize = 1; 45// Size in bytes reserved for the delta time of the largest observed 46// sequence number in ack frames. 47const size_t kQuicDeltaTimeLargestObservedSize = 4; 48// Size in bytes reserved for the number of missing packets in ack frames. 49const size_t kNumberOfMissingPacketsSize = 1; 50 51// This class receives callbacks from the framer when packets 52// are processed. 53class NET_EXPORT_PRIVATE QuicFramerVisitorInterface { 54 public: 55 virtual ~QuicFramerVisitorInterface() {} 56 57 // Called if an error is detected in the QUIC protocol. 58 virtual void OnError(QuicFramer* framer) = 0; 59 60 // Called only when |is_server_| is true and the the framer gets a packet with 61 // version flag true and the version on the packet doesn't match 62 // |quic_version_|. The visitor should return true after it updates the 63 // version of the |framer_| to |received_version| or false to stop processing 64 // this packet. 65 virtual bool OnProtocolVersionMismatch(QuicVersion received_version) = 0; 66 67 // Called when a new packet has been received, before it 68 // has been validated or processed. 69 virtual void OnPacket() = 0; 70 71 // Called when a public reset packet has been parsed but has not yet 72 // been validated. 73 virtual void OnPublicResetPacket( 74 const QuicPublicResetPacket& packet) = 0; 75 76 // Called only when |is_server_| is false and a version negotiation packet has 77 // been parsed. 78 virtual void OnVersionNegotiationPacket( 79 const QuicVersionNegotiationPacket& packet) = 0; 80 81 // Called when a lost packet has been recovered via FEC, 82 // before it has been processed. 83 virtual void OnRevivedPacket() = 0; 84 85 // Called when the complete header of a packet had been parsed. 86 // If OnPacketHeader returns false, framing for this packet will cease. 87 virtual bool OnPacketHeader(const QuicPacketHeader& header) = 0; 88 89 // Called when a data packet is parsed that is part of an FEC group. 90 // |payload| is the non-encrypted FEC protected payload of the packet. 91 virtual void OnFecProtectedPayload(base::StringPiece payload) = 0; 92 93 // Called when a StreamFrame has been parsed. 94 virtual bool OnStreamFrame(const QuicStreamFrame& frame) = 0; 95 96 // Called when a AckFrame has been parsed. If OnAckFrame returns false, 97 // the framer will stop parsing the current packet. 98 virtual bool OnAckFrame(const QuicAckFrame& frame) = 0; 99 100 // Called when a CongestionFeedbackFrame has been parsed. 101 virtual bool OnCongestionFeedbackFrame( 102 const QuicCongestionFeedbackFrame& frame) = 0; 103 104 // Called when a RstStreamFrame has been parsed. 105 virtual bool OnRstStreamFrame(const QuicRstStreamFrame& frame) = 0; 106 107 // Called when a ConnectionCloseFrame has been parsed. 108 virtual bool OnConnectionCloseFrame( 109 const QuicConnectionCloseFrame& frame) = 0; 110 111 // Called when a GoAwayFrame has been parsed. 112 virtual bool OnGoAwayFrame(const QuicGoAwayFrame& frame) = 0; 113 114 // Called when FEC data has been parsed. 115 virtual void OnFecData(const QuicFecData& fec) = 0; 116 117 // Called when a packet has been completely processed. 118 virtual void OnPacketComplete() = 0; 119}; 120 121class NET_EXPORT_PRIVATE QuicFecBuilderInterface { 122 public: 123 virtual ~QuicFecBuilderInterface() {} 124 125 // Called when a data packet is constructed that is part of an FEC group. 126 // |payload| is the non-encrypted FEC protected payload of the packet. 127 virtual void OnBuiltFecProtectedPayload(const QuicPacketHeader& header, 128 base::StringPiece payload) = 0; 129}; 130 131// This class calculates the received entropy of the ack packet being 132// framed, should it get truncated. 133class NET_EXPORT_PRIVATE QuicReceivedEntropyHashCalculatorInterface { 134 public: 135 virtual ~QuicReceivedEntropyHashCalculatorInterface() {} 136 137 // When an ack frame gets truncated while being framed the received 138 // entropy of the ack frame needs to be calculated since the some of the 139 // missing packets are not added and the largest observed might be lowered. 140 // This should return the received entropy hash of the packets received up to 141 // and including |sequence_number|. 142 virtual QuicPacketEntropyHash EntropyHash( 143 QuicPacketSequenceNumber sequence_number) const = 0; 144}; 145 146// Class for parsing and constructing QUIC packets. It has a 147// QuicFramerVisitorInterface that is called when packets are parsed. 148// It also has a QuicFecBuilder that is called when packets are constructed 149// in order to generate FEC data for subsequently building FEC packets. 150class NET_EXPORT_PRIVATE QuicFramer { 151 public: 152 // Constructs a new framer that installs a kNULL QuicEncrypter and 153 // QuicDecrypter for level ENCRYPTION_NONE. |supported_versions| specifies the 154 // list of supported QUIC versions. |quic_version_| is set to the maximum 155 // version in |supported_versions|. 156 QuicFramer(const QuicVersionVector& supported_versions, 157 QuicTime creation_time, 158 bool is_server); 159 160 virtual ~QuicFramer(); 161 162 // Returns true if |version| is a supported protocol version. 163 bool IsSupportedVersion(const QuicVersion version) const; 164 165 // Calculates the largest observed packet to advertise in the case an Ack 166 // Frame was truncated. last_written in this case is the iterator for the 167 // last missing packet which fit in the outgoing ack. 168 static QuicPacketSequenceNumber CalculateLargestObserved( 169 const SequenceNumberSet& missing_packets, 170 SequenceNumberSet::const_iterator last_written); 171 172 // Set callbacks to be called from the framer. A visitor must be set, or 173 // else the framer will likely crash. It is acceptable for the visitor 174 // to do nothing. If this is called multiple times, only the last visitor 175 // will be used. 176 void set_visitor(QuicFramerVisitorInterface* visitor) { 177 visitor_ = visitor; 178 } 179 180 // Set a builder to be called from the framer when building FEC protected 181 // packets. If this is called multiple times, only the last builder 182 // will be used. The builder need not be set. 183 void set_fec_builder(QuicFecBuilderInterface* builder) { 184 fec_builder_ = builder; 185 } 186 187 const QuicVersionVector& supported_versions() const { 188 return supported_versions_; 189 } 190 191 QuicVersion version() const { 192 return quic_version_; 193 } 194 195 void set_version(const QuicVersion version); 196 197 // Does not DCHECK for supported version. Used by tests to set unsupported 198 // version to trigger version negotiation. 199 void set_version_for_tests(const QuicVersion version) { 200 quic_version_ = version; 201 } 202 203 // Set entropy calculator to be called from the framer when it needs the 204 // entropy of a truncated ack frame. An entropy calculator must be set or else 205 // the framer will likely crash. If this is called multiple times, only the 206 // last calculator will be used. 207 void set_received_entropy_calculator( 208 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator) { 209 entropy_calculator_ = entropy_calculator; 210 } 211 212 QuicErrorCode error() const { 213 return error_; 214 } 215 216 // Pass a UDP packet into the framer for parsing. 217 // Return true if the packet was processed succesfully. |packet| must be a 218 // single, complete UDP packet (not a frame of a packet). This packet 219 // might be null padded past the end of the payload, which will be correctly 220 // ignored. 221 bool ProcessPacket(const QuicEncryptedPacket& packet); 222 223 // Pass a data packet that was revived from FEC data into the framer 224 // for parsing. 225 // Return true if the packet was processed succesfully. |payload| must be 226 // the complete DECRYPTED payload of the revived packet. 227 bool ProcessRevivedPacket(QuicPacketHeader* header, 228 base::StringPiece payload); 229 230 // Largest size in bytes of all stream frame fields without the payload. 231 static size_t GetMinStreamFrameSize(QuicVersion version, 232 QuicStreamId stream_id, 233 QuicStreamOffset offset, 234 bool last_frame_in_packet); 235 // Size in bytes of all ack frame fields without the missing packets. 236 static size_t GetMinAckFrameSize(); 237 // Size in bytes of all reset stream frame without the error details. 238 static size_t GetMinRstStreamFrameSize(); 239 // Size in bytes of all connection close frame fields without the error 240 // details and the missing packets from the enclosed ack frame. 241 static size_t GetMinConnectionCloseFrameSize(); 242 // Size in bytes of all GoAway frame fields without the reason phrase. 243 static size_t GetMinGoAwayFrameSize(); 244 // The maximum number of nacks which can be transmitted in a single ack packet 245 // without exceeding kMaxPacketSize. 246 static size_t GetMaxUnackedPackets(QuicPacketHeader header); 247 // Size in bytes required to serialize the stream id. 248 static size_t GetStreamIdSize(QuicStreamId stream_id); 249 // Size in bytes required to serialize the stream offset. 250 static size_t GetStreamOffsetSize(QuicStreamOffset offset); 251 // Size in bytes required for a serialized version negotiation packet 252 static size_t GetVersionNegotiationPacketSize(size_t number_versions); 253 254 255 static bool CanTruncate(const QuicFrame& frame, size_t free_bytes); 256 257 // Returns the number of bytes added to the packet for the specified frame, 258 // and 0 if the frame doesn't fit. Includes the header size for the first 259 // frame. 260 size_t GetSerializedFrameLength(const QuicFrame& frame, 261 size_t free_bytes, 262 bool first_frame, 263 bool last_frame); 264 265 // Returns the associated data from the encrypted packet |encrypted| as a 266 // stringpiece. 267 static base::StringPiece GetAssociatedDataFromEncryptedPacket( 268 const QuicEncryptedPacket& encrypted, 269 QuicGuidLength guid_length, 270 bool includes_version, 271 QuicSequenceNumberLength sequence_number_length); 272 273 // Returns a SerializedPacket whose |packet| member is owned by the caller, 274 // and is populated with the fields in |header| and |frames|, or is NULL if 275 // the packet could not be created. 276 // TODO(ianswett): Used for testing only. 277 SerializedPacket BuildUnsizedDataPacket(const QuicPacketHeader& header, 278 const QuicFrames& frames); 279 280 // Returns a SerializedPacket whose |packet| member is owned by the caller, 281 // is created from the first |num_frames| frames, or is NULL if the packet 282 // could not be created. The packet must be of size |packet_size|. 283 SerializedPacket BuildDataPacket(const QuicPacketHeader& header, 284 const QuicFrames& frames, 285 size_t packet_size); 286 287 // Returns a SerializedPacket whose |packet| member is owned by the caller, 288 // and is populated with the fields in |header| and |fec|, or is NULL if the 289 // packet could not be created. 290 SerializedPacket BuildFecPacket(const QuicPacketHeader& header, 291 const QuicFecData& fec); 292 293 // Returns a new public reset packet, owned by the caller. 294 static QuicEncryptedPacket* BuildPublicResetPacket( 295 const QuicPublicResetPacket& packet); 296 297 QuicEncryptedPacket* BuildVersionNegotiationPacket( 298 const QuicPacketPublicHeader& header, 299 const QuicVersionVector& supported_versions); 300 301 // SetDecrypter sets the primary decrypter, replacing any that already exists, 302 // and takes ownership. If an alternative decrypter is in place then the 303 // function DCHECKs. This is intended for cases where one knows that future 304 // packets will be using the new decrypter and the previous decrypter is not 305 // obsolete. 306 void SetDecrypter(QuicDecrypter* decrypter); 307 308 // SetAlternativeDecrypter sets a decrypter that may be used to decrypt 309 // future packets and takes ownership of it. If |latch_once_used| is true, 310 // then the first time that the decrypter is successful it will replace the 311 // primary decrypter. Otherwise both decrypters will remain active and the 312 // primary decrypter will be the one last used. 313 void SetAlternativeDecrypter(QuicDecrypter* decrypter, 314 bool latch_once_used); 315 316 const QuicDecrypter* decrypter() const; 317 const QuicDecrypter* alternative_decrypter() const; 318 319 // Changes the encrypter used for level |level| to |encrypter|. The function 320 // takes ownership of |encrypter|. 321 void SetEncrypter(EncryptionLevel level, QuicEncrypter* encrypter); 322 const QuicEncrypter* encrypter(EncryptionLevel level) const; 323 324 // SwapCryptersForTest exchanges the state of the crypters with |other|. To 325 // be used in tests only. 326 void SwapCryptersForTest(QuicFramer* other); 327 328 // Returns a new encrypted packet, owned by the caller. 329 QuicEncryptedPacket* EncryptPacket(EncryptionLevel level, 330 QuicPacketSequenceNumber sequence_number, 331 const QuicPacket& packet); 332 333 // Returns the maximum length of plaintext that can be encrypted 334 // to ciphertext no larger than |ciphertext_size|. 335 size_t GetMaxPlaintextSize(size_t ciphertext_size); 336 337 const std::string& detailed_error() { return detailed_error_; } 338 339 // Read the full 8 byte guid from a packet header. 340 // Return true on success, else false. 341 static bool ReadGuidFromPacket(const QuicEncryptedPacket& packet, 342 QuicGuid* guid); 343 344 private: 345 friend class test::QuicFramerPeer; 346 347 QuicPacketEntropyHash GetPacketEntropyHash( 348 const QuicPacketHeader& header) const; 349 350 bool ProcessDataPacket(const QuicPacketPublicHeader& public_header, 351 const QuicEncryptedPacket& packet); 352 353 bool ProcessPublicResetPacket(const QuicPacketPublicHeader& public_header); 354 355 bool ProcessVersionNegotiationPacket(QuicPacketPublicHeader* public_header); 356 357 bool WritePacketHeader(const QuicPacketHeader& header, 358 QuicDataWriter* writer); 359 360 bool ProcessPublicHeader(QuicPacketPublicHeader* header); 361 362 bool ProcessPacketHeader(QuicPacketHeader* header, 363 const QuicEncryptedPacket& packet); 364 365 bool ProcessPacketSequenceNumber( 366 QuicSequenceNumberLength sequence_number_length, 367 QuicPacketSequenceNumber* sequence_number); 368 bool ProcessFrameData(); 369 bool ProcessStreamFrame(uint8 frame_type, QuicStreamFrame* frame); 370 bool ProcessAckFrame(QuicAckFrame* frame); 371 bool ProcessReceivedInfo(ReceivedPacketInfo* received_info); 372 bool ProcessSentInfo(SentPacketInfo* sent_info); 373 bool ProcessQuicCongestionFeedbackFrame( 374 QuicCongestionFeedbackFrame* congestion_feedback); 375 bool ProcessRstStreamFrame(QuicRstStreamFrame* frame); 376 bool ProcessConnectionCloseFrame(QuicConnectionCloseFrame* frame); 377 bool ProcessGoAwayFrame(QuicGoAwayFrame* frame); 378 379 bool DecryptPayload(const QuicPacketHeader& header, 380 const QuicEncryptedPacket& packet); 381 382 // Returns the full packet sequence number from the truncated 383 // wire format version and the last seen packet sequence number. 384 QuicPacketSequenceNumber CalculatePacketSequenceNumberFromWire( 385 QuicSequenceNumberLength sequence_number_length, 386 QuicPacketSequenceNumber packet_sequence_number) const; 387 388 // Computes the wire size in bytes of the payload of |frame|. 389 size_t ComputeFrameLength(const QuicFrame& frame, bool last_frame_in_packet); 390 391 static bool AppendPacketSequenceNumber( 392 QuicSequenceNumberLength sequence_number_length, 393 QuicPacketSequenceNumber packet_sequence_number, 394 QuicDataWriter* writer); 395 396 bool AppendTypeByte(const QuicFrame& frame, 397 bool last_frame_in_packet, 398 QuicDataWriter* writer); 399 bool AppendStreamFramePayload(const QuicStreamFrame& frame, 400 bool last_frame_in_packet, 401 QuicDataWriter* builder); 402 bool AppendAckFramePayload(const QuicAckFrame& frame, 403 QuicDataWriter* builder); 404 bool AppendQuicCongestionFeedbackFramePayload( 405 const QuicCongestionFeedbackFrame& frame, 406 QuicDataWriter* builder); 407 bool AppendRstStreamFramePayload(const QuicRstStreamFrame& frame, 408 QuicDataWriter* builder); 409 bool AppendConnectionCloseFramePayload( 410 const QuicConnectionCloseFrame& frame, 411 QuicDataWriter* builder); 412 bool AppendGoAwayFramePayload(const QuicGoAwayFrame& frame, 413 QuicDataWriter* writer); 414 bool RaiseError(QuicErrorCode error); 415 416 void set_error(QuicErrorCode error) { 417 error_ = error; 418 } 419 420 void set_detailed_error(const char* error) { 421 detailed_error_ = error; 422 } 423 424 std::string detailed_error_; 425 scoped_ptr<QuicDataReader> reader_; 426 QuicFramerVisitorInterface* visitor_; 427 QuicFecBuilderInterface* fec_builder_; 428 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator_; 429 QuicErrorCode error_; 430 // Updated by ProcessPacketHeader when it succeeds. 431 QuicPacketSequenceNumber last_sequence_number_; 432 // Updated by WritePacketHeader. 433 QuicGuid last_serialized_guid_; 434 // Buffer containing decrypted payload data during parsing. 435 scoped_ptr<QuicData> decrypted_; 436 // Version of the protocol being used. 437 QuicVersion quic_version_; 438 // This vector contains QUIC versions which we currently support. 439 // This should be ordered such that the highest supported version is the first 440 // element, with subsequent elements in descending order (versions can be 441 // skipped as necessary). 442 QuicVersionVector supported_versions_; 443 // Primary decrypter used to decrypt packets during parsing. 444 scoped_ptr<QuicDecrypter> decrypter_; 445 // Alternative decrypter that can also be used to decrypt packets. 446 scoped_ptr<QuicDecrypter> alternative_decrypter_; 447 // alternative_decrypter_latch_is true if, when |alternative_decrypter_| 448 // successfully decrypts a packet, we should install it as the only 449 // decrypter. 450 bool alternative_decrypter_latch_; 451 // Encrypters used to encrypt packets via EncryptPacket(). 452 scoped_ptr<QuicEncrypter> encrypter_[NUM_ENCRYPTION_LEVELS]; 453 // Tracks if the framer is being used by the entity that received the 454 // connection or the entity that initiated it. 455 bool is_server_; 456 // The time this frames was created. Time written to the wire will be 457 // written as a delta from this value. 458 QuicTime creation_time_; 459 460 DISALLOW_COPY_AND_ASSIGN(QuicFramer); 461}; 462 463} // namespace net 464 465#endif // NET_QUIC_QUIC_FRAMER_H_ 466