asn1.h File Reference

Generic ASN.1 parsing. More...

`#include "config.h"`
`#include <stddef.h>`
`#include "bignum.h"`
Include dependency graph for asn1.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | mbedtls_asn1_buf
| Type-length-value structure that allows for ASN1 using DER. More...
struct | mbedtls_asn1_bitstring
| Container for ASN1 bit strings. More...
struct | mbedtls_asn1_sequence
| Container for a sequence of ASN.1 items. More...
struct | mbedtls_asn1_named_data
| Container for a sequence or list of 'named' ASN.1 data items. More...

## Macros

#define | MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
| Returns the size of the binary string, without the trailing \0. More...
#define | MBEDTLS_OID_CMP(oid_str, oid_buf)
| Compares an mbedtls_asn1_buf structure to a reference OID. More...
ASN1 Error codes
These error codes are OR'ed to X509 error codes for higher error granularity. ASN1 is a standard to specify data structures.
#define | MBEDTLS_ERR_ASN1_OUT_OF_DATA -0x0060
| Out of data when parsing an ASN1 data structure. More...
#define | MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062
| ASN1 tag was of an unexpected value. More...
#define | MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064
| Error when trying to determine the length or invalid length. More...
#define | MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066
| Actual length differs from expected length. More...
#define | MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068
| Data is invalid. More...
#define | MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A
| Memory allocation failed. More...
#define | MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C
| Buffer too small when writing ASN.1 data structure. More...
DER constants

These constants comply with DER encoded the ANS1 type tags.

DER encoding uses hexadecimal representation. An example DER sequence is:

- 0x02 – tag indicating INTEGER
- 0x01 – length in octets
- 0x05 – value Such sequences are typically read into `mbedtls_x509_buf`.

#define | MBEDTLS_ASN1_BOOLEAN 0x01
#define | MBEDTLS_ASN1_INTEGER 0x02
#define | MBEDTLS_ASN1_BIT_STRING 0x03
#define | MBEDTLS_ASN1_OCTET_STRING 0x04
#define | MBEDTLS_ASN1_NULL 0x05
#define | MBEDTLS_ASN1_OID 0x06
#define | MBEDTLS_ASN1_UTF8_STRING 0x0C
#define | MBEDTLS_ASN1_SEQUENCE 0x10
#define | MBEDTLS_ASN1_SET 0x11
#define | MBEDTLS_ASN1_PRINTABLE_STRING 0x13
#define | MBEDTLS_ASN1_T61_STRING 0x14
#define | MBEDTLS_ASN1_IA5_STRING 0x16
#define | MBEDTLS_ASN1_UTC_TIME 0x17
#define | MBEDTLS_ASN1_GENERALIZED_TIME 0x18
#define | MBEDTLS_ASN1_UNIVERSAL_STRING 0x1C
#define | MBEDTLS_ASN1_BMP_STRING 0x1E
#define | MBEDTLS_ASN1_PRIMITIVE 0x00
#define | MBEDTLS_ASN1_CONSTRUCTED 0x20
#define | MBEDTLS_ASN1_CONTEXT_SPECIFIC 0x80

## Functions to parse ASN.1 data structures

