1 /** 2 * \file asn1.h 3 * 4 * \brief Generic ASN.1 parsing 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 9 * 10 * Licensed under the Apache License, Version 2.0 (the "License"); you may 11 * not use this file except in compliance with the License. 12 * You may obtain a copy of the License at 13 * 14 * http://www.apache.org/licenses/LICENSE-2.0 15 * 16 * Unless required by applicable law or agreed to in writing, software 17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 19 * See the License for the specific language governing permissions and 20 * limitations under the License. 21 */ 22 #ifndef MBEDTLS_ASN1_H 23 #define MBEDTLS_ASN1_H 24 #include "mbedtls/private_access.h" 25 26 #include "mbedtls/build_info.h" 27 28 #include <stddef.h> 29 30 #if defined(MBEDTLS_BIGNUM_C) 31 #include "mbedtls/bignum.h" 32 #endif 33 34 /** 35 * \addtogroup asn1_module 36 * \{ 37 */ 38 39 /** 40 * \name ASN1 Error codes 41 * These error codes are OR'ed to X509 error codes for 42 * higher error granularity. 43 * ASN1 is a standard to specify data structures. 44 * \{ 45 */ 46 /** Out of data when parsing an ASN1 data structure. */ 47 #define MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060 48 /** ASN1 tag was of an unexpected value. */ 49 #define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062 50 /** Error when trying to determine the length or invalid length. */ 51 #define MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064 52 /** Actual length differs from expected length. */ 53 #define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066 54 /** Data is invalid. */ 55 #define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068 56 /** Memory allocation failed */ 57 #define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A 58 /** Buffer too small when writing ASN.1 data structure. */ 59 #define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C 60 61 /* \} name */ 62 63 /** 64 * \name DER constants 65 * These constants comply with the DER encoded ASN.1 type tags. 66 * DER encoding uses hexadecimal representation. 67 * An example DER sequence is:\n 68 * - 0x02 -- tag indicating INTEGER 69 * - 0x01 -- length in octets 70 * - 0x05 -- value 71 * Such sequences are typically read into \c ::mbedtls_x509_buf. 72 * \{ 73 */ 74 #define MBEDTLS_ASN1_BOOLEAN 0x01 75 #define MBEDTLS_ASN1_INTEGER 0x02 76 #define MBEDTLS_ASN1_BIT_STRING 0x03 77 #define MBEDTLS_ASN1_OCTET_STRING 0x04 78 #define MBEDTLS_ASN1_NULL 0x05 79 #define MBEDTLS_ASN1_OID 0x06 80 #define MBEDTLS_ASN1_ENUMERATED 0x0A 81 #define MBEDTLS_ASN1_UTF8_STRING 0x0C 82 #define MBEDTLS_ASN1_SEQUENCE 0x10 83 #define MBEDTLS_ASN1_SET 0x11 84 #define MBEDTLS_ASN1_PRINTABLE_STRING 0x13 85 #define MBEDTLS_ASN1_T61_STRING 0x14 86 #define MBEDTLS_ASN1_IA5_STRING 0x16 87 #define MBEDTLS_ASN1_UTC_TIME 0x17 88 #define MBEDTLS_ASN1_GENERALIZED_TIME 0x18 89 #define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C 90 #define MBEDTLS_ASN1_BMP_STRING 0x1E 91 #define MBEDTLS_ASN1_PRIMITIVE 0x00 92 #define MBEDTLS_ASN1_CONSTRUCTED 0x20 93 #define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80 94 95 /* Slightly smaller way to check if tag is a string tag 96 * compared to canonical implementation. */ 97 #define MBEDTLS_ASN1_IS_STRING_TAG( tag ) \ 98 ( ( tag ) < 32u && ( \ 99 ( ( 1u << ( tag ) ) & ( ( 1u << MBEDTLS_ASN1_BMP_STRING ) | \ 100 ( 1u << MBEDTLS_ASN1_UTF8_STRING ) | \ 101 ( 1u << MBEDTLS_ASN1_T61_STRING ) | \ 102 ( 1u << MBEDTLS_ASN1_IA5_STRING ) | \ 103 ( 1u << MBEDTLS_ASN1_UNIVERSAL_STRING ) | \ 104 ( 1u << MBEDTLS_ASN1_PRINTABLE_STRING ) | \ 105 ( 1u << MBEDTLS_ASN1_BIT_STRING ) ) ) != 0 ) ) 106 107 /* 108 * Bit masks for each of the components of an ASN.1 tag as specified in 109 * ITU X.690 (08/2015), section 8.1 "General rules for encoding", 110 * paragraph 8.1.2.2: 111 * 112 * Bit 8 7 6 5 1 113 * +-------+-----+------------+ 114 * | Class | P/C | Tag number | 115 * +-------+-----+------------+ 116 */ 117 #define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0 118 #define MBEDTLS_ASN1_TAG_PC_MASK 0x20 119 #define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F 120 121 /* \} name */ 122 /* \} addtogroup asn1_module */ 123 124 /** Returns the size of the binary string, without the trailing \\0 */ 125 #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1) 126 127 /** 128 * Compares an mbedtls_asn1_buf structure to a reference OID. 129 * 130 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a 131 * 'unsigned char *oid' here! 132 */ 133 #define MBEDTLS_OID_CMP(oid_str, oid_buf) \ 134 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \ 135 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 ) 136 137 #define MBEDTLS_OID_CMP_RAW(oid_str, oid_buf, oid_buf_len) \ 138 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf_len) ) || \ 139 memcmp( (oid_str), (oid_buf), (oid_buf_len) ) != 0 ) 140 141 #ifdef __cplusplus 142 extern "C" { 143 #endif 144 145 /** 146 * \name Functions to parse ASN.1 data structures 147 * \{ 148 */ 149 150 /** 151 * Type-length-value structure that allows for ASN1 using DER. 152 */ 153 typedef struct mbedtls_asn1_buf 154 { 155 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */ 156 size_t len; /**< ASN1 length, in octets. */ 157 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */ 158 } 159 mbedtls_asn1_buf; 160 161 /** 162 * Container for ASN1 bit strings. 163 */ 164 typedef struct mbedtls_asn1_bitstring 165 { 166 size_t len; /**< ASN1 length, in octets. */ 167 unsigned char unused_bits; /**< Number of unused bits at the end of the string */ 168 unsigned char *p; /**< Raw ASN1 data for the bit string */ 169 } 170 mbedtls_asn1_bitstring; 171 172 /** 173 * Container for a sequence of ASN.1 items 174 */ 175 typedef struct mbedtls_asn1_sequence 176 { 177 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */ 178 179 /** The next entry in the sequence. 180 * 181 * The details of memory management for sequences are not documented and 182 * may change in future versions. Set this field to \p NULL when 183 * initializing a structure, and do not modify it except via Mbed TLS 184 * library functions. 185 */ 186 struct mbedtls_asn1_sequence *next; 187 } 188 mbedtls_asn1_sequence; 189 190 /** 191 * Container for a sequence or list of 'named' ASN.1 data items 192 */ 193 typedef struct mbedtls_asn1_named_data 194 { 195 mbedtls_asn1_buf oid; /**< The object identifier. */ 196 mbedtls_asn1_buf val; /**< The named value. */ 197 198 /** The next entry in the sequence. 199 * 200 * The details of memory management for named data sequences are not 201 * documented and may change in future versions. Set this field to \p NULL 202 * when initializing a structure, and do not modify it except via Mbed TLS 203 * library functions. 204 */ 205 struct mbedtls_asn1_named_data *next; 206 207 /** Merge next item into the current one? 208 * 209 * This field exists for the sake of Mbed TLS's X.509 certificate parsing 210 * code and may change in future versions of the library. 211 */ 212 unsigned char MBEDTLS_PRIVATE(next_merged); 213 } 214 mbedtls_asn1_named_data; 215 216 /** 217 * \brief Get the length of an ASN.1 element. 218 * Updates the pointer to immediately behind the length. 219 * 220 * \param p On entry, \c *p points to the first byte of the length, 221 * i.e. immediately after the tag. 222 * On successful completion, \c *p points to the first byte 223 * after the length, i.e. the first byte of the content. 224 * On error, the value of \c *p is undefined. 225 * \param end End of data. 226 * \param len On successful completion, \c *len contains the length 227 * read from the ASN.1 input. 228 * 229 * \return 0 if successful. 230 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element 231 * would end beyond \p end. 232 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable. 233 */ 234 int mbedtls_asn1_get_len( unsigned char **p, 235 const unsigned char *end, 236 size_t *len ); 237 238 /** 239 * \brief Get the tag and length of the element. 240 * Check for the requested tag. 241 * Updates the pointer to immediately behind the tag and length. 242 * 243 * \param p On entry, \c *p points to the start of the ASN.1 element. 244 * On successful completion, \c *p points to the first byte 245 * after the length, i.e. the first byte of the content. 246 * On error, the value of \c *p is undefined. 247 * \param end End of data. 248 * \param len On successful completion, \c *len contains the length 249 * read from the ASN.1 input. 250 * \param tag The expected tag. 251 * 252 * \return 0 if successful. 253 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start 254 * with the requested tag. 255 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element 256 * would end beyond \p end. 257 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable. 258 */ 259 int mbedtls_asn1_get_tag( unsigned char **p, 260 const unsigned char *end, 261 size_t *len, int tag ); 262 263 /** 264 * \brief Retrieve a boolean ASN.1 tag and its value. 265 * Updates the pointer to immediately behind the full tag. 266 * 267 * \param p On entry, \c *p points to the start of the ASN.1 element. 268 * On successful completion, \c *p points to the first byte 269 * beyond the ASN.1 element. 270 * On error, the value of \c *p is undefined. 271 * \param end End of data. 272 * \param val On success, the parsed value (\c 0 or \c 1). 273 * 274 * \return 0 if successful. 275 * \return An ASN.1 error code if the input does not start with 276 * a valid ASN.1 BOOLEAN. 277 */ 278 int mbedtls_asn1_get_bool( unsigned char **p, 279 const unsigned char *end, 280 int *val ); 281 282 /** 283 * \brief Retrieve an integer ASN.1 tag and its value. 284 * Updates the pointer to immediately behind the full tag. 285 * 286 * \param p On entry, \c *p points to the start of the ASN.1 element. 287 * On successful completion, \c *p points to the first byte 288 * beyond the ASN.1 element. 289 * On error, the value of \c *p is undefined. 290 * \param end End of data. 291 * \param val On success, the parsed value. 292 * 293 * \return 0 if successful. 294 * \return An ASN.1 error code if the input does not start with 295 * a valid ASN.1 INTEGER. 296 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 297 * not fit in an \c int. 298 */ 299 int mbedtls_asn1_get_int( unsigned char **p, 300 const unsigned char *end, 301 int *val ); 302 303 /** 304 * \brief Retrieve an enumerated ASN.1 tag and its value. 305 * Updates the pointer to immediately behind the full tag. 306 * 307 * \param p On entry, \c *p points to the start of the ASN.1 element. 308 * On successful completion, \c *p points to the first byte 309 * beyond the ASN.1 element. 310 * On error, the value of \c *p is undefined. 311 * \param end End of data. 312 * \param val On success, the parsed value. 313 * 314 * \return 0 if successful. 315 * \return An ASN.1 error code if the input does not start with 316 * a valid ASN.1 ENUMERATED. 317 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 318 * not fit in an \c int. 319 */ 320 int mbedtls_asn1_get_enum( unsigned char **p, 321 const unsigned char *end, 322 int *val ); 323 324 /** 325 * \brief Retrieve a bitstring ASN.1 tag and its value. 326 * Updates the pointer to immediately behind the full tag. 327 * 328 * \param p On entry, \c *p points to the start of the ASN.1 element. 329 * On successful completion, \c *p is equal to \p end. 330 * On error, the value of \c *p is undefined. 331 * \param end End of data. 332 * \param bs On success, ::mbedtls_asn1_bitstring information about 333 * the parsed value. 334 * 335 * \return 0 if successful. 336 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains 337 * extra data after a valid BIT STRING. 338 * \return An ASN.1 error code if the input does not start with 339 * a valid ASN.1 BIT STRING. 340 */ 341 int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end, 342 mbedtls_asn1_bitstring *bs ); 343 344 /** 345 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its 346 * value. 347 * Updates the pointer to the beginning of the bit/octet string. 348 * 349 * \param p On entry, \c *p points to the start of the ASN.1 element. 350 * On successful completion, \c *p points to the first byte 351 * of the content of the BIT STRING. 352 * On error, the value of \c *p is undefined. 353 * \param end End of data. 354 * \param len On success, \c *len is the length of the content in bytes. 355 * 356 * \return 0 if successful. 357 * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with 358 * a valid BIT STRING with a nonzero number of unused bits. 359 * \return An ASN.1 error code if the input does not start with 360 * a valid ASN.1 BIT STRING. 361 */ 362 int mbedtls_asn1_get_bitstring_null( unsigned char **p, 363 const unsigned char *end, 364 size_t *len ); 365 366 /** 367 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>". 368 * Updates the pointer to immediately behind the full sequence tag. 369 * 370 * This function allocates memory for the sequence elements. You can free 371 * the allocated memory with mbedtls_asn1_sequence_free(). 372 * 373 * \note On error, this function may return a partial list in \p cur. 374 * You must set `cur->next = NULL` before calling this function! 375 * Otherwise it is impossible to distinguish a previously non-null 376 * pointer from a pointer to an object allocated by this function. 377 * 378 * \note If the sequence is empty, this function does not modify 379 * \c *cur. If the sequence is valid and non-empty, this 380 * function sets `cur->buf.tag` to \p tag. This allows 381 * callers to distinguish between an empty sequence and 382 * a one-element sequence. 383 * 384 * \param p On entry, \c *p points to the start of the ASN.1 element. 385 * On successful completion, \c *p is equal to \p end. 386 * On error, the value of \c *p is undefined. 387 * \param end End of data. 388 * \param cur A ::mbedtls_asn1_sequence which this function fills. 389 * When this function returns, \c *cur is the head of a linked 390 * list. Each node in this list is allocated with 391 * mbedtls_calloc() apart from \p cur itself, and should 392 * therefore be freed with mbedtls_free(). 393 * The list describes the content of the sequence. 394 * The head of the list (i.e. \c *cur itself) describes the 395 * first element, `*cur->next` describes the second element, etc. 396 * For each element, `buf.tag == tag`, `buf.len` is the length 397 * of the content of the content of the element, and `buf.p` 398 * points to the first byte of the content (i.e. immediately 399 * past the length of the element). 400 * Note that list elements may be allocated even on error. 401 * \param tag Each element of the sequence must have this tag. 402 * 403 * \return 0 if successful. 404 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains 405 * extra data after a valid SEQUENCE OF \p tag. 406 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with 407 * an ASN.1 SEQUENCE in which an element has a tag that 408 * is different from \p tag. 409 * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed. 410 * \return An ASN.1 error code if the input does not start with 411 * a valid ASN.1 SEQUENCE. 412 */ 413 int mbedtls_asn1_get_sequence_of( unsigned char **p, 414 const unsigned char *end, 415 mbedtls_asn1_sequence *cur, 416 int tag ); 417 /** 418 * \brief Free a heap-allocated linked list presentation of 419 * an ASN.1 sequence, including the first element. 420 * 421 * There are two common ways to manage the memory used for the representation 422 * of a parsed ASN.1 sequence: 423 * - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc(). 424 * Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of(). 425 * When you have finished processing the sequence, 426 * call mbedtls_asn1_sequence_free() on `head`. 427 * - Allocate a head node `mbedtls_asn1_sequence *head` in any manner, 428 * for example on the stack. Make sure that `head->next == NULL`. 429 * Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of(). 430 * When you have finished processing the sequence, 431 * call mbedtls_asn1_sequence_free() on `head->cur`, 432 * then free `head` itself in the appropriate manner. 433 * 434 * \param seq The address of the first sequence component. This may 435 * be \c NULL, in which case this functions returns 436 * immediately. 437 */ 438 void mbedtls_asn1_sequence_free( mbedtls_asn1_sequence *seq ); 439 440 /** 441 * \brief Traverse an ASN.1 SEQUENCE container and 442 * call a callback for each entry. 443 * 444 * This function checks that the input is a SEQUENCE of elements that 445 * each have a "must" tag, and calls a callback function on the elements 446 * that have a "may" tag. 447 * 448 * For example, to validate that the input is a SEQUENCE of `tag1` and call 449 * `cb` on each element, use 450 * ``` 451 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx); 452 * ``` 453 * 454 * To validate that the input is a SEQUENCE of ANY and call `cb` on 455 * each element, use 456 * ``` 457 * mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx); 458 * ``` 459 * 460 * To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING} 461 * and call `cb` on each element that is an OCTET STRING, use 462 * ``` 463 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx); 464 * ``` 465 * 466 * The callback is called on the elements with a "may" tag from left to 467 * right. If the input is not a valid SEQUENCE of elements with a "must" tag, 468 * the callback is called on the elements up to the leftmost point where 469 * the input is invalid. 470 * 471 * \warning This function is still experimental and may change 472 * at any time. 473 * 474 * \param p The address of the pointer to the beginning of 475 * the ASN.1 SEQUENCE header. This is updated to 476 * point to the end of the ASN.1 SEQUENCE container 477 * on a successful invocation. 478 * \param end The end of the ASN.1 SEQUENCE container. 479 * \param tag_must_mask A mask to be applied to the ASN.1 tags found within 480 * the SEQUENCE before comparing to \p tag_must_value. 481 * \param tag_must_val The required value of each ASN.1 tag found in the 482 * SEQUENCE, after masking with \p tag_must_mask. 483 * Mismatching tags lead to an error. 484 * For example, a value of \c 0 for both \p tag_must_mask 485 * and \p tag_must_val means that every tag is allowed, 486 * while a value of \c 0xFF for \p tag_must_mask means 487 * that \p tag_must_val is the only allowed tag. 488 * \param tag_may_mask A mask to be applied to the ASN.1 tags found within 489 * the SEQUENCE before comparing to \p tag_may_value. 490 * \param tag_may_val The desired value of each ASN.1 tag found in the 491 * SEQUENCE, after masking with \p tag_may_mask. 492 * Mismatching tags will be silently ignored. 493 * For example, a value of \c 0 for \p tag_may_mask and 494 * \p tag_may_val means that any tag will be considered, 495 * while a value of \c 0xFF for \p tag_may_mask means 496 * that all tags with value different from \p tag_may_val 497 * will be ignored. 498 * \param cb The callback to trigger for each component 499 * in the ASN.1 SEQUENCE that matches \p tag_may_val. 500 * The callback function is called with the following 501 * parameters: 502 * - \p ctx. 503 * - The tag of the current element. 504 * - A pointer to the start of the current element's 505 * content inside the input. 506 * - The length of the content of the current element. 507 * If the callback returns a non-zero value, 508 * the function stops immediately, 509 * forwarding the callback's return value. 510 * \param ctx The context to be passed to the callback \p cb. 511 * 512 * \return \c 0 if successful the entire ASN.1 SEQUENCE 513 * was traversed without parsing or callback errors. 514 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input 515 * contains extra data after a valid SEQUENCE 516 * of elements with an accepted tag. 517 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts 518 * with an ASN.1 SEQUENCE in which an element has a tag 519 * that is not accepted. 520 * \return An ASN.1 error code if the input does not start with 521 * a valid ASN.1 SEQUENCE. 522 * \return A non-zero error code forwarded from the callback 523 * \p cb in case the latter returns a non-zero value. 524 */ 525 int mbedtls_asn1_traverse_sequence_of( 526 unsigned char **p, 527 const unsigned char *end, 528 unsigned char tag_must_mask, unsigned char tag_must_val, 529 unsigned char tag_may_mask, unsigned char tag_may_val, 530 int (*cb)( void *ctx, int tag, 531 unsigned char* start, size_t len ), 532 void *ctx ); 533 534 #if defined(MBEDTLS_BIGNUM_C) 535 /** 536 * \brief Retrieve an integer ASN.1 tag and its value. 537 * Updates the pointer to immediately behind the full tag. 538 * 539 * \param p On entry, \c *p points to the start of the ASN.1 element. 540 * On successful completion, \c *p points to the first byte 541 * beyond the ASN.1 element. 542 * On error, the value of \c *p is undefined. 543 * \param end End of data. 544 * \param X On success, the parsed value. 545 * 546 * \return 0 if successful. 547 * \return An ASN.1 error code if the input does not start with 548 * a valid ASN.1 INTEGER. 549 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 550 * not fit in an \c int. 551 * \return An MPI error code if the parsed value is too large. 552 */ 553 int mbedtls_asn1_get_mpi( unsigned char **p, 554 const unsigned char *end, 555 mbedtls_mpi *X ); 556 #endif /* MBEDTLS_BIGNUM_C */ 557 558 /** 559 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence. 560 * Updates the pointer to immediately behind the full 561 * AlgorithmIdentifier. 562 * 563 * \param p On entry, \c *p points to the start of the ASN.1 element. 564 * On successful completion, \c *p points to the first byte 565 * beyond the AlgorithmIdentifier element. 566 * On error, the value of \c *p is undefined. 567 * \param end End of data. 568 * \param alg The buffer to receive the OID. 569 * \param params The buffer to receive the parameters. 570 * This is zeroized if there are no parameters. 571 * 572 * \return 0 if successful or a specific ASN.1 or MPI error code. 573 */ 574 int mbedtls_asn1_get_alg( unsigned char **p, 575 const unsigned char *end, 576 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params ); 577 578 /** 579 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no 580 * params. 581 * Updates the pointer to immediately behind the full 582 * AlgorithmIdentifier. 583 * 584 * \param p On entry, \c *p points to the start of the ASN.1 element. 585 * On successful completion, \c *p points to the first byte 586 * beyond the AlgorithmIdentifier element. 587 * On error, the value of \c *p is undefined. 588 * \param end End of data. 589 * \param alg The buffer to receive the OID. 590 * 591 * \return 0 if successful or a specific ASN.1 or MPI error code. 592 */ 593 int mbedtls_asn1_get_alg_null( unsigned char **p, 594 const unsigned char *end, 595 mbedtls_asn1_buf *alg ); 596 597 /** 598 * \brief Find a specific named_data entry in a sequence or list based on 599 * the OID. 600 * 601 * \param list The list to seek through 602 * \param oid The OID to look for 603 * \param len Size of the OID 604 * 605 * \return NULL if not found, or a pointer to the existing entry. 606 */ 607 const mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( const mbedtls_asn1_named_data *list, 608 const char *oid, size_t len ); 609 610 /** 611 * \brief Free a mbedtls_asn1_named_data entry 612 * 613 * \param entry The named data entry to free. 614 * This function calls mbedtls_free() on 615 * `entry->oid.p` and `entry->val.p`. 616 */ 617 void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry ); 618 619 /** 620 * \brief Free all entries in a mbedtls_asn1_named_data list. 621 * 622 * \param head Pointer to the head of the list of named data entries to free. 623 * This function calls mbedtls_asn1_free_named_data() and 624 * mbedtls_free() on each list element and 625 * sets \c *head to \c NULL. 626 */ 627 void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head ); 628 629 #ifdef __cplusplus 630 } 631 #endif 632 633 #endif /* asn1.h */ 634