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.
5 #ifndef NET_QUIC_QUIC_FRAMER_H_
6 #define NET_QUIC_QUIC_FRAMER_H_
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"
29 // Number of bytes reserved for the frame type preceding each frame.
30 const size_t kQuicFrameTypeSize = 1;
31 // Number of bytes reserved for error code.
32 const size_t kQuicErrorCodeSize = 4;
33 // Number of bytes reserved to denote the length of error details field.
34 const size_t kQuicErrorDetailsLengthSize = 2;
36 // Maximum number of bytes reserved for stream id.
37 const size_t kQuicMaxStreamIdSize = 4;
38 // Maximum number of bytes reserved for byte offset in stream frame.
39 const size_t kQuicMaxStreamOffsetSize = 8;
40 // Number of bytes reserved to store payload length in stream frame.
41 const size_t kQuicStreamPayloadLengthSize = 2;
43 // Size in bytes of the entropy hash sent in ack frames.
44 const size_t kQuicEntropyHashSize = 1;
45 // Size in bytes reserved for the delta time of the largest observed
46 // sequence number in ack frames.
47 // TODO(ianswett): Remove this once QUIC_VERSION_11 is removed.
48 const size_t kQuicv11DeltaTimeLargestObservedSize = 4;
49 const size_t kQuicDeltaTimeLargestObservedSize = 2;
50 // Size in bytes reserved for the number of missing packets in ack frames.
51 const size_t kNumberOfMissingPacketsSize = 1;
53 // This class receives callbacks from the framer when packets
55 class NET_EXPORT_PRIVATE QuicFramerVisitorInterface {
57 virtual ~QuicFramerVisitorInterface() {}
59 // Called if an error is detected in the QUIC protocol.
60 virtual void OnError(QuicFramer* framer) = 0;
62 // Called only when |is_server_| is true and the the framer gets a packet with
63 // version flag true and the version on the packet doesn't match
64 // |quic_version_|. The visitor should return true after it updates the
65 // version of the |framer_| to |received_version| or false to stop processing
67 virtual bool OnProtocolVersionMismatch(QuicVersion received_version) = 0;
69 // Called when a new packet has been received, before it
70 // has been validated or processed.
71 virtual void OnPacket() = 0;
73 // Called when a public reset packet has been parsed but has not yet
75 virtual void OnPublicResetPacket(
76 const QuicPublicResetPacket& packet) = 0;
78 // Called only when |is_server_| is false and a version negotiation packet has
80 virtual void OnVersionNegotiationPacket(
81 const QuicVersionNegotiationPacket& packet) = 0;
83 // Called when a lost packet has been recovered via FEC,
84 // before it has been processed.
85 virtual void OnRevivedPacket() = 0;
87 // Called when the complete header of a packet had been parsed.
88 // If OnPacketHeader returns false, framing for this packet will cease.
89 virtual bool OnPacketHeader(const QuicPacketHeader& header) = 0;
91 // Called when a data packet is parsed that is part of an FEC group.
92 // |payload| is the non-encrypted FEC protected payload of the packet.
93 virtual void OnFecProtectedPayload(base::StringPiece payload) = 0;
95 // Called when a StreamFrame has been parsed.
96 virtual bool OnStreamFrame(const QuicStreamFrame& frame) = 0;
98 // Called when a AckFrame has been parsed. If OnAckFrame returns false,
99 // the framer will stop parsing the current packet.
100 virtual bool OnAckFrame(const QuicAckFrame& frame) = 0;
102 // Called when a CongestionFeedbackFrame has been parsed.
103 virtual bool OnCongestionFeedbackFrame(
104 const QuicCongestionFeedbackFrame& frame) = 0;
106 // Called when a RstStreamFrame has been parsed.
107 virtual bool OnRstStreamFrame(const QuicRstStreamFrame& frame) = 0;
109 // Called when a ConnectionCloseFrame has been parsed.
110 virtual bool OnConnectionCloseFrame(
111 const QuicConnectionCloseFrame& frame) = 0;
113 // Called when a GoAwayFrame has been parsed.
114 virtual bool OnGoAwayFrame(const QuicGoAwayFrame& frame) = 0;
116 // Called when FEC data has been parsed.
117 virtual void OnFecData(const QuicFecData& fec) = 0;
119 // Called when a packet has been completely processed.
120 virtual void OnPacketComplete() = 0;
123 class NET_EXPORT_PRIVATE QuicFecBuilderInterface {
125 virtual ~QuicFecBuilderInterface() {}
127 // Called when a data packet is constructed that is part of an FEC group.
128 // |payload| is the non-encrypted FEC protected payload of the packet.
129 virtual void OnBuiltFecProtectedPayload(const QuicPacketHeader& header,
130 base::StringPiece payload) = 0;
133 // This class calculates the received entropy of the ack packet being
134 // framed, should it get truncated.
135 class NET_EXPORT_PRIVATE QuicReceivedEntropyHashCalculatorInterface {
137 virtual ~QuicReceivedEntropyHashCalculatorInterface() {}
139 // When an ack frame gets truncated while being framed the received
140 // entropy of the ack frame needs to be calculated since the some of the
141 // missing packets are not added and the largest observed might be lowered.
142 // This should return the received entropy hash of the packets received up to
143 // and including |sequence_number|.
144 virtual QuicPacketEntropyHash EntropyHash(
145 QuicPacketSequenceNumber sequence_number) const = 0;
148 // Class for parsing and constructing QUIC packets. It has a
149 // QuicFramerVisitorInterface that is called when packets are parsed.
150 // It also has a QuicFecBuilder that is called when packets are constructed
151 // in order to generate FEC data for subsequently building FEC packets.
152 class NET_EXPORT_PRIVATE QuicFramer {
154 // Constructs a new framer that installs a kNULL QuicEncrypter and
155 // QuicDecrypter for level ENCRYPTION_NONE. |supported_versions| specifies the
156 // list of supported QUIC versions. |quic_version_| is set to the maximum
157 // version in |supported_versions|.
158 QuicFramer(const QuicVersionVector& supported_versions,
159 QuicTime creation_time,
162 virtual ~QuicFramer();
164 // Returns true if |version| is a supported protocol version.
165 bool IsSupportedVersion(const QuicVersion version) const;
167 // Calculates the largest observed packet to advertise in the case an Ack
168 // Frame was truncated. last_written in this case is the iterator for the
169 // last missing packet which fit in the outgoing ack.
170 static QuicPacketSequenceNumber CalculateLargestObserved(
171 const SequenceNumberSet& missing_packets,
172 SequenceNumberSet::const_iterator last_written);
174 // Set callbacks to be called from the framer. A visitor must be set, or
175 // else the framer will likely crash. It is acceptable for the visitor
176 // to do nothing. If this is called multiple times, only the last visitor
178 void set_visitor(QuicFramerVisitorInterface* visitor) {
182 // Set a builder to be called from the framer when building FEC protected
183 // packets. If this is called multiple times, only the last builder
184 // will be used. The builder need not be set.
185 void set_fec_builder(QuicFecBuilderInterface* builder) {
186 fec_builder_ = builder;
189 const QuicVersionVector& supported_versions() const {
190 return supported_versions_;
193 QuicVersion version() const {
194 return quic_version_;
197 void set_version(const QuicVersion version);
199 // Does not DCHECK for supported version. Used by tests to set unsupported
200 // version to trigger version negotiation.
201 void set_version_for_tests(const QuicVersion version) {
202 quic_version_ = version;
205 // Set entropy calculator to be called from the framer when it needs the
206 // entropy of a truncated ack frame. An entropy calculator must be set or else
207 // the framer will likely crash. If this is called multiple times, only the
208 // last calculator will be used.
209 void set_received_entropy_calculator(
210 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator) {
211 entropy_calculator_ = entropy_calculator;
214 QuicErrorCode error() const {
218 // Pass a UDP packet into the framer for parsing.
219 // Return true if the packet was processed succesfully. |packet| must be a
220 // single, complete UDP packet (not a frame of a packet). This packet
221 // might be null padded past the end of the payload, which will be correctly
223 bool ProcessPacket(const QuicEncryptedPacket& packet);
225 // Pass a data packet that was revived from FEC data into the framer
227 // Return true if the packet was processed succesfully. |payload| must be
228 // the complete DECRYPTED payload of the revived packet.
229 bool ProcessRevivedPacket(QuicPacketHeader* header,
230 base::StringPiece payload);
232 // Largest size in bytes of all stream frame fields without the payload.
233 static size_t GetMinStreamFrameSize(QuicVersion version,
234 QuicStreamId stream_id,
235 QuicStreamOffset offset,
236 bool last_frame_in_packet);
237 // Size in bytes of all ack frame fields without the missing packets.
238 // TODO(ianswett): Remove this once QUIC_VERSION_11 is removed.
239 static size_t GetMinAckFrameSizev11();
240 static size_t GetMinAckFrameSize(
242 QuicSequenceNumberLength sequence_number_length,
243 QuicSequenceNumberLength largest_observed_length);
244 // Size in bytes of all reset stream frame without the error details.
245 static size_t GetMinRstStreamFrameSize();
246 // Size in bytes of all connection close frame fields without the error
247 // details and the missing packets from the enclosed ack frame.
248 static size_t GetMinConnectionCloseFrameSize();
249 // Size in bytes of all GoAway frame fields without the reason phrase.
250 static size_t GetMinGoAwayFrameSize();
251 // The maximum number of nacks which can be transmitted in a single ack packet
252 // without exceeding kDefaultMaxPacketSize.
253 static size_t GetMaxUnackedPackets(QuicPacketHeader header);
254 // Size in bytes required to serialize the stream id.
255 static size_t GetStreamIdSize(QuicStreamId stream_id);
256 // Size in bytes required to serialize the stream offset.
257 static size_t GetStreamOffsetSize(QuicStreamOffset offset);
258 // Size in bytes required for a serialized version negotiation packet
259 static size_t GetVersionNegotiationPacketSize(size_t number_versions);
262 static bool CanTruncate(
263 QuicVersion version, const QuicFrame& frame, size_t free_bytes);
265 // Returns the number of bytes added to the packet for the specified frame,
266 // and 0 if the frame doesn't fit. Includes the header size for the first
268 size_t GetSerializedFrameLength(
269 const QuicFrame& frame,
273 QuicSequenceNumberLength sequence_number_length);
275 // Returns the associated data from the encrypted packet |encrypted| as a
277 static base::StringPiece GetAssociatedDataFromEncryptedPacket(
278 const QuicEncryptedPacket& encrypted,
279 QuicGuidLength guid_length,
280 bool includes_version,
281 QuicSequenceNumberLength sequence_number_length);
283 // Returns a SerializedPacket whose |packet| member is owned by the caller,
284 // and is populated with the fields in |header| and |frames|, or is NULL if
285 // the packet could not be created.
286 // TODO(ianswett): Used for testing only.
287 SerializedPacket BuildUnsizedDataPacket(const QuicPacketHeader& header,
288 const QuicFrames& frames);
290 // Returns a SerializedPacket whose |packet| member is owned by the caller,
291 // is created from the first |num_frames| frames, or is NULL if the packet
292 // could not be created. The packet must be of size |packet_size|.
293 SerializedPacket BuildDataPacket(const QuicPacketHeader& header,
294 const QuicFrames& frames,
297 // Returns a SerializedPacket whose |packet| member is owned by the caller,
298 // and is populated with the fields in |header| and |fec|, or is NULL if the
299 // packet could not be created.
300 SerializedPacket BuildFecPacket(const QuicPacketHeader& header,
301 const QuicFecData& fec);
303 // Returns a new public reset packet, owned by the caller.
304 static QuicEncryptedPacket* BuildPublicResetPacket(
305 const QuicPublicResetPacket& packet);
307 QuicEncryptedPacket* BuildVersionNegotiationPacket(
308 const QuicPacketPublicHeader& header,
309 const QuicVersionVector& supported_versions);
311 // SetDecrypter sets the primary decrypter, replacing any that already exists,
312 // and takes ownership. If an alternative decrypter is in place then the
313 // function DCHECKs. This is intended for cases where one knows that future
314 // packets will be using the new decrypter and the previous decrypter is not
316 void SetDecrypter(QuicDecrypter* decrypter);
318 // SetAlternativeDecrypter sets a decrypter that may be used to decrypt
319 // future packets and takes ownership of it. If |latch_once_used| is true,
320 // then the first time that the decrypter is successful it will replace the
321 // primary decrypter. Otherwise both decrypters will remain active and the
322 // primary decrypter will be the one last used.
323 void SetAlternativeDecrypter(QuicDecrypter* decrypter,
324 bool latch_once_used);
326 const QuicDecrypter* decrypter() const;
327 const QuicDecrypter* alternative_decrypter() const;
329 // Changes the encrypter used for level |level| to |encrypter|. The function
330 // takes ownership of |encrypter|.
331 void SetEncrypter(EncryptionLevel level, QuicEncrypter* encrypter);
332 const QuicEncrypter* encrypter(EncryptionLevel level) const;
334 // SwapCryptersForTest exchanges the state of the crypters with |other|. To
335 // be used in tests only.
336 void SwapCryptersForTest(QuicFramer* other);
338 // Returns a new encrypted packet, owned by the caller.
339 QuicEncryptedPacket* EncryptPacket(EncryptionLevel level,
340 QuicPacketSequenceNumber sequence_number,
341 const QuicPacket& packet);
343 // Returns the maximum length of plaintext that can be encrypted
344 // to ciphertext no larger than |ciphertext_size|.
345 size_t GetMaxPlaintextSize(size_t ciphertext_size);
347 const std::string& detailed_error() { return detailed_error_; }
349 // Read the full 8 byte guid from a packet header.
350 // Return true on success, else false.
351 static bool ReadGuidFromPacket(const QuicEncryptedPacket& packet,
354 static QuicSequenceNumberLength ReadSequenceNumberLength(uint8 flags);
356 // The minimum sequence number length required to represent |sequence_number|.
357 static QuicSequenceNumberLength GetMinSequenceNumberLength(
358 QuicPacketSequenceNumber sequence_number);
361 friend class test::QuicFramerPeer;
363 typedef std::map<QuicPacketSequenceNumber, uint8> NackRangeMap;
368 virtual ~AckFrameInfo();
370 // The maximum delta between ranges.
371 QuicPacketSequenceNumber max_delta;
372 // Nack ranges starting with start sequence numbers and lengths.
373 NackRangeMap nack_ranges;
376 QuicPacketEntropyHash GetPacketEntropyHash(
377 const QuicPacketHeader& header) const;
379 bool ProcessDataPacket(const QuicPacketPublicHeader& public_header,
380 const QuicEncryptedPacket& packet);
382 bool ProcessPublicResetPacket(const QuicPacketPublicHeader& public_header);
384 bool ProcessVersionNegotiationPacket(QuicPacketPublicHeader* public_header);
386 bool ProcessPublicHeader(QuicPacketPublicHeader* header);
388 bool ProcessPacketHeader(QuicPacketHeader* header,
389 const QuicEncryptedPacket& packet);
391 bool ProcessPacketSequenceNumber(
392 QuicSequenceNumberLength sequence_number_length,
393 QuicPacketSequenceNumber* sequence_number);
394 bool ProcessFrameData(const QuicPacketHeader& header);
395 bool ProcessStreamFrame(uint8 frame_type, QuicStreamFrame* frame);
396 bool ProcessAckFrame(const QuicPacketHeader& header,
398 QuicAckFrame* frame);
399 // TODO(ianswett): Remove this once QUIC_VERSION_11 is removed.
400 bool ProcessReceivedInfoV11(ReceivedPacketInfo* received_info);
401 bool ProcessReceivedInfo(uint8 frame_type, ReceivedPacketInfo* received_info);
402 bool ProcessSentInfo(const QuicPacketHeader& public_header,
403 SentPacketInfo* sent_info);
404 bool ProcessQuicCongestionFeedbackFrame(
405 QuicCongestionFeedbackFrame* congestion_feedback);
406 bool ProcessRstStreamFrame(QuicRstStreamFrame* frame);
407 bool ProcessConnectionCloseFrame(QuicConnectionCloseFrame* frame);
408 bool ProcessGoAwayFrame(QuicGoAwayFrame* frame);
410 bool DecryptPayload(const QuicPacketHeader& header,
411 const QuicEncryptedPacket& packet);
413 // Returns the full packet sequence number from the truncated
414 // wire format version and the last seen packet sequence number.
415 QuicPacketSequenceNumber CalculatePacketSequenceNumberFromWire(
416 QuicSequenceNumberLength sequence_number_length,
417 QuicPacketSequenceNumber packet_sequence_number) const;
419 // Computes the wire size in bytes of the |ack| frame, assuming no truncation.
420 size_t GetAckFrameSize(const QuicAckFrame& ack,
421 QuicSequenceNumberLength sequence_number_length);
423 // Computes the wire size in bytes of the payload of |frame|.
424 size_t ComputeFrameLength(const QuicFrame& frame,
425 bool last_frame_in_packet,
426 QuicSequenceNumberLength sequence_number_length);
428 static bool AppendPacketSequenceNumber(
429 QuicSequenceNumberLength sequence_number_length,
430 QuicPacketSequenceNumber packet_sequence_number,
431 QuicDataWriter* writer);
433 static uint8 GetSequenceNumberFlags(
434 QuicSequenceNumberLength sequence_number_length);
436 static AckFrameInfo GetAckFrameInfo(const QuicAckFrame& frame);
438 bool AppendPacketHeader(const QuicPacketHeader& header,
439 QuicDataWriter* writer);
440 bool AppendTypeByte(const QuicFrame& frame,
441 bool last_frame_in_packet,
442 QuicDataWriter* writer);
443 bool AppendStreamFramePayload(const QuicStreamFrame& frame,
444 bool last_frame_in_packet,
445 QuicDataWriter* builder);
446 bool AppendAckFramePayloadAndTypeByte(const QuicPacketHeader& header,
447 const QuicAckFrame& frame,
448 QuicDataWriter* builder);
449 // TODO(ianswett): Remove this once QUIC_VERSION_11 is removed.
450 bool AppendAckFramePayloadV11(const QuicAckFrame& frame,
451 QuicDataWriter* builder);
452 bool AppendQuicCongestionFeedbackFramePayload(
453 const QuicCongestionFeedbackFrame& frame,
454 QuicDataWriter* builder);
455 bool AppendRstStreamFramePayload(const QuicRstStreamFrame& frame,
456 QuicDataWriter* builder);
457 bool AppendConnectionCloseFramePayload(
458 const QuicConnectionCloseFrame& frame,
459 QuicDataWriter* builder);
460 bool AppendGoAwayFramePayload(const QuicGoAwayFrame& frame,
461 QuicDataWriter* writer);
462 bool RaiseError(QuicErrorCode error);
464 void set_error(QuicErrorCode error) {
468 void set_detailed_error(const char* error) {
469 detailed_error_ = error;
472 std::string detailed_error_;
473 scoped_ptr<QuicDataReader> reader_;
474 QuicFramerVisitorInterface* visitor_;
475 QuicFecBuilderInterface* fec_builder_;
476 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator_;
477 QuicErrorCode error_;
478 // Updated by ProcessPacketHeader when it succeeds.
479 QuicPacketSequenceNumber last_sequence_number_;
480 // Updated by WritePacketHeader.
481 QuicGuid last_serialized_guid_;
482 // Buffer containing decrypted payload data during parsing.
483 scoped_ptr<QuicData> decrypted_;
484 // Version of the protocol being used.
485 QuicVersion quic_version_;
486 // This vector contains QUIC versions which we currently support.
487 // This should be ordered such that the highest supported version is the first
488 // element, with subsequent elements in descending order (versions can be
489 // skipped as necessary).
490 QuicVersionVector supported_versions_;
491 // Primary decrypter used to decrypt packets during parsing.
492 scoped_ptr<QuicDecrypter> decrypter_;
493 // Alternative decrypter that can also be used to decrypt packets.
494 scoped_ptr<QuicDecrypter> alternative_decrypter_;
495 // alternative_decrypter_latch_is true if, when |alternative_decrypter_|
496 // successfully decrypts a packet, we should install it as the only
498 bool alternative_decrypter_latch_;
499 // Encrypters used to encrypt packets via EncryptPacket().
500 scoped_ptr<QuicEncrypter> encrypter_[NUM_ENCRYPTION_LEVELS];
501 // Tracks if the framer is being used by the entity that received the
502 // connection or the entity that initiated it.
504 // The time this frames was created. Time written to the wire will be
505 // written as a delta from this value.
506 QuicTime creation_time_;
508 DISALLOW_COPY_AND_ASSIGN(QuicFramer);
513 #endif // NET_QUIC_QUIC_FRAMER_H_