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 const size_t kQuicDeltaTimeLargestObservedSize = 2;
48 // Size in bytes reserved for the number of missing packets in ack frames.
49 const size_t kNumberOfMissingPacketsSize = 1;
50 // Size in bytes reserved for the number of revived packets in ack frames.
51 const size_t kNumberOfRevivedPacketsSize = 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 public header has been parsed, but has not been
88 // authenticated. If it returns false, framing for this packet will cease.
89 virtual bool OnUnauthenticatedPublicHeader(
90 const QuicPacketPublicHeader& header) = 0;
92 // Called when the unauthenticated portion of the header has been parsed.
93 // If OnUnauthenticatedHeader returns false, framing for this packet will
95 virtual bool OnUnauthenticatedHeader(const QuicPacketHeader& header) = 0;
97 // Called when a packet has been decrypted. |level| is the encryption level
99 virtual void OnDecryptedPacket(EncryptionLevel level) = 0;
101 // Called when the complete header of a packet had been parsed.
102 // If OnPacketHeader returns false, framing for this packet will cease.
103 virtual bool OnPacketHeader(const QuicPacketHeader& header) = 0;
105 // Called when a data packet is parsed that is part of an FEC group.
106 // |payload| is the non-encrypted FEC protected payload of the packet.
107 virtual void OnFecProtectedPayload(base::StringPiece payload) = 0;
109 // Called when a StreamFrame has been parsed.
110 virtual bool OnStreamFrame(const QuicStreamFrame& frame) = 0;
112 // Called when a AckFrame has been parsed. If OnAckFrame returns false,
113 // the framer will stop parsing the current packet.
114 virtual bool OnAckFrame(const QuicAckFrame& frame) = 0;
116 // Called when a CongestionFeedbackFrame has been parsed.
117 virtual bool OnCongestionFeedbackFrame(
118 const QuicCongestionFeedbackFrame& frame) = 0;
120 // Called when a StopWaitingFrame has been parsed.
121 virtual bool OnStopWaitingFrame(const QuicStopWaitingFrame& frame) = 0;
123 // Called when a PingFrame has been parsed.
124 virtual bool OnPingFrame(const QuicPingFrame& frame) = 0;
126 // Called when a RstStreamFrame has been parsed.
127 virtual bool OnRstStreamFrame(const QuicRstStreamFrame& frame) = 0;
129 // Called when a ConnectionCloseFrame has been parsed.
130 virtual bool OnConnectionCloseFrame(
131 const QuicConnectionCloseFrame& frame) = 0;
133 // Called when a GoAwayFrame has been parsed.
134 virtual bool OnGoAwayFrame(const QuicGoAwayFrame& frame) = 0;
136 // Called when a WindowUpdateFrame has been parsed.
137 virtual bool OnWindowUpdateFrame(const QuicWindowUpdateFrame& frame) = 0;
139 // Called when a BlockedFrame has been parsed.
140 virtual bool OnBlockedFrame(const QuicBlockedFrame& frame) = 0;
142 // Called when FEC data has been parsed.
143 virtual void OnFecData(const QuicFecData& fec) = 0;
145 // Called when a packet has been completely processed.
146 virtual void OnPacketComplete() = 0;
149 class NET_EXPORT_PRIVATE QuicFecBuilderInterface {
151 virtual ~QuicFecBuilderInterface() {}
153 // Called when a data packet is constructed that is part of an FEC group.
154 // |payload| is the non-encrypted FEC protected payload of the packet.
155 virtual void OnBuiltFecProtectedPayload(const QuicPacketHeader& header,
156 base::StringPiece payload) = 0;
159 // This class calculates the received entropy of the ack packet being
160 // framed, should it get truncated.
161 class NET_EXPORT_PRIVATE QuicReceivedEntropyHashCalculatorInterface {
163 virtual ~QuicReceivedEntropyHashCalculatorInterface() {}
165 // When an ack frame gets truncated while being framed the received
166 // entropy of the ack frame needs to be calculated since the some of the
167 // missing packets are not added and the largest observed might be lowered.
168 // This should return the received entropy hash of the packets received up to
169 // and including |sequence_number|.
170 virtual QuicPacketEntropyHash EntropyHash(
171 QuicPacketSequenceNumber sequence_number) const = 0;
174 // Class for parsing and constructing QUIC packets. It has a
175 // QuicFramerVisitorInterface that is called when packets are parsed.
176 // It also has a QuicFecBuilder that is called when packets are constructed
177 // in order to generate FEC data for subsequently building FEC packets.
178 class NET_EXPORT_PRIVATE QuicFramer {
180 // Constructs a new framer that installs a kNULL QuicEncrypter and
181 // QuicDecrypter for level ENCRYPTION_NONE. |supported_versions| specifies the
182 // list of supported QUIC versions. |quic_version_| is set to the maximum
183 // version in |supported_versions|.
184 QuicFramer(const QuicVersionVector& supported_versions,
185 QuicTime creation_time,
188 virtual ~QuicFramer();
190 // Returns true if |version| is a supported protocol version.
191 bool IsSupportedVersion(const QuicVersion version) const;
193 // Set callbacks to be called from the framer. A visitor must be set, or
194 // else the framer will likely crash. It is acceptable for the visitor
195 // to do nothing. If this is called multiple times, only the last visitor
197 void set_visitor(QuicFramerVisitorInterface* visitor) {
201 // Set a builder to be called from the framer when building FEC protected
202 // packets. If this is called multiple times, only the last builder
203 // will be used. The builder need not be set.
204 void set_fec_builder(QuicFecBuilderInterface* builder) {
205 fec_builder_ = builder;
208 const QuicVersionVector& supported_versions() const {
209 return supported_versions_;
212 QuicVersion version() const {
213 return quic_version_;
216 void set_version(const QuicVersion version);
218 // Does not DCHECK for supported version. Used by tests to set unsupported
219 // version to trigger version negotiation.
220 void set_version_for_tests(const QuicVersion version) {
221 quic_version_ = version;
224 // Set entropy calculator to be called from the framer when it needs the
225 // entropy of a truncated ack frame. An entropy calculator must be set or else
226 // the framer will likely crash. If this is called multiple times, only the
227 // last calculator will be used.
228 void set_received_entropy_calculator(
229 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator) {
230 entropy_calculator_ = entropy_calculator;
233 QuicErrorCode error() const {
237 // Pass a UDP packet into the framer for parsing.
238 // Return true if the packet was processed succesfully. |packet| must be a
239 // single, complete UDP packet (not a frame of a packet). This packet
240 // might be null padded past the end of the payload, which will be correctly
242 bool ProcessPacket(const QuicEncryptedPacket& packet);
244 // Pass a data packet that was revived from FEC data into the framer
246 // Return true if the packet was processed succesfully. |payload| must be
247 // the complete DECRYPTED payload of the revived packet.
248 bool ProcessRevivedPacket(QuicPacketHeader* header,
249 base::StringPiece payload);
251 // Largest size in bytes of all stream frame fields without the payload.
252 static size_t GetMinStreamFrameSize(QuicVersion version,
253 QuicStreamId stream_id,
254 QuicStreamOffset offset,
255 bool last_frame_in_packet,
256 InFecGroup is_in_fec_group);
257 // Size in bytes of all ack frame fields without the missing packets.
258 static size_t GetMinAckFrameSize(
260 QuicSequenceNumberLength sequence_number_length,
261 QuicSequenceNumberLength largest_observed_length);
262 // Size in bytes of a stop waiting frame.
263 static size_t GetStopWaitingFrameSize(
264 QuicSequenceNumberLength sequence_number_length);
265 // Size in bytes of all reset stream frame without the error details.
266 static size_t GetMinRstStreamFrameSize(QuicVersion quic_version);
267 // Size in bytes of all connection close frame fields without the error
268 // details and the missing packets from the enclosed ack frame.
269 static size_t GetMinConnectionCloseFrameSize();
270 // Size in bytes of all GoAway frame fields without the reason phrase.
271 static size_t GetMinGoAwayFrameSize();
272 // Size in bytes of all WindowUpdate frame fields.
273 static size_t GetWindowUpdateFrameSize();
274 // Size in bytes of all Blocked frame fields.
275 static size_t GetBlockedFrameSize();
276 // Size in bytes required to serialize the stream id.
277 static size_t GetStreamIdSize(QuicStreamId stream_id);
278 // Size in bytes required to serialize the stream offset.
279 static size_t GetStreamOffsetSize(QuicStreamOffset offset);
280 // Size in bytes required for a serialized version negotiation packet
281 static size_t GetVersionNegotiationPacketSize(size_t number_versions);
283 // Returns the number of bytes added to the packet for the specified frame,
284 // and 0 if the frame doesn't fit. Includes the header size for the first
286 size_t GetSerializedFrameLength(
287 const QuicFrame& frame,
289 bool first_frame_in_packet,
290 bool last_frame_in_packet,
291 InFecGroup is_in_fec_group,
292 QuicSequenceNumberLength sequence_number_length);
294 // Returns the associated data from the encrypted packet |encrypted| as a
296 static base::StringPiece GetAssociatedDataFromEncryptedPacket(
297 const QuicEncryptedPacket& encrypted,
298 QuicConnectionIdLength connection_id_length,
299 bool includes_version,
300 QuicSequenceNumberLength sequence_number_length);
302 // Returns a SerializedPacket whose |packet| member is owned by the caller,
303 // and is populated with the fields in |header| and |frames|, or is NULL if
304 // the packet could not be created.
305 // TODO(ianswett): Used for testing only.
306 SerializedPacket BuildUnsizedDataPacket(const QuicPacketHeader& header,
307 const QuicFrames& frames);
309 // Returns a SerializedPacket whose |packet| member is owned by the caller,
310 // is created from the first |num_frames| frames, or is NULL if the packet
311 // could not be created. The packet must be of size |packet_size|.
312 SerializedPacket BuildDataPacket(const QuicPacketHeader& header,
313 const QuicFrames& frames,
316 // Returns a SerializedPacket whose |packet| member is owned by the caller,
317 // and is populated with the fields in |header| and |fec|, or is NULL if the
318 // packet could not be created.
319 SerializedPacket BuildFecPacket(const QuicPacketHeader& header,
320 const QuicFecData& fec);
322 // Returns a new public reset packet, owned by the caller.
323 static QuicEncryptedPacket* BuildPublicResetPacket(
324 const QuicPublicResetPacket& packet);
326 QuicEncryptedPacket* BuildVersionNegotiationPacket(
327 const QuicPacketPublicHeader& header,
328 const QuicVersionVector& supported_versions);
330 // SetDecrypter sets the primary decrypter, replacing any that already exists,
331 // and takes ownership. If an alternative decrypter is in place then the
332 // function DCHECKs. This is intended for cases where one knows that future
333 // packets will be using the new decrypter and the previous decrypter is now
334 // obsolete. |level| indicates the encryption level of the new decrypter.
335 void SetDecrypter(QuicDecrypter* decrypter, EncryptionLevel level);
337 // SetAlternativeDecrypter sets a decrypter that may be used to decrypt
338 // future packets and takes ownership of it. |level| indicates the encryption
339 // level of the decrypter. If |latch_once_used| is true, then the first time
340 // that the decrypter is successful it will replace the primary decrypter.
341 // Otherwise both decrypters will remain active and the primary decrypter
342 // will be the one last used.
343 void SetAlternativeDecrypter(QuicDecrypter* decrypter,
344 EncryptionLevel level,
345 bool latch_once_used);
347 const QuicDecrypter* decrypter() const;
348 const QuicDecrypter* alternative_decrypter() const;
350 // Changes the encrypter used for level |level| to |encrypter|. The function
351 // takes ownership of |encrypter|.
352 void SetEncrypter(EncryptionLevel level, QuicEncrypter* encrypter);
353 const QuicEncrypter* encrypter(EncryptionLevel level) const;
355 // Returns a new encrypted packet, owned by the caller.
356 QuicEncryptedPacket* EncryptPacket(EncryptionLevel level,
357 QuicPacketSequenceNumber sequence_number,
358 const QuicPacket& packet);
360 // Returns the maximum length of plaintext that can be encrypted
361 // to ciphertext no larger than |ciphertext_size|.
362 size_t GetMaxPlaintextSize(size_t ciphertext_size);
364 const std::string& detailed_error() { return detailed_error_; }
366 // The minimum sequence number length required to represent |sequence_number|.
367 static QuicSequenceNumberLength GetMinSequenceNumberLength(
368 QuicPacketSequenceNumber sequence_number);
370 void SetSupportedVersions(const QuicVersionVector& versions) {
371 supported_versions_ = versions;
372 quic_version_ = versions[0];
375 void set_validate_flags(bool value) { validate_flags_ = value; }
378 friend class test::QuicFramerPeer;
380 typedef std::map<QuicPacketSequenceNumber, uint8> NackRangeMap;
382 struct AckFrameInfo {
386 // The maximum delta between ranges.
387 QuicPacketSequenceNumber max_delta;
388 // Nack ranges starting with start sequence numbers and lengths.
389 NackRangeMap nack_ranges;
392 QuicPacketEntropyHash GetPacketEntropyHash(
393 const QuicPacketHeader& header) const;
395 bool ProcessDataPacket(const QuicPacketPublicHeader& public_header,
396 const QuicEncryptedPacket& packet);
398 bool ProcessPublicResetPacket(const QuicPacketPublicHeader& public_header);
400 bool ProcessVersionNegotiationPacket(QuicPacketPublicHeader* public_header);
402 bool ProcessPublicHeader(QuicPacketPublicHeader* header);
404 bool ProcessPacketHeader(QuicPacketHeader* header,
405 const QuicEncryptedPacket& packet);
407 bool ProcessPacketSequenceNumber(
408 QuicSequenceNumberLength sequence_number_length,
409 QuicPacketSequenceNumber* sequence_number);
410 bool ProcessFrameData(const QuicPacketHeader& header);
411 bool ProcessStreamFrame(uint8 frame_type, QuicStreamFrame* frame);
412 bool ProcessAckFrame(const QuicPacketHeader& header,
414 QuicAckFrame* frame);
415 bool ProcessReceivedInfo(uint8 frame_type, ReceivedPacketInfo* received_info);
416 bool ProcessStopWaitingFrame(const QuicPacketHeader& public_header,
417 QuicStopWaitingFrame* stop_waiting);
418 bool ProcessQuicCongestionFeedbackFrame(
419 QuicCongestionFeedbackFrame* congestion_feedback);
420 bool ProcessRstStreamFrame(QuicRstStreamFrame* frame);
421 bool ProcessConnectionCloseFrame(QuicConnectionCloseFrame* frame);
422 bool ProcessGoAwayFrame(QuicGoAwayFrame* frame);
423 bool ProcessWindowUpdateFrame(QuicWindowUpdateFrame* frame);
424 bool ProcessBlockedFrame(QuicBlockedFrame* frame);
426 bool DecryptPayload(const QuicPacketHeader& header,
427 const QuicEncryptedPacket& packet);
429 // Returns the full packet sequence number from the truncated
430 // wire format version and the last seen packet sequence number.
431 QuicPacketSequenceNumber CalculatePacketSequenceNumberFromWire(
432 QuicSequenceNumberLength sequence_number_length,
433 QuicPacketSequenceNumber packet_sequence_number) const;
435 // Computes the wire size in bytes of the |ack| frame, assuming no truncation.
436 size_t GetAckFrameSize(const QuicAckFrame& ack,
437 QuicSequenceNumberLength sequence_number_length);
439 // Computes the wire size in bytes of the payload of |frame|.
440 size_t ComputeFrameLength(const QuicFrame& frame,
441 bool last_frame_in_packet,
442 InFecGroup is_in_fec_group,
443 QuicSequenceNumberLength sequence_number_length);
445 static bool AppendPacketSequenceNumber(
446 QuicSequenceNumberLength sequence_number_length,
447 QuicPacketSequenceNumber packet_sequence_number,
448 QuicDataWriter* writer);
450 static uint8 GetSequenceNumberFlags(
451 QuicSequenceNumberLength sequence_number_length);
453 static AckFrameInfo GetAckFrameInfo(const QuicAckFrame& frame);
455 // The Append* methods attempt to write the provided header or frame using the
456 // |writer|, and return true if successful.
457 bool AppendPacketHeader(const QuicPacketHeader& header,
458 QuicDataWriter* writer);
459 bool AppendTypeByte(const QuicFrame& frame,
460 bool last_frame_in_packet,
461 QuicDataWriter* writer);
462 bool AppendStreamFrame(const QuicStreamFrame& frame,
463 bool last_frame_in_packet,
464 QuicDataWriter* builder);
465 bool AppendAckFrameAndTypeByte(const QuicPacketHeader& header,
466 const QuicAckFrame& frame,
467 QuicDataWriter* builder);
468 bool AppendCongestionFeedbackFrame(const QuicCongestionFeedbackFrame& frame,
469 QuicDataWriter* builder);
470 bool AppendStopWaitingFrame(const QuicPacketHeader& header,
471 const QuicStopWaitingFrame& frame,
472 QuicDataWriter* builder);
473 bool AppendRstStreamFrame(const QuicRstStreamFrame& frame,
474 QuicDataWriter* builder);
475 bool AppendConnectionCloseFrame(const QuicConnectionCloseFrame& frame,
476 QuicDataWriter* builder);
477 bool AppendGoAwayFrame(const QuicGoAwayFrame& frame, QuicDataWriter* writer);
478 bool AppendWindowUpdateFrame(const QuicWindowUpdateFrame& frame,
479 QuicDataWriter* writer);
480 bool AppendBlockedFrame(const QuicBlockedFrame& frame,
481 QuicDataWriter* writer);
483 bool RaiseError(QuicErrorCode error);
485 void set_error(QuicErrorCode error) {
489 void set_detailed_error(const char* error) {
490 detailed_error_ = error;
493 std::string detailed_error_;
494 scoped_ptr<QuicDataReader> reader_;
495 QuicFramerVisitorInterface* visitor_;
496 QuicFecBuilderInterface* fec_builder_;
497 QuicReceivedEntropyHashCalculatorInterface* entropy_calculator_;
498 QuicErrorCode error_;
499 // Updated by ProcessPacketHeader when it succeeds.
500 QuicPacketSequenceNumber last_sequence_number_;
501 // Updated by WritePacketHeader.
502 QuicConnectionId last_serialized_connection_id_;
503 // Buffer containing decrypted payload data during parsing.
504 scoped_ptr<QuicData> decrypted_;
505 // Version of the protocol being used.
506 QuicVersion quic_version_;
507 // This vector contains QUIC versions which we currently support.
508 // This should be ordered such that the highest supported version is the first
509 // element, with subsequent elements in descending order (versions can be
510 // skipped as necessary).
511 QuicVersionVector supported_versions_;
512 // Primary decrypter used to decrypt packets during parsing.
513 scoped_ptr<QuicDecrypter> decrypter_;
514 // Alternative decrypter that can also be used to decrypt packets.
515 scoped_ptr<QuicDecrypter> alternative_decrypter_;
516 // The encryption level of |decrypter_|.
517 EncryptionLevel decrypter_level_;
518 // The encryption level of |alternative_decrypter_|.
519 EncryptionLevel alternative_decrypter_level_;
520 // |alternative_decrypter_latch_| is true if, when |alternative_decrypter_|
521 // successfully decrypts a packet, we should install it as the only
523 bool alternative_decrypter_latch_;
524 // Encrypters used to encrypt packets via EncryptPacket().
525 scoped_ptr<QuicEncrypter> encrypter_[NUM_ENCRYPTION_LEVELS];
526 // Tracks if the framer is being used by the entity that received the
527 // connection or the entity that initiated it.
529 // If false, skip validation that the public flags are set to legal values.
530 bool validate_flags_;
531 // The time this frames was created. Time written to the wire will be
532 // written as a delta from this value.
533 QuicTime creation_time_;
535 DISALLOW_COPY_AND_ASSIGN(QuicFramer);
540 #endif // NET_QUIC_QUIC_FRAMER_H_