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 #if defined(VENDOR_REDEFINE_TEE_API_C) 34 #include "mbedtls/hw_redefine_tee_api.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 */ 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 */ 125 /* \} addtogroup asn1_module */ 126 127 /** Returns the size of the binary string, without the trailing \\0 */ 128 #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1) 129 130 /** 131 * Compares an mbedtls_asn1_buf structure to a reference OID. 132 * 133 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a 134 * 'unsigned char *oid' here! 135 */ 136 #define MBEDTLS_OID_CMP(oid_str, oid_buf) \ 137 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \ 138 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 ) 139 140 #define MBEDTLS_OID_CMP_RAW(oid_str, oid_buf, oid_buf_len) \ 141 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf_len) ) || \ 142 memcmp( (oid_str), (oid_buf), (oid_buf_len) ) != 0 ) 143 144 #ifdef __cplusplus 145 extern "C" { 146 #endif 147 148 /** 149 * \name Functions to parse ASN.1 data structures 150 * \{ 151 */ 152 153 /** 154 * Type-length-value structure that allows for ASN1 using DER. 155 */ 156 typedef struct mbedtls_asn1_buf 157 { 158 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */ 159 size_t len; /**< ASN1 length, in octets. */ 160 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */ 161 } 162 mbedtls_asn1_buf; 163 164 /** 165 * Container for ASN1 bit strings. 166 */ 167 typedef struct mbedtls_asn1_bitstring 168 { 169 size_t len; /**< ASN1 length, in octets. */ 170 unsigned char unused_bits; /**< Number of unused bits at the end of the string */ 171 unsigned char *p; /**< Raw ASN1 data for the bit string */ 172 } 173 mbedtls_asn1_bitstring; 174 175 /** 176 * Container for a sequence of ASN.1 items 177 */ 178 typedef struct mbedtls_asn1_sequence 179 { 180 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */ 181 182 /** The next entry in the sequence. 183 * 184 * The details of memory management for sequences are not documented and 185 * may change in future versions. Set this field to \p NULL when 186 * initializing a structure, and do not modify it except via Mbed TLS 187 * library functions. 188 */ 189 struct mbedtls_asn1_sequence *next; 190 } 191 mbedtls_asn1_sequence; 192 193 /** 194 * Container for a sequence or list of 'named' ASN.1 data items 195 */ 196 typedef struct mbedtls_asn1_named_data 197 { 198 mbedtls_asn1_buf oid; /**< The object identifier. */ 199 mbedtls_asn1_buf val; /**< The named value. */ 200 201 /** The next entry in the sequence. 202 * 203 * The details of memory management for named data sequences are not 204 * documented and may change in future versions. Set this field to \p NULL 205 * when initializing a structure, and do not modify it except via Mbed TLS 206 * library functions. 207 */ 208 struct mbedtls_asn1_named_data *next; 209 210 /** Merge next item into the current one? 211 * 212 * This field exists for the sake of Mbed TLS's X.509 certificate parsing 213 * code and may change in future versions of the library. 214 */ 215 unsigned char MBEDTLS_PRIVATE(next_merged); 216 } 217 mbedtls_asn1_named_data; 218 219 /** 220 * \brief Get the length of an ASN.1 element. 221 * Updates the pointer to immediately behind the length. 222 * 223 * \param p On entry, \c *p points to the first byte of the length, 224 * i.e. immediately after the tag. 225 * On successful completion, \c *p points to the first byte 226 * after the length, i.e. the first byte of the content. 227 * On error, the value of \c *p is undefined. 228 * \param end End of data. 229 * \param len On successful completion, \c *len contains the length 230 * read from the ASN.1 input. 231 * 232 * \return 0 if successful. 233 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element 234 * would end beyond \p end. 235 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable. 236 */ 237 int mbedtls_asn1_get_len( unsigned char **p, 238 const unsigned char *end, 239 size_t *len ); 240 241 /** 242 * \brief Get the tag and length of the element. 243 * Check for the requested tag. 244 * Updates the pointer to immediately behind the tag and length. 245 * 246 * \param p On entry, \c *p points to the start of the ASN.1 element. 247 * On successful completion, \c *p points to the first byte 248 * after the length, i.e. the first byte of the content. 249 * On error, the value of \c *p is undefined. 250 * \param end End of data. 251 * \param len On successful completion, \c *len contains the length 252 * read from the ASN.1 input. 253 * \param tag The expected tag. 254 * 255 * \return 0 if successful. 256 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start 257 * with the requested tag. 258 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element 259 * would end beyond \p end. 260 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable. 261 */ 262 int mbedtls_asn1_get_tag( unsigned char **p, 263 const unsigned char *end, 264 size_t *len, int tag ); 265 266 /** 267 * \brief Retrieve a boolean ASN.1 tag and its value. 268 * Updates the pointer to immediately behind the full tag. 269 * 270 * \param p On entry, \c *p points to the start of the ASN.1 element. 271 * On successful completion, \c *p points to the first byte 272 * beyond the ASN.1 element. 273 * On error, the value of \c *p is undefined. 274 * \param end End of data. 275 * \param val On success, the parsed value (\c 0 or \c 1). 276 * 277 * \return 0 if successful. 278 * \return An ASN.1 error code if the input does not start with 279 * a valid ASN.1 BOOLEAN. 280 */ 281 int mbedtls_asn1_get_bool( unsigned char **p, 282 const unsigned char *end, 283 int *val ); 284 285 /** 286 * \brief Retrieve an integer ASN.1 tag and its value. 287 * Updates the pointer to immediately behind the full tag. 288 * 289 * \param p On entry, \c *p points to the start of the ASN.1 element. 290 * On successful completion, \c *p points to the first byte 291 * beyond the ASN.1 element. 292 * On error, the value of \c *p is undefined. 293 * \param end End of data. 294 * \param val On success, the parsed value. 295 * 296 * \return 0 if successful. 297 * \return An ASN.1 error code if the input does not start with 298 * a valid ASN.1 INTEGER. 299 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 300 * not fit in an \c int. 301 */ 302 int mbedtls_asn1_get_int( unsigned char **p, 303 const unsigned char *end, 304 int *val ); 305 306 /** 307 * \brief Retrieve an enumerated ASN.1 tag and its value. 308 * Updates the pointer to immediately behind the full tag. 309 * 310 * \param p On entry, \c *p points to the start of the ASN.1 element. 311 * On successful completion, \c *p points to the first byte 312 * beyond the ASN.1 element. 313 * On error, the value of \c *p is undefined. 314 * \param end End of data. 315 * \param val On success, the parsed value. 316 * 317 * \return 0 if successful. 318 * \return An ASN.1 error code if the input does not start with 319 * a valid ASN.1 ENUMERATED. 320 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 321 * not fit in an \c int. 322 */ 323 int mbedtls_asn1_get_enum( unsigned char **p, 324 const unsigned char *end, 325 int *val ); 326 327 /** 328 * \brief Retrieve a bitstring ASN.1 tag and its value. 329 * Updates the pointer to immediately behind the full tag. 330 * 331 * \param p On entry, \c *p points to the start of the ASN.1 element. 332 * On successful completion, \c *p is equal to \p end. 333 * On error, the value of \c *p is undefined. 334 * \param end End of data. 335 * \param bs On success, ::mbedtls_asn1_bitstring information about 336 * the parsed value. 337 * 338 * \return 0 if successful. 339 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains 340 * extra data after a valid BIT STRING. 341 * \return An ASN.1 error code if the input does not start with 342 * a valid ASN.1 BIT STRING. 343 */ 344 int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end, 345 mbedtls_asn1_bitstring *bs ); 346 347 /** 348 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its 349 * value. 350 * Updates the pointer to the beginning of the bit/octet string. 351 * 352 * \param p On entry, \c *p points to the start of the ASN.1 element. 353 * On successful completion, \c *p points to the first byte 354 * of the content of the BIT STRING. 355 * On error, the value of \c *p is undefined. 356 * \param end End of data. 357 * \param len On success, \c *len is the length of the content in bytes. 358 * 359 * \return 0 if successful. 360 * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with 361 * a valid BIT STRING with a nonzero number of unused bits. 362 * \return An ASN.1 error code if the input does not start with 363 * a valid ASN.1 BIT STRING. 364 */ 365 int mbedtls_asn1_get_bitstring_null( unsigned char **p, 366 const unsigned char *end, 367 size_t *len ); 368 369 /** 370 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>". 371 * Updates the pointer to immediately behind the full sequence tag. 372 * 373 * This function allocates memory for the sequence elements. You can free 374 * the allocated memory with mbedtls_asn1_sequence_free(). 375 * 376 * \note On error, this function may return a partial list in \p cur. 377 * You must set `cur->next = NULL` before calling this function! 378 * Otherwise it is impossible to distinguish a previously non-null 379 * pointer from a pointer to an object allocated by this function. 380 * 381 * \note If the sequence is empty, this function does not modify 382 * \c *cur. If the sequence is valid and non-empty, this 383 * function sets `cur->buf.tag` to \p tag. This allows 384 * callers to distinguish between an empty sequence and 385 * a one-element sequence. 386 * 387 * \param p On entry, \c *p points to the start of the ASN.1 element. 388 * On successful completion, \c *p is equal to \p end. 389 * On error, the value of \c *p is undefined. 390 * \param end End of data. 391 * \param cur A ::mbedtls_asn1_sequence which this function fills. 392 * When this function returns, \c *cur is the head of a linked 393 * list. Each node in this list is allocated with 394 * mbedtls_calloc() apart from \p cur itself, and should 395 * therefore be freed with mbedtls_free(). 396 * The list describes the content of the sequence. 397 * The head of the list (i.e. \c *cur itself) describes the 398 * first element, `*cur->next` describes the second element, etc. 399 * For each element, `buf.tag == tag`, `buf.len` is the length 400 * of the content of the content of the element, and `buf.p` 401 * points to the first byte of the content (i.e. immediately 402 * past the length of the element). 403 * Note that list elements may be allocated even on error. 404 * \param tag Each element of the sequence must have this tag. 405 * 406 * \return 0 if successful. 407 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains 408 * extra data after a valid SEQUENCE OF \p tag. 409 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with 410 * an ASN.1 SEQUENCE in which an element has a tag that 411 * is different from \p tag. 412 * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed. 413 * \return An ASN.1 error code if the input does not start with 414 * a valid ASN.1 SEQUENCE. 415 */ 416 int mbedtls_asn1_get_sequence_of( unsigned char **p, 417 const unsigned char *end, 418 mbedtls_asn1_sequence *cur, 419 int tag ); 420 /** 421 * \brief Free a heap-allocated linked list presentation of 422 * an ASN.1 sequence, including the first element. 423 * 424 * There are two common ways to manage the memory used for the representation 425 * of a parsed ASN.1 sequence: 426 * - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc(). 427 * Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of(). 428 * When you have finished processing the sequence, 429 * call mbedtls_asn1_sequence_free() on `head`. 430 * - Allocate a head node `mbedtls_asn1_sequence *head` in any manner, 431 * for example on the stack. Make sure that `head->next == NULL`. 432 * Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of(). 433 * When you have finished processing the sequence, 434 * call mbedtls_asn1_sequence_free() on `head->cur`, 435 * then free `head` itself in the appropriate manner. 436 * 437 * \param seq The address of the first sequence component. This may 438 * be \c NULL, in which case this functions returns 439 * immediately. 440 */ 441 void mbedtls_asn1_sequence_free( mbedtls_asn1_sequence *seq ); 442 443 /** 444 * \brief Traverse an ASN.1 SEQUENCE container and 445 * call a callback for each entry. 446 * 447 * This function checks that the input is a SEQUENCE of elements that 448 * each have a "must" tag, and calls a callback function on the elements 449 * that have a "may" tag. 450 * 451 * For example, to validate that the input is a SEQUENCE of `tag1` and call 452 * `cb` on each element, use 453 * ``` 454 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx); 455 * ``` 456 * 457 * To validate that the input is a SEQUENCE of ANY and call `cb` on 458 * each element, use 459 * ``` 460 * mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx); 461 * ``` 462 * 463 * To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING} 464 * and call `cb` on each element that is an OCTET STRING, use 465 * ``` 466 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx); 467 * ``` 468 * 469 * The callback is called on the elements with a "may" tag from left to 470 * right. If the input is not a valid SEQUENCE of elements with a "must" tag, 471 * the callback is called on the elements up to the leftmost point where 472 * the input is invalid. 473 * 474 * \warning This function is still experimental and may change 475 * at any time. 476 * 477 * \param p The address of the pointer to the beginning of 478 * the ASN.1 SEQUENCE header. This is updated to 479 * point to the end of the ASN.1 SEQUENCE container 480 * on a successful invocation. 481 * \param end The end of the ASN.1 SEQUENCE container. 482 * \param tag_must_mask A mask to be applied to the ASN.1 tags found within 483 * the SEQUENCE before comparing to \p tag_must_value. 484 * \param tag_must_val The required value of each ASN.1 tag found in the 485 * SEQUENCE, after masking with \p tag_must_mask. 486 * Mismatching tags lead to an error. 487 * For example, a value of \c 0 for both \p tag_must_mask 488 * and \p tag_must_val means that every tag is allowed, 489 * while a value of \c 0xFF for \p tag_must_mask means 490 * that \p tag_must_val is the only allowed tag. 491 * \param tag_may_mask A mask to be applied to the ASN.1 tags found within 492 * the SEQUENCE before comparing to \p tag_may_value. 493 * \param tag_may_val The desired value of each ASN.1 tag found in the 494 * SEQUENCE, after masking with \p tag_may_mask. 495 * Mismatching tags will be silently ignored. 496 * For example, a value of \c 0 for \p tag_may_mask and 497 * \p tag_may_val means that any tag will be considered, 498 * while a value of \c 0xFF for \p tag_may_mask means 499 * that all tags with value different from \p tag_may_val 500 * will be ignored. 501 * \param cb The callback to trigger for each component 502 * in the ASN.1 SEQUENCE that matches \p tag_may_val. 503 * The callback function is called with the following 504 * parameters: 505 * - \p ctx. 506 * - The tag of the current element. 507 * - A pointer to the start of the current element's 508 * content inside the input. 509 * - The length of the content of the current element. 510 * If the callback returns a non-zero value, 511 * the function stops immediately, 512 * forwarding the callback's return value. 513 * \param ctx The context to be passed to the callback \p cb. 514 * 515 * \return \c 0 if successful the entire ASN.1 SEQUENCE 516 * was traversed without parsing or callback errors. 517 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input 518 * contains extra data after a valid SEQUENCE 519 * of elements with an accepted tag. 520 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts 521 * with an ASN.1 SEQUENCE in which an element has a tag 522 * that is not accepted. 523 * \return An ASN.1 error code if the input does not start with 524 * a valid ASN.1 SEQUENCE. 525 * \return A non-zero error code forwarded from the callback 526 * \p cb in case the latter returns a non-zero value. 527 */ 528 int mbedtls_asn1_traverse_sequence_of( 529 unsigned char **p, 530 const unsigned char *end, 531 unsigned char tag_must_mask, unsigned char tag_must_val, 532 unsigned char tag_may_mask, unsigned char tag_may_val, 533 int (*cb)( void *ctx, int tag, 534 unsigned char* start, size_t len ), 535 void *ctx ); 536 537 #if defined(MBEDTLS_BIGNUM_C) 538 /** 539 * \brief Retrieve an integer ASN.1 tag and its value. 540 * Updates the pointer to immediately behind the full tag. 541 * 542 * \param p On entry, \c *p points to the start of the ASN.1 element. 543 * On successful completion, \c *p points to the first byte 544 * beyond the ASN.1 element. 545 * On error, the value of \c *p is undefined. 546 * \param end End of data. 547 * \param X On success, the parsed value. 548 * 549 * \return 0 if successful. 550 * \return An ASN.1 error code if the input does not start with 551 * a valid ASN.1 INTEGER. 552 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does 553 * not fit in an \c int. 554 * \return An MPI error code if the parsed value is too large. 555 */ 556 int mbedtls_asn1_get_mpi( unsigned char **p, 557 const unsigned char *end, 558 mbedtls_mpi *X ); 559 #endif /* MBEDTLS_BIGNUM_C */ 560 561 /** 562 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence. 563 * Updates the pointer to immediately behind the full 564 * AlgorithmIdentifier. 565 * 566 * \param p On entry, \c *p points to the start of the ASN.1 element. 567 * On successful completion, \c *p points to the first byte 568 * beyond the AlgorithmIdentifier element. 569 * On error, the value of \c *p is undefined. 570 * \param end End of data. 571 * \param alg The buffer to receive the OID. 572 * \param params The buffer to receive the parameters. 573 * This is zeroized if there are no parameters. 574 * 575 * \return 0 if successful or a specific ASN.1 or MPI error code. 576 */ 577 int mbedtls_asn1_get_alg( unsigned char **p, 578 const unsigned char *end, 579 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params ); 580 581 /** 582 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no 583 * params. 584 * Updates the pointer to immediately behind the full 585 * AlgorithmIdentifier. 586 * 587 * \param p On entry, \c *p points to the start of the ASN.1 element. 588 * On successful completion, \c *p points to the first byte 589 * beyond the AlgorithmIdentifier element. 590 * On error, the value of \c *p is undefined. 591 * \param end End of data. 592 * \param alg The buffer to receive the OID. 593 * 594 * \return 0 if successful or a specific ASN.1 or MPI error code. 595 */ 596 int mbedtls_asn1_get_alg_null( unsigned char **p, 597 const unsigned char *end, 598 mbedtls_asn1_buf *alg ); 599 600 /** 601 * \brief Find a specific named_data entry in a sequence or list based on 602 * the OID. 603 * 604 * \param list The list to seek through 605 * \param oid The OID to look for 606 * \param len Size of the OID 607 * 608 * \return NULL if not found, or a pointer to the existing entry. 609 */ 610 const mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( const mbedtls_asn1_named_data *list, 611 const char *oid, size_t len ); 612 613 /** 614 * \brief Free a mbedtls_asn1_named_data entry 615 * 616 * \param entry The named data entry to free. 617 * This function calls mbedtls_free() on 618 * `entry->oid.p` and `entry->val.p`. 619 */ 620 void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry ); 621 622 /** 623 * \brief Free all entries in a mbedtls_asn1_named_data list. 624 * 625 * \param head Pointer to the head of the list of named data entries to free. 626 * This function calls mbedtls_asn1_free_named_data() and 627 * mbedtls_free() on each list element and 628 * sets \c *head to \c NULL. 629 */ 630 void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head ); 631 632 #ifdef __cplusplus 633 } 634 #endif 635 636 #endif /* asn1.h */ 637