common/mbedtls/asn1.h

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