1 /* $OpenBSD: bytestring.h,v 1.18 2021/05/16 08:32:49 jsing Exp $ */ 2 /* 3 * Copyright (c) 2014, Google Inc. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 12 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 14 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 15 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ 16 17 #ifndef OPENSSL_HEADER_BYTESTRING_H 18 #define OPENSSL_HEADER_BYTESTRING_H 19 20 #include <sys/types.h> 21 #include <stdint.h> 22 23 __BEGIN_HIDDEN_DECLS 24 25 /* 26 * Bytestrings are used for parsing and building TLS and ASN.1 messages. 27 * 28 * A "CBS" (CRYPTO ByteString) represents a string of bytes in memory and 29 * provides utility functions for safely parsing length-prefixed structures 30 * like TLS and ASN.1 from it. 31 * 32 * A "CBB" (CRYPTO ByteBuilder) is a memory buffer that grows as needed and 33 * provides utility functions for building length-prefixed messages. 34 */ 35 36 /* CRYPTO ByteString */ 37 typedef struct cbs_st { 38 const uint8_t *data; 39 size_t initial_len; 40 size_t len; 41 } CBS; 42 43 /* 44 * CBS_init sets |cbs| to point to |data|. It does not take ownership of 45 * |data|. 46 */ 47 void CBS_init(CBS *cbs, const uint8_t *data, size_t len); 48 49 /* 50 * CBS_skip advances |cbs| by |len| bytes. It returns one on success and zero 51 * otherwise. 52 */ 53 int CBS_skip(CBS *cbs, size_t len); 54 55 /* 56 * CBS_data returns a pointer to the contents of |cbs|. 57 */ 58 const uint8_t *CBS_data(const CBS *cbs); 59 60 /* 61 * CBS_len returns the number of bytes remaining in |cbs|. 62 */ 63 size_t CBS_len(const CBS *cbs); 64 65 /* 66 * CBS_offset returns the current offset into the original data of |cbs|. 67 */ 68 size_t CBS_offset(const CBS *cbs); 69 70 /* 71 * CBS_stow copies the current contents of |cbs| into |*out_ptr| and 72 * |*out_len|. If |*out_ptr| is not NULL, the contents are freed with 73 * free. It returns one on success and zero on allocation failure. On 74 * success, |*out_ptr| should be freed with free. If |cbs| is empty, 75 * |*out_ptr| will be NULL. 76 */ 77 int CBS_stow(const CBS *cbs, uint8_t **out_ptr, size_t *out_len); 78 79 /* 80 * CBS_strdup copies the current contents of |cbs| into |*out_ptr| as a 81 * NUL-terminated C string. If |*out_ptr| is not NULL, the contents are freed 82 * with free. It returns one on success and zero on allocation 83 * failure. On success, |*out_ptr| should be freed with free. 84 * 85 * NOTE: If |cbs| contains NUL bytes, the string will be truncated. Call 86 * |CBS_contains_zero_byte(cbs)| to check for NUL bytes. 87 */ 88 int CBS_strdup(const CBS *cbs, char **out_ptr); 89 90 /* 91 * CBS_write_bytes writes all of the remaining data from |cbs| into |dst| 92 * if it is at most |dst_len| bytes. If |copied| is not NULL, it will be set 93 * to the amount copied. It returns one on success and zero otherwise. 94 */ 95 int CBS_write_bytes(const CBS *cbs, uint8_t *dst, size_t dst_len, 96 size_t *copied); 97 98 /* 99 * CBS_contains_zero_byte returns one if the current contents of |cbs| contains 100 * a NUL byte and zero otherwise. 101 */ 102 int CBS_contains_zero_byte(const CBS *cbs); 103 104 /* 105 * CBS_mem_equal compares the current contents of |cbs| with the |len| bytes 106 * starting at |data|. If they're equal, it returns one, otherwise zero. If the 107 * lengths match, it uses a constant-time comparison. 108 */ 109 int CBS_mem_equal(const CBS *cbs, const uint8_t *data, size_t len); 110 111 /* 112 * CBS_get_u8 sets |*out| to the next uint8_t from |cbs| and advances |cbs|. It 113 * returns one on success and zero on error. 114 */ 115 int CBS_get_u8(CBS *cbs, uint8_t *out); 116 117 /* 118 * CBS_get_u16 sets |*out| to the next, big-endian uint16_t from |cbs| and 119 * advances |cbs|. It returns one on success and zero on error. 120 */ 121 int CBS_get_u16(CBS *cbs, uint16_t *out); 122 123 /* 124 * CBS_get_u24 sets |*out| to the next, big-endian 24-bit value from |cbs| and 125 * advances |cbs|. It returns one on success and zero on error. 126 */ 127 int CBS_get_u24(CBS *cbs, uint32_t *out); 128 129 /* 130 * CBS_get_u32 sets |*out| to the next, big-endian uint32_t value from |cbs| 131 * and advances |cbs|. It returns one on success and zero on error. 132 */ 133 int CBS_get_u32(CBS *cbs, uint32_t *out); 134 135 /* 136 * CBS_get_bytes sets |*out| to the next |len| bytes from |cbs| and advances 137 * |cbs|. It returns one on success and zero on error. 138 */ 139 int CBS_get_bytes(CBS *cbs, CBS *out, size_t len); 140 141 /* 142 * CBS_get_u8_length_prefixed sets |*out| to the contents of an 8-bit, 143 * length-prefixed value from |cbs| and advances |cbs| over it. It returns one 144 * on success and zero on error. 145 */ 146 int CBS_get_u8_length_prefixed(CBS *cbs, CBS *out); 147 148 /* 149 * CBS_get_u16_length_prefixed sets |*out| to the contents of a 16-bit, 150 * big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It 151 * returns one on success and zero on error. 152 */ 153 int CBS_get_u16_length_prefixed(CBS *cbs, CBS *out); 154 155 /* 156 * CBS_get_u24_length_prefixed sets |*out| to the contents of a 24-bit, 157 * big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It 158 * returns one on success and zero on error. 159 */ 160 int CBS_get_u24_length_prefixed(CBS *cbs, CBS *out); 161 162 163 /* Parsing ASN.1 */ 164 165 /* 166 * While an identifier can be multiple octets, this library only handles the 167 * single octet variety currently. This limits support up to tag number 30 168 * since tag number 31 is a reserved value to indicate multiple octets. 169 */ 170 171 /* Bits 8 and 7: class tag type: See X.690 section 8.1.2.2. */ 172 #define CBS_ASN1_UNIVERSAL 0x00 173 #define CBS_ASN1_APPLICATION 0x40 174 #define CBS_ASN1_CONTEXT_SPECIFIC 0x80 175 #define CBS_ASN1_PRIVATE 0xc0 176 177 /* Bit 6: Primitive or constructed: See X.690 section 8.1.2.3. */ 178 #define CBS_ASN1_PRIMITIVE 0x00 179 #define CBS_ASN1_CONSTRUCTED 0x20 180 181 /* 182 * Bits 5 to 1 are the tag number. See X.680 section 8.6 for tag numbers of 183 * the universal class. 184 */ 185 186 /* 187 * Common universal identifier octets. 188 * See X.690 section 8.1 and X.680 section 8.6 for universal tag numbers. 189 * 190 * Note: These definitions are the cause of some of the strange behavior in 191 * CBS's bs_ber.c. 192 * 193 * In BER, it is the sender's option to use primitive or constructed for 194 * bitstring (X.690 section 8.6.1) and octetstring (X.690 section 8.7.1). 195 * 196 * In DER, bitstring and octetstring are required to be primitive 197 * (X.690 section 10.2). 198 */ 199 #define CBS_ASN1_BOOLEAN (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0x1) 200 #define CBS_ASN1_INTEGER (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0x2) 201 #define CBS_ASN1_BITSTRING (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0x3) 202 #define CBS_ASN1_OCTETSTRING (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0x4) 203 #define CBS_ASN1_OBJECT (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0x6) 204 #define CBS_ASN1_ENUMERATED (CBS_ASN1_UNIVERSAL | CBS_ASN1_PRIMITIVE | 0xa) 205 #define CBS_ASN1_SEQUENCE (CBS_ASN1_UNIVERSAL | CBS_ASN1_CONSTRUCTED | 0x10) 206 #define CBS_ASN1_SET (CBS_ASN1_UNIVERSAL | CBS_ASN1_CONSTRUCTED | 0x11) 207 208 /* 209 * CBS_get_asn1 sets |*out| to the contents of DER-encoded, ASN.1 element (not 210 * including tag and length bytes) and advances |cbs| over it. The ASN.1 211 * element must match |tag_value|. It returns one on success and zero 212 * on error. 213 * 214 * Tag numbers greater than 30 are not supported (i.e. short form only). 215 */ 216 int CBS_get_asn1(CBS *cbs, CBS *out, unsigned int tag_value); 217 218 /* 219 * CBS_get_asn1_element acts like |CBS_get_asn1| but |out| will include the 220 * ASN.1 header bytes too. 221 */ 222 int CBS_get_asn1_element(CBS *cbs, CBS *out, unsigned int tag_value); 223 224 /* 225 * CBS_peek_asn1_tag looks ahead at the next ASN.1 tag and returns one 226 * if the next ASN.1 element on |cbs| would have tag |tag_value|. If 227 * |cbs| is empty or the tag does not match, it returns zero. Note: if 228 * it returns one, CBS_get_asn1 may still fail if the rest of the 229 * element is malformed. 230 */ 231 int CBS_peek_asn1_tag(const CBS *cbs, unsigned int tag_value); 232 233 /* 234 * CBS_get_any_asn1_element sets |*out| to contain the next ASN.1 element from 235 * |*cbs| (including header bytes) and advances |*cbs|. It sets |*out_tag| to 236 * the tag number and |*out_header_len| to the length of the ASN.1 header. 237 * Each of |out|, |out_tag|, and |out_header_len| may be NULL to ignore 238 * the value. 239 * 240 * Tag numbers greater than 30 are not supported (i.e. short form only). 241 */ 242 int CBS_get_any_asn1_element(CBS *cbs, CBS *out, unsigned int *out_tag, 243 size_t *out_header_len); 244 245 /* 246 * CBS_get_asn1_uint64 gets an ASN.1 INTEGER from |cbs| using |CBS_get_asn1| 247 * and sets |*out| to its value. It returns one on success and zero on error, 248 * where error includes the integer being negative, or too large to represent 249 * in 64 bits. 250 */ 251 int CBS_get_asn1_uint64(CBS *cbs, uint64_t *out); 252 253 /* 254 * CBS_get_optional_asn1 gets an optional explicitly-tagged element 255 * from |cbs| tagged with |tag| and sets |*out| to its contents. If 256 * present, it sets |*out_present| to one, otherwise zero. It returns 257 * one on success, whether or not the element was present, and zero on 258 * decode failure. 259 */ 260 int CBS_get_optional_asn1(CBS *cbs, CBS *out, int *out_present, 261 unsigned int tag); 262 263 /* 264 * CBS_get_optional_asn1_octet_string gets an optional 265 * explicitly-tagged OCTET STRING from |cbs|. If present, it sets 266 * |*out| to the string and |*out_present| to one. Otherwise, it sets 267 * |*out| to empty and |*out_present| to zero. |out_present| may be 268 * NULL. It returns one on success, whether or not the element was 269 * present, and zero on decode failure. 270 */ 271 int CBS_get_optional_asn1_octet_string(CBS *cbs, CBS *out, int *out_present, 272 unsigned int tag); 273 274 /* 275 * CBS_get_optional_asn1_uint64 gets an optional explicitly-tagged 276 * INTEGER from |cbs|. If present, it sets |*out| to the 277 * value. Otherwise, it sets |*out| to |default_value|. It returns one 278 * on success, whether or not the element was present, and zero on 279 * decode failure. 280 */ 281 int CBS_get_optional_asn1_uint64(CBS *cbs, uint64_t *out, unsigned int tag, 282 uint64_t default_value); 283 284 /* 285 * CBS_get_optional_asn1_bool gets an optional, explicitly-tagged BOOLEAN from 286 * |cbs|. If present, it sets |*out| to either zero or one, based on the 287 * boolean. Otherwise, it sets |*out| to |default_value|. It returns one on 288 * success, whether or not the element was present, and zero on decode 289 * failure. 290 */ 291 int CBS_get_optional_asn1_bool(CBS *cbs, int *out, unsigned int tag, 292 int default_value); 293 294 295 /* 296 * CRYPTO ByteBuilder. 297 * 298 * |CBB| objects allow one to build length-prefixed serialisations. A |CBB| 299 * object is associated with a buffer and new buffers are created with 300 * |CBB_init|. Several |CBB| objects can point at the same buffer when a 301 * length-prefix is pending, however only a single |CBB| can be 'current' at 302 * any one time. For example, if one calls |CBB_add_u8_length_prefixed| then 303 * the new |CBB| points at the same buffer as the original. But if the original 304 * |CBB| is used then the length prefix is written out and the new |CBB| must 305 * not be used again. 306 * 307 * If one needs to force a length prefix to be written out because a |CBB| is 308 * going out of scope, use |CBB_flush|. 309 */ 310 311 struct cbb_buffer_st { 312 uint8_t *buf; 313 314 /* The number of valid bytes. */ 315 size_t len; 316 317 /* The size of buf. */ 318 size_t cap; 319 320 /* 321 * One iff |buf| is owned by this object. If not then |buf| cannot be 322 * resized. 323 */ 324 char can_resize; 325 }; 326 327 typedef struct cbb_st { 328 struct cbb_buffer_st *base; 329 330 /* 331 * offset is the offset from the start of |base->buf| to the position of any 332 * pending length-prefix. 333 */ 334 size_t offset; 335 336 /* child points to a child CBB if a length-prefix is pending. */ 337 struct cbb_st *child; 338 339 /* 340 * pending_len_len contains the number of bytes in a pending length-prefix, 341 * or zero if no length-prefix is pending. 342 */ 343 uint8_t pending_len_len; 344 345 char pending_is_asn1; 346 347 /* 348 * is_top_level is true iff this is a top-level |CBB| (as opposed to a child 349 * |CBB|). Top-level objects are valid arguments for |CBB_finish|. 350 */ 351 char is_top_level; 352 } CBB; 353 354 /* 355 * CBB_init initialises |cbb| with |initial_capacity|. Since a |CBB| grows as 356 * needed, the |initial_capacity| is just a hint. It returns one on success or 357 * zero on error. 358 */ 359 int CBB_init(CBB *cbb, size_t initial_capacity); 360 361 /* 362 * CBB_init_fixed initialises |cbb| to write to |len| bytes at |buf|. Since 363 * |buf| cannot grow, trying to write more than |len| bytes will cause CBB 364 * functions to fail. It returns one on success or zero on error. 365 */ 366 int CBB_init_fixed(CBB *cbb, uint8_t *buf, size_t len); 367 368 /* 369 * CBB_cleanup frees all resources owned by |cbb| and other |CBB| objects 370 * writing to the same buffer. This should be used in an error case where a 371 * serialisation is abandoned. 372 */ 373 void CBB_cleanup(CBB *cbb); 374 375 /* 376 * CBB_finish completes any pending length prefix and sets |*out_data| to a 377 * malloced buffer and |*out_len| to the length of that buffer. The caller 378 * takes ownership of the buffer and, unless the buffer was fixed with 379 * |CBB_init_fixed|, must call |free| when done. 380 * 381 * It can only be called on a "top level" |CBB|, i.e. one initialised with 382 * |CBB_init| or |CBB_init_fixed|. It returns one on success and zero on 383 * error. 384 */ 385 int CBB_finish(CBB *cbb, uint8_t **out_data, size_t *out_len); 386 387 /* 388 * CBB_flush causes any pending length prefixes to be written out and any child 389 * |CBB| objects of |cbb| to be invalidated. It returns one on success or zero 390 * on error. 391 */ 392 int CBB_flush(CBB *cbb); 393 394 /* 395 * CBB_discard_child discards the current unflushed child of |cbb|. Neither the 396 * child's contents nor the length prefix will be included in the output. 397 */ 398 void CBB_discard_child(CBB *cbb); 399 400 /* 401 * CBB_add_u8_length_prefixed sets |*out_contents| to a new child of |cbb|. The 402 * data written to |*out_contents| will be prefixed in |cbb| with an 8-bit 403 * length. It returns one on success or zero on error. 404 */ 405 int CBB_add_u8_length_prefixed(CBB *cbb, CBB *out_contents); 406 407 /* 408 * CBB_add_u16_length_prefixed sets |*out_contents| to a new child of |cbb|. 409 * The data written to |*out_contents| will be prefixed in |cbb| with a 16-bit, 410 * big-endian length. It returns one on success or zero on error. 411 */ 412 int CBB_add_u16_length_prefixed(CBB *cbb, CBB *out_contents); 413 414 /* 415 * CBB_add_u24_length_prefixed sets |*out_contents| to a new child of |cbb|. 416 * The data written to |*out_contents| will be prefixed in |cbb| with a 24-bit, 417 * big-endian length. It returns one on success or zero on error. 418 */ 419 int CBB_add_u24_length_prefixed(CBB *cbb, CBB *out_contents); 420 421 /* 422 * CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an 423 * ASN.1 object can be written. The |tag| argument will be used as the tag for 424 * the object. Passing in |tag| number 31 will return in an error since only 425 * single octet identifiers are supported. It returns one on success or zero 426 * on error. 427 */ 428 int CBB_add_asn1(CBB *cbb, CBB *out_contents, unsigned int tag); 429 430 /* 431 * CBB_add_bytes appends |len| bytes from |data| to |cbb|. It returns one on 432 * success and zero otherwise. 433 */ 434 int CBB_add_bytes(CBB *cbb, const uint8_t *data, size_t len); 435 436 /* 437 * CBB_add_space appends |len| bytes to |cbb| and sets |*out_data| to point to 438 * the beginning of that space. The caller must then write |len| bytes of 439 * actual contents to |*out_data|. It returns one on success and zero 440 * otherwise. 441 */ 442 int CBB_add_space(CBB *cbb, uint8_t **out_data, size_t len); 443 444 /* 445 * CBB_add_u8 appends an 8-bit number from |value| to |cbb|. It returns one on 446 * success and zero otherwise. 447 */ 448 int CBB_add_u8(CBB *cbb, size_t value); 449 450 /* 451 * CBB_add_u8 appends a 16-bit, big-endian number from |value| to |cbb|. It 452 * returns one on success and zero otherwise. 453 */ 454 int CBB_add_u16(CBB *cbb, size_t value); 455 456 /* 457 * CBB_add_u24 appends a 24-bit, big-endian number from |value| to |cbb|. It 458 * returns one on success and zero otherwise. 459 */ 460 int CBB_add_u24(CBB *cbb, size_t value); 461 462 /* 463 * CBB_add_u32 appends a 32-bit, big-endian number from |value| to |cbb|. It 464 * returns one on success and zero otherwise. 465 */ 466 int CBB_add_u32(CBB *cbb, size_t value); 467 468 /* 469 * CBB_add_asn1_uint64 writes an ASN.1 INTEGER into |cbb| using |CBB_add_asn1| 470 * and writes |value| in its contents. It returns one on success and zero on 471 * error. 472 */ 473 int CBB_add_asn1_uint64(CBB *cbb, uint64_t value); 474 475 #ifdef LIBRESSL_INTERNAL 476 /* 477 * CBS_dup sets |out| to point to cbs's |data| and |len|. It results in two 478 * CBS that point to the same buffer. 479 */ 480 void CBS_dup(const CBS *cbs, CBS *out); 481 482 /* 483 * cbs_get_any_asn1_element sets |*out| to contain the next ASN.1 element from 484 * |*cbs| (including header bytes) and advances |*cbs|. It sets |*out_tag| to 485 * the tag number and |*out_header_len| to the length of the ASN.1 header. If 486 * strict mode is disabled and the element has indefinite length then |*out| 487 * will only contain the header. Each of |out|, |out_tag|, and 488 * |out_header_len| may be NULL to ignore the value. 489 * 490 * Tag numbers greater than 30 are not supported (i.e. short form only). 491 */ 492 int cbs_get_any_asn1_element_internal(CBS *cbs, CBS *out, unsigned int *out_tag, 493 size_t *out_header_len, int strict); 494 495 /* 496 * CBS_asn1_indefinite_to_definite reads an ASN.1 structure from |in|. If it 497 * finds indefinite-length elements that otherwise appear to be valid DER, it 498 * attempts to convert the DER-like data to DER and sets |*out| and 499 * |*out_length| to describe a malloced buffer containing the DER data. 500 * Additionally, |*in| will be advanced over the ASN.1 data. 501 * 502 * If it doesn't find any indefinite-length elements then it sets |*out| to 503 * NULL and |*in| is unmodified. 504 * 505 * This is NOT a conversion from BER to DER. There are many restrictions when 506 * dealing with DER data. This is only concerned with one: indefinite vs. 507 * definite form. However, this suffices to handle the PKCS#7 and PKCS#12 output 508 * from NSS. 509 * 510 * It returns one on success and zero otherwise. 511 */ 512 int CBS_asn1_indefinite_to_definite(CBS *in, uint8_t **out, size_t *out_len); 513 #endif /* LIBRESSL_INTERNAL */ 514 515 __END_HIDDEN_DECLS 516 517 #endif /* OPENSSL_HEADER_BYTESTRING_H */ 518