| 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 */
|
|---|
![(please configure the [header_logo] section in trac.ini)](/trac_user/contrib/chrome/site/your_project_logo.png){kind=logo}
