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