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 <stdint.h> 9 10 #include <memory> 11 #include <vector> 12 13 #include "base/containers/span.h" 14 #include "base/macros.h" 15 #include "base/memory/scoped_refptr.h" 16 #include "net/base/net_export.h" 17 18 namespace net { 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 // Contains four-byte data representing "masking key" of WebSocket frames. 63 struct WebSocketMaskingKey { 64 char key[WebSocketFrameHeader::kMaskingKeyLength]; 65 }; 66 67 // Constructor to avoid a lot of repetitive initialisation. WebSocketFrameHeaderWebSocketFrameHeader68 explicit WebSocketFrameHeader(OpCode opCode) : opcode(opCode) {} 69 70 // Create a clone of this object on the heap. 71 std::unique_ptr<WebSocketFrameHeader> Clone() const; 72 73 // Overwrite this object with the fields from |source|. 74 void CopyFrom(const WebSocketFrameHeader& source); 75 76 // Members below correspond to each item in WebSocket frame header. 77 // See <http://tools.ietf.org/html/rfc6455#section-5.2> for details. 78 bool final = false; 79 bool reserved1 = false; 80 bool reserved2 = false; 81 bool reserved3 = false; 82 OpCode opcode; 83 bool masked = false; 84 WebSocketMaskingKey masking_key = {}; 85 uint64_t payload_length = 0; 86 87 private: 88 DISALLOW_COPY_AND_ASSIGN(WebSocketFrameHeader); 89 }; 90 91 // Contains an entire WebSocket frame including payload. This is used by APIs 92 // that are not concerned about retaining the original frame boundaries (because 93 // frames may need to be split in order for the data to fit in memory). 94 struct NET_EXPORT_PRIVATE WebSocketFrame { 95 // A frame must always have an opcode, so this parameter is compulsory. 96 explicit WebSocketFrame(WebSocketFrameHeader::OpCode opcode); 97 ~WebSocketFrame(); 98 99 // |header| is always present. 100 WebSocketFrameHeader header; 101 102 // |payload| is always unmasked even if the frame is masked. The size of 103 // |payload| is given by |header.payload_length|. 104 // The lifetime of |payload| is not defined by WebSocketFrameChunk. It is the 105 // responsibility of the creator to ensure it remains valid for the lifetime 106 // of this object. This should be documented in the code that creates this 107 // object. 108 // TODO(yoicho): Find more better way to clarify the life cycle. 109 const char* payload = nullptr; 110 111 private: 112 DISALLOW_COPY_AND_ASSIGN(WebSocketFrame); 113 }; 114 115 // Structure describing one chunk of a WebSocket frame. 116 // 117 // The payload of a WebSocket frame may be divided into multiple chunks. 118 // You need to look at |final_chunk| member variable to detect the end of a 119 // series of chunk objects of a WebSocket frame. 120 // 121 // Frame dissection is necessary to handle frames that are too large to store in 122 // the browser memory without losing information about the frame boundaries. In 123 // practice, most code does not need to worry about the original frame 124 // boundaries and can use the WebSocketFrame type declared above. 125 // 126 // Users of this struct should treat WebSocket frames as a data stream; it's 127 // important to keep the frame data flowing, especially in the browser process. 128 // Users should not let the data stuck somewhere in the pipeline. 129 // 130 // This struct is used for reading WebSocket frame data (created by 131 // WebSocketFrameParser). To construct WebSocket frames, use functions below. 132 struct NET_EXPORT WebSocketFrameChunk { 133 WebSocketFrameChunk(); 134 ~WebSocketFrameChunk(); 135 136 // Non-null |header| is provided only if this chunk is the first part of 137 // a series of chunks. 138 std::unique_ptr<WebSocketFrameHeader> header; 139 140 // Indicates this part is the last chunk of a frame. 141 bool final_chunk; 142 143 // |payload| is always unmasked even if the frame is masked. |payload| might 144 // be empty in the first chunk. 145 // The lifetime of |payload| is not defined by WebSocketFrameChunk. It is the 146 // responsibility of the creator to ensure it remains valid for the lifetime 147 // of this object. This should be documented in the code that creates this 148 // object. 149 // TODO(yoicho): Find more better way to clarify the life cycle. 150 base::span<const char> payload; 151 152 private: 153 DISALLOW_COPY_AND_ASSIGN(WebSocketFrameChunk); 154 }; 155 156 using WebSocketMaskingKey = WebSocketFrameHeader::WebSocketMaskingKey; 157 158 // Returns the size of WebSocket frame header. The size of WebSocket frame 159 // header varies from 2 bytes to 14 bytes depending on the payload length 160 // and maskedness. 161 NET_EXPORT int GetWebSocketFrameHeaderSize(const WebSocketFrameHeader& header); 162 163 // Writes wire format of a WebSocket frame header into |output|, and returns 164 // the number of bytes written. 165 // 166 // WebSocket frame format is defined at: 167 // <http://tools.ietf.org/html/rfc6455#section-5.2>. This function writes 168 // everything but payload data in a WebSocket frame to |buffer|. 169 // 170 // If |header->masked| is true, |masking_key| must point to a valid 171 // WebSocketMaskingKey object containing the masking key for that frame 172 // (possibly generated by GenerateWebSocketMaskingKey() function below). 173 // Otherwise, |masking_key| must be NULL. 174 // 175 // |buffer| should have enough size to contain the frame header. 176 // GetWebSocketFrameHeaderSize() can be used to know the size of header 177 // beforehand. If the size of |buffer| is insufficient, this function returns 178 // ERR_INVALID_ARGUMENT and does not write any data to |buffer|. 179 NET_EXPORT int WriteWebSocketFrameHeader(const WebSocketFrameHeader& header, 180 const WebSocketMaskingKey* masking_key, 181 char* buffer, 182 int buffer_size); 183 184 // Generates a masking key suitable for use in a new WebSocket frame. 185 NET_EXPORT WebSocketMaskingKey GenerateWebSocketMaskingKey(); 186 187 // Masks WebSocket frame payload. 188 // 189 // A client must mask every WebSocket frame by XOR'ing the frame payload 190 // with four-byte random data (masking key). This function applies the masking 191 // to the given payload data. 192 // 193 // This function masks |data| with |masking_key|, assuming |data| is partial 194 // data starting from |frame_offset| bytes from the beginning of the payload 195 // data. 196 // 197 // Since frame masking is a reversible operation, this function can also be 198 // used for unmasking a WebSocket frame. 199 NET_EXPORT void MaskWebSocketFramePayload( 200 const WebSocketMaskingKey& masking_key, 201 uint64_t frame_offset, 202 char* data, 203 int data_size); 204 205 } // namespace net 206 207 #endif // NET_WEBSOCKETS_WEBSOCKET_FRAME_H_ 208