mbed TLS v2.16.0: asn1.h File Reference

mbed TLS v2.16.0

Data Structures | Macros
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
struct | mbedtls_asn1_bitstring
struct | mbedtls_asn1_sequence
struct | mbedtls_asn1_named_data

## Macros
#define | MBEDTLS_OID_SIZE(x) (sizeof(x) - 1)
#define | MBEDTLS_OID_CMP(oid_str, oid_buf)
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
#define | MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062
#define | MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064
#define | MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066
#define | MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068
#define | MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A
#define | MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C
DER constants
These constants comply with the DER encoded ASN.1 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
#define | MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0
#define | MBEDTLS_ASN1_TAG_PC_MASK 0x20
#define | MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F

## Functions to parse ASN.1 data structures
typedef struct mbedtls_asn1_buf | mbedtls_asn1_buf
typedef struct mbedtls_asn1_bitstring | mbedtls_asn1_bitstring
typedef struct mbedtls_asn1_sequence | mbedtls_asn1_sequence
typedef struct mbedtls_asn1_named_data | mbedtls_asn1_named_data
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. 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. Check for the requested tag. Updates the pointer to immediately behind the tag and length. More...
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. More...
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. 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. Updates the pointer to immediately behind the full tag. 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. Updates the pointer to the beginning of the bit/octet string. 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. Updates the pointer to immediately behind the full 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. Updates the pointer to immediately behind the full AlgorithmIdentifier. 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. Updates the pointer to immediately behind the full AlgorithmIdentifier. 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.

Definition in file asn1.h.

## Macro Definition Documentation

## ◆ MBEDTLS_OID_CMP

#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)
Definition: asn1.h:110

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 118 of file asn1.h.

## ◆ MBEDTLS_OID_SIZE

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

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

Definition at line 110 of file asn1.h.

## Typedef Documentation

## ◆ mbedtls_asn1_bitstring

typedef struct mbedtls_asn1_bitstring mbedtls_asn1_bitstring

Container for ASN1 bit strings.

## ◆ mbedtls_asn1_buf

typedef struct mbedtls_asn1_buf mbedtls_asn1_buf

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

## ◆ mbedtls_asn1_named_data

typedef struct mbedtls_asn1_named_data mbedtls_asn1_named_data

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

## ◆ mbedtls_asn1_sequence

typedef struct mbedtls_asn1_sequence mbedtls_asn1_sequence

Container for a sequence of ASN.1 items

## Function Documentation

## ◆ mbedtls_asn1_find_named_data()

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.

## ◆ mbedtls_asn1_free_named_data()

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

## ◆ mbedtls_asn1_free_named_data_list()

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

## ◆ mbedtls_asn1_get_alg()

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.

## ◆ mbedtls_asn1_get_alg_null()

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.

## ◆ mbedtls_asn1_get_bitstring()

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.

## ◆ mbedtls_asn1_get_bitstring_null()

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.

## ◆ mbedtls_asn1_get_bool()

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.

## ◆ mbedtls_asn1_get_int()

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.

## ◆ mbedtls_asn1_get_len()

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.

## ◆ mbedtls_asn1_get_mpi()

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.

## ◆ mbedtls_asn1_get_sequence_of()

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.

## ◆ mbedtls_asn1_get_tag()

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.