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 // Number of bytes reserved for stream id
37 const size_t kQuicStreamIdSize
= 4;
38 // Number of bytes reserved for fin flag in stream frame.
39 const size_t kQuicStreamFinSize
= 1;
40 // Number of bytes reserved for byte offset in stream frame.
41 const size_t kQuicStreamOffsetSize
= 8;
42 // Number of bytes reserved to store payload length in stream frame.
43 const size_t kQuicStreamPayloadLengthSize
= 2;
45 // Size in bytes of the entropy hash sent in ack frames.
46 const size_t kQuicEntropyHashSize
= 1;
47 // Size in bytes reserved for the delta time of the largest observed
48 // sequence number in ack frames.
49 const size_t kQuicDeltaTimeLargestObservedSize
= 4;
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(QuicVersionTag 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
ReceivedEntropyHash(
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 will own |decrypter| and |encrypter|.
155 QuicFramer(QuicVersionTag quic_version
,
156 QuicDecrypter
* decrypter
,
157 QuicEncrypter
* encrypter
,
158 QuicTime creation_time
,
161 virtual ~QuicFramer();
163 // Returns true if |version| is a supported protocol version.
164 bool IsSupportedVersion(QuicVersionTag version
);
166 // Calculates the largest observed packet to advertise in the case an Ack
167 // Frame was truncated. last_written in this case is the iterator for the
168 // last missing packet which fit in the outgoing ack.
169 static QuicPacketSequenceNumber
CalculateLargestObserved(
170 const SequenceNumberSet
& missing_packets
,
171 SequenceNumberSet::const_iterator last_written
);
173 // Set callbacks to be called from the framer. A visitor must be set, or
174 // else the framer will likely crash. It is acceptable for the visitor
175 // to do nothing. If this is called multiple times, only the last visitor
177 void set_visitor(QuicFramerVisitorInterface
* visitor
) {
181 // Set a builder to be called from the framer when building FEC protected
182 // packets. If this is called multiple times, only the last builder
183 // will be used. The builder need not be set.
184 void set_fec_builder(QuicFecBuilderInterface
* builder
) {
185 fec_builder_
= builder
;
188 QuicVersionTag
version() const {
189 return quic_version_
;
192 void set_version(QuicVersionTag version
) {
193 DCHECK(IsSupportedVersion(version
));
194 quic_version_
= version
;
197 // Set entropy calculator to be called from the framer when it needs the
198 // entropy of a truncated ack frame. An entropy calculator must be set or else
199 // the framer will likely crash. If this is called multiple times, only the
200 // last visitor will be used.
201 void set_entropy_calculator(
202 QuicReceivedEntropyHashCalculatorInterface
* entropy_calculator
) {
203 entropy_calculator_
= entropy_calculator
;
206 QuicErrorCode
error() const {
210 // Pass a UDP packet into the framer for parsing.
211 // Return true if the packet was processed succesfully. |packet| must be a
212 // single, complete UDP packet (not a frame of a packet). This packet
213 // might be null padded past the end of the payload, which will be correctly
215 bool ProcessPacket(const QuicEncryptedPacket
& packet
);
217 // Pass a data packet that was revived from FEC data into the framer
219 // Return true if the packet was processed succesfully. |payload| must be
220 // the complete DECRYPTED payload of the revived packet.
221 bool ProcessRevivedPacket(QuicPacketHeader
* header
,
222 base::StringPiece payload
);
224 // Size in bytes of all stream frame fields without the payload.
225 static size_t GetMinStreamFrameSize();
226 // Size in bytes of all ack frame fields without the missing packets.
227 static size_t GetMinAckFrameSize();
228 // Size in bytes of all reset stream frame without the error details.
229 static size_t GetMinRstStreamFrameSize();
230 // Size in bytes of all connection close frame fields without the error
231 // details and the missing packets from the enclosed ack frame.
232 static size_t GetMinConnectionCloseFrameSize();
233 // Size in bytes of all GoAway frame fields without the reason phrase.
234 static size_t GetMinGoAwayFrameSize();
235 // Size in bytes required for a serialized version negotiation packet
236 size_t GetVersionNegotiationPacketSize(size_t number_versions
);
238 // Returns the number of bytes added to the packet for the specified frame,
239 // and 0 if the frame doesn't fit. Includes the header size for the first
241 size_t GetSerializedFrameLength(
242 const QuicFrame
& frame
, size_t free_bytes
, bool first_frame
);
244 // Returns the associated data from the encrypted packet |encrypted| as a
246 static base::StringPiece
GetAssociatedDataFromEncryptedPacket(
247 const QuicEncryptedPacket
& encrypted
, bool includes_version
);
249 // Returns a SerializedPacket whose |packet| member is owned by the caller,
250 // and is populated with the fields in |header| and |frames|, or is NULL if
251 // the packet could not be created.
252 // TODO(ianswett): Used for testing only.
253 SerializedPacket
ConstructFrameDataPacket(const QuicPacketHeader
& header
,
254 const QuicFrames
& frames
);
256 // Returns a SerializedPacket whose |packet| member is owned by the caller,
257 // is created from the first |num_frames| frames, or is NULL if the packet
258 // could not be created. The packet must be of size |packet_size|.
259 SerializedPacket
ConstructFrameDataPacket(const QuicPacketHeader
& header
,
260 const QuicFrames
& frames
,
263 // Returns a SerializedPacket whose |packet| member is owned by the caller,
264 // and is populated with the fields in |header| and |fec|, or is NULL if the
265 // packet could not be created.
266 SerializedPacket
ConstructFecPacket(const QuicPacketHeader
& header
,
267 const QuicFecData
& fec
);
269 // Returns a new public reset packet, owned by the caller.
270 static QuicEncryptedPacket
* ConstructPublicResetPacket(
271 const QuicPublicResetPacket
& packet
);
273 QuicEncryptedPacket
* ConstructVersionNegotiationPacket(
274 const QuicPacketPublicHeader
& header
,
275 const QuicVersionTagList
& supported_versions
);
277 QuicDecrypter
* decrypter() const { return decrypter_
.get(); }
278 void push_decrypter(QuicDecrypter
* decrypter
);
279 void pop_decrypter();
281 QuicEncrypter
* encrypter() const { return encrypter_
.get(); }
282 void set_encrypter(QuicEncrypter
* encrypter
);
284 // Returns a new encrypted packet, owned by the caller.
285 QuicEncryptedPacket
* EncryptPacket(QuicPacketSequenceNumber sequence_number
,
286 const QuicPacket
& packet
);
288 // Returns the maximum length of plaintext that can be encrypted
289 // to ciphertext no larger than |ciphertext_size|.
290 size_t GetMaxPlaintextSize(size_t ciphertext_size
);
292 const std::string
& detailed_error() { return detailed_error_
; }
294 // Read the guid from a packet header.
295 // Return true on success, else false.
296 static bool ReadGuidFromPacket(const QuicEncryptedPacket
& packet
,
300 friend class test::QuicFramerPeer
;
302 QuicPacketEntropyHash
GetPacketEntropyHash(
303 const QuicPacketHeader
& header
) const;
305 bool ProcessDataPacket(const QuicPacketPublicHeader
& public_header
,
306 const QuicEncryptedPacket
& packet
);
308 bool ProcessPublicResetPacket(const QuicPacketPublicHeader
& public_header
);
310 bool ProcessVersionNegotiationPacket(QuicPacketPublicHeader
* public_header
);
312 bool WritePacketHeader(const QuicPacketHeader
& header
,
313 QuicDataWriter
* writer
);
315 bool ProcessPublicHeader(QuicPacketPublicHeader
* header
);
317 bool ProcessPacketHeader(QuicPacketHeader
* header
,
318 const QuicEncryptedPacket
& packet
);
320 bool ProcessPacketSequenceNumber(QuicPacketSequenceNumber
* sequence_number
);
321 bool ProcessFrameData();
322 bool ProcessStreamFrame(QuicStreamFrame
* frame
);
323 bool ProcessAckFrame(QuicAckFrame
* frame
);
324 bool ProcessReceivedInfo(ReceivedPacketInfo
* received_info
);
325 bool ProcessSentInfo(SentPacketInfo
* sent_info
);
326 bool ProcessQuicCongestionFeedbackFrame(
327 QuicCongestionFeedbackFrame
* congestion_feedback
);
328 bool ProcessRstStreamFrame(QuicRstStreamFrame
* frame
);
329 bool ProcessConnectionCloseFrame(QuicConnectionCloseFrame
* frame
);
330 bool ProcessGoAwayFrame(QuicGoAwayFrame
* frame
);
332 bool DecryptPayload(QuicPacketSequenceNumber packet_sequence_number
,
334 const QuicEncryptedPacket
& packet
);
336 // Returns the full packet sequence number from the truncated
337 // wire format version and the last seen packet sequence number.
338 QuicPacketSequenceNumber
CalculatePacketSequenceNumberFromWire(
339 QuicPacketSequenceNumber packet_sequence_number
) const;
341 // Computes the wire size in bytes of the payload of |frame|.
342 size_t ComputeFrameLength(const QuicFrame
& frame
);
344 static bool AppendPacketSequenceNumber(
345 QuicPacketSequenceNumber packet_sequence_number
,
346 QuicDataWriter
* writer
);
348 bool AppendStreamFramePayload(const QuicStreamFrame
& frame
,
349 QuicDataWriter
* builder
);
350 bool AppendAckFramePayload(const QuicAckFrame
& frame
,
351 QuicDataWriter
* builder
);
352 bool AppendQuicCongestionFeedbackFramePayload(
353 const QuicCongestionFeedbackFrame
& frame
,
354 QuicDataWriter
* builder
);
355 bool AppendRstStreamFramePayload(const QuicRstStreamFrame
& frame
,
356 QuicDataWriter
* builder
);
357 bool AppendConnectionCloseFramePayload(
358 const QuicConnectionCloseFrame
& frame
,
359 QuicDataWriter
* builder
);
360 bool AppendGoAwayFramePayload(const QuicGoAwayFrame
& frame
,
361 QuicDataWriter
* writer
);
362 bool RaiseError(QuicErrorCode error
);
364 void set_error(QuicErrorCode error
) {
368 void set_detailed_error(const char* error
) {
369 detailed_error_
= error
;
372 std::string detailed_error_
;
373 scoped_ptr
<QuicDataReader
> reader_
;
374 QuicFramerVisitorInterface
* visitor_
;
375 QuicFecBuilderInterface
* fec_builder_
;
376 QuicReceivedEntropyHashCalculatorInterface
* entropy_calculator_
;
377 QuicErrorCode error_
;
378 // Updated by ProcessPacketHeader when it succeeds.
379 QuicPacketSequenceNumber last_sequence_number_
;
380 // Buffer containing decrypted payload data during parsing.
381 scoped_ptr
<QuicData
> decrypted_
;
382 // Version of the protocol being used.
383 QuicVersionTag quic_version_
;
384 // Primary decrypter used to decrypt packets during parsing.
385 scoped_ptr
<QuicDecrypter
> decrypter_
;
386 // Backup decrypter used to decrypt packets during parsing. May be NULL.
387 scoped_ptr
<QuicDecrypter
> backup_decrypter_
;
388 // Encrypter used to encrypt packets via EncryptPacket().
389 scoped_ptr
<QuicEncrypter
> encrypter_
;
390 // Tracks if the framer is being used by the entity that received the
391 // connection or the entity that initiated it.
393 // The time this frames was created. Time written to the wire will be
394 // written as a delta from this value.
395 QuicTime creation_time_
;
397 DISALLOW_COPY_AND_ASSIGN(QuicFramer
);
402 #endif // NET_QUIC_QUIC_FRAMER_H_