blob: 0a2727e121d7e55ee158029f9f0b2d1bc32160ec [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
Hanno Becker63e38fe2019-09-11 14:16:40 +0100135#define MBEDTLS_OID_CMP_RAW(oid_str, oid_buf, oid_buf_len) \
136 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf_len) ) || \
137 memcmp( (oid_str), (oid_buf), (oid_buf_len) ) != 0 )
138
Paul Bakkerefc30292011-11-10 14:43:23 +0000139#ifdef __cplusplus
140extern "C" {
141#endif
142
143/**
144 * \name Functions to parse ASN.1 data structures
145 * \{
146 */
147
148/**
149 * Type-length-value structure that allows for ASN1 using DER.
150 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200151typedef struct mbedtls_asn1_buf
Paul Bakkerefc30292011-11-10 14:43:23 +0000152{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200153 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
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 *p; /**< ASN1 data, e.g. in ASCII. */
156}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200157mbedtls_asn1_buf;
Paul Bakkerefc30292011-11-10 14:43:23 +0000158
159/**
160 * Container for ASN1 bit strings.
161 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200162typedef struct mbedtls_asn1_bitstring
Paul Bakkerefc30292011-11-10 14:43:23 +0000163{
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200164 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000165 unsigned char unused_bits; /**< Number of unused bits at the end of the string */
166 unsigned char *p; /**< Raw ASN1 data for the bit string */
167}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200168mbedtls_asn1_bitstring;
Paul Bakkerefc30292011-11-10 14:43:23 +0000169
170/**
171 * Container for a sequence of ASN.1 items
172 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200173typedef struct mbedtls_asn1_sequence
Paul Bakkerefc30292011-11-10 14:43:23 +0000174{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200175 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
176 struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000177}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200178mbedtls_asn1_sequence;
Paul Bakkerefc30292011-11-10 14:43:23 +0000179
180/**
Paul Bakkere5eae762013-08-26 12:05:14 +0200181 * Container for a sequence or list of 'named' ASN.1 data items
182 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200183typedef struct mbedtls_asn1_named_data
Paul Bakkere5eae762013-08-26 12:05:14 +0200184{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200185 mbedtls_asn1_buf oid; /**< The object identifier. */
186 mbedtls_asn1_buf val; /**< The named value. */
187 struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
Manuel Pégourié-Gonnard555fbf82015-02-04 17:11:55 +0000188 unsigned char next_merged; /**< Merge next item into the current one? */
Paul Bakkere5eae762013-08-26 12:05:14 +0200189}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200190mbedtls_asn1_named_data;
Paul Bakkere5eae762013-08-26 12:05:14 +0200191
192/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200193 * \brief Get the length of an ASN.1 element.
194 * Updates the pointer to immediately behind the length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000195 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100196 * \param p On entry, \c *p points to the first byte of the length,
197 * i.e. immediately after the tag.
198 * On successful completion, \c *p points to the first byte
199 * after the length, i.e. the first byte of the content.
200 * On error, the value of \c *p is undefined.
201 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200202 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100203 * read from the ASN.1 input.
Paul Bakkerefc30292011-11-10 14:43:23 +0000204 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100205 * \return 0 if successful.
206 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
207 * would end beyond \p end.
208 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000209 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200210int mbedtls_asn1_get_len( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100211 const unsigned char *end,
212 size_t *len );
Paul Bakkerefc30292011-11-10 14:43:23 +0000213
214/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100215 * \brief Get the tag and length of the element.
216 * Check for the requested tag.
Paul Bakkercdda0972013-09-09 12:51:29 +0200217 * Updates the pointer to immediately behind the tag and length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000218 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100219 * \param p On entry, \c *p points to the start of the ASN.1 element.
220 * On successful completion, \c *p points to the first byte
221 * after the length, i.e. the first byte of the content.
222 * On error, the value of \c *p is undefined.
223 * \param end End of data.
Gilles Peskinedc2db482019-09-20 21:06:01 +0200224 * \param len On successful completion, \c *len contains the length
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100225 * read from the ASN.1 input.
226 * \param tag The expected tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000227 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100228 * \return 0 if successful.
229 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start
230 * with the requested tag.
231 * \return #MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element
232 * would end beyond \p end.
233 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparseable.
Paul Bakkerefc30292011-11-10 14:43:23 +0000234 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200235int mbedtls_asn1_get_tag( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100236 const unsigned char *end,
237 size_t *len, int tag );
Paul Bakkerefc30292011-11-10 14:43:23 +0000238
239/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200240 * \brief Retrieve a boolean ASN.1 tag and its value.
241 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000242 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100243 * \param p On entry, \c *p points to the start of the ASN.1 element.
244 * On successful completion, \c *p points to the first byte
245 * beyond the ASN.1 element.
246 * On error, the value of \c *p is undefined.
247 * \param end End of data.
248 * \param val On success, the parsed value (\c 0 or \c 1).
Paul Bakkerefc30292011-11-10 14:43:23 +0000249 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100250 * \return 0 if successful.
251 * \return An ASN.1 error code if the input does not start with
252 * a valid ASN.1 BOOLEAN.
Paul Bakkerefc30292011-11-10 14:43:23 +0000253 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200254int mbedtls_asn1_get_bool( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100255 const unsigned char *end,
256 int *val );
Paul Bakkerefc30292011-11-10 14:43:23 +0000257
258/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200259 * \brief Retrieve an integer ASN.1 tag and its value.
260 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000261 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100262 * \param p On entry, \c *p points to the start of the ASN.1 element.
263 * On successful completion, \c *p points to the first byte
264 * beyond the ASN.1 element.
265 * On error, the value of \c *p is undefined.
266 * \param end End of data.
267 * \param val On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000268 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100269 * \return 0 if successful.
270 * \return An ASN.1 error code if the input does not start with
271 * a valid ASN.1 INTEGER.
272 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
273 * not fit in an \c int.
Paul Bakkerefc30292011-11-10 14:43:23 +0000274 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200275int mbedtls_asn1_get_int( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100276 const unsigned char *end,
277 int *val );
Paul Bakkerefc30292011-11-10 14:43:23 +0000278
279/**
Mykhailo Sopiha20180ca2019-10-29 15:58:10 +0200280 * \brief Retrieve an enumerated ASN.1 tag and its value.
281 * Updates the pointer to immediately behind the full tag.
282 *
283 * \param p On entry, \c *p points to the start of the ASN.1 element.
284 * On successful completion, \c *p points to the first byte
285 * beyond the ASN.1 element.
286 * On error, the value of \c *p is undefined.
287 * \param end End of data.
288 * \param val On success, the parsed value.
289 *
290 * \return 0 if successful.
291 * \return An ASN.1 error code if the input does not start with
292 * a valid ASN.1 ENUMERATED.
293 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
294 * not fit in an \c int.
295 */
296int mbedtls_asn1_get_enum( unsigned char **p,
297 const unsigned char *end,
298 int *val );
299
300/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200301 * \brief Retrieve a bitstring ASN.1 tag and its value.
302 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000303 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100304 * \param p On entry, \c *p points to the start of the ASN.1 element.
305 * On successful completion, \c *p is equal to \p end.
306 * On error, the value of \c *p is undefined.
307 * \param end End of data.
308 * \param bs On success, ::mbedtls_asn1_bitstring information about
309 * the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000310 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100311 * \return 0 if successful.
312 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
313 * extra data after a valid BIT STRING.
314 * \return An ASN.1 error code if the input does not start with
315 * a valid ASN.1 BIT STRING.
Paul Bakkerefc30292011-11-10 14:43:23 +0000316 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200317int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100318 mbedtls_asn1_bitstring *bs );
Paul Bakkerefc30292011-11-10 14:43:23 +0000319
320/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200321 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
322 * value.
323 * Updates the pointer to the beginning of the bit/octet string.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200324 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100325 * \param p On entry, \c *p points to the start of the ASN.1 element.
326 * On successful completion, \c *p points to the first byte
327 * of the content of the BIT STRING.
328 * On error, the value of \c *p is undefined.
329 * \param end End of data.
330 * \param len On success, \c *len is the length of the content in bytes.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200331 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100332 * \return 0 if successful.
333 * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with
334 * a valid BIT STRING with a nonzero number of unused bits.
335 * \return An ASN.1 error code if the input does not start with
336 * a valid ASN.1 BIT STRING.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200337 */
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100338int mbedtls_asn1_get_bitstring_null( unsigned char **p,
339 const unsigned char *end,
340 size_t *len );
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200341
342/**
Gilles Peskinedc2db482019-09-20 21:06:01 +0200343 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>".
344 * Updates the pointer to immediately behind the full sequence tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000345 *
Hanno Becker12ae27d2019-09-11 14:20:09 +0100346 * This function allocates memory for the sequence elements. You can free
347 * the allocated memory with mbedtls_asn1_sequence_free().
348 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100349 * \note On error, this function may return a partial list in \p cur.
350 * You must set `cur->next = NULL` before calling this function!
351 * Otherwise it is impossible to distinguish a previously non-null
352 * pointer from a pointer to an object allocated by this function.
Paul Bakkerefc30292011-11-10 14:43:23 +0000353 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100354 * \note If the sequence is empty, this function does not modify
355 * \c *cur. If the sequence is valid and non-empty, this
356 * function sets `cur->buf.tag` to \p tag. This allows
357 * callers to distinguish between an empty sequence and
358 * a one-element sequence.
359 *
360 * \param p On entry, \c *p points to the start of the ASN.1 element.
361 * On successful completion, \c *p is equal to \p end.
362 * On error, the value of \c *p is undefined.
363 * \param end End of data.
364 * \param cur A ::mbedtls_asn1_sequence which this function fills.
365 * When this function returns, \c *cur is the head of a linked
366 * list. Each node in this list is allocated with
367 * mbedtls_calloc() apart from \p cur itself, and should
368 * therefore be freed with mbedtls_free().
369 * The list describes the content of the sequence.
370 * The head of the list (i.e. \c *cur itself) describes the
371 * first element, `*cur->next` describes the second element, etc.
372 * For each element, `buf.tag == tag`, `buf.len` is the length
373 * of the content of the content of the element, and `buf.p`
374 * points to the first byte of the content (i.e. immediately
375 * past the length of the element).
376 * Note that list elements may be allocated even on error.
377 * \param tag Each element of the sequence must have this tag.
378 *
379 * \return 0 if successful.
380 * \return #MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains
381 * extra data after a valid SEQUENCE OF \p tag.
Gilles Peskineb5c74a52019-10-30 17:07:02 +0100382 * \return #MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with
383 * an ASN.1 SEQUENCE in which an element has a tag that
384 * is different from \p tag.
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100385 * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
386 * \return An ASN.1 error code if the input does not start with
Gilles Peskineb5c74a52019-10-30 17:07:02 +0100387 * a valid ASN.1 SEQUENCE.
Paul Bakkerefc30292011-11-10 14:43:23 +0000388 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200389int mbedtls_asn1_get_sequence_of( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100390 const unsigned char *end,
391 mbedtls_asn1_sequence *cur,
392 int tag );
Hanno Becker12ae27d2019-09-11 14:20:09 +0100393/**
394 * \brief Free a heap-allocated linked list presentation of
395 * an ASN.1 sequence, including the first element.
396 *
397 * There are two common ways to manage the memory used for the representation
398 * of a parsed ASN.1 sequence:
399 * - Allocate a head node `mbedtls_asn1_sequence *head` with mbedtls_calloc().
400 * Pass this node as the `cur` argument to mbedtls_asn1_get_sequence_of().
401 * When you have finished processing the sequence,
402 * call mbedtls_asn1_sequence_free() on `head`.
403 * - Allocate a head node `mbedtls_asn1_sequence *head` in any manner,
404 * for example on the stack. Make sure that `head->next == NULL`.
405 * Pass `head` as the `cur` argument to mbedtls_asn1_get_sequence_of().
406 * When you have finished processing the sequence,
407 * call mbedtls_asn1_sequence_free() on `head->cur`,
408 * then free `head` itself in the appropriate manner.
409 *
410 * \param seq The address of the first sequence component. This may
411 * be \c NULL, in which case this functions returns
412 * immediately.
413 */
414void mbedtls_asn1_sequence_free( mbedtls_asn1_sequence *seq );
Paul Bakkerefc30292011-11-10 14:43:23 +0000415
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200416#if defined(MBEDTLS_BIGNUM_C)
Paul Bakkerefc30292011-11-10 14:43:23 +0000417/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100418 * \brief Retrieve an integer ASN.1 tag and its value.
Paul Bakkercdda0972013-09-09 12:51:29 +0200419 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000420 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100421 * \param p On entry, \c *p points to the start of the ASN.1 element.
422 * On successful completion, \c *p points to the first byte
423 * beyond the ASN.1 element.
424 * On error, the value of \c *p is undefined.
425 * \param end End of data.
426 * \param X On success, the parsed value.
Paul Bakkerefc30292011-11-10 14:43:23 +0000427 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100428 * \return 0 if successful.
429 * \return An ASN.1 error code if the input does not start with
430 * a valid ASN.1 INTEGER.
431 * \return #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
432 * not fit in an \c int.
433 * \return An MPI error code if the parsed value is too large.
Paul Bakkerefc30292011-11-10 14:43:23 +0000434 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200435int mbedtls_asn1_get_mpi( unsigned char **p,
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100436 const unsigned char *end,
437 mbedtls_mpi *X );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200438#endif /* MBEDTLS_BIGNUM_C */
Paul Bakkerefc30292011-11-10 14:43:23 +0000439
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200440/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200441 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
442 * Updates the pointer to immediately behind the full
443 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200444 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100445 * \param p On entry, \c *p points to the start of the ASN.1 element.
446 * On successful completion, \c *p points to the first byte
447 * beyond the AlgorithmIdentifier element.
448 * On error, the value of \c *p is undefined.
449 * \param end End of data.
450 * \param alg The buffer to receive the OID.
451 * \param params The buffer to receive the parameters.
452 * This is zeroized if there are no parameters.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200453 *
454 * \return 0 if successful or a specific ASN.1 or MPI error code.
455 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200456int mbedtls_asn1_get_alg( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200457 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200458 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200459
460/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200461 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
462 * params.
463 * Updates the pointer to immediately behind the full
464 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200465 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100466 * \param p On entry, \c *p points to the start of the ASN.1 element.
467 * On successful completion, \c *p points to the first byte
468 * beyond the AlgorithmIdentifier element.
469 * On error, the value of \c *p is undefined.
470 * \param end End of data.
471 * \param alg The buffer to receive the OID.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200472 *
473 * \return 0 if successful or a specific ASN.1 or MPI error code.
474 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200475int mbedtls_asn1_get_alg_null( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200476 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200477 mbedtls_asn1_buf *alg );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200478
Paul Bakkere5eae762013-08-26 12:05:14 +0200479/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200480 * \brief Find a specific named_data entry in a sequence or list based on
481 * the OID.
Paul Bakkere5eae762013-08-26 12:05:14 +0200482 *
483 * \param list The list to seek through
484 * \param oid The OID to look for
485 * \param len Size of the OID
486 *
487 * \return NULL if not found, or a pointer to the existing entry.
488 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200489mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list,
Paul Bakkere5eae762013-08-26 12:05:14 +0200490 const char *oid, size_t len );
491
492/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200493 * \brief Free a mbedtls_asn1_named_data entry
Paul Bakkere5eae762013-08-26 12:05:14 +0200494 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100495 * \param entry The named data entry to free.
496 * This function calls mbedtls_free() on
497 * `entry->oid.p` and `entry->val.p`.
Paul Bakkere5eae762013-08-26 12:05:14 +0200498 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200499void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
Paul Bakkere5eae762013-08-26 12:05:14 +0200500
Paul Bakkerc547cc92013-09-09 12:01:23 +0200501/**
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100502 * \brief Free all entries in a mbedtls_asn1_named_data list.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200503 *
Gilles Peskinebcbe1df2019-03-01 17:57:43 +0100504 * \param head Pointer to the head of the list of named data entries to free.
505 * This function calls mbedtls_asn1_free_named_data() and
506 * mbedtls_free() on each list element and
507 * sets \c *head to \c NULL.
Paul Bakkerc547cc92013-09-09 12:01:23 +0200508 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200509void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
Paul Bakkerc547cc92013-09-09 12:01:23 +0200510
Paul Bakkerefc30292011-11-10 14:43:23 +0000511#ifdef __cplusplus
512}
513#endif
514
515#endif /* asn1.h */