1 /** 2 * \file asn1.h 3 * 4 * \brief Generic ASN.1 parsing 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_ASN1_H 24 #define MBEDTLS_ASN1_H 25 26 #if !defined(MBEDTLS_CONFIG_FILE) 27 #include "config.h" 28 #else 29 #include MBEDTLS_CONFIG_FILE 30 #endif 31 32 #include <stddef.h> 33 34 #if defined(MBEDTLS_BIGNUM_C) 35 #include "bignum.h" 36 #endif 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 */ 50 #define MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060 /**< Out of data when parsing an ASN1 data structure. */ 51 #define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062 /**< ASN1 tag was of an unexpected value. */ 52 #define MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064 /**< Error when trying to determine the length or invalid length. */ 53 #define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066 /**< Actual length differs from expected length. */ 54 #define MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068 /**< Data is invalid. (not used) */ 55 #define MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A /**< Memory allocation failed */ 56 #define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C /**< Buffer too small when writing ASN.1 data structure. */ 57 58 /* \} 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 ::mbedtls_x509_buf. 69 * \{ 70 */ 71 #define MBEDTLS_ASN1_BOOLEAN 0x01 72 #define MBEDTLS_ASN1_INTEGER 0x02 73 #define MBEDTLS_ASN1_BIT_STRING 0x03 74 #define MBEDTLS_ASN1_OCTET_STRING 0x04 75 #define MBEDTLS_ASN1_NULL 0x05 76 #define MBEDTLS_ASN1_OID 0x06 77 #define MBEDTLS_ASN1_UTF8_STRING 0x0C 78 #define MBEDTLS_ASN1_SEQUENCE 0x10 79 #define MBEDTLS_ASN1_SET 0x11 80 #define MBEDTLS_ASN1_PRINTABLE_STRING 0x13 81 #define MBEDTLS_ASN1_T61_STRING 0x14 82 #define MBEDTLS_ASN1_IA5_STRING 0x16 83 #define MBEDTLS_ASN1_UTC_TIME 0x17 84 #define MBEDTLS_ASN1_GENERALIZED_TIME 0x18 85 #define MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C 86 #define MBEDTLS_ASN1_BMP_STRING 0x1E 87 #define MBEDTLS_ASN1_PRIMITIVE 0x00 88 #define MBEDTLS_ASN1_CONSTRUCTED 0x20 89 #define MBEDTLS_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 MBEDTLS_OID_SIZE(x) (sizeof(x) - 1) 95 96 /** 97 * Compares an mbedtls_asn1_buf structure to a reference OID. 98 * 99 * Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a 100 * 'unsigned char *oid' here! 101 */ 102 #define MBEDTLS_OID_CMP(oid_str, oid_buf) \ 103 ( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \ 104 memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 ) 105 106 #ifdef __cplusplus 107 extern "C" { 108 #endif 109 110 /** 111 * \name Functions to parse ASN.1 data structures 112 * \{ 113 */ 114 115 /** 116 * Type-length-value structure that allows for ASN1 using DER. 117 */ 118 typedef struct mbedtls_asn1_buf 119 { 120 int tag; /**< ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING. */ 121 size_t len; /**< ASN1 length, in octets. */ 122 unsigned char *p; /**< ASN1 data, e.g. in ASCII. */ 123 } 124 mbedtls_asn1_buf; 125 126 /** 127 * Container for ASN1 bit strings. 128 */ 129 typedef struct mbedtls_asn1_bitstring 130 { 131 size_t len; /**< ASN1 length, in octets. */ 132 unsigned char unused_bits; /**< Number of unused bits at the end of the string */ 133 unsigned char *p; /**< Raw ASN1 data for the bit string */ 134 } 135 mbedtls_asn1_bitstring; 136 137 /** 138 * Container for a sequence of ASN.1 items 139 */ 140 typedef struct mbedtls_asn1_sequence 141 { 142 mbedtls_asn1_buf buf; /**< Buffer containing the given ASN.1 item. */ 143 struct mbedtls_asn1_sequence *next; /**< The next entry in the sequence. */ 144 } 145 mbedtls_asn1_sequence; 146 147 /** 148 * Container for a sequence or list of 'named' ASN.1 data items 149 */ 150 typedef struct mbedtls_asn1_named_data 151 { 152 mbedtls_asn1_buf oid; /**< The object identifier. */ 153 mbedtls_asn1_buf val; /**< The named value. */ 154 struct mbedtls_asn1_named_data *next; /**< The next entry in the sequence. */ 155 unsigned char next_merged; /**< Merge next item into the current one? */ 156 } 157 mbedtls_asn1_named_data; 158 159 /** 160 * \brief Get the length of an ASN.1 element. 161 * Updates the pointer to immediately behind the length. 162 * 163 * \param p The position in the ASN.1 data 164 * \param end End of data 165 * \param len The variable that will receive the value 166 * 167 * \return 0 if successful, MBEDTLS_ERR_ASN1_OUT_OF_DATA on reaching 168 * end of data, MBEDTLS_ERR_ASN1_INVALID_LENGTH if length is 169 * unparseable. 170 */ 171 int mbedtls_asn1_get_len( unsigned char **p, 172 const unsigned char *end, 173 size_t *len ); 174 175 /** 176 * \brief Get the tag and length of the tag. Check for the requested tag. 177 * Updates the pointer to immediately behind the tag and 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 length 182 * \param tag The expected tag 183 * 184 * \return 0 if successful, MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if tag did 185 * not match requested tag, or another specific ASN.1 error code. 186 */ 187 int mbedtls_asn1_get_tag( unsigned char **p, 188 const unsigned char *end, 189 size_t *len, int tag ); 190 191 /** 192 * \brief Retrieve a boolean ASN.1 tag and its value. 193 * Updates the pointer to immediately behind the full tag. 194 * 195 * \param p The position in the ASN.1 data 196 * \param end End of data 197 * \param val The variable that will receive the value 198 * 199 * \return 0 if successful or a specific ASN.1 error code. 200 */ 201 int mbedtls_asn1_get_bool( unsigned char **p, 202 const unsigned char *end, 203 int *val ); 204 205 /** 206 * \brief Retrieve an integer ASN.1 tag and its value. 207 * Updates the pointer to immediately behind the full tag. 208 * 209 * \param p The position in the ASN.1 data 210 * \param end End of data 211 * \param val The variable that will receive the value 212 * 213 * \return 0 if successful or a specific ASN.1 error code. 214 */ 215 int mbedtls_asn1_get_int( unsigned char **p, 216 const unsigned char *end, 217 int *val ); 218 219 /** 220 * \brief Retrieve a bitstring ASN.1 tag and its value. 221 * Updates the pointer to immediately behind the full tag. 222 * 223 * \param p The position in the ASN.1 data 224 * \param end End of data 225 * \param bs The variable that will receive the value 226 * 227 * \return 0 if successful or a specific ASN.1 error code. 228 */ 229 int mbedtls_asn1_get_bitstring( unsigned char **p, const unsigned char *end, 230 mbedtls_asn1_bitstring *bs); 231 232 /** 233 * \brief Retrieve a bitstring ASN.1 tag without unused bits and its 234 * value. 235 * Updates the pointer to the beginning of the bit/octet string. 236 * 237 * \param p The position in the ASN.1 data 238 * \param end End of data 239 * \param len Length of the actual bit/octect string in bytes 240 * 241 * \return 0 if successful or a specific ASN.1 error code. 242 */ 243 int mbedtls_asn1_get_bitstring_null( unsigned char **p, const unsigned char *end, 244 size_t *len ); 245 246 /** 247 * \brief Parses and splits an ASN.1 "SEQUENCE OF <tag>" 248 * Updated the pointer to immediately behind the full sequence tag. 249 * 250 * \param p The position in the ASN.1 data 251 * \param end End of data 252 * \param cur First variable in the chain to fill 253 * \param tag Type of sequence 254 * 255 * \return 0 if successful or a specific ASN.1 error code. 256 */ 257 int mbedtls_asn1_get_sequence_of( unsigned char **p, 258 const unsigned char *end, 259 mbedtls_asn1_sequence *cur, 260 int tag); 261 262 #if defined(MBEDTLS_BIGNUM_C) 263 /** 264 * \brief Retrieve a MPI value from an integer ASN.1 tag. 265 * Updates the pointer to immediately behind the full tag. 266 * 267 * \param p The position in the ASN.1 data 268 * \param end End of data 269 * \param X The MPI that will receive the value 270 * 271 * \return 0 if successful or a specific ASN.1 or MPI error code. 272 */ 273 int mbedtls_asn1_get_mpi( unsigned char **p, 274 const unsigned char *end, 275 mbedtls_mpi *X ); 276 #endif /* MBEDTLS_BIGNUM_C */ 277 278 /** 279 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence. 280 * Updates the pointer to immediately behind the full 281 * AlgorithmIdentifier. 282 * 283 * \param p The position in the ASN.1 data 284 * \param end End of data 285 * \param alg The buffer to receive the OID 286 * \param params The buffer to receive the params (if any) 287 * 288 * \return 0 if successful or a specific ASN.1 or MPI error code. 289 */ 290 int mbedtls_asn1_get_alg( unsigned char **p, 291 const unsigned char *end, 292 mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params ); 293 294 /** 295 * \brief Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no 296 * params. 297 * Updates the pointer to immediately behind the full 298 * AlgorithmIdentifier. 299 * 300 * \param p The position in the ASN.1 data 301 * \param end End of data 302 * \param alg The buffer to receive the OID 303 * 304 * \return 0 if successful or a specific ASN.1 or MPI error code. 305 */ 306 int mbedtls_asn1_get_alg_null( unsigned char **p, 307 const unsigned char *end, 308 mbedtls_asn1_buf *alg ); 309 310 /** 311 * \brief Find a specific named_data entry in a sequence or list based on 312 * the OID. 313 * 314 * \param list The list to seek through 315 * \param oid The OID to look for 316 * \param len Size of the OID 317 * 318 * \return NULL if not found, or a pointer to the existing entry. 319 */ 320 mbedtls_asn1_named_data *mbedtls_asn1_find_named_data( mbedtls_asn1_named_data *list, 321 const char *oid, size_t len ); 322 323 /** 324 * \brief Free a mbedtls_asn1_named_data entry 325 * 326 * \param entry The named data entry to free 327 */ 328 void mbedtls_asn1_free_named_data( mbedtls_asn1_named_data *entry ); 329 330 /** 331 * \brief Free all entries in a mbedtls_asn1_named_data list 332 * Head will be set to NULL 333 * 334 * \param head Pointer to the head of the list of named data entries to free 335 */ 336 void mbedtls_asn1_free_named_data_list( mbedtls_asn1_named_data **head ); 337 338 #ifdef __cplusplus 339 } 340 #endif 341 342 #endif /* asn1.h */ 343
