| 1 |
# uws_frame_encoder requirements |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
uws_frame_encoder is module that implements the WebSocket frame encoding rules. |
| 6 |
|
| 7 |
## References |
| 8 |
|
| 9 |
RFC6455 - The WebSocket Protocol. |
| 10 |
|
| 11 |
## Exposed API |
| 12 |
|
| 13 |
```c |
| 14 |
#define RESERVED_1 0x04 |
| 15 |
#define RESERVED_2 0x02 |
| 16 |
#define RESERVED_3 0x01 |
| 17 |
|
| 18 |
#define WS_FRAME_TYPE_VALUES \ |
| 19 |
WS_CONTINUATION_FRAME = 0x00, \ |
| 20 |
WS_TEXT_FRAME = 0x01, \ |
| 21 |
WS_BINARY_FRAME = 0x02, \ |
| 22 |
WS_RESERVED_NON_CONTROL_FRAME_3 = 0x03, \ |
| 23 |
WS_RESERVED_NON_CONTROL_FRAME_4 = 0x04, \ |
| 24 |
WS_RESERVED_NON_CONTROL_FRAME_5 = 0x05, \ |
| 25 |
WS_RESERVED_NON_CONTROL_FRAME_6 = 0x06, \ |
| 26 |
WS_RESERVED_NON_CONTROL_FRAME_7 = 0x07, \ |
| 27 |
WS_CLOSE_FRAME = 0x08, \ |
| 28 |
WS_PING_FRAME = 0x09, \ |
| 29 |
WS_PONG_FRAME = 0x0A, \ |
| 30 |
WS_RESERVED_CONTROL_FRAME_B = 0x0B, \ |
| 31 |
WS_RESERVED_CONTROL_FRAME_C = 0x0C, \ |
| 32 |
WS_RESERVED_CONTROL_FRAME_D = 0x0D, \ |
| 33 |
WS_RESERVED_CONTROL_FRAME_E = 0x0E, \ |
| 34 |
WS_RESERVED_CONTROL_FRAME_F = 0x0F |
| 35 |
|
| 36 |
MU_DEFINE_ENUM(WS_FRAME_TYPE, WS_FRAME_TYPE_VALUES); |
| 37 |
|
| 38 |
extern int uws_frame_encoder_encode(BUFFER_HANDLE encode_buffer, WS_FRAME_TYPE opcode, const unsigned char* payload, size_t length, bool is_masked, bool is_final, unsigned char reserved); |
| 39 |
``` |
| 40 |
|
| 41 |
### uws_create |
| 42 |
|
| 43 |
```c |
| 44 |
extern int uws_frame_encoder_encode(BUFFER_HANDLE encode_buffer, WS_FRAME_TYPE opcode, const unsigned char* payload, size_t length, bool is_masked, bool is_final, unsigned char reserved); |
| 45 |
``` |
| 46 |
|
| 47 |
**SRS_UWS_FRAME_ENCODER_01_001: [** `uws_frame_encoder_encode` shall encode the information given in `opcode`, `payload`, `length`, `is_masked`, `is_final` and `reserved` according to the RFC6455 into a new buffer. **]** |
| 48 |
|
| 49 |
**SRS_UWS_FRAME_ENCODER_01_044: [** On success `uws_frame_encoder_encode` shall return a non-NULL handle to the result buffer. **]** |
| 50 |
|
| 51 |
**SRS_UWS_FRAME_ENCODER_01_054: [** If `length` is greater than 0 and payload is NULL, then `uws_frame_encoder_encode` shall fail and return NULL. **]** |
| 52 |
|
| 53 |
**SRS_UWS_FRAME_ENCODER_01_048: [** The newly created buffer shall be created by calling `BUFFER_new`. **]** |
| 54 |
|
| 55 |
**SRS_UWS_FRAME_ENCODER_01_049: [** If `BUFFER_new` fails then `uws_frame_encoder_encode` shall fail and return NULL. **]** |
| 56 |
|
| 57 |
**SRS_UWS_FRAME_ENCODER_01_046: [** The result buffer shall be resized accordingly using `BUFFER_enlarge`. **]** |
| 58 |
|
| 59 |
**SRS_UWS_FRAME_ENCODER_01_047: [** If `BUFFER_enlarge` fails then `uws_frame_encoder_encode` shall fail and return NULL. **]** |
| 60 |
|
| 61 |
**SRS_UWS_FRAME_ENCODER_01_050: [** The allocated memory shall be accessed by calling `BUFFER_u_char`. **]** |
| 62 |
|
| 63 |
**SRS_UWS_FRAME_ENCODER_01_051: [** If `BUFFER_u_char` fails then `uws_frame_encoder_encode` shall fail and return a NULL. **]** |
| 64 |
|
| 65 |
**SRS_UWS_FRAME_ENCODER_01_052: [** If `reserved` has any bits set except the lowest 3 then `uws_frame_encoder_encode` shall fail and return NULL. **]** |
| 66 |
|
| 67 |
**SRS_UWS_FRAME_ENCODER_01_053: [** In order to obtain a 32 bit value for masking, `RANDOM_generate` shall be used 4 times (for each byte). **]** |
| 68 |
|
| 69 |
### RFC6455 relevant parts |
| 70 |
|
| 71 |
5. Data Framing |
| 72 |
|
| 73 |
5.2. Base Framing Protocol |
| 74 |
|
| 75 |
This wire format for the data transfer part is described by the ABNF [RFC5234] given in detail in this section. |
| 76 |
(Note that, unlike in other sections of this document, the ABNF in this section is operating on groups of bits. |
| 77 |
The length of each group of bits is indicated in a comment. |
| 78 |
When encoded on the wire, the most significant bit is the leftmost in the ABNF). |
| 79 |
A high-level overview of the framing is given in the following figure. |
| 80 |
In a case of conflict between the figure below and the ABNF specified later in this section, the figure is authoritative. |
| 81 |
|
| 82 |
0 1 2 3 |
| 83 |
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 |
| 84 |
+-+-+-+-+-------+-+-------------+-------------------------------+ |
| 85 |
|F|R|R|R| opcode|M| Payload len | Extended payload length | |
| 86 |
|I|S|S|S| (4) |A| (7) | (16/64) | |
| 87 |
|N|V|V|V| |S| | (if payload len==126/127) | |
| 88 |
| |1|2|3| |K| | | |
| 89 |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - + |
| 90 |
| Extended payload length continued, if payload len == 127 | |
| 91 |
+ - - - - - - - - - - - - - - - +-------------------------------+ |
| 92 |
| |Masking-key, if MASK set to 1 | |
| 93 |
+-------------------------------+-------------------------------+ |
| 94 |
| Masking-key (continued) | Payload Data | |
| 95 |
+-------------------------------- - - - - - - - - - - - - - - - + |
| 96 |
: Payload Data continued ... : |
| 97 |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + |
| 98 |
| Payload Data continued ... | |
| 99 |
+---------------------------------------------------------------+ |
| 100 |
|
| 101 |
FIN: 1 bit |
| 102 |
|
| 103 |
**SRS_UWS_FRAME_ENCODER_01_002: [** Indicates that this is the final fragment in a message. **]** |
| 104 |
**SRS_UWS_FRAME_ENCODER_01_003: [** The first fragment MAY also be the final fragment. **]** |
| 105 |
|
| 106 |
RSV1, RSV2, RSV3: 1 bit each |
| 107 |
|
| 108 |
**SRS_UWS_FRAME_ENCODER_01_004: [** MUST be 0 unless an extension is negotiated that defines meanings for non-zero values. **]** |
| 109 |
If a nonzero value is received and none of the negotiated extensions defines the meaning of such a nonzero value, the receiving endpoint MUST _Fail the WebSocket Connection_. |
| 110 |
|
| 111 |
Opcode: 4 bits |
| 112 |
|
| 113 |
Defines the interpretation of the "Payload data". |
| 114 |
**SRS_UWS_FRAME_ENCODER_01_006: [** If an unknown opcode is received, the receiving endpoint MUST _Fail the WebSocket Connection_. **]** |
| 115 |
The following values are defined. |
| 116 |
|
| 117 |
**SRS_UWS_FRAME_ENCODER_01_007: [** * %x0 denotes a continuation frame **]** |
| 118 |
|
| 119 |
**SRS_UWS_FRAME_ENCODER_01_008: [** * %x1 denotes a text frame **]** |
| 120 |
|
| 121 |
**SRS_UWS_FRAME_ENCODER_01_009: [** * %x2 denotes a binary frame **]** |
| 122 |
|
| 123 |
**SRS_UWS_FRAME_ENCODER_01_010: [** * %x3-7 are reserved for further non-control frames **]** |
| 124 |
|
| 125 |
**SRS_UWS_FRAME_ENCODER_01_011: [** * %x8 denotes a connection close **]** |
| 126 |
|
| 127 |
**SRS_UWS_FRAME_ENCODER_01_012: [** * %x9 denotes a ping **]** |
| 128 |
|
| 129 |
**SRS_UWS_FRAME_ENCODER_01_013: [** * %xA denotes a pong **]** |
| 130 |
|
| 131 |
**SRS_UWS_FRAME_ENCODER_01_014: [** * %xB-F are reserved for further control frames **]** |
| 132 |
|
| 133 |
Mask: 1 bit |
| 134 |
|
| 135 |
**SRS_UWS_FRAME_ENCODER_01_015: [** Defines whether the "Payload data" is masked. **]** |
| 136 |
**SRS_UWS_FRAME_ENCODER_01_016: [** If set to 1, a masking key is present in masking-key, and this is used to unmask the "Payload data" as per Section 5.3. **]** |
| 137 |
All frames sent from client to server have this bit set to 1. |
| 138 |
|
| 139 |
Payload length: 7 bits, 7+16 bits, or 7+64 bits |
| 140 |
|
| 141 |
**SRS_UWS_FRAME_ENCODER_01_018: [** The length of the "Payload data", in bytes: **]** **SRS_UWS_FRAME_ENCODER_01_043: [** if 0-125, that is the payload length. **]** |
| 142 |
**SRS_UWS_FRAME_ENCODER_01_019: [** If 126, the following 2 bytes interpreted as a 16-bit unsigned integer are the payload length. **]** |
| 143 |
**SRS_UWS_FRAME_ENCODER_01_020: [** If 127, the following 8 bytes interpreted as a 64-bit unsigned integer (the most significant bit MUST be 0) are the payload length. **]** |
| 144 |
**SRS_UWS_FRAME_ENCODER_01_021: [** Multibyte length quantities are expressed in network byte order. **]** |
| 145 |
**SRS_UWS_FRAME_ENCODER_01_022: [** Note that in all cases, the minimal number of bytes MUST be used to encode the length, for example, the length of a 124-byte-long string can't be encoded as the sequence 126, 0, 124. **]** |
| 146 |
**SRS_UWS_FRAME_ENCODER_01_023: [** The payload length is the length of the "Extension data" + the length of the "Application data". **]** |
| 147 |
The length of the "Extension data" may be zero, in which case the payload length is the length of the "Application data". |
| 148 |
|
| 149 |
Masking-key: 0 or 4 bytes |
| 150 |
|
| 151 |
All frames sent from the client to the server are masked by a 32-bit value that is contained within the frame. |
| 152 |
**SRS_UWS_FRAME_ENCODER_01_026: [** This field is present if the mask bit is set to 1 and is absent if the mask bit is set to 0. **]** |
| 153 |
See Section 5.3 for further information on client-to-server masking. |
| 154 |
|
| 155 |
Payload data: (x+y) bytes |
| 156 |
|
| 157 |
The "Payload data" is defined as "Extension data" concatenated with "Application data". |
| 158 |
|
| 159 |
Extension data: x bytes |
| 160 |
|
| 161 |
The "Extension data" is 0 bytes unless an extension has been negotiated. |
| 162 |
Any extension MUST specify the length of the "Extension data", or how that length may be calculated, and how the extension use MUST be negotiated during the opening handshake. |
| 163 |
If present, the "Extension data" is included in the total payload length. |
| 164 |
|
| 165 |
Application data: y bytes |
| 166 |
|
| 167 |
Arbitrary "Application data", taking up the remainder of the frame after any "Extension data". |
| 168 |
The length of the "Application data" is equal to the payload length minus the length of the "Extension data". |
| 169 |
|
| 170 |
The base framing protocol is formally defined by the following ABNF [RFC5234]. |
| 171 |
It is important to note that the representation of this data is binary, not ASCII characters. |
| 172 |
As such, a field with a length of 1 bit that takes values %x0 / %x1 is represented as a single bit whose value is 0 or 1, not a full byte (octet) that stands for the characters "0" or "1" in the ASCII encoding. |
| 173 |
A field with a length of 4 bits with values between %x0-F again is represented by 4 bits, again NOT by an ASCII character or full byte (octet) with these values. |
| 174 |
[RFC5234] does not specify a character encoding: "Rules resolve into a string of terminal values, sometimes called characters. In ABNF, a character is merely a non-negative integer. In certain contexts, a specific mapping (encoding) of values into a character set (such as ASCII) will be specified." |
| 175 |
Here, the specified encoding is a binary encoding where each terminal value is encoded in the specified number of bits, which varies for each field. |
| 176 |
|
| 177 |
ws-frame = frame-fin ; 1 bit in length |
| 178 |
frame-rsv1 ; 1 bit in length |
| 179 |
frame-rsv2 ; 1 bit in length |
| 180 |
frame-rsv3 ; 1 bit in length |
| 181 |
frame-opcode ; 4 bits in length |
| 182 |
frame-masked ; 1 bit in length |
| 183 |
frame-payload-length ; either 7, 7+16, |
| 184 |
; or 7+64 bits in |
| 185 |
; length |
| 186 |
[ frame-masking-key ] ; 32 bits in length |
| 187 |
frame-payload-data ; n*8 bits in |
| 188 |
; length, where |
| 189 |
; n >= 0 |
| 190 |
|
| 191 |
frame-fin = %x0 ; more frames of this message follow |
| 192 |
/ %x1 ; final frame of this message |
| 193 |
; 1 bit in length |
| 194 |
|
| 195 |
frame-rsv1 = %x0 / %x1 |
| 196 |
; 1 bit in length, MUST be 0 unless |
| 197 |
; negotiated otherwise |
| 198 |
|
| 199 |
frame-rsv2 = %x0 / %x1 |
| 200 |
; 1 bit in length, MUST be 0 unless |
| 201 |
; negotiated otherwise |
| 202 |
|
| 203 |
frame-rsv3 = %x0 / %x1 |
| 204 |
; 1 bit in length, MUST be 0 unless |
| 205 |
; negotiated otherwise |
| 206 |
|
| 207 |
frame-opcode = frame-opcode-non-control / |
| 208 |
frame-opcode-control / |
| 209 |
frame-opcode-cont |
| 210 |
|
| 211 |
frame-opcode-cont = %x0 ; frame continuation |
| 212 |
|
| 213 |
frame-opcode-non-control= %x1 ; text frame |
| 214 |
/ %x2 ; binary frame |
| 215 |
/ %x3-7 |
| 216 |
; 4 bits in length, |
| 217 |
; reserved for further non-control frames |
| 218 |
|
| 219 |
frame-opcode-control = %x8 ; connection close |
| 220 |
/ %x9 ; ping |
| 221 |
/ %xA ; pong |
| 222 |
/ %xB-F ; reserved for further control |
| 223 |
; frames |
| 224 |
; 4 bits in length |
| 225 |
|
| 226 |
frame-masked = %x0 |
| 227 |
; frame is not masked, no frame-masking-key |
| 228 |
/ %x1 |
| 229 |
; frame is masked, frame-masking-key present |
| 230 |
; 1 bit in length |
| 231 |
|
| 232 |
frame-payload-length = ( %x00-7D ) |
| 233 |
/ ( %x7E frame-payload-length-16 ) |
| 234 |
/ ( %x7F frame-payload-length-63 ) |
| 235 |
; 7, 7+16, or 7+64 bits in length, |
| 236 |
; respectively |
| 237 |
|
| 238 |
frame-payload-length-16 = %x0000-FFFF ; 16 bits in length |
| 239 |
|
| 240 |
frame-payload-length-63 = %x0000000000000000-7FFFFFFFFFFFFFFF |
| 241 |
; 64 bits in length |
| 242 |
|
| 243 |
frame-masking-key = 4( %x00-FF ) |
| 244 |
; present only if frame-masked is 1 |
| 245 |
; 32 bits in length |
| 246 |
|
| 247 |
frame-payload-data = (frame-masked-extension-data |
| 248 |
frame-masked-application-data) |
| 249 |
; when frame-masked is 1 |
| 250 |
/ (frame-unmasked-extension-data |
| 251 |
frame-unmasked-application-data) |
| 252 |
; when frame-masked is 0 |
| 253 |
|
| 254 |
frame-masked-extension-data = *( %x00-FF ) |
| 255 |
; reserved for future extensibility |
| 256 |
; n*8 bits in length, where n >= 0 |
| 257 |
|
| 258 |
frame-masked-application-data = *( %x00-FF ) |
| 259 |
; n*8 bits in length, where n >= 0 |
| 260 |
|
| 261 |
frame-unmasked-extension-data = *( %x00-FF ) |
| 262 |
; reserved for future extensibility |
| 263 |
; n*8 bits in length, where n >= 0 |
| 264 |
|
| 265 |
frame-unmasked-application-data = *( %x00-FF ) |
| 266 |
; n*8 bits in length, where n >= 0 |
| 267 |
|
| 268 |
5.3. Client-to-Server Masking |
| 269 |
|
| 270 |
**SRS_UWS_FRAME_ENCODER_01_033: [** A masked frame MUST have the field frame-masked set to 1, as defined in Section 5.2. **]** |
| 271 |
|
| 272 |
**SRS_UWS_FRAME_ENCODER_01_034: [** The masking key is contained completely within the frame, as defined in Section 5.2 as frame-masking-key. **]** |
| 273 |
|
| 274 |
**SRS_UWS_FRAME_ENCODER_01_035: [** It is used to mask the "Payload data" defined in the same section as frame-payload-data, which includes "Extension data" and "Application data". **]** |
| 275 |
|
| 276 |
**SRS_UWS_FRAME_ENCODER_01_036: [** The masking key is a 32-bit value chosen at random by the client. **]** |
| 277 |
|
| 278 |
**SRS_UWS_FRAME_ENCODER_01_037: [** When preparing a masked frame, the client MUST pick a fresh masking key from the set of allowed 32-bit values. **]** |
| 279 |
|
| 280 |
**SRS_UWS_FRAME_ENCODER_01_038: [** The masking key needs to be unpredictable; thus, the masking key MUST be derived from a strong source of entropy, and the masking key for a given frame MUST NOT make it simple for a server/proxy to predict the masking key for a subsequent frame. **]** |
| 281 |
|
| 282 |
The unpredictability of the masking key is essential to prevent authors of malicious applications from selecting the bytes that appear on the wire. |
| 283 |
RFC 4086 [RFC4086] discusses what entails a suitable source of entropy for security-sensitive applications. |
| 284 |
|
| 285 |
The masking does not affect the length of the "Payload data". |
| 286 |
|
| 287 |
**SRS_UWS_FRAME_ENCODER_01_039: [** To convert masked data into unmasked data, or vice versa, the following algorithm is applied. **]** |
| 288 |
|
| 289 |
**SRS_UWS_FRAME_ENCODER_01_040: [** The same algorithm applies regardless of the direction of the translation, e.g., the same steps are applied to mask the data as to unmask the data. **]** |
| 290 |
|
| 291 |
**SRS_UWS_FRAME_ENCODER_01_041: [** Octet i of the transformed data ("transformed-octet-i") is the XOR of octet i of the original data ("original-octet-i") with octet at index i modulo 4 of the masking key ("masking-key-octet-j"): **]** |
| 292 |
|
| 293 |
j = i MOD 4 |
| 294 |
transformed-octet-i = original-octet-i XOR masking-key-octet-j |
| 295 |
|
| 296 |
**SRS_UWS_FRAME_ENCODER_01_042: [** The payload length, indicated in the framing as frame-payload-length, does NOT include the length of the masking key. **]** |
| 297 |
It is the length of the "Payload data", e.g., the number of bytes following the masking key. |