typedef struct mbedtls_asn1_buf | mbedtls_asn1_buf
| Type-length-value structure that allows for ASN1 using DER. More...
typedef struct mbedtls_asn1_bitstring | mbedtls_asn1_bitstring
| Container for ASN1 bit strings. More...
typedef struct mbedtls_asn1_sequence | mbedtls_asn1_sequence
| Container for a sequence of ASN.1 items. More...
typedef struct mbedtls_asn1_named_data | mbedtls_asn1_named_data
| Container for a sequence or list of 'named' ASN.1 data items. More...
int | mbedtls_asn1_get_len (unsigned char **p, const unsigned char *end, size_t *len)
| Get the length of an ASN.1 element. More...
int | mbedtls_asn1_get_tag (unsigned char **p, const unsigned char *end, size_t *len, int tag)
| Get the tag and length of the tag. More...
int | mbedtls_asn1_get_bool (unsigned char **p, const unsigned char *end, int *val)
| Retrieve a boolean ASN.1 tag and its value. More...
int | mbedtls_asn1_get_int (unsigned char **p, const unsigned char *end, int *val)
| Retrieve an integer ASN.1 tag and its value. More...
int | mbedtls_asn1_get_bitstring (unsigned char **p, const unsigned char *end, mbedtls_asn1_bitstring *bs)
| Retrieve a bitstring ASN.1 tag and its value. More...
int | mbedtls_asn1_get_bitstring_null (unsigned char **p, const unsigned char *end, size_t *len)
| Retrieve a bitstring ASN.1 tag without unused bits and its value. More...
int | mbedtls_asn1_get_sequence_of (unsigned char **p, const unsigned char *end, mbedtls_asn1_sequence *cur, int tag)
| Parses and splits an ASN.1 "SEQUENCE OF <tag>" Updated the pointer to immediately behind the full sequence tag. More...
int | mbedtls_asn1_get_mpi (unsigned char **p, const unsigned char *end, mbedtls_mpi *X)
| Retrieve a MPI value from an integer ASN.1 tag. More...
int | mbedtls_asn1_get_alg (unsigned char **p, const unsigned char *end, mbedtls_asn1_buf *alg, mbedtls_asn1_buf *params)
| Retrieve an AlgorithmIdentifier ASN.1 sequence. More...
int | mbedtls_asn1_get_alg_null (unsigned char **p, const unsigned char *end, mbedtls_asn1_buf *alg)
| Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no params. More...
mbedtls_asn1_named_data * | mbedtls_asn1_find_named_data (mbedtls_asn1_named_data *list, const char *oid, size_t len)
| Find a specific named_data entry in a sequence or list based on the OID. More...
void | mbedtls_asn1_free_named_data (mbedtls_asn1_named_data *entry)
| Free a mbedtls_asn1_named_data entry. More...
void | mbedtls_asn1_free_named_data_list (mbedtls_asn1_named_data **head)
| Free all entries in a mbedtls_asn1_named_data list Head will be set to NULL. More...

## Detailed Description

Generic ASN.1 parsing.

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file asn1.h.

## Macro Definition Documentation

#define MBEDTLS_OID_CMP | ( |  | oid_str,
|  |  | oid_buf
| ) |  |

Value:
( ( MBEDTLS_OID_SIZE(oid_str) != (oid_buf)->len ) || \
memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) != 0 )
MBEDTLS_OID_SIZE
#define MBEDTLS_OID_SIZE(x)
Returns the size of the binary string, without the trailing \0.
Definition: asn1.h:94

Compares an mbedtls_asn1_buf structure to a reference OID.

Only works for 'defined' oid_str values (MBEDTLS_OID_HMAC_SHA1), you cannot use a 'unsigned char *oid' here!

Definition at line 102 of file asn1.h.

#define MBEDTLS_OID_SIZE | ( |  | x | ) | (sizeof(x) - 1)

Returns the size of the binary string, without the trailing \0.

Definition at line 94 of file asn1.h.

## Typedef Documentation

typedef struct mbedtls_asn1_bitstring mbedtls_asn1_bitstring

Container for ASN1 bit strings.

typedef struct mbedtls_asn1_buf mbedtls_asn1_buf

Type-length-value structure that allows for ASN1 using DER.

typedef struct mbedtls_asn1_named_data mbedtls_asn1_named_data

Container for a sequence or list of 'named' ASN.1 data items.

typedef struct mbedtls_asn1_sequence mbedtls_asn1_sequence

Container for a sequence of ASN.1 items.

## Function Documentation

mbedtls_asn1_named_data* mbedtls_asn1_find_named_data | ( | mbedtls_asn1_named_data * | list,
|  | const char * | oid,
|  | size_t | len
| ) |  |

Find a specific named_data entry in a sequence or list based on the OID.

Parameters

  list | The list to seek through
  oid | The OID to look for
  len | Size of the OID

