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