1 | /**
|
---|
2 | * \file asn1.h
|
---|
3 | *
|
---|
4 | * \brief Generic ASN.1 parsing
|
---|
5 | */
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
|
---|
8 | * SPDX-License-Identifier: Apache-2.0
|
---|
9 | *
|
---|
10 | * Licensed under the Apache License, Version 2.0 (the "License"); you may
|
---|
11 | * not use this file except in compliance with the License.
|
---|
12 | * You may obtain a copy of the License at
|
---|
13 | *
|
---|
14 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
15 | *
|
---|
16 | * Unless required by applicable law or agreed to in writing, software
|
---|
17 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
---|
18 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
19 | * See the License for the specific language governing permissions and
|
---|
20 | * limitations under the License.
|
---|
21 | *
|
---|
22 | * This file is part of mbed TLS (https://tls.mbed.org)
|
---|
23 | */
|
---|
24 | #ifndef MBEDTLS_ASN1_H
|
---|
25 | #define MBEDTLS_ASN1_H
|
---|
26 |
|
---|
27 | #if !defined(MBEDTLS_CONFIG_FILE)
|
---|
28 | #include "config.h"
|
---|
29 | #else
|
---|
30 | #include MBEDTLS_CONFIG_FILE
|
---|
31 | #endif
|
---|
32 |
|
---|
33 | #include <stddef.h>
|
---|
34 |
|
---|
35 | #if defined(MBEDTLS_BIGNUM_C)
|
---|
36 | #include "bignum.h"
|
---|
37 | #endif
|
---|
38 |
|
---|
39 | /**
|
---|
40 | * \addtogroup asn1_module
|
---|
41 | * \{
|
---|
42 | */
|
---|
43 |
|
---|
44 | /**
|
---|
45 | * \name ASN1 Error codes
|
---|
46 | * These error codes are OR'ed to X509 error codes for
|
---|
47 | * higher error granularity.
|
---|
48 | * ASN1 is a standard to specify data structures.
|
---|
49 | * \{
|
---|
50 | */
|
---|
51 | #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) */
|
---|
56 | #define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A /**< Memory allocation failed */
|
---|
57 | #define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C /**< Buffer too small when writing ASN.1 data structure. */
|
---|
58 |
|
---|
59 | /* \} name */
|
---|
60 |
|
---|
61 | /**
|
---|
62 | * \name DER constants
|
---|
63 | * These constants comply with the DER encoded ASN.1 type tags.
|
---|
64 | * 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
|
---|
69 | * Such sequences are typically read into \c ::mbedtls_x509_buf.
|
---|
70 | * \{
|
---|
71 | */
|
---|
72 | #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
|
---|
91 |
|
---|
92 | /*
|
---|
93 | * Bit masks for each of the components of an ASN.1 tag as specified in
|
---|
94 | * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
|
---|
95 | * paragraph 8.1.2.2:
|
---|
96 | *
|
---|
97 | * Bit 8 7 6 5 1
|
---|
98 | * +-------+-----+------------+
|
---|
99 | * | Class | P/C | Tag number |
|
---|
100 | * +-------+-----+------------+
|
---|
101 | */
|
---|
102 | #define MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
|
---|
103 | #define MBEDTLS_ASN1_TAG_PC_MASK 0x20
|
---|
104 | #define MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F
|
---|
105 |
|
---|
106 | /* \} name */
|
---|
107 | /* \} addtogroup asn1_module */
|
---|
108 |
|
---|
109 | /** Returns the size of the binary string, without the trailing \\0 */
|
---|
110 | #define MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
|
---|
111 |
|
---|
112 | /**
|
---|
113 | * Compares an mbedtls_asn1_buf structure to a reference OID.
|
---|
114 | *
|
---|
115 | * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a
|
---|
116 | * 'unsigned char *oid' here!
|
---|
117 | */
|
---|
118 | #define MBEDTLS_OID_CMP(oid_str, oid_buf) \
|
---|
119 | ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \
|
---|
120 | memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 )
|
---|
121 |
|
---|
122 | #ifdef __cplusplus
|
---|
123 | extern "C" {
|
---|
124 | #endif
|
---|
125 |
|
---|
126 | /**
|
---|
127 | * \name Functions to parse ASN.1 data structures
|
---|
128 | * \{
|
---|
129 | */
|
---|
130 |
|
---|
131 | /**
|
---|
132 | * Type-length-value structure that allows for ASN1 using DER.
|
---|
133 | */
|
---|
134 | typedef struct mbedtls_asn1_buf
|
---|
135 | {
|
---|
136 | int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */
|
---|
137 | size_t len; /**< ASN1 length, in octets. */
|
---|
138 | unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
|
---|
139 | }
|
---|
140 | mbedtls_asn1_buf;
|
---|
141 |
|
---|
142 | /**
|
---|
143 | * Container for ASN1 bit strings.
|
---|
144 | */
|
---|
145 | typedef struct mbedtls_asn1_bitstring
|
---|
146 | {
|
---|
147 | size_t len; /**< ASN1 length, in octets. */
|
---|
148 | unsigned char unused_bits; /**< Number of unused bits at the end of the string */
|
---|
149 | unsigned char *p; /**< Raw ASN1 data for the bit string */
|
---|
150 | }
|
---|
151 | mbedtls_asn1_bitstring;
|
---|
152 |
|
---|
153 | /**
|
---|
154 | * Container for a sequence of ASN.1 items
|
---|
155 | */
|
---|
156 | typedef struct mbedtls_asn1_sequence
|
---|
157 | {
|
---|
158 | mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
|
---|
159 | struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */
|
---|
160 | }
|
---|
161 | mbedtls_asn1_sequence;
|
---|
162 |
|
---|
163 | /**
|
---|
164 | * Container for a sequence or list of 'named' ASN.1 data items
|
---|
165 | */
|
---|
166 | typedef struct mbedtls_asn1_named_data
|
---|
167 | {
|
---|
168 | mbedtls_asn1_buf oid; /**< The object identifier. */
|
---|
169 | mbedtls_asn1_buf val; /**< The named value. */
|
---|
170 | struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */
|
---|
171 | unsigned char next_merged; /**< Merge next item into the current one? */
|
---|
172 | }
|
---|
173 | mbedtls_asn1_named_data;
|
---|
174 |
|
---|
175 | /**
|
---|
176 | * \brief Get the length of an ASN.1 element.
|
---|
177 | * Updates the pointer to immediately behind the length.
|
---|
178 | *
|
---|
179 | * \param p The position in the ASN.1 data
|
---|
180 | * \param end End of data
|
---|
181 | * \param len The variable that will receive the value
|
---|
182 | *
|
---|
183 | * \return 0 if successful, MBEDTLS_ERR_ASN1_OUT_OF_DATA on reaching
|
---|
184 | * end of data, MBEDTLS_ERR_ASN1_INVALID_LENGTH if length is
|
---|
185 | * unparseable.
|
---|
186 | */
|
---|
187 | int mbedtls_asn1_get_len( unsigned char **p,
|
---|
188 | const unsigned char *end,
|
---|
189 | size_t *len );
|
---|
190 |
|
---|
191 | /**
|
---|
192 | * \brief Get the tag and length of the tag. Check for the requested tag.
|
---|
193 | * Updates the pointer to immediately behind the tag and length.
|
---|
194 | *
|
---|
195 | * \param p The position in the ASN.1 data
|
---|
196 | * \param end End of data
|
---|
197 | * \param len The variable that will receive the length
|
---|
198 | * \param tag The expected tag
|
---|
199 | *
|
---|
200 | * \return 0 if successful, MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if tag did
|
---|
201 | * not match requested tag, or another specific ASN.1 error code.
|
---|
202 | */
|
---|
203 | int mbedtls_asn1_get_tag( unsigned char **p,
|
---|
204 | const unsigned char *end,
|
---|
205 | size_t *len, int tag );
|
---|
206 |
|
---|
207 | /**
|
---|
208 | * \brief Retrieve a boolean ASN.1 tag and its value.
|
---|
209 | * Updates the pointer to immediately behind the full tag.
|
---|
210 | *
|
---|
211 | * \param p The position in the ASN.1 data
|
---|
212 | * \param end End of data
|
---|
213 | * \param val The variable that will receive the value
|
---|
214 | *
|
---|
215 | * \return 0 if successful or a specific ASN.1 error code.
|
---|
216 | */
|
---|
217 | int mbedtls_asn1_get_bool( unsigned char **p,
|
---|
218 | const unsigned char *end,
|
---|
219 | int *val );
|
---|
220 |
|
---|
221 | /**
|
---|
222 | * \brief Retrieve an integer ASN.1 tag and its value.
|
---|
223 | * Updates the pointer to immediately behind the full tag.
|
---|
224 | *
|
---|
225 | * \param p The position in the ASN.1 data
|
---|
226 | * \param end End of data
|
---|
227 | * \param val The variable that will receive the value
|
---|
228 | *
|
---|
229 | * \return 0 if successful or a specific ASN.1 error code.
|
---|
230 | */
|
---|
231 | int mbedtls_asn1_get_int( unsigned char **p,
|
---|
232 | const unsigned char *end,
|
---|
233 | int *val );
|
---|
234 |
|
---|
235 | /**
|
---|
236 | * \brief Retrieve a bitstring ASN.1 tag and its value.
|
---|
237 | * Updates the pointer to immediately behind the full tag.
|
---|
238 | *
|
---|
239 | * \param p The position in the ASN.1 data
|
---|
240 | * \param end End of data
|
---|
241 | * \param bs The variable that will receive the value
|
---|
242 | *
|
---|
243 | * \return 0 if successful or a specific ASN.1 error code.
|
---|
244 | */
|
---|
245 | int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end,
|
---|
246 | mbedtls_asn1_bitstring *bs);
|
---|
247 |
|
---|
248 | /**
|
---|
249 | * \brief Retrieve a bitstring ASN.1 tag without unused bits and its
|
---|
250 | * value.
|
---|
251 | * Updates the pointer to the beginning of the bit/octet string.
|
---|
252 | *
|
---|
253 | * \param p The position in the ASN.1 data
|
---|
254 | * \param end End of data
|
---|
255 | * \param len Length of the actual bit/octect string in bytes
|
---|
256 | *
|
---|
257 | * \return 0 if successful or a specific ASN.1 error code.
|
---|
258 | */
|
---|
259 | int mbedtls_asn1_get_bitstring_null( unsigned char **p, const unsigned char *end,
|
---|
260 | size_t *len );
|
---|
261 |
|
---|
262 | /**
|
---|
263 | * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>"
|
---|
264 | * Updated the pointer to immediately behind the full sequence tag.
|
---|
265 | *
|
---|
266 | * \param p The position in the ASN.1 data
|
---|
267 | * \param end End of data
|
---|
268 | * \param cur First variable in the chain to fill
|
---|
269 | * \param tag Type of sequence
|
---|
270 | *
|
---|
271 | * \return 0 if successful or a specific ASN.1 error code.
|
---|
272 | */
|
---|
273 | int mbedtls_asn1_get_sequence_of( unsigned char **p,
|
---|
274 | const unsigned char *end,
|
---|
275 | mbedtls_asn1_sequence *cur,
|
---|
276 | int tag);
|
---|
277 |
|
---|
278 | #if defined(MBEDTLS_BIGNUM_C)
|
---|
279 | /**
|
---|
280 | * \brief Retrieve a MPI value from an integer ASN.1 tag.
|
---|
281 | * Updates the pointer to immediately behind the full tag.
|
---|
282 | *
|
---|
283 | * \param p The position in the ASN.1 data
|
---|
284 | * \param end End of data
|
---|
285 | * \param X The MPI that will receive the value
|
---|
286 | *
|
---|
287 | * \return 0 if successful or a specific ASN.1 or MPI error code.
|
---|
288 | */
|
---|
289 | int mbedtls_asn1_get_mpi( unsigned char **p,
|
---|
290 | const unsigned char *end,
|
---|
291 | mbedtls_mpi *X );
|
---|
292 | #endif /* MBEDTLS_BIGNUM_C */
|
---|
293 |
|
---|
294 | /**
|
---|
295 | * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence.
|
---|
296 | * Updates the pointer to immediately behind the full
|
---|
297 | * AlgorithmIdentifier.
|
---|
298 | *
|
---|
299 | * \param p The position in the ASN.1 data
|
---|
300 | * \param end End of data
|
---|
301 | * \param alg The buffer to receive the OID
|
---|
302 | * \param params The buffer to receive the params (if any)
|
---|
303 | *
|
---|
304 | * \return 0 if successful or a specific ASN.1 or MPI error code.
|
---|
305 | */
|
---|
306 | int mbedtls_asn1_get_alg( unsigned char **p,
|
---|
307 | const unsigned char *end,
|
---|
308 | mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params );
|
---|
309 |
|
---|
310 | /**
|
---|
311 | * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no
|
---|
312 | * params.
|
---|
313 | * Updates the pointer to immediately behind the full
|
---|
314 | * AlgorithmIdentifier.
|
---|
315 | *
|
---|
316 | * \param p The position in the ASN.1 data
|
---|
317 | * \param end End of data
|
---|
318 | * \param alg The buffer to receive the OID
|
---|
319 | *
|
---|
320 | * \return 0 if successful or a specific ASN.1 or MPI error code.
|
---|
321 | */
|
---|
322 | int mbedtls_asn1_get_alg_null( unsigned char **p,
|
---|
323 | const unsigned char *end,
|
---|
324 | mbedtls_asn1_buf *alg );
|
---|
325 |
|
---|
326 | /**
|
---|
327 | * \brief Find a specific named_data entry in a sequence or list based on
|
---|
328 | * the OID.
|
---|
329 | *
|
---|
330 | * \param list The list to seek through
|
---|
331 | * \param oid The OID to look for
|
---|
332 | * \param len Size of the OID
|
---|
333 | *
|
---|
334 | * \return NULL if not found, or a pointer to the existing entry.
|
---|
335 | */
|
---|
336 | mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list,
|
---|
337 | const char *oid, size_t len );
|
---|
338 |
|
---|
339 | /**
|
---|
340 | * \brief Free a mbedtls_asn1_named_data entry
|
---|
341 | *
|
---|
342 | * \param entry The named data entry to free
|
---|
343 | */
|
---|
344 | void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry );
|
---|
345 |
|
---|
346 | /**
|
---|
347 | * \brief Free all entries in a mbedtls_asn1_named_data list
|
---|
348 | * Head will be set to NULL
|
---|
349 | *
|
---|
350 | * \param head Pointer to the head of the list of named data entries to free
|
---|
351 | */
|
---|
352 | void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head );
|
---|
353 |
|
---|
354 | #ifdef __cplusplus
|
---|
355 | }
|
---|
356 | #endif
|
---|
357 |
|
---|
358 | #endif /* asn1.h */
|
---|