blob: c676fd3662cd136e7c567cc68a6554c8e3536506 [file] [log] [blame]
Paul Bakkerefc30292011-11-10 14:43:23 +00001/**
2 * \file asn1.h
3 *
4 * \brief Generic ASN.1 parsing
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +00008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakkerefc30292011-11-10 14:43:23 +00009 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020010#ifndef MBEDTLS_ASN1_H
11#define MBEDTLS_ASN1_H
Paul Bakkerefc30292011-11-10 14:43:23 +000012
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020013#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010014#include "mbedtls/config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020015#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020016#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020017#endif
Paul Bakkerefc30292011-11-10 14:43:23 +000018
Rich Evans00ab4702015-02-06 13:43:58 +000019#include <stddef.h>
20
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020021#if defined(MBEDTLS_BIGNUM_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010022#include "mbedtls/bignum.h"
Paul Bakkerefc30292011-11-10 14:43:23 +000023#endif
24
Paul Bakker9af723c2014-05-01 13:03:14 +020025/**
Paul Bakkerefc30292011-11-10 14:43:23 +000026 * \addtogroup asn1_module
Paul Bakker9af723c2014-05-01 13:03:14 +020027 * \{
Paul Bakkerefc30292011-11-10 14:43:23 +000028 */
Paul Bakker9af723c2014-05-01 13:03:14 +020029
Paul Bakkerefc30292011-11-10 14:43:23 +000030/**
31 * \name ASN1 Error codes
32 * These error codes are OR'ed to X509 error codes for
Paul Bakker9af723c2014-05-01 13:03:14 +020033 * higher error granularity.
Paul Bakkerefc30292011-11-10 14:43:23 +000034 * ASN1 is a standard to specify data structures.
35 * \{
36 */
Gilles Peskinea3974432021-07-26 18:48:10 +020037/** Out of data when parsing an ASN1 data structure. */
38#define MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060
39/** ASN1 tag was of an unexpected value. */
40#define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062
41/** Error when trying to determine the length or invalid length. */
42#define MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064
43/** Actual length differs from expected length. */
44#define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066
45/** Data is invalid. */
46#define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068
47/** Memory allocation failed */
48#define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A
49/** Buffer too small when writing ASN.1 data structure. */
50#define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C
Paul Bakker05888152012-02-16 10:26:57 +000051
Andrzej Kurek73afe272022-01-24 10:31:06 -050052/** \} name ASN1 Error codes */
Paul Bakkerefc30292011-11-10 14:43:23 +000053
54/**
55 * \name DER constants
Andres Amaya Garcia9fb02052017-08-25 17:24:44 +010056 * These constants comply with the DER encoded ASN.1 type tags.
Paul Bakkerefc30292011-11-10 14:43:23 +000057 * DER encoding uses hexadecimal representation.
58 * An example DER sequence is:\n
59 * - 0x02 -- tag indicating INTEGER
60 * - 0x01 -- length in octets
61 * - 0x05 -- value
Gilles Peskine96ddb0a2020-02-26 19:50:01 +010062 * Such sequences are typically read into \c ::mbedtls_x509_buf.
Paul Bakkerefc30292011-11-10 14:43:23 +000063 * \{
64 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020065#define MBEDTLS_ASN1_BOOLEAN 0x01
66#define MBEDTLS_ASN1_INTEGER 0x02
67#define MBEDTLS_ASN1_BIT_STRING 0x03
68#define MBEDTLS_ASN1_OCTET_STRING 0x04
69#define MBEDTLS_ASN1_NULL 0x05
70#define MBEDTLS_ASN1_OID 0x06
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +020071#define MBEDTLS_ASN1_ENUMERATED 0x0A
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020072#define MBEDTLS_ASN1_UTF8_STRING 0x0C
73#define MBEDTLS_ASN1_SEQUENCE 0x10
74#define MBEDTLS_ASN1_SET 0x11
75#define MBEDTLS_ASN1_PRINTABLE_STRING 0x13
76#define MBEDTLS_ASN1_T61_STRING 0x14
77#define MBEDTLS_ASN1_IA5_STRING 0x16
78#define MBEDTLS_ASN1_UTC_TIME 0x17
79#define MBEDTLS_ASN1_GENERALIZED_TIME 0x18
80#define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C
81#define MBEDTLS_ASN1_BMP_STRING 0x1E
82#define MBEDTLS_ASN1_PRIMITIVE 0x00
83#define MBEDTLS_ASN1_CONSTRUCTED 0x20
84#define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +010085
Hanno Beckercba71222019-09-11 14:15:10 +010086/* Slightly smaller way to check if tag is a string tag
87 * compared to canonical implementation. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010088#define MBEDTLS_ASN1_IS_STRING_TAG(tag) \
89 ((tag) < 32u && ( \
90 ((1u << (tag)) & ((1u << MBEDTLS_ASN1_BMP_STRING) | \
91 (1u << MBEDTLS_ASN1_UTF8_STRING) | \
92 (1u << MBEDTLS_ASN1_T61_STRING) | \
93 (1u << MBEDTLS_ASN1_IA5_STRING) | \
94 (1u << MBEDTLS_ASN1_UNIVERSAL_STRING) | \
95 (1u << MBEDTLS_ASN1_PRINTABLE_STRING) | \
96 (1u << MBEDTLS_ASN1_BIT_STRING))) != 0))
Hanno Beckercba71222019-09-11 14:15:10 +010097
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +010098/*
99 * Bit masks for each of the components of an ASN.1 tag as specified in
Gilles Peskine1ed45ea2018-03-08 18:16:45 +0100100 * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
101 * paragraph 8.1.2.2:
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +0100102 *
103 * Bit 8 7 6 5 1
104 * +-------+-----+------------+
105 * | Class | P/C | Tag number |
106 * +-------+-----+------------+
107 */
Andres Amaya Garcia7786abc2017-11-07 20:21:56 +0000108#define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
109#define MBEDTLS_ASN1_TAG_PC_MASK 0x20
110#define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +0100111
Andrzej Kurek73afe272022-01-24 10:31:06 -0500112/** \} name DER constants */
Paul Bakkerefc30292011-11-10 14:43:23 +0000113
114/** Returns the size of the binary string, without the trailing \\0 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200115#define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
Paul Bakkerefc30292011-11-10 14:43:23 +0000116
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100117/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200118 * Compares an mbedtls_asn1_buf structure to a reference OID.
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100119 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200120 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100121 * 'unsigned char *oid' here!
Paul Bakkere5eae762013-08-26 12:05:14 +0200122 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200123#define MBEDTLS_OID_CMP(oid_str, oid_buf) \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100124 ((MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len) || \
125 memcmp((oid_str), (oid_buf)->p, (oid_buf)->len) != 0)
Paul Bakkerc70b9822013-04-07 22:00:46 +0200126
Hanno Becker63e38fe2019-09-11 14:16:40 +0100127#define MBEDTLS_OID_CMP_RAW(oid_str, oid_buf, oid_buf_len) \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100128 ((MBEDTLS_OID_SIZE(oid_str) != (oid_buf_len)) || \
129 memcmp((oid_str), (oid_buf), (oid_buf_len)) != 0)
Hanno Becker63e38fe2019-09-11 14:16:40 +0100130
Paul Bakkerefc30292011-11-10 14:43:23 +0000131#ifdef __cplusplus
132extern "C" {
133#endif
134
135/**
136 * \name Functions to parse ASN.1 data structures
137 * \{
138 */
139
140/**
141 * Type-length-value structure that allows for ASN1 using DER.
142 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100143typedef struct mbedtls_asn1_buf {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200144 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200145 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000146 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
147}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200148mbedtls_asn1_buf;
Paul Bakkerefc30292011-11-10 14:43:23 +0000149
150/**
151 * Container for ASN1 bit strings.
152 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100153typedef struct mbedtls_asn1_bitstring {
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200154 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000155 unsigned char unused_bits; /**< Number of unused bits at the end of the string */
156 unsigned char *p; /**< Raw ASN1 data for the bit string */
157}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200158mbedtls_asn1_bitstring;
Paul Bakkerefc30292011-11-10 14:43:23 +0000159
160/**
161 * Container for a sequence of ASN.1 items
162 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100163typedef struct mbedtls_asn1_sequence {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200164 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
165 struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000166}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200167mbedtls_asn1_sequence;
Paul Bakkerefc30292011-11-10 14:43:23 +0000168
169/**
Paul Bakkere5eae762013-08-26 12:05:14 +0200170 * Container for a sequence or list of 'named' ASN.1 data items
171 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100172typedef struct mbedtls_asn1_named_data {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200173 mbedtls_asn1_buf oid; /**< The object identifier. */
174 mbedtls_asn1_buf val; /**< The named value. */
175 struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
Manuel Pégourié-Gonnard555fbf82015-02-04 17:11:55 +0000176 unsigned char next_merged; /**< Merge next item into the current one? */
Paul Bakkere5eae762013-08-26 12:05:14 +0200177}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200178mbedtls_asn1_named_data;
Paul Bakkere5eae762013-08-26 12:05:14 +0200179
180/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200181 * \brief Get the length of an ASN.1 element.
182 * Updates the pointer to immediately behind the length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000183 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100184 * \param p On entry, \c *p points to the first byte of the length,
185 * i.e. immediately after the tag.
186 * On successful completion, \c *p points to the first byte
187 * after the length, i.e. the first byte of the content.
188 * On error, the value of \c *p is undefined.
189 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200190 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100191 * read from the ASN.1 input.
Paul Bakkerefc30292011-11-10 14:43:23 +0000192 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100193 * \return 0 if successful.
194 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
195 * would end beyond \p end.
Andrzej Kurek293e4522022-04-13 14:28:52 -0400196 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000197 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100198int mbedtls_asn1_get_len(unsigned char **p,
199 const unsigned char *end,
200 size_t *len);
Paul Bakkerefc30292011-11-10 14:43:23 +0000201
202/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100203 * \brief Get the tag and length of the element.
204 * Check for the requested tag.
Paul Bakkercdda0972013-09-09 12:51:29 +0200205 * Updates the pointer to immediately behind the tag and length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000206 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100207 * \param p On entry, \c *p points to the start of the ASN.1 element.
208 * On successful completion, \c *p points to the first byte
209 * after the length, i.e. the first byte of the content.
210 * On error, the value of \c *p is undefined.
211 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200212 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100213 * read from the ASN.1 input.
214 * \param tag The expected tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000215 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100216 * \return 0 if successful.
217 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start
218 * with the requested tag.
219 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
220 * would end beyond \p end.
Shaun Case0e7791f2021-12-20 21:14:10 -0800221 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000222 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100223int mbedtls_asn1_get_tag(unsigned char **p,
224 const unsigned char *end,
225 size_t *len, int tag);
Paul Bakkerefc30292011-11-10 14:43:23 +0000226
227/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200228 * \brief Retrieve a boolean ASN.1 tag and its value.
229 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000230 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100231 * \param p On entry, \c *p points to the start of the ASN.1 element.
232 * On successful completion, \c *p points to the first byte
233 * beyond the ASN.1 element.
234 * On error, the value of \c *p is undefined.
235 * \param end End of data.
236 * \param val On success, the parsed value (\c 0 or \c 1).
Paul Bakkerefc30292011-11-10 14:43:23 +0000237 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100238 * \return 0 if successful.
239 * \return An ASN.1 error code if the input does not start with
240 * a valid ASN.1 BOOLEAN.
Paul Bakkerefc30292011-11-10 14:43:23 +0000241 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100242int mbedtls_asn1_get_bool(unsigned char **p,
243 const unsigned char *end,
244 int *val);
Paul Bakkerefc30292011-11-10 14:43:23 +0000245
246/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200247 * \brief Retrieve an integer ASN.1 tag and its value.
248 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000249 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100250 * \param p On entry, \c *p points to the start of the ASN.1 element.
251 * On successful completion, \c *p points to the first byte
252 * beyond the ASN.1 element.
253 * On error, the value of \c *p is undefined.
254 * \param end End of data.
255 * \param val On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000256 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100257 * \return 0 if successful.
258 * \return An ASN.1 error code if the input does not start with
259 * a valid ASN.1 INTEGER.
260 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
261 * not fit in an \c int.
Paul Bakkerefc30292011-11-10 14:43:23 +0000262 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100263int mbedtls_asn1_get_int(unsigned char **p,
264 const unsigned char *end,
265 int *val);
Paul Bakkerefc30292011-11-10 14:43:23 +0000266
267/**
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +0200268 * \brief Retrieve an enumerated ASN.1 tag and its value.
269 * Updates the pointer to immediately behind the full tag.
270 *
271 * \param p On entry, \c *p points to the start of the ASN.1 element.
272 * On successful completion, \c *p points to the first byte
273 * beyond the ASN.1 element.
274 * On error, the value of \c *p is undefined.
275 * \param end End of data.
276 * \param val On success, the parsed value.
277 *
278 * \return 0 if successful.
279 * \return An ASN.1 error code if the input does not start with
280 * a valid ASN.1 ENUMERATED.
281 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
282 * not fit in an \c int.
283 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100284int mbedtls_asn1_get_enum(unsigned char **p,
285 const unsigned char *end,
286 int *val);
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +0200287
288/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200289 * \brief Retrieve a bitstring ASN.1 tag and its value.
290 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000291 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100292 * \param p On entry, \c *p points to the start of the ASN.1 element.
293 * On successful completion, \c *p is equal to \p end.
294 * On error, the value of \c *p is undefined.
295 * \param end End of data.
296 * \param bs On success, ::mbedtls_asn1_bitstring information about
297 * the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000298 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100299 * \return 0 if successful.
300 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
301 * extra data after a valid BIT STRING.
302 * \return An ASN.1 error code if the input does not start with
303 * a valid ASN.1 BIT STRING.
Paul Bakkerefc30292011-11-10 14:43:23 +0000304 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100305int mbedtls_asn1_get_bitstring(unsigned char **p, const unsigned char *end,
306 mbedtls_asn1_bitstring *bs);
Paul Bakkerefc30292011-11-10 14:43:23 +0000307
308/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200309 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
310 * value.
311 * Updates the pointer to the beginning of the bit/octet string.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200312 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100313 * \param p On entry, \c *p points to the start of the ASN.1 element.
314 * On successful completion, \c *p points to the first byte
315 * of the content of the BIT STRING.
316 * On error, the value of \c *p is undefined.
317 * \param end End of data.
318 * \param len On success, \c *len is the length of the content in bytes.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200319 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100320 * \return 0 if successful.
321 * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with
322 * a valid BIT STRING with a nonzero number of unused bits.
323 * \return An ASN.1 error code if the input does not start with
324 * a valid ASN.1 BIT STRING.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200325 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100326int mbedtls_asn1_get_bitstring_null(unsigned char **p,
327 const unsigned char *end,
328 size_t *len);
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200329
330/**
Gilles Peskinedc2db482019-09-20 21:06:01 +0200331 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>".
332 * Updates the pointer to immediately behind the full sequence tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000333 *
Hanno Becker12ae27d2019-09-11 14:20:09 +0100334 * This function allocates memory for the sequence elements. You can free
335 * the allocated memory with mbedtls_asn1_sequence_free().
336 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100337 * \note On error, this function may return a partial list in \p cur.
338 * You must set `cur->next = NULL` before calling this function!
339 * Otherwise it is impossible to distinguish a previously non-null
340 * pointer from a pointer to an object allocated by this function.
Paul Bakkerefc30292011-11-10 14:43:23 +0000341 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100342 * \note If the sequence is empty, this function does not modify
343 * \c *cur. If the sequence is valid and non-empty, this
344 * function sets `cur->buf.tag` to \p tag. This allows
345 * callers to distinguish between an empty sequence and
346 * a one-element sequence.
347 *
348 * \param p On entry, \c *p points to the start of the ASN.1 element.
349 * On successful completion, \c *p is equal to \p end.
350 * On error, the value of \c *p is undefined.
351 * \param end End of data.
352 * \param cur A ::mbedtls_asn1_sequence which this function fills.
353 * When this function returns, \c *cur is the head of a linked
354 * list. Each node in this list is allocated with
355 * mbedtls_calloc() apart from \p cur itself, and should
356 * therefore be freed with mbedtls_free().
357 * The list describes the content of the sequence.
358 * The head of the list (i.e. \c *cur itself) describes the
359 * first element, `*cur->next` describes the second element, etc.
360 * For each element, `buf.tag == tag`, `buf.len` is the length
361 * of the content of the content of the element, and `buf.p`
362 * points to the first byte of the content (i.e. immediately
363 * past the length of the element).
364 * Note that list elements may be allocated even on error.
365 * \param tag Each element of the sequence must have this tag.
366 *
367 * \return 0 if successful.
368 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
369 * extra data after a valid SEQUENCE OF \p tag.
Gilles Peskineb5c74a52019-10-30 17:07:02 +0100370 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with
371 * an ASN.1 SEQUENCE in which an element has a tag that
372 * is different from \p tag.
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100373 * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
374 * \return An ASN.1 error code if the input does not start with
Gilles Peskineb5c74a52019-10-30 17:07:02 +0100375 * a valid ASN.1 SEQUENCE.
Paul Bakkerefc30292011-11-10 14:43:23 +0000376 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100377int mbedtls_asn1_get_sequence_of(unsigned char **p,
378 const unsigned char *end,
379 mbedtls_asn1_sequence *cur,
380 int tag);
Hanno Becker12ae27d2019-09-11 14:20:09 +0100381/**
382 * \brief Free a heap-allocated linked list presentation of
383 * an ASN.1 sequence, including the first element.
384 *
385 * There are two common ways to manage the memory used for the representation
386 * of a parsed ASN.1 sequence:
387 * - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc().
388 * Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of().
389 * When you have finished processing the sequence,
390 * call mbedtls_asn1_sequence_free() on `head`.
391 * - Allocate a head node `mbedtls_asn1_sequence *head` in any manner,
392 * for example on the stack. Make sure that `head->next == NULL`.
393 * Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of().
394 * When you have finished processing the sequence,
395 * call mbedtls_asn1_sequence_free() on `head->cur`,
396 * then free `head` itself in the appropriate manner.
397 *
398 * \param seq The address of the first sequence component. This may
399 * be \c NULL, in which case this functions returns
400 * immediately.
401 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100402void mbedtls_asn1_sequence_free(mbedtls_asn1_sequence *seq);
Paul Bakkerefc30292011-11-10 14:43:23 +0000403
Hanno Becker199b7092019-09-11 14:21:26 +0100404/**
405 * \brief Traverse an ASN.1 SEQUENCE container and
406 * call a callback for each entry.
407 *
408 * This function checks that the input is a SEQUENCE of elements that
409 * each have a "must" tag, and calls a callback function on the elements
410 * that have a "may" tag.
411 *
412 * For example, to validate that the input is a SEQUENCE of `tag1` and call
413 * `cb` on each element, use
414 * ```
415 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx);
416 * ```
417 *
418 * To validate that the input is a SEQUENCE of ANY and call `cb` on
419 * each element, use
420 * ```
421 * mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx);
422 * ```
423 *
424 * To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING}
425 * and call `cb` on each element that is an OCTET STRING, use
426 * ```
427 * mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx);
428 * ```
429 *
430 * The callback is called on the elements with a "may" tag from left to
431 * right. If the input is not a valid SEQUENCE of elements with a "must" tag,
432 * the callback is called on the elements up to the leftmost point where
433 * the input is invalid.
434 *
435 * \warning This function is still experimental and may change
436 * at any time.
437 *
438 * \param p The address of the pointer to the beginning of
439 * the ASN.1 SEQUENCE header. This is updated to
440 * point to the end of the ASN.1 SEQUENCE container
441 * on a successful invocation.
442 * \param end The end of the ASN.1 SEQUENCE container.
443 * \param tag_must_mask A mask to be applied to the ASN.1 tags found within
Andrzej Kureka4900422022-02-17 10:06:44 -0500444 * the SEQUENCE before comparing to \p tag_must_val.
Hanno Becker199b7092019-09-11 14:21:26 +0100445 * \param tag_must_val The required value of each ASN.1 tag found in the
446 * SEQUENCE, after masking with \p tag_must_mask.
447 * Mismatching tags lead to an error.
448 * For example, a value of \c 0 for both \p tag_must_mask
449 * and \p tag_must_val means that every tag is allowed,
450 * while a value of \c 0xFF for \p tag_must_mask means
451 * that \p tag_must_val is the only allowed tag.
452 * \param tag_may_mask A mask to be applied to the ASN.1 tags found within
Andrzej Kureka4900422022-02-17 10:06:44 -0500453 * the SEQUENCE before comparing to \p tag_may_val.
Hanno Becker199b7092019-09-11 14:21:26 +0100454 * \param tag_may_val The desired value of each ASN.1 tag found in the
455 * SEQUENCE, after masking with \p tag_may_mask.
456 * Mismatching tags will be silently ignored.
457 * For example, a value of \c 0 for \p tag_may_mask and
458 * \p tag_may_val means that any tag will be considered,
459 * while a value of \c 0xFF for \p tag_may_mask means
460 * that all tags with value different from \p tag_may_val
461 * will be ignored.
462 * \param cb The callback to trigger for each component
463 * in the ASN.1 SEQUENCE that matches \p tag_may_val.
464 * The callback function is called with the following
465 * parameters:
466 * - \p ctx.
467 * - The tag of the current element.
468 * - A pointer to the start of the current element's
469 * content inside the input.
470 * - The length of the content of the current element.
471 * If the callback returns a non-zero value,
472 * the function stops immediately,
473 * forwarding the callback's return value.
474 * \param ctx The context to be passed to the callback \p cb.
475 *
476 * \return \c 0 if successful the entire ASN.1 SEQUENCE
477 * was traversed without parsing or callback errors.
478 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input
479 * contains extra data after a valid SEQUENCE
480 * of elements with an accepted tag.
481 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts
482 * with an ASN.1 SEQUENCE in which an element has a tag
483 * that is not accepted.
484 * \return An ASN.1 error code if the input does not start with
485 * a valid ASN.1 SEQUENCE.
486 * \return A non-zero error code forwarded from the callback
487 * \p cb in case the latter returns a non-zero value.
488 */
489int mbedtls_asn1_traverse_sequence_of(
490 unsigned char **p,
491 const unsigned char *end,
Hanno Becker34aada22020-02-03 10:39:55 +0000492 unsigned char tag_must_mask, unsigned char tag_must_val,
493 unsigned char tag_may_mask, unsigned char tag_may_val,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100494 int (*cb)(void *ctx, int tag,
495 unsigned char *start, size_t len),
496 void *ctx);
Hanno Becker199b7092019-09-11 14:21:26 +0100497
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200498#if defined(MBEDTLS_BIGNUM_C)
Paul Bakkerefc30292011-11-10 14:43:23 +0000499/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100500 * \brief Retrieve an integer ASN.1 tag and its value.
Paul Bakkercdda0972013-09-09 12:51:29 +0200501 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000502 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100503 * \param p On entry, \c *p points to the start of the ASN.1 element.
504 * On successful completion, \c *p points to the first byte
505 * beyond the ASN.1 element.
506 * On error, the value of \c *p is undefined.
507 * \param end End of data.
508 * \param X On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000509 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100510 * \return 0 if successful.
511 * \return An ASN.1 error code if the input does not start with
512 * a valid ASN.1 INTEGER.
513 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
514 * not fit in an \c int.
515 * \return An MPI error code if the parsed value is too large.
Paul Bakkerefc30292011-11-10 14:43:23 +0000516 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100517int mbedtls_asn1_get_mpi(unsigned char **p,
518 const unsigned char *end,
519 mbedtls_mpi *X);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200520#endif /* MBEDTLS_BIGNUM_C */
Paul Bakkerefc30292011-11-10 14:43:23 +0000521
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200522/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200523 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
524 * Updates the pointer to immediately behind the full
525 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200526 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100527 * \param p On entry, \c *p points to the start of the ASN.1 element.
528 * On successful completion, \c *p points to the first byte
529 * beyond the AlgorithmIdentifier element.
530 * On error, the value of \c *p is undefined.
531 * \param end End of data.
532 * \param alg The buffer to receive the OID.
533 * \param params The buffer to receive the parameters.
534 * This is zeroized if there are no parameters.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200535 *
536 * \return 0 if successful or a specific ASN.1 or MPI error code.
537 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100538int mbedtls_asn1_get_alg(unsigned char **p,
539 const unsigned char *end,
540 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params);
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200541
542/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200543 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
544 * params.
545 * Updates the pointer to immediately behind the full
546 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200547 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100548 * \param p On entry, \c *p points to the start of the ASN.1 element.
549 * On successful completion, \c *p points to the first byte
550 * beyond the AlgorithmIdentifier element.
551 * On error, the value of \c *p is undefined.
552 * \param end End of data.
553 * \param alg The buffer to receive the OID.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200554 *
555 * \return 0 if successful or a specific ASN.1 or MPI error code.
556 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100557int mbedtls_asn1_get_alg_null(unsigned char **p,
558 const unsigned char *end,
559 mbedtls_asn1_buf *alg);
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200560
Paul Bakkere5eae762013-08-26 12:05:14 +0200561/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200562 * \brief Find a specific named_data entry in a sequence or list based on
563 * the OID.
Paul Bakkere5eae762013-08-26 12:05:14 +0200564 *
565 * \param list The list to seek through
566 * \param oid The OID to look for
567 * \param len Size of the OID
568 *
569 * \return NULL if not found, or a pointer to the existing entry.
570 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100571mbedtls_asn1_named_data *mbedtls_asn1_find_named_data(mbedtls_asn1_named_data *list,
572 const char *oid, size_t len);
Paul Bakkere5eae762013-08-26 12:05:14 +0200573
574/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200575 * \brief Free a mbedtls_asn1_named_data entry
Paul Bakkere5eae762013-08-26 12:05:14 +0200576 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100577 * \param entry The named data entry to free.
578 * This function calls mbedtls_free() on
579 * `entry->oid.p` and `entry->val.p`.
Paul Bakkere5eae762013-08-26 12:05:14 +0200580 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100581void mbedtls_asn1_free_named_data(mbedtls_asn1_named_data *entry);
Paul Bakkere5eae762013-08-26 12:05:14 +0200582
Paul Bakkerc547cc92013-09-09 12:01:23 +0200583/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100584 * \brief Free all entries in a mbedtls_asn1_named_data list.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200585 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100586 * \param head Pointer to the head of the list of named data entries to free.
587 * This function calls mbedtls_asn1_free_named_data() and
588 * mbedtls_free() on each list element and
589 * sets \c *head to \c NULL.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200590 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100591void mbedtls_asn1_free_named_data_list(mbedtls_asn1_named_data **head);
Paul Bakkerc547cc92013-09-09 12:01:23 +0200592
Andrzej Kurek73afe272022-01-24 10:31:06 -0500593/** \} name Functions to parse ASN.1 data structures */
Andrzej Kurekff632d52022-01-24 10:32:00 -0500594/** \} addtogroup asn1_module */
Andrzej Kurek73afe272022-01-24 10:31:06 -0500595
Paul Bakkerefc30292011-11-10 14:43:23 +0000596#ifdef __cplusplus
597}
598#endif
599
600#endif /* asn1.h */