1 /* 2 * Copyright (c) 2014 by Farsight Security, Inc. 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to deal in the Software without restriction, including 7 * without limitation the rights to use, copy, modify, merge, publish, 8 * distribute, sublicense, and/or sell copies of the Software, and to 9 * permit persons to whom the Software is furnished to do so, subject to 10 * the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included 13 * in all copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 21 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 22 * 23 */ 24 25 #ifndef FSTRM_CONTROL_H 26 #define FSTRM_CONTROL_H 27 28 /** 29 * \defgroup fstrm_control fstrm_control 30 * 31 * `fstrm_control` is an interface for encoding and decoding Frame Streams 32 * control frames. 33 * 34 * Two types of frames are possible in a Frame Streams byte stream: **data 35 * frames** and **control frames**. Both are variable length byte sequences 36 * prefixed by a 32-bit big endian unsigned integer (the **frame length**) 37 * specifying the length of the following byte sequence. If this frame length 38 * value is greater than zero, the **frame length** specifies the **data frame 39 * length**, and a data frame follows it. If the frame length is zero (i.e., it 40 * is the four byte sequence `00 00 00 00`), this is an **escape sequence**, 41 * which means that a control frame follows. The control frame itself is 42 * prefixed by a 32-bit big endian unsigned integer (the **control frame 43 * length**) specifying the length of the following **control frame payload**. 44 * 45 * There are two types of control frames used for uni-directional streams: 46 * `START` and `STOP`. These control frame types bracket the stream of data 47 * frames. `START` indicates the beginning of the stream and communicates 48 * metadata about the stream to follow, and `STOP` indicates the end of the 49 * stream. 50 * 51 * Bi-directional streams make use of three additional control frame types: 52 * `READY`, `ACCEPT`, and `FINISH`. These control frame types are used in a 53 * simple handshake protocol between sender and receiver. 54 * 55 * A uni-directional Frame Streams byte stream normally consists of the 56 * following: 57 * 58 * 1. The `START` control frame. 59 * 2. A sequence of zero or more data frames or control frames that are not of 60 * the control frame types `START`, `STOP`, `ACCEPT`, `READY`, or 61 * `FINISH`. 62 * 3. The `STOP` control frame. 63 * 64 * The `START` and `STOP` control frames are not optional. The `START` control 65 * frame must appear at the beginning of the byte stream, and the `STOP` control 66 * frame must appear at the end of the byte stream. (If the byte stream has an 67 * end.) `START` control frames must not appear anywhere other than at the 68 * beginning of the byte stream, and `STOP` control frames must not appear 69 * anywhere other than at the end of the byte stream. Only one `START` control 70 * frame and only one `STOP` control frame may appear in a Frame Streams byte 71 * stream. 72 * 73 * Control frames may optionally include zero or more **control frame fields**. 74 * There is currently one type of control frame field defined: `CONTENT_TYPE`. 75 * This field specifies a variable length byte sequence describing the encoding 76 * of data frames that appear in the Frame Streams byte stream. This field is 77 * used by cooperating programs to unambiguously identify how to interpret the 78 * data frames in a particular Frame Streams byte stream. For instance, this 79 * field may specify a particular schema to use to interpret the data frames 80 * appearing in the byte stream. Zero, one, or more `CONTENT_TYPE` fields may 81 * appear in `READY` or `ACCEPT` control frames. Zero or one `CONTENT_TYPE` 82 * fields may appear in `START` control frames. No `CONTENT_TYPE` fields may 83 * appear in `STOP` or `FINISH` control frames. 84 * 85 * A uni-directional Frame Streams encoder would normally produce a byte stream 86 * as follows: 87 * 88 * 1. Write the `START` **control frame**. 89 * + At the start of the byte stream, write the four byte **escape 90 * sequence** `00 00 00 00` that precedes control frames. 91 * + Write the **control frame length** as a 32-bit big endian unsigned 92 * integer. 93 * + Write the **control frame payload**. It must be a `START` control 94 * frame. It may optionally specify a `CONTENT_TYPE` field. 95 * 2. Write zero or more **data frames**. 96 * 3. Write the `STOP` **control frame**. 97 * + At the start of the byte stream, write the four byte **escape 98 * sequence** `00 00 00 00` that precedes control frames. 99 * + Write the **control frame length** as a 32-bit big endian unsigned 100 * integer. 101 * + Write the **control frame payload**. It must be a `STOP` control 102 * frame. 103 * 104 * A uni-directional Frame Streams decoder would normally process the byte 105 * stream as follows: 106 * 107 * 1. Read the `START` control frame. 108 * + At the start of the byte stream, read the four byte **escape 109 * sequence** `00 00 00 00` that precedes control frames. 110 * + Read the 32-bit big endian unsigned integer specifying the **control 111 * frame length**. 112 * + Decode the **control frame payload**. It must be a `START` control 113 * frame. It may optionally specify a `CONTENT_TYPE` field. 114 * 2. Repeatedly read data frames or control frames following the `START` 115 * control frame. 116 * + Read the **frame length**, a 32-bit big endian unsigned integer. 117 * + If the **frame length** is zero, a control frame follows: 118 * + Read the 32-bit big endian unsigned integer specifying the 119 * **control frame length**. 120 * + Decode the **control frame payload**. If it is a `STOP` 121 * control frame, the end of the Frame Streams byte stream has 122 * occurred, and no frames follow. Break out of the decoding loop 123 * and halt processing. (`READY`, `ACCEPT`, `START`, and `FINISH` 124 * may not occur here. For forward compatibility, control frames of 125 * types other than the types `READY`, `ACCEPT`, `START`, `STOP`, 126 * and `FINISH` must be ignored here. No control frames specified 127 * in the future may alter the encoding of succeeding frames.) 128 * + If the **frame length** is non-zero, it specifies the number of bytes 129 * in the following **data frame**. Consume these bytes from the byte 130 * stream. 131 * 132 * The functions fstrm_control_encode() and fstrm_control_decode() are provided 133 * to encode and decode control frames. See the detailed descriptions of those 134 * functions for code examples showing their usage. 135 * 136 * @{ 137 */ 138 139 /** 140 * The maximum length in bytes of an "Accept", "Start", or "Stop" control frame 141 * payload. This excludes the escape sequence and the control frame length. 142 */ 143 #define FSTRM_CONTROL_FRAME_LENGTH_MAX 512 144 145 /** 146 * The maximum length in bytes of a "Content Type" control frame field payload. 147 * This excludes the field type and payload length. 148 */ 149 #define FSTRM_CONTROL_FIELD_CONTENT_TYPE_LENGTH_MAX 256 150 151 /** 152 * Control frame types. 153 */ 154 typedef enum { 155 /** Control frame type value for "Accept" control frames. */ 156 FSTRM_CONTROL_ACCEPT = 0x01, 157 158 /** Control frame type value for "Start" control frames. */ 159 FSTRM_CONTROL_START = 0x02, 160 161 /** Control frame type value for "Stop" control frames. */ 162 FSTRM_CONTROL_STOP = 0x03, 163 164 /** Control frame type value for "Ready" control frames. */ 165 FSTRM_CONTROL_READY = 0x04, 166 167 /** Control frame type value for "Finish" control frames. */ 168 FSTRM_CONTROL_FINISH = 0x05, 169 } fstrm_control_type; 170 171 /** 172 * Control frame field types. These are optional fields that can appear in 173 * control frames. 174 */ 175 typedef enum { 176 /** 177 * Control frame field type value for the "Content Type" control frame 178 * option. 179 */ 180 FSTRM_CONTROL_FIELD_CONTENT_TYPE = 0x01, 181 } fstrm_control_field; 182 183 /** 184 * Flags for controlling the behavior of the encoding and decoding functions. 185 */ 186 typedef enum { 187 /** 188 * Set to control whether to include the control frame header in 189 * encoding/decoding operations. 190 * 191 * Causes fstrm_control_encode() and fstrm_control_encoded_size() to 192 * include the control frame header containing the escape sequence and 193 * control frame payload length in the encoded output. Otherwise, only 194 * the control frame payload itself is encoded. 195 * 196 * Tells fstrm_control_decode() that the input buffer to be decoded 197 * begins with the control frame header containing the escape sequence 198 * and control frame payload length. (Note that this requires the caller 199 * to peek at the input buffer to calculate the right buffer length.) 200 * Otherwise, the input buffer begins with the control frame payload. 201 */ 202 FSTRM_CONTROL_FLAG_WITH_HEADER = (1 << 0), 203 } fstrm_control_flag; 204 205 /** 206 * Convert an `fstrm_control_type` enum value to a string representation. 207 * Unknown values are represented as `"FSTRM_CONTROL_UNKNOWN"`. 208 * 209 * \param type The `fstrm_control_type` enum value. 210 * \return The string representation of the enum value. (Always non-NULL.) 211 */ 212 const char * 213 fstrm_control_type_to_str(fstrm_control_type type); 214 215 /** 216 * Convert an `fstrm_control_field` enum value to a string representation. 217 * Unknown values are represented as `"FSTRM_CONTROL_FIELD_UNKNOWN"`. 218 * 219 * \param f_type The `fstrm_control_field` enum value. 220 * \return The string representation of the enum value. (Always non-NULL.) 221 */ 222 const char * 223 fstrm_control_field_type_to_str(fstrm_control_field f_type); 224 225 /** 226 * Initialize an `fstrm_control` object. This object represents Frame Streams 227 * control frames and is used for encoding and decoding control frames. 228 * 229 * \return 230 * An `fstrm_control` object. 231 */ 232 struct fstrm_control * 233 fstrm_control_init(void); 234 235 /** 236 * Destroy an `fstrm_control` object. 237 * 238 * \param[in] c 239 * Pointer to an `fstrm_control` object. 240 */ 241 void 242 fstrm_control_destroy(struct fstrm_control **c); 243 244 /** 245 * Reinitialize an `fstrm_control` object. This resets the internal state to 246 * default values. 247 * 248 * \param c 249 * `fstrm_control` object. 250 */ 251 void 252 fstrm_control_reset(struct fstrm_control *c); 253 254 /** 255 * Retrieve the type of the control frame. 256 * 257 * \param c 258 * `fstrm_control` object. 259 * \param[out] type 260 * Type of the control frame. 261 * 262 * \retval #fstrm_res_success 263 * \retval #fstrm_res_failure 264 */ 265 fstrm_res 266 fstrm_control_get_type( 267 const struct fstrm_control *c, 268 fstrm_control_type *type); 269 270 /** 271 * Set the type of the control frame. 272 * 273 * \param c 274 * `fstrm_control` object. 275 * \param[in] type 276 * Type of the control frame. 277 * 278 * \retval #fstrm_res_success 279 * \retval #fstrm_res_failure 280 */ 281 fstrm_res 282 fstrm_control_set_type( 283 struct fstrm_control *c, 284 fstrm_control_type type); 285 286 /** 287 * Retrieve the number of "Content Type" fields present in the control frame. 288 * 289 * \param c 290 * `fstrm_control` object. 291 * \param[out] n_content_type 292 * The number of "Content Type" fields. 293 * 294 * \retval #fstrm_res_success 295 * \retval #fstrm_res_failure 296 */ 297 fstrm_res 298 fstrm_control_get_num_field_content_type( 299 const struct fstrm_control *c, 300 size_t *n_content_type); 301 302 /** 303 * Retrieve a "Content Type" field from the control frame. This function 304 * returns a reference which must not be modified. Control frames may contain 305 * zero, one, or more "Content Type" fields. 306 * 307 * \see fstrm_control_get_num_field_content_type() 308 * 309 * \param c 310 * `fstrm_control` object. 311 * \param[in] idx 312 * The index of the "Content Type" field to retrieve. 313 * \param[out] content_type 314 * Pointer to where the reference to the "Content Type" string will be 315 * stored. Note that this string is not NUL-terminated and may contain 316 * embedded NULs. 317 * \param[out] len_content_type 318 * The number of bytes in `content_type`. 319 * 320 * \retval #fstrm_res_success 321 * The control frame has a "Content Type" field. 322 * \retval #fstrm_res_failure 323 * The control frame does not have a "Content Type" field. 324 */ 325 fstrm_res 326 fstrm_control_get_field_content_type( 327 const struct fstrm_control *c, 328 const size_t idx, 329 const uint8_t **content_type, 330 size_t *len_content_type); 331 332 /** 333 * Add a "Content Type" field to the control frame. This function makes a copy 334 * of the provided string. This function may be called multiple times, in which 335 * case multiple "Content Type" fields will be added to the control frame. 336 * 337 * The "Content Type" fields are removed on a call to fstrm_control_reset(). 338 * 339 * \param c 340 * `fstrm_control` object. 341 * \param[in] content_type 342 * The "Content Type" string to copy. Note that this string is not 343 * NUL-terminated and may contain embedded NULs. 344 * \param[in] len_content_type 345 * The number of bytes in `content_type`. 346 * 347 * \retval #fstrm_res_success 348 * The "Content Type" field was successfully added. 349 * \retval #fstrm_res_failure 350 * The "Content Type" string is too long. 351 */ 352 fstrm_res 353 fstrm_control_add_field_content_type( 354 struct fstrm_control *c, 355 const uint8_t *content_type, 356 size_t len_content_type); 357 358 /** 359 * Check if the control frame matches a particular content type value. That is, 360 * the content type given in the `match` and `len_match` parameters is checked 361 * for compatibility with the content types (if any) specified in the control 362 * frame. 363 * 364 * \param c 365 * `fstrm_control` object. 366 * \param match 367 * The "Content Type" string to match. Note that this string is not 368 * NUL-terminated and may contain embedded NULs. May be NULL, in which case 369 * the control frame must not have any content type fields in order to 370 * match. 371 * \param len_match 372 * The number of bytes in `match`. 373 * 374 * \retval #fstrm_res_success 375 * A match was found. 376 * \retval #fstrm_res_failure 377 * A match was not found. 378 */ 379 fstrm_res 380 fstrm_control_match_field_content_type( 381 const struct fstrm_control *c, 382 const uint8_t *match, 383 const size_t len_match); 384 385 /** 386 * Decode a control frame from a buffer. The buffer starts with either the 387 * escape sequence or the control frame payload depending on whether the 388 * `FSTRM_CONTROL_FLAG_WITH_HEADER` flag is set or not. In either case, the 389 * 'len_control_frame' parameter must be exact. Underflow or overflow is not 390 * permitted. 391 * 392 * The following code example shows a function that decodes a control frame 393 * payload: 394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 395 static fstrm_res 396 decode_control_frame(const void *control_frame, size_t len_control_frame) 397 { 398 fstrm_res res; 399 fstrm_control_type c_type; 400 struct fstrm_control *c; 401 uint32_t flags = 0; 402 403 c = fstrm_control_init(); 404 405 res = fstrm_control_decode(c, control_frame, len_control_frame, flags); 406 if (res != fstrm_res_success) { 407 puts("fstrm_control_decode() failed."); 408 fstrm_control_destroy(&c); 409 return res; 410 } 411 412 res = fstrm_control_get_type(c, &c_type); 413 if (res != fstrm_res_success) { 414 puts("fstrm_control_get_type() failed."); 415 fstrm_control_destroy(&c); 416 return res; 417 } 418 printf("The control frame is of type %s (%u).\n", 419 fstrm_control_type_to_str(c_type), c_type); 420 421 size_t n_content_type; 422 res = fstrm_control_get_num_field_content_type(c, &n_content_type); 423 if (res != fstrm_res_success) { 424 puts("fstrm_control_get_num_field_content_type() failed."); 425 fstrm_control_destroy(&c); 426 return res; 427 } 428 429 const uint8_t *content_type; 430 size_t len_content_type; 431 for (size_t idx = 0; idx < n_content_type; idx++) { 432 res = fstrm_control_get_field_content_type(c, idx, 433 &content_type, &len_content_type); 434 if (res == fstrm_res_success) { 435 printf("The control frame has a CONTENT_TYPE field of length %zd.\n", 436 len_content_type); 437 } 438 } 439 440 fstrm_control_destroy(&c); 441 return fstrm_res_success; 442 } 443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 444 * 445 * \param c 446 * `fstrm_control` object. Its state will be overwritten. 447 * \param[in] control_frame 448 * Buffer containing the serialized control frame. 449 * \param[in] len_control_frame 450 * The number of bytes in `control_frame`. This parameter must specify the 451 * exact number of bytes in the control frame. 452 * \param flags 453 * Flags controlling the decoding process. See #fstrm_control_flag. 454 * 455 * \retval #fstrm_res_success 456 * \retval #fstrm_res_failure 457 */ 458 fstrm_res 459 fstrm_control_decode( 460 struct fstrm_control *c, 461 const void *control_frame, 462 size_t len_control_frame, 463 const uint32_t flags); 464 465 /** 466 * Calculate the number of bytes needed to serialize the control frame. 467 * 468 * \param c 469 * `fstrm_control` object. 470 * \param[out] len_control_frame 471 * The number of bytes needed to encode `c`. 472 * \param flags 473 * Flags controlling the encoding process. See #fstrm_control_flag. 474 * 475 * \retval #fstrm_res_success 476 * \retval #fstrm_res_failure 477 */ 478 fstrm_res 479 fstrm_control_encoded_size( 480 const struct fstrm_control *c, 481 size_t *len_control_frame, 482 const uint32_t flags); 483 484 /** 485 * Encode a control frame into a buffer. Since a Frame Streams control frame is 486 * a variable length byte sequence of up to #FSTRM_CONTROL_FRAME_LENGTH_MAX 487 * bytes, this function can be used in two different ways. The first way is to 488 * call fstrm_control_encoded_size() to obtain the exact number of bytes needed 489 * to encode the frame, and then pass a buffer of this exact size to 490 * fstrm_control_encode(). The following example shows this usage: 491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 492 fstrm_res res; 493 struct fstrm_control *c; 494 uint8_t *control_frame; 495 size_t len_control_frame; 496 uint32_t flags = 0; 497 498 c = fstrm_control_init(); 499 res = fstrm_control_set_type(c, FSTRM_CONTROL_START); 500 if (res != fstrm_res_success) { 501 // Error handling goes here. 502 } 503 504 // Calculate the number of bytes needed. 505 res = fstrm_control_encoded_size(c, &len_control_frame, flags); 506 if (res != fstrm_res_success) { 507 // Error handling goes here. 508 } 509 510 // 'len_control_frame' now specifies the number of bytes required for 511 // the control frame. Allocate the needed space. 512 control_frame = malloc(len_control_frame); 513 if (!control_frame) { 514 // Error handling goes here. 515 } 516 517 // Serialize the control frame into the allocated buffer. 518 res = fstrm_control_encode(c, control_frame, &len_control_frame, 0); 519 if (res != fstrm_res_success) { 520 // Error handling goes here. 521 } 522 523 // Do something with 'control_frame' and 'len_control_frame'. 524 525 // Clean up. 526 free(control_frame); 527 fstrm_control_destroy(&c); 528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 529 * 530 * The second way to use fstrm_control_encode() is to allocate a statically 531 * sized buffer of #FSTRM_CONTROL_FRAME_LENGTH_MAX bytes. The exact number of 532 * bytes serialized by the encoder will be returned in the `len_control_frame` 533 * parameter. The following example shows this usage: 534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 535 fstrm_res res; 536 struct fstrm_control *c; 537 uint8_t control_frame[FSTRM_CONTROL_FRAME_LENGTH_MAX]; 538 size_t len_control_frame = sizeof(control_frame); 539 540 c = fstrm_control_init(); 541 res = fstrm_control_set_type(c, FSTRM_CONTROL_START); 542 if (res != fstrm_res_success) { 543 // Error handling. 544 } 545 546 // Serialize the control frame. 547 res = fstrm_control_encode(c, control_frame, &len_control_frame, 0); 548 if (res != fstrm_res_success) { 549 // Error handling goes here. 550 } 551 552 // Do something with 'control_frame' and 'len_control_frame'. 553 554 // Clean up. 555 fstrm_control_destroy(&c); 556 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 557 * 558 * \param c 559 * `fstrm_control` object. 560 * \param[out] control_frame 561 * The buffer in which to serialize the control frame. 562 * \param[in,out] len_control_frame 563 * The size in bytes of `control_frame`. On a successful return, contains 564 * the number of bytes actually written into `control_frame`. 565 * \param flags 566 * Flags controlling the encoding process. See #fstrm_control_flag. 567 * 568 * \retval #fstrm_res_success 569 * \retval #fstrm_res_failure 570 */ 571 fstrm_res 572 fstrm_control_encode( 573 const struct fstrm_control *c, 574 void *control_frame, 575 size_t *len_control_frame, 576 const uint32_t flags); 577 578 /**@}*/ 579 580 #endif /* FSTRM_CONTROL_H */ 581