Returns
  NULL if not found, or a pointer to the existing entry.

void mbedtls_asn1_free_named_data | ( | mbedtls_asn1_named_data * | entry | ) |

Free a mbedtls_asn1_named_data entry.

Parameters

  entry | The named data entry to free

void mbedtls_asn1_free_named_data_list | ( | mbedtls_asn1_named_data ** | head | ) |

Free all entries in a mbedtls_asn1_named_data list Head will be set to NULL.

Parameters

  head | Pointer to the head of the list of named data entries to free

int mbedtls_asn1_get_alg | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | mbedtls_asn1_buf * | alg,
|  | mbedtls_asn1_buf * | params
| ) |  |

Retrieve an AlgorithmIdentifier ASN.1 sequence.

Updates the pointer to immediately behind the full AlgorithmIdentifier.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  alg | The buffer to receive the OID
  params | The buffer to receive the params (if any)

Returns
  0 if successful or a specific ASN.1 or MPI error code.

int mbedtls_asn1_get_alg_null | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | mbedtls_asn1_buf * | alg
| ) |  |

Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no params.

Updates the pointer to immediately behind the full AlgorithmIdentifier.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  alg | The buffer to receive the OID

Returns
  0 if successful or a specific ASN.1 or MPI error code.

int mbedtls_asn1_get_bitstring | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | mbedtls_asn1_bitstring * | bs
| ) |  |

Retrieve a bitstring ASN.1 tag and its value.

Updates the pointer to immediately behind the full tag.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  bs | The variable that will receive the value

Returns
  0 if successful or a specific ASN.1 error code.

int mbedtls_asn1_get_bitstring_null | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | size_t * | len
| ) |  |

Retrieve a bitstring ASN.1 tag without unused bits and its value.

Updates the pointer to the beginning of the bit/octet string.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  len | Length of the actual bit/octect string in bytes

Returns
  0 if successful or a specific ASN.1 error code.

int mbedtls_asn1_get_bool | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | int * | val
| ) |  |

Retrieve a boolean ASN.1 tag and its value.

Updates the pointer to immediately behind the full tag.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  val | The variable that will receive the value

Returns
  0 if successful or a specific ASN.1 error code.

int mbedtls_asn1_get_int | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | int * | val
| ) |  |

Retrieve an integer ASN.1 tag and its value.

Updates the pointer to immediately behind the full tag.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  val | The variable that will receive the value

Returns
  0 if successful or a specific ASN.1 error code.

int mbedtls_asn1_get_len | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | size_t * | len
| ) |  |

Get the length of an ASN.1 element.

Updates the pointer to immediately behind the length.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  len | The variable that will receive the value

Returns
  0 if successful, MBEDTLS_ERR_ASN1_OUT_OF_DATA on reaching end of data, MBEDTLS_ERR_ASN1_INVALID_LENGTH if length is unparseable.

int mbedtls_asn1_get_mpi | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | mbedtls_mpi * | X
| ) |  |

Retrieve a MPI value from an integer ASN.1 tag.

Updates the pointer to immediately behind the full tag.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  X | The MPI that will receive the value

Returns
  0 if successful or a specific ASN.1 or MPI error code.

int mbedtls_asn1_get_sequence_of | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | mbedtls_asn1_sequence * | cur,
|  | int | tag
| ) |  |

Parses and splits an ASN.1 "SEQUENCE OF <tag>" Updated the pointer to immediately behind the full sequence tag.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  cur | First variable in the chain to fill
  tag | Type of sequence

Returns
  0 if successful or a specific ASN.1 error code.

int mbedtls_asn1_get_tag | ( | unsigned char ** | p,
|  | const unsigned char * | end,
|  | size_t * | len,
|  | int | tag
| ) |  |

Get the tag and length of the tag.

Check for the requested tag. Updates the pointer to immediately behind the tag and length.

Parameters

  p | The position in the ASN.1 data
  end | End of data
  len | The variable that will receive the length
  tag | The expected tag

Returns
  0 if successful, MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if tag did not match requested tag, or another specific ASN.1 error code.