WebSocket++  0.8.3-dev
C++ websocket client/server library
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
frame.hpp
1 /*
2  * Copyright (c) 2014, Peter Thorson. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  * * Redistributions of source code must retain the above copyright
7  * notice, this list of conditions and the following disclaimer.
8  * * Redistributions in binary form must reproduce the above copyright
9  * notice, this list of conditions and the following disclaimer in the
10  * documentation and/or other materials provided with the distribution.
11  * * Neither the name of the WebSocket++ Project nor the
12  * names of its contributors may be used to endorse or promote products
13  * derived from this software without specific prior written permission.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED. IN NO EVENT SHALL PETER THORSON BE LIABLE FOR ANY
19  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  *
26  */
27 
28 #ifndef WEBSOCKETPP_FRAME_HPP
29 #define WEBSOCKETPP_FRAME_HPP
30 
31 #include <algorithm>
32 #include <string>
33 
34 #include <websocketpp/common/system_error.hpp>
35 #include <websocketpp/common/network.hpp>
36 
37 #include <websocketpp/utilities.hpp>
38 
39 namespace websocketpp {
40 /// Data structures and utility functions for manipulating WebSocket frames
41 /**
42  * namespace frame provides a number of data structures and utility functions
43  * for reading, writing, and manipulating binary encoded WebSocket frames.
44  */
45 namespace frame {
46 
47 /// Minimum length of a WebSocket frame header.
48 static unsigned int const BASIC_HEADER_LENGTH = 2;
49 /// Maximum length of a WebSocket header
50 static unsigned int const MAX_HEADER_LENGTH = 14;
51 /// Maximum length of the variable portion of the WebSocket header
52 static unsigned int const MAX_EXTENDED_HEADER_LENGTH = 12;
53 
54 /// Two byte conversion union
55 union uint16_converter {
56  uint16_t i;
57  uint8_t c[2];
58 };
59 
60 /// Four byte conversion union
61 union uint32_converter {
62  uint32_t i;
63  uint8_t c[4];
64 };
65 
66 /// Eight byte conversion union
67 union uint64_converter {
68  uint64_t i;
69  uint8_t c[8];
70 };
71 
72 /// Constants and utility functions related to WebSocket opcodes
73 /**
74  * WebSocket Opcodes are 4 bits. See RFC6455 section 5.2.
75  */
76 namespace opcode {
77  enum value {
78  continuation = 0x0,
79  text = 0x1,
80  binary = 0x2,
81  rsv3 = 0x3,
82  rsv4 = 0x4,
83  rsv5 = 0x5,
84  rsv6 = 0x6,
85  rsv7 = 0x7,
86  close = 0x8,
87  ping = 0x9,
88  pong = 0xA,
89  control_rsvb = 0xB,
90  control_rsvc = 0xC,
91  control_rsvd = 0xD,
92  control_rsve = 0xE,
93  control_rsvf = 0xF,
94 
95  CONTINUATION = 0x0,
96  TEXT = 0x1,
97  BINARY = 0x2,
98  RSV3 = 0x3,
99  RSV4 = 0x4,
100  RSV5 = 0x5,
101  RSV6 = 0x6,
102  RSV7 = 0x7,
103  CLOSE = 0x8,
104  PING = 0x9,
105  PONG = 0xA,
106  CONTROL_RSVB = 0xB,
107  CONTROL_RSVC = 0xC,
108  CONTROL_RSVD = 0xD,
109  CONTROL_RSVE = 0xE,
110  CONTROL_RSVF = 0xF
111  };
112 
113  /// Check if an opcode is reserved
114  /**
115  * @param v The opcode to test.
116  * @return Whether or not the opcode is reserved.
117  */
118  inline bool reserved(value v) {
119  return (v >= rsv3 && v <= rsv7) ||
120  (v >= control_rsvb && v <= control_rsvf);
121  }
122 
123  /// Check if an opcode is invalid
124  /**
125  * Invalid opcodes are negative or require greater than 4 bits to store.
126  *
127  * @param v The opcode to test.
128  * @return Whether or not the opcode is invalid.
129  */
130  inline bool invalid(value v) {
131  return (v > 0xF || v < 0);
132  }
133 
134  /// Check if an opcode is for a control frame
135  /**
136  * @param v The opcode to test.
137  * @return Whether or not the opcode is a control opcode.
138  */
139  inline bool is_control(value v) {
140  return v >= 0x8;
141  }
142 }
143 
144 /// Constants related to frame and payload limits
145 namespace limits {
146  /// Minimum length of a WebSocket frame header.
147  static unsigned int const basic_header_length = 2;
148 
149  /// Maximum length of a WebSocket header
150  static unsigned int const max_header_length = 14;
151 
152  /// Maximum length of the variable portion of the WebSocket header
153  static unsigned int const max_extended_header_length = 12;
154 
155  /// Maximum size of a basic WebSocket payload
156  static uint8_t const payload_size_basic = 125;
157 
158  /// Maximum size of an extended WebSocket payload (basic payload = 126)
159  static uint16_t const payload_size_extended = 0xFFFF; // 2^16, 65535
160 
161  /// Maximum size of a jumbo WebSocket payload (basic payload = 127)
162  static uint64_t const payload_size_jumbo = 0x7FFFFFFFFFFFFFFFLL;//2^63
163 
164  /// Maximum size of close frame reason
165  /**
166  * This is payload_size_basic - 2 bytes (as first two bytes are used for
167  * the close code
168  */
169  static uint8_t const close_reason_size = 123;
170 }
171 
172 
173 // masks for fields in the basic header
174 static uint8_t const BHB0_OPCODE = 0x0F;
175 static uint8_t const BHB0_RSV3 = 0x10;
176 static uint8_t const BHB0_RSV2 = 0x20;
177 static uint8_t const BHB0_RSV1 = 0x40;
178 static uint8_t const BHB0_FIN = 0x80;
179 
180 static uint8_t const BHB1_PAYLOAD = 0x7F;
181 static uint8_t const BHB1_MASK = 0x80;
182 
183 static uint8_t const payload_size_code_16bit = 0x7E; // 126
184 static uint8_t const payload_size_code_64bit = 0x7F; // 127
185 
186 typedef uint32_converter masking_key_type;
187 
188 /// The constant size component of a WebSocket frame header
189 struct basic_header {
190  basic_header() : b0(0x00),b1(0x00) {}
191 
192  basic_header(uint8_t p0, uint8_t p1) : b0(p0), b1(p1) {}
193 
194  basic_header(opcode::value op, uint64_t size, bool fin, bool mask,
195  bool rsv1 = false, bool rsv2 = false, bool rsv3 = false) : b0(0x00),
196  b1(0x00)
197  {
198  if (fin) {
199  b0 |= BHB0_FIN;
200  }
201  if (rsv1) {
202  b0 |= BHB0_RSV1;
203  }
204  if (rsv2) {
205  b0 |= BHB0_RSV2;
206  }
207  if (rsv3) {
208  b0 |= BHB0_RSV3;
209  }
210  b0 |= (op & BHB0_OPCODE);
211 
212  if (mask) {
213  b1 |= BHB1_MASK;
214  }
215 
216  uint8_t basic_value;
217 
218  if (size <= limits::payload_size_basic) {
219  basic_value = static_cast<uint8_t>(size);
220  } else if (size <= limits::payload_size_extended) {
221  basic_value = payload_size_code_16bit;
222  } else {
223  basic_value = payload_size_code_64bit;
224  }
225 
226 
227  b1 |= basic_value;
228  }
229 
230  uint8_t b0;
231  uint8_t b1;
232 };
233 
234 /// The variable size component of a WebSocket frame header
235 struct extended_header {
236  extended_header() {
237  std::fill_n(this->bytes,MAX_EXTENDED_HEADER_LENGTH,0x00);
238  }
239 
240  extended_header(uint64_t payload_size) {
241  std::fill_n(this->bytes,MAX_EXTENDED_HEADER_LENGTH,0x00);
242 
243  copy_payload(payload_size);
244  }
245 
246  extended_header(uint64_t payload_size, uint32_t masking_key) {
247  std::fill_n(this->bytes,MAX_EXTENDED_HEADER_LENGTH,0x00);
248 
249  // Copy payload size
250  int offset = copy_payload(payload_size);
251 
252  // Copy Masking Key
253  uint32_converter temp32;
254  temp32.i = masking_key;
255  std::copy(temp32.c,temp32.c+4,bytes+offset);
256  }
257 
258  uint8_t bytes[MAX_EXTENDED_HEADER_LENGTH];
259 private:
260  int copy_payload(uint64_t payload_size) {
261  int payload_offset = 0;
262 
263  if (payload_size <= limits::payload_size_basic) {
264  payload_offset = 8;
265  } else if (payload_size <= limits::payload_size_extended) {
266  payload_offset = 6;
267  }
268 
269  uint64_converter temp64;
270  temp64.i = lib::net::_htonll(payload_size);
271  std::copy(temp64.c+payload_offset,temp64.c+8,bytes);
272 
273  return 8-payload_offset;
274  }
275 };
276 
277 bool get_fin(basic_header const &h);
278 void set_fin(basic_header &h, bool value);
279 bool get_rsv1(basic_header const &h);
280 void set_rsv1(basic_header &h, bool value);
281 bool get_rsv2(basic_header const &h);
282 void set_rsv2(basic_header &h, bool value);
283 bool get_rsv3(basic_header const &h);
284 void set_rsv3(basic_header &h, bool value);
285 opcode::value get_opcode(basic_header const &h);
286 bool get_masked(basic_header const &h);
287 void set_masked(basic_header &h, bool value);
290 unsigned int get_masking_key_offset(basic_header const &);
291 
292 std::string write_header(basic_header const &, extended_header const &);
293 masking_key_type get_masking_key(basic_header const &, extended_header const &);
297 
300 
301 // Functions for performing xor based masking and unmasking
302 template <typename input_iter, typename output_iter>
303 void byte_mask(input_iter b, input_iter e, output_iter o, masking_key_type
304  const & key, size_t key_offset = 0);
305 template <typename iter_type>
306 void byte_mask(iter_type b, iter_type e, masking_key_type const & key,
307  size_t key_offset = 0);
308 void word_mask_exact(uint8_t * input, uint8_t * output, size_t length,
309  masking_key_type const & key);
310 void word_mask_exact(uint8_t * data, size_t length, masking_key_type const &
311  key);
315 
316 /// Check whether the frame's FIN bit is set.
317 /**
318  * @param [in] h The basic header to extract from.
319  * @return True if the header's fin bit is set.
320  */
321 inline bool get_fin(basic_header const & h) {
322  return ((h.b0 & BHB0_FIN) == BHB0_FIN);
323 }
324 
325 /// Set the frame's FIN bit
326 /**
327  * @param [out] h Header to set.
328  * @param [in] value Value to set it to.
329  */
330 inline void set_fin(basic_header & h, bool value) {
331  h.b0 = (value ? h.b0 | BHB0_FIN : h.b0 & ~BHB0_FIN);
332 }
333 
334 /// check whether the frame's RSV1 bit is set
335 /**
336  * @param [in] h The basic header to extract from.
337  * @return True if the header's RSV1 bit is set.
338  */
339 inline bool get_rsv1(const basic_header &h) {
340  return ((h.b0 & BHB0_RSV1) == BHB0_RSV1);
341 }
342 
343 /// Set the frame's RSV1 bit
344 /**
345  * @param [out] h Header to set.
346  * @param [in] value Value to set it to.
347  */
348 inline void set_rsv1(basic_header &h, bool value) {
349  h.b0 = (value ? h.b0 | BHB0_RSV1 : h.b0 & ~BHB0_RSV1);
350 }
351 
352 /// check whether the frame's RSV2 bit is set
353 /**
354  * @param [in] h The basic header to extract from.
355  * @return True if the header's RSV2 bit is set.
356  */
357 inline bool get_rsv2(const basic_header &h) {
358  return ((h.b0 & BHB0_RSV2) == BHB0_RSV2);
359 }
360 
361 /// Set the frame's RSV2 bit
362 /**
363  * @param [out] h Header to set.
364  * @param [in] value Value to set it to.
365  */
366 inline void set_rsv2(basic_header &h, bool value) {
367  h.b0 = (value ? h.b0 | BHB0_RSV2 : h.b0 & ~BHB0_RSV2);
368 }
369 
370 /// check whether the frame's RSV3 bit is set
371 /**
372  * @param [in] h The basic header to extract from.
373  * @return True if the header's RSV3 bit is set.
374  */
375 inline bool get_rsv3(const basic_header &h) {
376  return ((h.b0 & BHB0_RSV3) == BHB0_RSV3);
377 }
378 
379 /// Set the frame's RSV3 bit
380 /**
381  * @param [out] h Header to set.
382  * @param [in] value Value to set it to.
383  */
384 inline void set_rsv3(basic_header &h, bool value) {
385  h.b0 = (value ? h.b0 | BHB0_RSV3 : h.b0 & ~BHB0_RSV3);
386 }
387 
388 /// Extract opcode from basic header
389 /**
390  * @param [in] h The basic header to extract from.
391  * @return The opcode value of the header.
392  */
393 inline opcode::value get_opcode(const basic_header &h) {
394  return opcode::value(h.b0 & BHB0_OPCODE);
395 }
396 
397 /// check whether the frame is masked
398 /**
399  * @param [in] h The basic header to extract from.
400  * @return True if the header mask bit is set.
401  */
402 inline bool get_masked(basic_header const & h) {
403  return ((h.b1 & BHB1_MASK) == BHB1_MASK);
404 }
405 
406 /// Set the frame's MASK bit
407 /**
408  * @param [out] h Header to set.
409  * @param value Value to set it to.
410  */
411 inline void set_masked(basic_header & h, bool value) {
412  h.b1 = (value ? h.b1 | BHB1_MASK : h.b1 & ~BHB1_MASK);
413 }
414 
415 /// Extracts the raw payload length specified in the basic header
416 /**
417  * A basic WebSocket frame header contains a 7 bit value that represents the
418  * payload size. There are two reserved values that are used to indicate that
419  * the actual payload size will not fit in 7 bits and that the full payload
420  * size is included in a separate field. The values are as follows:
421  *
422  * PAYLOAD_SIZE_CODE_16BIT (0x7E) indicates that the actual payload is less
423  * than 16 bit
424  *
425  * PAYLOAD_SIZE_CODE_64BIT (0x7F) indicates that the actual payload is less
426  * than 63 bit
427  *
428  * @param [in] h Basic header to read value from.
429  * @return The exact size encoded in h.
430  */
432  return h.b1 & BHB1_PAYLOAD;
433 }
434 
435 /// Calculates the full length of the header based on the first bytes.
436 /**
437  * A WebSocket frame header always has at least two bytes. Encoded within the
438  * first two bytes is all the information necessary to calculate the full
439  * (variable) header length. get_header_len() calculates the full header
440  * length for the given two byte basic header.
441  *
442  * @param h Basic frame header to extract size from.
443  * @return Full length of the extended header.
444  */
446  // TODO: check extensions?
447 
448  // masking key offset represents the space used for the extended length
449  // fields
450  size_t size = BASIC_HEADER_LENGTH + get_masking_key_offset(h);
451 
452  // If the header is masked there is a 4 byte masking key
453  if (get_masked(h)) {
454  size += 4;
455  }
456 
457  return size;
458 }
459 
460 /// Calculate the offset location of the masking key within the extended header
461 /**
462  * Calculate the offset location of the masking key within the extended header
463  * using information from its corresponding basic header
464  *
465  * @param h Corresponding basic header to calculate from.
466  *
467  * @return byte offset of the first byte of the masking key
468  */
469 inline unsigned int get_masking_key_offset(const basic_header &h) {
470  if (get_basic_size(h) == payload_size_code_16bit) {
471  return 2;
472  } else if (get_basic_size(h) == payload_size_code_64bit) {
473  return 8;
474  } else {
475  return 0;
476  }
477 }
478 
479 /// Generate a properly sized contiguous string that encodes a full frame header
480 /**
481  * Copy the basic header h and extended header e into a properly sized
482  * contiguous frame header string for the purposes of writing out to the wire.
483  *
484  * @param h The basic header to include
485  * @param e The extended header to include
486  *
487  * @return A contiguous string containing h and e
488  */
489 inline std::string prepare_header(const basic_header &h, const
491 {
492  std::string ret;
493 
494  ret.push_back(char(h.b0));
495  ret.push_back(char(h.b1));
496  ret.append(
497  reinterpret_cast<const char*>(e.bytes),
498  get_header_len(h)-BASIC_HEADER_LENGTH
499  );
500 
501  return ret;
502 }
503 
504 /// Extract the masking key from a frame header
505 /**
506  * Note that while read and written as an integer at times, this value is not
507  * an integer and should never be interpreted as one. Big and little endian
508  * machines will generate and store masking keys differently without issue as
509  * long as the integer values remain irrelivant.
510  *
511  * @param h The basic header to extract from
512  * @param e The extended header to extract from
513  *
514  * @return The masking key as an integer.
515  */
516 inline masking_key_type get_masking_key(const basic_header &h, const
517  extended_header &e)
518 {
519  masking_key_type temp32;
520 
521  if (!get_masked(h)) {
522  temp32.i = 0;
523  } else {
524  unsigned int offset = get_masking_key_offset(h);
525  std::copy(e.bytes+offset,e.bytes+offset+4,temp32.c);
526  }
527 
528  return temp32;
529 }
530 
531 /// Extract the extended size field from an extended header
532 /**
533  * It is the responsibility of the caller to verify that e is a valid extended
534  * header. This function assumes that e contains an extended payload size.
535  *
536  * @param e The extended header to extract from
537  *
538  * @return The size encoded in the extended header in host byte order
539  */
541  uint16_converter temp16;
542  std::copy(e.bytes,e.bytes+2,temp16.c);
543  return ntohs(temp16.i);
544 }
545 
546 /// Extract the jumbo size field from an extended header
547 /**
548  * It is the responsibility of the caller to verify that e is a valid extended
549  * header. This function assumes that e contains a jumbo payload size.
550  *
551  * @param e The extended header to extract from
552  *
553  * @return The size encoded in the extended header in host byte order
554  */
556  uint64_converter temp64;
557  std::copy(e.bytes,e.bytes+8,temp64.c);
558  return lib::net::_ntohll(temp64.i);
559 }
560 
561 /// Extract the full payload size field from a WebSocket header
562 /**
563  * It is the responsibility of the caller to verify that h and e together
564  * represent a valid WebSocket frame header. This function assumes only that h
565  * and e are valid. It uses information in the basic header to determine where
566  * to look for the payload_size
567  *
568  * @param h The basic header to extract from
569  * @param e The extended header to extract from
570  *
571  * @return The size encoded in the combined header in host byte order.
572  */
575 {
576  uint8_t val = get_basic_size(h);
577 
578  if (val <= limits::payload_size_basic) {
579  return val;
580  } else if (val == payload_size_code_16bit) {
581  return get_extended_size(e);
582  } else {
583  return get_jumbo_size(e);
584  }
585 }
586 
587 /// Extract a masking key into a value the size of a machine word.
588 /**
589  * Machine word size must be 4 or 8.
590  *
591  * @param key Masking key to extract from
592  *
593  * @return prepared key as a machine word
594  */
596  size_t low_bits = static_cast<size_t>(key.i);
597 
598  if (sizeof(size_t) == 8) {
599  uint64_t high_bits = static_cast<size_t>(key.i);
600  return static_cast<size_t>((high_bits << 32) | low_bits);
601  } else {
602  return low_bits;
603  }
604 }
605 
606 /// circularly shifts the supplied prepared masking key by offset bytes
607 /**
608  * Prepared_key must be the output of prepare_masking_key with the associated
609  * restrictions on the machine word size. offset must be greater than or equal
610  * to zero and less than sizeof(size_t).
611  */
613  if (offset == 0) {
614  return prepared_key;
615  }
616  if (lib::net::is_little_endian()) {
617  size_t temp = prepared_key << (sizeof(size_t)-offset)*8;
618  return (prepared_key >> offset*8) | temp;
619  } else {
620  size_t temp = prepared_key >> (sizeof(size_t)-offset)*8;
621  return (prepared_key << offset*8) | temp;
622  }
623 }
624 
625 /// Byte by byte mask/unmask
626 /**
627  * Iterator based byte by byte masking and unmasking for WebSocket payloads.
628  * Performs masking in place using the supplied key offset by the supplied
629  * offset number of bytes.
630  *
631  * This function is simple and can be done in place on input with arbitrary
632  * lengths and does not vary based on machine word size. It is slow.
633  *
634  * @param b Beginning iterator to start masking
635  *
636  * @param e Ending iterator to end masking
637  *
638  * @param o Beginning iterator to store masked results
639  *
640  * @param key 32 bit key to mask with.
641  *
642  * @param key_offset offset value to start masking at.
643  */
644 template <typename input_iter, typename output_iter>
645 void byte_mask(input_iter first, input_iter last, output_iter result,
646  masking_key_type const & key, size_t key_offset)
647 {
648  size_t key_index = key_offset%4;
649  while (first != last) {
650  *result = *first ^ key.c[key_index++];
651  key_index %= 4;
652  ++result;
653  ++first;
654  }
655 }
656 
657 /// Byte by byte mask/unmask (in place)
658 /**
659  * Iterator based byte by byte masking and unmasking for WebSocket payloads.
660  * Performs masking in place using the supplied key offset by the supplied
661  * offset number of bytes.
662  *
663  * This function is simple and can be done in place on input with arbitrary
664  * lengths and does not vary based on machine word size. It is slow.
665  *
666  * @param b Beginning iterator to start masking
667  *
668  * @param e Ending iterator to end masking
669  *
670  * @param key 32 bit key to mask with.
671  *
672  * @param key_offset offset value to start masking at.
673  */
674 template <typename iter_type>
675 void byte_mask(iter_type b, iter_type e, masking_key_type const & key,
676  size_t key_offset)
677 {
678  byte_mask(b,e,b,key,key_offset);
679 }
680 
681 /// Exact word aligned mask/unmask
682 /**
683  * Balanced combination of byte by byte and circular word by word masking.
684  * Best used to mask complete messages at once. Has much higher setup costs than
685  * word_mask_circ but works with exact sized buffers.
686  *
687  * Buffer based word by word masking and unmasking for WebSocket payloads.
688  * Masking is done in word by word chunks with the remainder not divisible by
689  * the word size done byte by byte.
690  *
691  * input and output must both be at least length bytes. Exactly length bytes
692  * will be written.
693  *
694  * @param input buffer to mask or unmask
695  *
696  * @param output buffer to store the output. May be the same as input.
697  *
698  * @param length length of data buffer
699  *
700  * @param key Masking key to use
701  */
702 inline void word_mask_exact(uint8_t* input, uint8_t* output, size_t length,
703  const masking_key_type& key)
704 {
705  size_t prepared_key = prepare_masking_key(key);
706  size_t n = length/sizeof(size_t);
707  size_t* input_word = reinterpret_cast<size_t*>(input);
708  size_t* output_word = reinterpret_cast<size_t*>(output);
709 
710  for (size_t i = 0; i < n; i++) {
711  output_word[i] = input_word[i] ^ prepared_key;
712  }
713 
714  for (size_t i = n*sizeof(size_t); i < length; i++) {
715  output[i] = input[i] ^ key.c[i%4];
716  }
717 }
718 
719 /// Exact word aligned mask/unmask (in place)
720 /**
721  * In place version of word_mask_exact
722  *
723  * @see word_mask_exact
724  *
725  * @param data buffer to read and write from
726  *
727  * @param length length of data buffer
728  *
729  * @param key Masking key to use
730  */
731 inline void word_mask_exact(uint8_t* data, size_t length, const
732  masking_key_type& key)
733 {
734  word_mask_exact(data,data,length,key);
735 }
736 
737 /// Circular word aligned mask/unmask
738 /**
739  * Performs a circular mask/unmask in word sized chunks using pre-prepared keys
740  * that store state between calls. Best for providing streaming masking or
741  * unmasking of small chunks at a time of a larger message. Requires that the
742  * underlying allocated size of the data buffer be a multiple of the word size.
743  * Data in the buffer after `length` will be overwritten only with the same
744  * values that were originally present.
745  *
746  * Buffer based word by word masking and unmasking for WebSocket payloads.
747  * Performs masking in place using the supplied key. Casts the data buffer to
748  * an array of size_t's and performs masking word by word. The underlying
749  * buffer size must be a muliple of the word size.
750  *
751  * word_mask returns a copy of prepared_key circularly shifted based on the
752  * length value. The returned value may be fed back into word_mask when more
753  * data is available.
754  *
755  * input and output must both have length at least:
756  * ceil(length/sizeof(size_t))*sizeof(size_t)
757  * Exactly that many bytes will be written, although only exactly length bytes
758  * will be changed (trailing bytes will be replaced without masking)
759  *
760  * @param data Character buffer to mask
761  *
762  * @param length Length of data
763  *
764  * @param prepared_key Prepared key to use.
765  *
766  * @return the prepared_key shifted to account for the input length
767  */
770 {
771  size_t n = length / sizeof(size_t); // whole words
772  size_t l = length - (n * sizeof(size_t)); // remaining bytes
773  size_t * input_word = reinterpret_cast<size_t *>(input);
774  size_t * output_word = reinterpret_cast<size_t *>(output);
775 
776  // mask word by word
777  for (size_t i = 0; i < n; i++) {
778  output_word[i] = input_word[i] ^ prepared_key;
779  }
780 
781  // mask partial word at the end
782  size_t start = length - l;
783  uint8_t * byte_key = reinterpret_cast<uint8_t *>(&prepared_key);
784  for (size_t i = 0; i < l; ++i) {
785  output[start+i] = input[start+i] ^ byte_key[i];
786  }
787 
788  return circshift_prepared_key(prepared_key,l);
789 }
790 
791 /// Circular word aligned mask/unmask (in place)
792 /**
793  * In place version of word_mask_circ
794  *
795  * @see word_mask_circ
796  *
797  * @param data Character buffer to read from and write to
798  *
799  * @param length Length of data
800  *
801  * @param prepared_key Prepared key to use.
802  *
803  * @return the prepared_key shifted to account for the input length
804  */
806  return word_mask_circ(data,data,length,prepared_key);
807 }
808 
809 /// Circular byte aligned mask/unmask
810 /**
811  * Performs a circular mask/unmask in byte sized chunks using pre-prepared keys
812  * that store state between calls. Best for providing streaming masking or
813  * unmasking of small chunks at a time of a larger message. Requires that the
814  * underlying allocated size of the data buffer be a multiple of the word size.
815  * Data in the buffer after `length` will be overwritten only with the same
816  * values that were originally present.
817  *
818  * word_mask returns a copy of prepared_key circularly shifted based on the
819  * length value. The returned value may be fed back into byte_mask when more
820  * data is available.
821  *
822  * @param data Character buffer to mask
823  *
824  * @param length Length of data
825  *
826  * @param prepared_key Prepared key to use.
827  *
828  * @return the prepared_key shifted to account for the input length
829  */
832 {
833  uint32_converter key;
834  key.i = prepared_key;
835 
836  for (size_t i = 0; i < length; ++i) {
837  output[i] = input[i] ^ key.c[i % 4];
838  }
839 
840  return circshift_prepared_key(prepared_key,length % 4);
841 }
842 
843 /// Circular byte aligned mask/unmask (in place)
844 /**
845  * In place version of byte_mask_circ
846  *
847  * @see byte_mask_circ
848  *
849  * @param data Character buffer to read from and write to
850  *
851  * @param length Length of data
852  *
853  * @param prepared_key Prepared key to use.
854  *
855  * @return the prepared_key shifted to account for the input length
856  */
858  return byte_mask_circ(data,data,length,prepared_key);
859 }
860 
861 } // namespace frame
862 } // namespace websocketpp
863 
864 #endif //WEBSOCKETPP_FRAME_HPP
websocketpp::frame::MAX_EXTENDED_HEADER_LENGTH
static unsigned int const MAX_EXTENDED_HEADER_LENGTH
Maximum length of the variable portion of the WebSocket header.
Definition: frame.hpp:52
websocketpp::frame::get_rsv3
bool get_rsv3(basic_header const &h)
check whether the frame's RSV3 bit is set
Definition: frame.hpp:375
websocketpp::frame::set_rsv2
void set_rsv2(basic_header &h, bool value)
Set the frame's RSV2 bit.
Definition: frame.hpp:366
websocketpp::frame::get_rsv2
bool get_rsv2(basic_header const &h)
check whether the frame's RSV2 bit is set
Definition: frame.hpp:357
websocketpp::frame::get_rsv1
bool get_rsv1(basic_header const &h)
check whether the frame's RSV1 bit is set
Definition: frame.hpp:339
websocketpp::frame::opcode
Constants and utility functions related to WebSocket opcodes.
Definition: frame.hpp:76
websocketpp::frame::opcode::reserved
bool reserved(value v)
Check if an opcode is reserved.
Definition: frame.hpp:118
websocketpp::frame::get_fin
bool get_fin(basic_header const &h)
Check whether the frame's FIN bit is set.
Definition: frame.hpp:321
websocketpp::frame::limits::basic_header_length
static unsigned int const basic_header_length
Minimum length of a WebSocket frame header.
Definition: frame.hpp:147
websocketpp::frame::get_payload_size
uint64_t get_payload_size(basic_header const &, extended_header const &)
Extract the full payload size field from a WebSocket header.
Definition: frame.hpp:573
websocketpp::frame::get_header_len
size_t get_header_len(basic_header const &)
Calculates the full length of the header based on the first bytes.
Definition: frame.hpp:445
websocketpp::frame::byte_mask
void byte_mask(iter_type b, iter_type e, masking_key_type const &key, size_t key_offset=0)
Byte by byte mask/unmask (in place)
Definition: frame.hpp:675
websocketpp::frame::set_masked
void set_masked(basic_header &h, bool value)
Set the frame's MASK bit.
Definition: frame.hpp:411
websocketpp::frame::limits::close_reason_size
static uint8_t const close_reason_size
Maximum size of close frame reason.
Definition: frame.hpp:169
websocketpp::frame::word_mask_exact
void word_mask_exact(uint8_t *input, uint8_t *output, size_t length, masking_key_type const &key)
Exact word aligned mask/unmask.
Definition: frame.hpp:702
websocketpp::frame::limits::payload_size_basic
static uint8_t const payload_size_basic
Maximum size of a basic WebSocket payload.
Definition: frame.hpp:156
websocketpp::frame::get_masking_key
masking_key_type get_masking_key(basic_header const &, extended_header const &)
Extract the masking key from a frame header.
Definition: frame.hpp:516
websocketpp::frame::limits::max_header_length
static unsigned int const max_header_length
Maximum length of a WebSocket header.
Definition: frame.hpp:150
websocketpp::versions_supported
static std::vector< int > const versions_supported(helper, helper+4)
Container that stores the list of protocol versions supported.
websocketpp::frame::opcode::is_control
bool is_control(value v)
Check if an opcode is for a control frame.
Definition: frame.hpp:139
websocketpp::frame::set_rsv3
void set_rsv3(basic_header &h, bool value)
Set the frame's RSV3 bit.
Definition: frame.hpp:384
websocketpp::frame::opcode::invalid
bool invalid(value v)
Check if an opcode is invalid.
Definition: frame.hpp:130
websocketpp::frame::basic_header
The constant size component of a WebSocket frame header.
Definition: frame.hpp:189
websocketpp::frame::byte_mask
void byte_mask(input_iter b, input_iter e, output_iter o, masking_key_type const &key, size_t key_offset=0)
Byte by byte mask/unmask.
Definition: frame.hpp:645
websocketpp::frame::word_mask_circ
size_t word_mask_circ(uint8_t *data, size_t length, size_t prepared_key)
Circular word aligned mask/unmask (in place)
Definition: frame.hpp:805
websocketpp::frame::limits
Constants related to frame and payload limits.
Definition: frame.hpp:145
websocketpp::frame::limits::payload_size_jumbo
static uint64_t const payload_size_jumbo
Maximum size of a jumbo WebSocket payload (basic payload = 127)
Definition: frame.hpp:162
websocketpp::frame::word_mask_exact
void word_mask_exact(uint8_t *data, size_t length, masking_key_type const &key)
Exact word aligned mask/unmask (in place)
Definition: frame.hpp:731
websocketpp::frame::MAX_HEADER_LENGTH
static unsigned int const MAX_HEADER_LENGTH
Maximum length of a WebSocket header.
Definition: frame.hpp:50
websocketpp::frame::get_jumbo_size
uint64_t get_jumbo_size(extended_header const &)
Extract the jumbo size field from an extended header.
Definition: frame.hpp:555
websocketpp::frame::set_fin
void set_fin(basic_header &h, bool value)
Set the frame's FIN bit.
Definition: frame.hpp:330
websocketpp::frame::prepare_masking_key
size_t prepare_masking_key(masking_key_type const &key)
Extract a masking key into a value the size of a machine word.
Definition: frame.hpp:595
websocketpp::frame::byte_mask_circ
size_t byte_mask_circ(uint8_t *input, uint8_t *output, size_t length, size_t prepared_key)
Circular byte aligned mask/unmask.
Definition: frame.hpp:830
websocketpp::frame::get_opcode
opcode::value get_opcode(basic_header const &h)
Extract opcode from basic header.
Definition: frame.hpp:393
websocketpp::frame::get_masked
bool get_masked(basic_header const &h)
check whether the frame is masked
Definition: frame.hpp:402
websocketpp::frame::limits::max_extended_header_length
static unsigned int const max_extended_header_length
Maximum length of the variable portion of the WebSocket header.
Definition: frame.hpp:153
websocketpp::frame
Data structures and utility functions for manipulating WebSocket frames.
Definition: frame.hpp:45
websocketpp::frame::prepare_header
std::string prepare_header(const basic_header &h, const extended_header &e)
Generate a properly sized contiguous string that encodes a full frame header.
Definition: frame.hpp:489
websocketpp::frame::get_masking_key_offset
unsigned int get_masking_key_offset(basic_header const &)
Calculate the offset location of the masking key within the extended header.
Definition: frame.hpp:469
websocketpp::frame::limits::payload_size_extended
static uint16_t const payload_size_extended
Maximum size of an extended WebSocket payload (basic payload = 126)
Definition: frame.hpp:159
websocketpp::frame::byte_mask_circ
size_t byte_mask_circ(uint8_t *data, size_t length, size_t prepared_key)
Circular byte aligned mask/unmask (in place)
Definition: frame.hpp:857
websocketpp::frame::BASIC_HEADER_LENGTH
static unsigned int const BASIC_HEADER_LENGTH
Minimum length of a WebSocket frame header.
Definition: frame.hpp:48
websocketpp::frame::word_mask_circ
size_t word_mask_circ(uint8_t *input, uint8_t *output, size_t length, size_t prepared_key)
Circular word aligned mask/unmask.
Definition: frame.hpp:768
websocketpp::frame::circshift_prepared_key
size_t circshift_prepared_key(size_t prepared_key, size_t offset)
circularly shifts the supplied prepared masking key by offset bytes
Definition: frame.hpp:612
websocketpp::frame::set_rsv1
void set_rsv1(basic_header &h, bool value)
Set the frame's RSV1 bit.
Definition: frame.hpp:348
websocketpp::frame::get_extended_size
uint16_t get_extended_size(extended_header const &)
Extract the extended size field from an extended header.
Definition: frame.hpp:540
websocketpp::frame::get_basic_size
uint8_t get_basic_size(basic_header const &)
Extracts the raw payload length specified in the basic header.
Definition: frame.hpp:431