Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/uws_frame_encoder_requirements.md

raw
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.