blob: 1cfd414e35f5357f90adfd4c4b4a328d00f39c0e [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/*
Manuel Pégourié-Gonnard6fb81872015-07-27 11:11:48 +02007 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02008 * 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.
Paul Bakkerefc30292011-11-10 14:43:23 +000021 *
Manuel Pégourié-Gonnardfe446432015-03-06 13:17:10 +000022 * This file is part of mbed TLS (https://tls.mbed.org)
Paul Bakkerefc30292011-11-10 14:43:23 +000023 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020024#ifndef MBEDTLS_ASN1_H
25#define MBEDTLS_ASN1_H
Paul Bakkerefc30292011-11-10 14:43:23 +000026
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020027#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010028#include "mbedtls/config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020029#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020030#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020031#endif
Paul Bakkerefc30292011-11-10 14:43:23 +000032
Rich Evans00ab4702015-02-06 13:43:58 +000033#include <stddef.h>
34
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020035#if defined(MBEDTLS_BIGNUM_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010036#include "mbedtls/bignum.h"
Paul Bakkerefc30292011-11-10 14:43:23 +000037#endif
38
Paul Bakker9af723c2014-05-01 13:03:14 +020039/**
Paul Bakkerefc30292011-11-10 14:43:23 +000040 * \addtogroup asn1_module
Paul Bakker9af723c2014-05-01 13:03:14 +020041 * \{
Paul Bakkerefc30292011-11-10 14:43:23 +000042 */
Paul Bakker9af723c2014-05-01 13:03:14 +020043
Paul Bakkerefc30292011-11-10 14:43:23 +000044/**
45 * \name ASN1 Error codes
46 * These error codes are OR'ed to X509 error codes for
Paul Bakker9af723c2014-05-01 13:03:14 +020047 * higher error granularity.
Paul Bakkerefc30292011-11-10 14:43:23 +000048 * ASN1 is a standard to specify data structures.
49 * \{
50 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020051#define MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060 /**< Out of data when parsing an ASN1 data structure. */
52#define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062 /**< ASN1 tag was of an unexpected value. */
53#define MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064 /**< Error when trying to determine the length or invalid length. */
54#define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066 /**< Actual length differs from expected length. */
Gilles Peskineaac38532019-09-11 16:52:01 +020055#define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068 /**< Data is invalid. */
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +020056#define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A /**< Memory allocation failed */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020057#define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C /**< Buffer too small when writing ASN.1 data structure. */
Paul Bakker05888152012-02-16 10:26:57 +000058
Paul Bakkerefc30292011-11-10 14:43:23 +000059/* \} name */
60
61/**
62 * \name DER constants
Andres Amaya Garcia9fb02052017-08-25 17:24:44 +010063 * These constants comply with the DER encoded ASN.1 type tags.
Paul Bakkerefc30292011-11-10 14:43:23 +000064 * DER encoding uses hexadecimal representation.
65 * An example DER sequence is:\n
66 * - 0x02 -- tag indicating INTEGER
67 * - 0x01 -- length in octets
68 * - 0x05 -- value
Jaeden Amerod8087712018-11-05 14:24:29 +000069 * Such sequences are typically read into Mbed TLS's \c mbedtls_x509_buf.
Paul Bakkerefc30292011-11-10 14:43:23 +000070 * \{
71 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020072#define MBEDTLS_ASN1_BOOLEAN 0x01
73#define MBEDTLS_ASN1_INTEGER 0x02
74#define MBEDTLS_ASN1_BIT_STRING 0x03
75#define MBEDTLS_ASN1_OCTET_STRING 0x04
76#define MBEDTLS_ASN1_NULL 0x05
77#define MBEDTLS_ASN1_OID 0x06
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +020078#define MBEDTLS_ASN1_ENUMERATED 0x0A
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020079#define MBEDTLS_ASN1_UTF8_STRING 0x0C
80#define MBEDTLS_ASN1_SEQUENCE 0x10
81#define MBEDTLS_ASN1_SET 0x11
82#define MBEDTLS_ASN1_PRINTABLE_STRING 0x13
83#define MBEDTLS_ASN1_T61_STRING 0x14
84#define MBEDTLS_ASN1_IA5_STRING 0x16
85#define MBEDTLS_ASN1_UTC_TIME 0x17
86#define MBEDTLS_ASN1_GENERALIZED_TIME 0x18
87#define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C
88#define MBEDTLS_ASN1_BMP_STRING 0x1E
89#define MBEDTLS_ASN1_PRIMITIVE 0x00
90#define MBEDTLS_ASN1_CONSTRUCTED 0x20
91#define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +010092
Hanno Beckercba71222019-09-11 14:15:10 +010093/* Slightly smaller way to check if tag is a string tag
94 * compared to canonical implementation. */
95#define MBEDTLS_ASN1_IS_STRING_TAG( tag ) \
96 ( ( tag ) < 32u && ( \
97 ( ( 1u << ( tag ) ) & ( ( 1u << MBEDTLS_ASN1_BMP_STRING ) | \
98 ( 1u << MBEDTLS_ASN1_UTF8_STRING ) | \
99 ( 1u << MBEDTLS_ASN1_T61_STRING ) | \
100 ( 1u << MBEDTLS_ASN1_IA5_STRING ) | \
101 ( 1u << MBEDTLS_ASN1_UNIVERSAL_STRING ) | \
102 ( 1u << MBEDTLS_ASN1_PRINTABLE_STRING ) | \
103 ( 1u << MBEDTLS_ASN1_BIT_STRING ) ) ) != 0 ) )
104
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +0100105/*
106 * Bit masks for each of the components of an ASN.1 tag as specified in
Gilles Peskine1ed45ea2018-03-08 18:16:45 +0100107 * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
108 * paragraph 8.1.2.2:
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +0100109 *
110 * Bit 8 7 6 5 1
111 * +-------+-----+------------+
112 * | Class | P/C | Tag number |
113 * +-------+-----+------------+
114 */
Andres Amaya Garcia7786abc2017-11-07 20:21:56 +0000115#define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
116#define MBEDTLS_ASN1_TAG_PC_MASK 0x20
117#define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F
Andres Amaya Garcia7512bf72017-08-25 17:12:11 +0100118
Paul Bakkerefc30292011-11-10 14:43:23 +0000119/* \} name */
120/* \} addtogroup asn1_module */
121
122/** Returns the size of the binary string, without the trailing \\0 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200123#define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
Paul Bakkerefc30292011-11-10 14:43:23 +0000124
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100125/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200126 * Compares an mbedtls_asn1_buf structure to a reference OID.
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100127 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200128 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100129 * 'unsigned char *oid' here!
Paul Bakkere5eae762013-08-26 12:05:14 +0200130 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200131#define MBEDTLS_OID_CMP(oid_str, oid_buf) \
132 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \
Manuel Pégourié-Gonnard6e064372015-03-19 16:54:56 +0000133 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 )
Paul Bakkerc70b9822013-04-07 22:00:46 +0200134
Paul Bakkerefc30292011-11-10 14:43:23 +0000135#ifdef __cplusplus
136extern "C" {
137#endif
138
139/**
140 * \name Functions to parse ASN.1 data structures
141 * \{
142 */
143
144/**
145 * Type-length-value structure that allows for ASN1 using DER.
146 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200147typedef struct mbedtls_asn1_buf
Paul Bakkerefc30292011-11-10 14:43:23 +0000148{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200149 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200150 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000151 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
152}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200153mbedtls_asn1_buf;
Paul Bakkerefc30292011-11-10 14:43:23 +0000154
155/**
156 * Container for ASN1 bit strings.
157 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200158typedef struct mbedtls_asn1_bitstring
Paul Bakkerefc30292011-11-10 14:43:23 +0000159{
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200160 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000161 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}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200164mbedtls_asn1_bitstring;
Paul Bakkerefc30292011-11-10 14:43:23 +0000165
166/**
167 * Container for a sequence of ASN.1 items
168 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200169typedef struct mbedtls_asn1_sequence
Paul Bakkerefc30292011-11-10 14:43:23 +0000170{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200171 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
172 struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000173}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200174mbedtls_asn1_sequence;
Paul Bakkerefc30292011-11-10 14:43:23 +0000175
176/**
Paul Bakkere5eae762013-08-26 12:05:14 +0200177 * Container for a sequence or list of 'named' ASN.1 data items
178 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200179typedef struct mbedtls_asn1_named_data
Paul Bakkere5eae762013-08-26 12:05:14 +0200180{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200181 mbedtls_asn1_buf oid; /**< The object identifier. */
182 mbedtls_asn1_buf val; /**< The named value. */
183 struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
Manuel Pégourié-Gonnard555fbf82015-02-04 17:11:55 +0000184 unsigned char next_merged; /**< Merge next item into the current one? */
Paul Bakkere5eae762013-08-26 12:05:14 +0200185}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200186mbedtls_asn1_named_data;
Paul Bakkere5eae762013-08-26 12:05:14 +0200187
188/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200189 * \brief Get the length of an ASN.1 element.
190 * Updates the pointer to immediately behind the length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000191 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100192 * \param p On entry, \c *p points to the first byte of the length,
193 * i.e. immediately after the tag.
194 * On successful completion, \c *p points to the first byte
195 * after the length, i.e. the first byte of the content.
196 * On error, the value of \c *p is undefined.
197 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200198 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100199 * read from the ASN.1 input.
Paul Bakkerefc30292011-11-10 14:43:23 +0000200 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100201 * \return 0 if successful.
202 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
203 * would end beyond \p end.
204 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000205 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200206int mbedtls_asn1_get_len( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100207 const unsigned char *end,
208 size_t *len );
Paul Bakkerefc30292011-11-10 14:43:23 +0000209
210/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100211 * \brief Get the tag and length of the element.
212 * Check for the requested tag.
Paul Bakkercdda0972013-09-09 12:51:29 +0200213 * Updates the pointer to immediately behind the tag and length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000214 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100215 * \param p On entry, \c *p points to the start of the ASN.1 element.
216 * On successful completion, \c *p points to the first byte
217 * after the length, i.e. the first byte of the content.
218 * On error, the value of \c *p is undefined.
219 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200220 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100221 * read from the ASN.1 input.
222 * \param tag The expected tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000223 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100224 * \return 0 if successful.
225 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start
226 * with the requested tag.
227 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
228 * would end beyond \p end.
229 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000230 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200231int mbedtls_asn1_get_tag( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100232 const unsigned char *end,
233 size_t *len, int tag );
Paul Bakkerefc30292011-11-10 14:43:23 +0000234
235/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200236 * \brief Retrieve a boolean ASN.1 tag and its value.
237 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000238 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100239 * \param p On entry, \c *p points to the start of the ASN.1 element.
240 * On successful completion, \c *p points to the first byte
241 * beyond the ASN.1 element.
242 * On error, the value of \c *p is undefined.
243 * \param end End of data.
244 * \param val On success, the parsed value (\c 0 or \c 1).
Paul Bakkerefc30292011-11-10 14:43:23 +0000245 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100246 * \return 0 if successful.
247 * \return An ASN.1 error code if the input does not start with
248 * a valid ASN.1 BOOLEAN.
Paul Bakkerefc30292011-11-10 14:43:23 +0000249 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200250int mbedtls_asn1_get_bool( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100251 const unsigned char *end,
252 int *val );
Paul Bakkerefc30292011-11-10 14:43:23 +0000253
254/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200255 * \brief Retrieve an integer ASN.1 tag and its value.
256 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000257 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100258 * \param p On entry, \c *p points to the start of the ASN.1 element.
259 * On successful completion, \c *p points to the first byte
260 * beyond the ASN.1 element.
261 * On error, the value of \c *p is undefined.
262 * \param end End of data.
263 * \param val On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000264 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100265 * \return 0 if successful.
266 * \return An ASN.1 error code if the input does not start with
267 * a valid ASN.1 INTEGER.
268 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
269 * not fit in an \c int.
Paul Bakkerefc30292011-11-10 14:43:23 +0000270 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200271int mbedtls_asn1_get_int( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100272 const unsigned char *end,
273 int *val );
Paul Bakkerefc30292011-11-10 14:43:23 +0000274
275/**
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +0200276 * \brief Retrieve an enumerated ASN.1 tag and its value.
277 * Updates the pointer to immediately behind the full tag.
278 *
279 * \param p On entry, \c *p points to the start of the ASN.1 element.
280 * On successful completion, \c *p points to the first byte
281 * beyond the ASN.1 element.
282 * On error, the value of \c *p is undefined.
283 * \param end End of data.
284 * \param val On success, the parsed value.
285 *
286 * \return 0 if successful.
287 * \return An ASN.1 error code if the input does not start with
288 * a valid ASN.1 ENUMERATED.
289 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
290 * not fit in an \c int.
291 */
292int mbedtls_asn1_get_enum( unsigned char **p,
293 const unsigned char *end,
294 int *val );
295
296/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200297 * \brief Retrieve a bitstring ASN.1 tag and its value.
298 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000299 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100300 * \param p On entry, \c *p points to the start of the ASN.1 element.
301 * On successful completion, \c *p is equal to \p end.
302 * On error, the value of \c *p is undefined.
303 * \param end End of data.
304 * \param bs On success, ::mbedtls_asn1_bitstring information about
305 * the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000306 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100307 * \return 0 if successful.
308 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
309 * extra data after a valid BIT STRING.
310 * \return An ASN.1 error code if the input does not start with
311 * a valid ASN.1 BIT STRING.
Paul Bakkerefc30292011-11-10 14:43:23 +0000312 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200313int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100314 mbedtls_asn1_bitstring *bs );
Paul Bakkerefc30292011-11-10 14:43:23 +0000315
316/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200317 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
318 * value.
319 * Updates the pointer to the beginning of the bit/octet string.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200320 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100321 * \param p On entry, \c *p points to the start of the ASN.1 element.
322 * On successful completion, \c *p points to the first byte
323 * of the content of the BIT STRING.
324 * On error, the value of \c *p is undefined.
325 * \param end End of data.
326 * \param len On success, \c *len is the length of the content in bytes.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200327 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100328 * \return 0 if successful.
329 * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with
330 * a valid BIT STRING with a nonzero number of unused bits.
331 * \return An ASN.1 error code if the input does not start with
332 * a valid ASN.1 BIT STRING.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200333 */
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100334int mbedtls_asn1_get_bitstring_null( unsigned char **p,
335 const unsigned char *end,
336 size_t *len );
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200337
338/**
Gilles Peskinedc2db482019-09-20 21:06:01 +0200339 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>".
340 * Updates the pointer to immediately behind the full sequence tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000341 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100342 * \note On error, this function may return a partial list in \p cur.
343 * You must set `cur->next = NULL` before calling this function!
344 * Otherwise it is impossible to distinguish a previously non-null
345 * pointer from a pointer to an object allocated by this function.
Paul Bakkerefc30292011-11-10 14:43:23 +0000346 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100347 * \note If the sequence is empty, this function does not modify
348 * \c *cur. If the sequence is valid and non-empty, this
349 * function sets `cur->buf.tag` to \p tag. This allows
350 * callers to distinguish between an empty sequence and
351 * a one-element sequence.
352 *
353 * \param p On entry, \c *p points to the start of the ASN.1 element.
354 * On successful completion, \c *p is equal to \p end.
355 * On error, the value of \c *p is undefined.
356 * \param end End of data.
357 * \param cur A ::mbedtls_asn1_sequence which this function fills.
358 * When this function returns, \c *cur is the head of a linked
359 * list. Each node in this list is allocated with
360 * mbedtls_calloc() apart from \p cur itself, and should
361 * therefore be freed with mbedtls_free().
362 * The list describes the content of the sequence.
363 * The head of the list (i.e. \c *cur itself) describes the
364 * first element, `*cur->next` describes the second element, etc.
365 * For each element, `buf.tag == tag`, `buf.len` is the length
366 * of the content of the content of the element, and `buf.p`
367 * points to the first byte of the content (i.e. immediately
368 * past the length of the element).
369 * Note that list elements may be allocated even on error.
370 * \param tag Each element of the sequence must have this tag.
371 *
372 * \return 0 if successful.
373 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
374 * extra data after a valid SEQUENCE OF \p tag.
375 * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
376 * \return An ASN.1 error code if the input does not start with
377 * a valid ASN.1 BIT STRING.
Paul Bakkerefc30292011-11-10 14:43:23 +0000378 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200379int mbedtls_asn1_get_sequence_of( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100380 const unsigned char *end,
381 mbedtls_asn1_sequence *cur,
382 int tag );
Paul Bakkerefc30292011-11-10 14:43:23 +0000383
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200384#if defined(MBEDTLS_BIGNUM_C)
Paul Bakkerefc30292011-11-10 14:43:23 +0000385/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100386 * \brief Retrieve an integer ASN.1 tag and its value.
Paul Bakkercdda0972013-09-09 12:51:29 +0200387 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000388 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100389 * \param p On entry, \c *p points to the start of the ASN.1 element.
390 * On successful completion, \c *p points to the first byte
391 * beyond the ASN.1 element.
392 * On error, the value of \c *p is undefined.
393 * \param end End of data.
394 * \param X On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000395 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100396 * \return 0 if successful.
397 * \return An ASN.1 error code if the input does not start with
398 * a valid ASN.1 INTEGER.
399 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
400 * not fit in an \c int.
401 * \return An MPI error code if the parsed value is too large.
Paul Bakkerefc30292011-11-10 14:43:23 +0000402 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200403int mbedtls_asn1_get_mpi( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100404 const unsigned char *end,
405 mbedtls_mpi *X );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200406#endif /* MBEDTLS_BIGNUM_C */
Paul Bakkerefc30292011-11-10 14:43:23 +0000407
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200408/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200409 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
410 * Updates the pointer to immediately behind the full
411 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200412 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100413 * \param p On entry, \c *p points to the start of the ASN.1 element.
414 * On successful completion, \c *p points to the first byte
415 * beyond the AlgorithmIdentifier element.
416 * On error, the value of \c *p is undefined.
417 * \param end End of data.
418 * \param alg The buffer to receive the OID.
419 * \param params The buffer to receive the parameters.
420 * This is zeroized if there are no parameters.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200421 *
422 * \return 0 if successful or a specific ASN.1 or MPI error code.
423 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200424int mbedtls_asn1_get_alg( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200425 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200426 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200427
428/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200429 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
430 * params.
431 * Updates the pointer to immediately behind the full
432 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200433 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100434 * \param p On entry, \c *p points to the start of the ASN.1 element.
435 * On successful completion, \c *p points to the first byte
436 * beyond the AlgorithmIdentifier element.
437 * On error, the value of \c *p is undefined.
438 * \param end End of data.
439 * \param alg The buffer to receive the OID.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200440 *
441 * \return 0 if successful or a specific ASN.1 or MPI error code.
442 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200443int mbedtls_asn1_get_alg_null( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200444 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200445 mbedtls_asn1_buf *alg );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200446
Paul Bakkere5eae762013-08-26 12:05:14 +0200447/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200448 * \brief Find a specific named_data entry in a sequence or list based on
449 * the OID.
Paul Bakkere5eae762013-08-26 12:05:14 +0200450 *
451 * \param list The list to seek through
452 * \param oid The OID to look for
453 * \param len Size of the OID
454 *
455 * \return NULL if not found, or a pointer to the existing entry.
456 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200457mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list,
Paul Bakkere5eae762013-08-26 12:05:14 +0200458 const char *oid, size_t len );
459
460/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200461 * \brief Free a mbedtls_asn1_named_data entry
Paul Bakkere5eae762013-08-26 12:05:14 +0200462 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100463 * \param entry The named data entry to free.
464 * This function calls mbedtls_free() on
465 * `entry->oid.p` and `entry->val.p`.
Paul Bakkere5eae762013-08-26 12:05:14 +0200466 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200467void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
Paul Bakkere5eae762013-08-26 12:05:14 +0200468
Paul Bakkerc547cc92013-09-09 12:01:23 +0200469/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100470 * \brief Free all entries in a mbedtls_asn1_named_data list.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200471 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100472 * \param head Pointer to the head of the list of named data entries to free.
473 * This function calls mbedtls_asn1_free_named_data() and
474 * mbedtls_free() on each list element and
475 * sets \c *head to \c NULL.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200476 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200477void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
Paul Bakkerc547cc92013-09-09 12:01:23 +0200478
Paul Bakkerefc30292011-11-10 14:43:23 +0000479#ifdef __cplusplus
480}
481#endif
482
483#endif /* asn1.h */