blob: fde328a128b197ab9a19649472438843d71a7e1f [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)
Paul Bakkerccdb0282011-12-15 19:49:51 +000028#include "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)
Paul Bakkerccdb0282011-12-15 19:49:51 +000036#include "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. */
55#define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068 /**< Data is invalid. (not used) */
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
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020069 * Such sequences are typically read into \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
78#define MBEDTLS_ASN1_UTF8_STRING 0x0C
79#define MBEDTLS_ASN1_SEQUENCE 0x10
80#define MBEDTLS_ASN1_SET 0x11
81#define MBEDTLS_ASN1_PRINTABLE_STRING 0x13
82#define MBEDTLS_ASN1_T61_STRING 0x14
83#define MBEDTLS_ASN1_IA5_STRING 0x16
84#define MBEDTLS_ASN1_UTC_TIME 0x17
85#define MBEDTLS_ASN1_GENERALIZED_TIME 0x18
86#define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C
87#define MBEDTLS_ASN1_BMP_STRING 0x1E
88#define MBEDTLS_ASN1_PRIMITIVE 0x00
89#define MBEDTLS_ASN1_CONSTRUCTED 0x20
90#define MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80
Paul Bakkerefc30292011-11-10 14:43:23 +000091/* \} name */
92/* \} addtogroup asn1_module */
93
94/** Returns the size of the binary string, without the trailing \\0 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095#define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
Paul Bakkerefc30292011-11-10 14:43:23 +000096
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +010097/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020098 * Compares an mbedtls_asn1_buf structure to a reference OID.
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +010099 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200100 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a
Manuel Pégourié-Gonnarde76b7502014-01-23 19:15:29 +0100101 * 'unsigned char *oid' here!
Paul Bakkere5eae762013-08-26 12:05:14 +0200102 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200103#define MBEDTLS_OID_CMP(oid_str, oid_buf) \
104 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \
Manuel Pégourié-Gonnard6e064372015-03-19 16:54:56 +0000105 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 )
Paul Bakkerc70b9822013-04-07 22:00:46 +0200106
Paul Bakkerefc30292011-11-10 14:43:23 +0000107#ifdef __cplusplus
108extern "C" {
109#endif
110
111/**
112 * \name Functions to parse ASN.1 data structures
113 * \{
114 */
115
116/**
117 * Type-length-value structure that allows for ASN1 using DER.
118 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200119typedef struct mbedtls_asn1_buf
Paul Bakkerefc30292011-11-10 14:43:23 +0000120{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200121 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200122 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000123 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
124}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200125mbedtls_asn1_buf;
Paul Bakkerefc30292011-11-10 14:43:23 +0000126
127/**
128 * Container for ASN1 bit strings.
129 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200130typedef struct mbedtls_asn1_bitstring
Paul Bakkerefc30292011-11-10 14:43:23 +0000131{
Manuel Pégourié-Gonnardb8186a52015-06-18 14:58:58 +0200132 size_t len; /**< ASN1 length, in octets. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000133 unsigned char unused_bits; /**< Number of unused bits at the end of the string */
134 unsigned char *p; /**< Raw ASN1 data for the bit string */
135}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200136mbedtls_asn1_bitstring;
Paul Bakkerefc30292011-11-10 14:43:23 +0000137
138/**
139 * Container for a sequence of ASN.1 items
140 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200141typedef struct mbedtls_asn1_sequence
Paul Bakkerefc30292011-11-10 14:43:23 +0000142{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200143 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
144 struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
Paul Bakkerefc30292011-11-10 14:43:23 +0000145}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200146mbedtls_asn1_sequence;
Paul Bakkerefc30292011-11-10 14:43:23 +0000147
148/**
Paul Bakkere5eae762013-08-26 12:05:14 +0200149 * Container for a sequence or list of 'named' ASN.1 data items
150 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200151typedef struct mbedtls_asn1_named_data
Paul Bakkere5eae762013-08-26 12:05:14 +0200152{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200153 mbedtls_asn1_buf oid; /**< The object identifier. */
154 mbedtls_asn1_buf val; /**< The named value. */
155 struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
Manuel Pégourié-Gonnard555fbf82015-02-04 17:11:55 +0000156 unsigned char next_merged; /**< Merge next item into the current one? */
Paul Bakkere5eae762013-08-26 12:05:14 +0200157}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200158mbedtls_asn1_named_data;
Paul Bakkere5eae762013-08-26 12:05:14 +0200159
160/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200161 * \brief Get the length of an ASN.1 element.
162 * Updates the pointer to immediately behind the length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000163 *
164 * \param p The position in the ASN.1 data
165 * \param end End of data
166 * \param len The variable that will receive the value
167 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200168 * \return 0 if successful, MBEDTLS_ERR_ASN1_OUT_OF_DATA on reaching
169 * end of data, MBEDTLS_ERR_ASN1_INVALID_LENGTH if length is
Paul Bakkerefc30292011-11-10 14:43:23 +0000170 * unparseable.
171 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200172int mbedtls_asn1_get_len( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000173 const unsigned char *end,
174 size_t *len );
175
176/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200177 * \brief Get the tag and length of the tag. Check for the requested tag.
178 * Updates the pointer to immediately behind the tag and length.
Paul Bakkerefc30292011-11-10 14:43:23 +0000179 *
180 * \param p The position in the ASN.1 data
181 * \param end End of data
182 * \param len The variable that will receive the length
183 * \param tag The expected tag
184 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200185 * \return 0 if successful, MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if tag did
Paul Bakkerefc30292011-11-10 14:43:23 +0000186 * not match requested tag, or another specific ASN.1 error code.
187 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200188int mbedtls_asn1_get_tag( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000189 const unsigned char *end,
190 size_t *len, int tag );
191
192/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200193 * \brief Retrieve a boolean ASN.1 tag and its value.
194 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000195 *
196 * \param p The position in the ASN.1 data
197 * \param end End of data
198 * \param val The variable that will receive the value
199 *
200 * \return 0 if successful or a specific ASN.1 error code.
201 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200202int mbedtls_asn1_get_bool( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000203 const unsigned char *end,
204 int *val );
205
206/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200207 * \brief Retrieve an integer ASN.1 tag and its value.
208 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000209 *
210 * \param p The position in the ASN.1 data
211 * \param end End of data
212 * \param val The variable that will receive the value
213 *
214 * \return 0 if successful or a specific ASN.1 error code.
215 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200216int mbedtls_asn1_get_int( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000217 const unsigned char *end,
218 int *val );
219
220/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200221 * \brief Retrieve a bitstring ASN.1 tag and its value.
222 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000223 *
224 * \param p The position in the ASN.1 data
225 * \param end End of data
226 * \param bs The variable that will receive the value
227 *
228 * \return 0 if successful or a specific ASN.1 error code.
229 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200230int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end,
231 mbedtls_asn1_bitstring *bs);
Paul Bakkerefc30292011-11-10 14:43:23 +0000232
233/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200234 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
235 * value.
236 * Updates the pointer to the beginning of the bit/octet string.
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200237 *
238 * \param p The position in the ASN.1 data
239 * \param end End of data
240 * \param len Length of the actual bit/octect string in bytes
241 *
242 * \return 0 if successful or a specific ASN.1 error code.
243 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200244int mbedtls_asn1_get_bitstring_null( unsigned char **p, const unsigned char *end,
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200245 size_t *len );
246
247/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200248 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>"
249 * Updated the pointer to immediately behind the full sequence tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000250 *
251 * \param p The position in the ASN.1 data
252 * \param end End of data
253 * \param cur First variable in the chain to fill
Paul Bakker8b21f7a2012-01-13 13:29:05 +0000254 * \param tag Type of sequence
Paul Bakkerefc30292011-11-10 14:43:23 +0000255 *
256 * \return 0 if successful or a specific ASN.1 error code.
257 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200258int mbedtls_asn1_get_sequence_of( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000259 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200260 mbedtls_asn1_sequence *cur,
Paul Bakkerefc30292011-11-10 14:43:23 +0000261 int tag);
262
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200263#if defined(MBEDTLS_BIGNUM_C)
Paul Bakkerefc30292011-11-10 14:43:23 +0000264/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200265 * \brief Retrieve a MPI value from an integer ASN.1 tag.
266 * Updates the pointer to immediately behind the full tag.
Paul Bakkerefc30292011-11-10 14:43:23 +0000267 *
268 * \param p The position in the ASN.1 data
269 * \param end End of data
270 * \param X The MPI that will receive the value
271 *
272 * \return 0 if successful or a specific ASN.1 or MPI error code.
273 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200274int mbedtls_asn1_get_mpi( unsigned char **p,
Paul Bakkerefc30292011-11-10 14:43:23 +0000275 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200276 mbedtls_mpi *X );
277#endif /* MBEDTLS_BIGNUM_C */
Paul Bakkerefc30292011-11-10 14:43:23 +0000278
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200279/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200280 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
281 * Updates the pointer to immediately behind the full
282 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200283 *
284 * \param p The position in the ASN.1 data
285 * \param end End of data
286 * \param alg The buffer to receive the OID
287 * \param params The buffer to receive the params (if any)
288 *
289 * \return 0 if successful or a specific ASN.1 or MPI error code.
290 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200291int mbedtls_asn1_get_alg( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200292 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200293 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200294
295/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200296 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
297 * params.
298 * Updates the pointer to immediately behind the full
299 * AlgorithmIdentifier.
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200300 *
301 * \param p The position in the ASN.1 data
302 * \param end End of data
303 * \param alg The buffer to receive the OID
304 *
305 * \return 0 if successful or a specific ASN.1 or MPI error code.
306 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200307int mbedtls_asn1_get_alg_null( unsigned char **p,
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200308 const unsigned char *end,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200309 mbedtls_asn1_buf *alg );
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200310
Paul Bakkere5eae762013-08-26 12:05:14 +0200311/**
Paul Bakkercdda0972013-09-09 12:51:29 +0200312 * \brief Find a specific named_data entry in a sequence or list based on
313 * the OID.
Paul Bakkere5eae762013-08-26 12:05:14 +0200314 *
315 * \param list The list to seek through
316 * \param oid The OID to look for
317 * \param len Size of the OID
318 *
319 * \return NULL if not found, or a pointer to the existing entry.
320 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200321mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list,
Paul Bakkere5eae762013-08-26 12:05:14 +0200322 const char *oid, size_t len );
323
324/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200325 * \brief Free a mbedtls_asn1_named_data entry
Paul Bakkere5eae762013-08-26 12:05:14 +0200326 *
327 * \param entry The named data entry to free
328 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200329void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
Paul Bakkere5eae762013-08-26 12:05:14 +0200330
Paul Bakkerc547cc92013-09-09 12:01:23 +0200331/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200332 * \brief Free all entries in a mbedtls_asn1_named_data list
Paul Bakkercdda0972013-09-09 12:51:29 +0200333 * Head will be set to NULL
Paul Bakkerc547cc92013-09-09 12:01:23 +0200334 *
335 * \param head Pointer to the head of the list of named data entries to free
336 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200337void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
Paul Bakkerc547cc92013-09-09 12:01:23 +0200338
Paul Bakkerefc30292011-11-10 14:43:23 +0000339#ifdef __cplusplus
340}
341#endif
342
343#endif /* asn1.h */