blob: 86a1bc8c14fde38d02aa136e7e766afaeacfcd0f [file] [log] [blame]
Paul Bakkerefc30292011-11-10 14:43:23 +00001/**
2 * \file asn1.h
3 *
4 * \brief Generic ASN.1 parsing
5 *
Paul Bakker407a0da2013-06-27 14:29:21 +02006 * Copyright (C) 2006-2013, Brainspark B.V.
Paul Bakkerefc30292011-11-10 14:43:23 +00007 *
8 * This file is part of PolarSSL (http://www.polarssl.org)
9 * Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License along
24 * with this program; if not, write to the Free Software Foundation, Inc.,
25 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 */
27#ifndef POLARSSL_ASN1_H
28#define POLARSSL_ASN1_H
29
Paul Bakkerccdb0282011-12-15 19:49:51 +000030#include "config.h"
Paul Bakkerefc30292011-11-10 14:43:23 +000031
32#if defined(POLARSSL_BIGNUM_C)
Paul Bakkerccdb0282011-12-15 19:49:51 +000033#include "bignum.h"
Paul Bakkerefc30292011-11-10 14:43:23 +000034#endif
35
36#include <string.h>
37
38/**
39 * \addtogroup asn1_module
40 * \{
41 */
42
43/**
44 * \name ASN1 Error codes
45 * These error codes are OR'ed to X509 error codes for
46 * higher error granularity.
47 * ASN1 is a standard to specify data structures.
48 * \{
49 */
Paul Bakkerbdb912d2012-02-13 23:11:30 +000050#define POLARSSL_ERR_ASN1_OUT_OF_DATA -0x0060 /**< Out of data when parsing an ASN1 data structure. */
51#define POLARSSL_ERR_ASN1_UNEXPECTED_TAG -0x0062 /**< ASN1 tag was of an unexpected value. */
52#define POLARSSL_ERR_ASN1_INVALID_LENGTH -0x0064 /**< Error when trying to determine the length or invalid length. */
53#define POLARSSL_ERR_ASN1_LENGTH_MISMATCH -0x0066 /**< Actual length differs from expected length. */
54#define POLARSSL_ERR_ASN1_INVALID_DATA -0x0068 /**< Data is invalid. (not used) */
55#define POLARSSL_ERR_ASN1_MALLOC_FAILED -0x006A /**< Memory allocation failed */
Paul Bakker05888152012-02-16 10:26:57 +000056#define POLARSSL_ERR_ASN1_BUF_TOO_SMALL -0x006C /**< Buffer too small when writing ASN.1 data structure. */
57
Paul Bakkerefc30292011-11-10 14:43:23 +000058/* \} name */
59
60/**
61 * \name DER constants
62 * These constants comply with DER encoded the ANS1 type tags.
63 * DER encoding uses hexadecimal representation.
64 * An example DER sequence is:\n
65 * - 0x02 -- tag indicating INTEGER
66 * - 0x01 -- length in octets
67 * - 0x05 -- value
68 * Such sequences are typically read into \c ::x509_buf.
69 * \{
70 */
71#define ASN1_BOOLEAN 0x01
72#define ASN1_INTEGER 0x02
73#define ASN1_BIT_STRING 0x03
74#define ASN1_OCTET_STRING 0x04
75#define ASN1_NULL 0x05
76#define ASN1_OID 0x06
77#define ASN1_UTF8_STRING 0x0C
78#define ASN1_SEQUENCE 0x10
79#define ASN1_SET 0x11
80#define ASN1_PRINTABLE_STRING 0x13
81#define ASN1_T61_STRING 0x14
82#define ASN1_IA5_STRING 0x16
83#define ASN1_UTC_TIME 0x17
84#define ASN1_GENERALIZED_TIME 0x18
85#define ASN1_UNIVERSAL_STRING 0x1C
86#define ASN1_BMP_STRING 0x1E
87#define ASN1_PRIMITIVE 0x00
88#define ASN1_CONSTRUCTED 0x20
89#define ASN1_CONTEXT_SPECIFIC 0x80
90/* \} name */
91/* \} addtogroup asn1_module */
92
93/** Returns the size of the binary string, without the trailing \\0 */
94#define OID_SIZE(x) (sizeof(x) - 1)
95
Paul Bakkere5eae762013-08-26 12:05:14 +020096/** Compares two asn1_buf structures for the same OID. Only works for
97 * 'defined' oid_str values (OID_HMAC_SHA1), you cannot use a 'unsigned
98 * char *oid' here!
99 */
Paul Bakkerc70b9822013-04-07 22:00:46 +0200100#define OID_CMP(oid_str, oid_buf) \
101 ( ( OID_SIZE(oid_str) == (oid_buf)->len ) && \
102 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) == 0 )
103
Paul Bakkerefc30292011-11-10 14:43:23 +0000104#ifdef __cplusplus
105extern "C" {
106#endif
107
108/**
109 * \name Functions to parse ASN.1 data structures
110 * \{
111 */
112
113/**
114 * Type-length-value structure that allows for ASN1 using DER.
115 */
116typedef struct _asn1_buf
117{
118 int tag; /**< ASN1 type, e.g. ASN1_UTF8_STRING. */
119 size_t len; /**< ASN1 length, e.g. in octets. */
120 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */
121}
122asn1_buf;
123
124/**
125 * Container for ASN1 bit strings.
126 */
127typedef struct _asn1_bitstring
128{
129 size_t len; /**< ASN1 length, e.g. in octets. */
130 unsigned char unused_bits; /**< Number of unused bits at the end of the string */
131 unsigned char *p; /**< Raw ASN1 data for the bit string */
132}
133asn1_bitstring;
134
135/**
136 * Container for a sequence of ASN.1 items
137 */
138typedef struct _asn1_sequence
139{
140 asn1_buf buf; /**< Buffer containing the given ASN.1 item. */
141 struct _asn1_sequence *next; /**< The next entry in the sequence. */
142}
143asn1_sequence;
144
145/**
Paul Bakkere5eae762013-08-26 12:05:14 +0200146 * Container for a sequence or list of 'named' ASN.1 data items
147 */
148typedef struct _asn1_named_data
149{
150 asn1_buf oid; /**< The object identifier. */
151 asn1_buf val; /**< The named value. */
152 struct _asn1_named_data *next; /**< The next entry in the sequence. */
153}
154asn1_named_data;
155
156/**
Paul Bakkerefc30292011-11-10 14:43:23 +0000157 * Get the length of an ASN.1 element.
158 * Updates the pointer to immediately behind the length.
159 *
160 * \param p The position in the ASN.1 data
161 * \param end End of data
162 * \param len The variable that will receive the value
163 *
164 * \return 0 if successful, POLARSSL_ERR_ASN1_OUT_OF_DATA on reaching
165 * end of data, POLARSSL_ERR_ASN1_INVALID_LENGTH if length is
166 * unparseable.
167 */
168int asn1_get_len( unsigned char **p,
169 const unsigned char *end,
170 size_t *len );
171
172/**
173 * Get the tag and length of the tag. Check for the requested tag.
174 * Updates the pointer to immediately behind the tag and length.
175 *
176 * \param p The position in the ASN.1 data
177 * \param end End of data
178 * \param len The variable that will receive the length
179 * \param tag The expected tag
180 *
181 * \return 0 if successful, POLARSSL_ERR_ASN1_UNEXPECTED_TAG if tag did
182 * not match requested tag, or another specific ASN.1 error code.
183 */
184int asn1_get_tag( unsigned char **p,
185 const unsigned char *end,
186 size_t *len, int tag );
187
188/**
189 * Retrieve a boolean ASN.1 tag and its value.
190 * Updates the pointer to immediately behind the full tag.
191 *
192 * \param p The position in the ASN.1 data
193 * \param end End of data
194 * \param val The variable that will receive the value
195 *
196 * \return 0 if successful or a specific ASN.1 error code.
197 */
198int asn1_get_bool( unsigned char **p,
199 const unsigned char *end,
200 int *val );
201
202/**
203 * Retrieve an integer ASN.1 tag and its value.
204 * Updates the pointer to immediately behind the full tag.
205 *
206 * \param p The position in the ASN.1 data
207 * \param end End of data
208 * \param val The variable that will receive the value
209 *
210 * \return 0 if successful or a specific ASN.1 error code.
211 */
212int asn1_get_int( unsigned char **p,
213 const unsigned char *end,
214 int *val );
215
216/**
217 * Retrieve a bitstring ASN.1 tag and its value.
218 * Updates the pointer to immediately behind the full tag.
219 *
220 * \param p The position in the ASN.1 data
221 * \param end End of data
222 * \param bs The variable that will receive the value
223 *
224 * \return 0 if successful or a specific ASN.1 error code.
225 */
226int asn1_get_bitstring( unsigned char **p, const unsigned char *end,
227 asn1_bitstring *bs);
228
229/**
Manuel Pégourié-Gonnarda2d4e642013-07-11 13:59:02 +0200230 * Retrieve a bitstring ASN.1 tag without unused bits and its value.
231 * Updates the pointer to the beginning of the bit/octet string.
232 *
233 * \param p The position in the ASN.1 data
234 * \param end End of data
235 * \param len Length of the actual bit/octect string in bytes
236 *
237 * \return 0 if successful or a specific ASN.1 error code.
238 */
239int asn1_get_bitstring_null( unsigned char **p, const unsigned char *end,
240 size_t *len );
241
242/**
Paul Bakkerefc30292011-11-10 14:43:23 +0000243 * Parses and splits an ASN.1 "SEQUENCE OF <tag>"
244 * Updated the pointer to immediately behind the full sequence tag.
245 *
246 * \param p The position in the ASN.1 data
247 * \param end End of data
248 * \param cur First variable in the chain to fill
Paul Bakker8b21f7a2012-01-13 13:29:05 +0000249 * \param tag Type of sequence
Paul Bakkerefc30292011-11-10 14:43:23 +0000250 *
251 * \return 0 if successful or a specific ASN.1 error code.
252 */
253int asn1_get_sequence_of( unsigned char **p,
254 const unsigned char *end,
255 asn1_sequence *cur,
256 int tag);
257
258#if defined(POLARSSL_BIGNUM_C)
259/**
260 * Retrieve a MPI value from an integer ASN.1 tag.
261 * Updates the pointer to immediately behind the full tag.
262 *
263 * \param p The position in the ASN.1 data
264 * \param end End of data
265 * \param X The MPI that will receive the value
266 *
267 * \return 0 if successful or a specific ASN.1 or MPI error code.
268 */
269int asn1_get_mpi( unsigned char **p,
270 const unsigned char *end,
271 mpi *X );
272#endif
273
Paul Bakkerf8d018a2013-06-29 12:16:17 +0200274/**
275 * Retrieve an AlgorithmIdentifier ASN.1 sequence.
276 * Updates the pointer to immediately behind the full AlgorithmIdentifier.
277 *
278 * \param p The position in the ASN.1 data
279 * \param end End of data
280 * \param alg The buffer to receive the OID
281 * \param params The buffer to receive the params (if any)
282 *
283 * \return 0 if successful or a specific ASN.1 or MPI error code.
284 */
285int asn1_get_alg( unsigned char **p,
286 const unsigned char *end,
287 asn1_buf *alg, asn1_buf *params );
288
289/**
290 * Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no params.
291 * Updates the pointer to immediately behind the full AlgorithmIdentifier.
292 *
293 * \param p The position in the ASN.1 data
294 * \param end End of data
295 * \param alg The buffer to receive the OID
296 *
297 * \return 0 if successful or a specific ASN.1 or MPI error code.
298 */
299int asn1_get_alg_null( unsigned char **p,
300 const unsigned char *end,
301 asn1_buf *alg );
302
Paul Bakkere5eae762013-08-26 12:05:14 +0200303/**
304 * Find a specific named_data entry in a sequence or list based on the OID.
305 *
306 * \param list The list to seek through
307 * \param oid The OID to look for
308 * \param len Size of the OID
309 *
310 * \return NULL if not found, or a pointer to the existing entry.
311 */
312asn1_named_data *asn1_find_named_data( asn1_named_data *list,
313 const char *oid, size_t len );
314
315/**
316 * Free a asn1_named_data entry
317 *
318 * \param entry The named data entry to free
319 */
320void asn1_free_named_data( asn1_named_data *entry );
321
Paul Bakkerc547cc92013-09-09 12:01:23 +0200322/**
323 * Free all entries in a asn1_named_data list
324 * Head will be set to NULL
325 *
326 * \param head Pointer to the head of the list of named data entries to free
327 */
328void asn1_free_named_data_list( asn1_named_data **head );
329
Paul Bakkerefc30292011-11-10 14:43:23 +0000330#ifdef __cplusplus
331}
332#endif
333
334#endif /* asn1.h */