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_WEBSOCKETS_WEBSOCKET_FRAME_H_ 6 #define NET_WEBSOCKETS_WEBSOCKET_FRAME_H_ 7 8 #include <vector> 9 10 #include "base/basictypes.h" 11 #include "base/memory/ref_counted.h" 12 #include "base/memory/scoped_ptr.h" 13 #include "net/base/net_export.h" 14 15 namespace net { 16 17 class IOBuffer; 18 class IOBufferWithSize; 19 20 // Represents a WebSocket frame header. 21 // 22 // Members of this class correspond to each element in WebSocket frame header 23 // (see http://tools.ietf.org/html/rfc6455#section-5.2). 24 struct NET_EXPORT WebSocketFrameHeader { 25 typedef int OpCode; 26 27 // Originally these constants were static const int, but to make it possible 28 // to use them in a switch statement they were changed to an enum. 29 enum OpCodeEnum { 30 kOpCodeContinuation = 0x0, 31 kOpCodeText = 0x1, 32 kOpCodeBinary = 0x2, 33 kOpCodeDataUnused = 0x3, 34 kOpCodeClose = 0x8, 35 kOpCodePing = 0x9, 36 kOpCodePong = 0xA, 37 kOpCodeControlUnused = 0xB, 38 }; 39 40 // Return true if |opcode| is one of the data opcodes known to this 41 // implementation. IsKnownDataOpCodeWebSocketFrameHeader42 static bool IsKnownDataOpCode(OpCode opcode) { 43 return opcode == kOpCodeContinuation || opcode == kOpCodeText || 44 opcode == kOpCodeBinary; 45 } 46 47 // Return true if |opcode| is one of the control opcodes known to this 48 // implementation. IsKnownControlOpCodeWebSocketFrameHeader49 static bool IsKnownControlOpCode(OpCode opcode) { 50 return opcode == kOpCodeClose || opcode == kOpCodePing || 51 opcode == kOpCodePong; 52 } 53 54 // These values must be a compile-time constant. "enum hack" is used here 55 // to make MSVC happy. 56 enum { 57 kBaseHeaderSize = 2, 58 kMaximumExtendedLengthSize = 8, 59 kMaskingKeyLength = 4 60 }; 61 62 // Constructor to avoid a lot of repetitive initialisation. WebSocketFrameHeaderWebSocketFrameHeader63 explicit WebSocketFrameHeader(OpCode opCode) 64 : final(false), 65 reserved1(false), 66 reserved2(false), 67 reserved3(false), 68 opcode(opCode), 69 masked(false), 70 payload_length(0) {} 71 72 // Create a clone of this object on the heap. 73 scoped_ptr<WebSocketFrameHeader> Clone() const; 74 75 // Overwrite this object with the fields from |source|. 76 void CopyFrom(const WebSocketFrameHeader& source); 77 78 // Members below correspond to each item in WebSocket frame header. 79 // See <http://tools.ietf.org/html/rfc6455#section-5.2> for details. 80 bool final; 81 bool reserved1; 82 bool reserved2; 83 bool reserved3; 84 OpCode opcode; 85 bool masked; 86 uint64 payload_length; 87 88 private: 89 DISALLOW_COPY_AND_ASSIGN(WebSocketFrameHeader); 90 }; 91 92 // Contains an entire WebSocket frame including payload. This is used by APIs 93 // that are not concerned about retaining the original frame boundaries (because 94 // frames may need to be split in order for the data to fit in memory). 95 struct NET_EXPORT_PRIVATE WebSocketFrame { 96 // A frame must always have an opcode, so this parameter is compulsory. 97 explicit WebSocketFrame(WebSocketFrameHeader::OpCode opcode); 98 ~WebSocketFrame(); 99 100 // |header| is always present. 101 WebSocketFrameHeader header; 102 103 // |data| is always unmasked even if the frame is masked. The size of |data| 104 // is given by |header.payload_length|. 105 scoped_refptr<IOBuffer> data; 106 }; 107 108 // Structure describing one chunk of a WebSocket frame. 109 // 110 // The payload of a WebSocket frame may be divided into multiple chunks. 111 // You need to look at |final_chunk| member variable to detect the end of a 112 // series of chunk objects of a WebSocket frame. 113 // 114 // Frame dissection is necessary to handle frames that are too large to store in 115 // the browser memory without losing information about the frame boundaries. In 116 // practice, most code does not need to worry about the original frame 117 // boundaries and can use the WebSocketFrame type declared above. 118 // 119 // Users of this struct should treat WebSocket frames as a data stream; it's 120 // important to keep the frame data flowing, especially in the browser process. 121 // Users should not let the data stuck somewhere in the pipeline. 122 // 123 // This struct is used for reading WebSocket frame data (created by 124 // WebSocketFrameParser). To construct WebSocket frames, use functions below. 125 struct NET_EXPORT WebSocketFrameChunk { 126 WebSocketFrameChunk(); 127 ~WebSocketFrameChunk(); 128 129 // Non-null |header| is provided only if this chunk is the first part of 130 // a series of chunks. 131 scoped_ptr<WebSocketFrameHeader> header; 132 133 // Indicates this part is the last chunk of a frame. 134 bool final_chunk; 135 136 // |data| is always unmasked even if the frame is masked. |data| might be 137 // null in the first chunk. 138 scoped_refptr<IOBufferWithSize> data; 139 }; 140 141 // Contains four-byte data representing "masking key" of WebSocket frames. 142 struct WebSocketMaskingKey { 143 char key[WebSocketFrameHeader::kMaskingKeyLength]; 144 }; 145 146 // Returns the size of WebSocket frame header. The size of WebSocket frame 147 // header varies from 2 bytes to 14 bytes depending on the payload length 148 // and maskedness. 149 NET_EXPORT int GetWebSocketFrameHeaderSize(const WebSocketFrameHeader& header); 150 151 // Writes wire format of a WebSocket frame header into |output|, and returns 152 // the number of bytes written. 153 // 154 // WebSocket frame format is defined at: 155 // <http://tools.ietf.org/html/rfc6455#section-5.2>. This function writes 156 // everything but payload data in a WebSocket frame to |buffer|. 157 // 158 // If |header->masked| is true, |masking_key| must point to a valid 159 // WebSocketMaskingKey object containing the masking key for that frame 160 // (possibly generated by GenerateWebSocketMaskingKey() function below). 161 // Otherwise, |masking_key| must be NULL. 162 // 163 // |buffer| should have enough size to contain the frame header. 164 // GetWebSocketFrameHeaderSize() can be used to know the size of header 165 // beforehand. If the size of |buffer| is insufficient, this function returns 166 // ERR_INVALID_ARGUMENT and does not write any data to |buffer|. 167 NET_EXPORT int WriteWebSocketFrameHeader(const WebSocketFrameHeader& header, 168 const WebSocketMaskingKey* masking_key, 169 char* buffer, 170 int buffer_size); 171 172 // Generates a masking key suitable for use in a new WebSocket frame. 173 NET_EXPORT WebSocketMaskingKey GenerateWebSocketMaskingKey(); 174 175 // Masks WebSocket frame payload. 176 // 177 // A client must mask every WebSocket frame by XOR'ing the frame payload 178 // with four-byte random data (masking key). This function applies the masking 179 // to the given payload data. 180 // 181 // This function masks |data| with |masking_key|, assuming |data| is partial 182 // data starting from |frame_offset| bytes from the beginning of the payload 183 // data. 184 // 185 // Since frame masking is a reversible operation, this function can also be 186 // used for unmasking a WebSocket frame. 187 NET_EXPORT void MaskWebSocketFramePayload( 188 const WebSocketMaskingKey& masking_key, 189 uint64 frame_offset, 190 char* data, 191 int data_size); 192 193 } // namespace net 194 195 #endif // NET_WEBSOCKETS_WEBSOCKET_FRAME_H_ 196