Asn1_module#

Modules#

Functions to parse ASN.1 data structures#

int

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

Get the length of an ASN.1 element.

int

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

Get the tag and length of the element.

int

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

Retrieve a boolean ASN.1 tag and its value.

int

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

Retrieve an integer ASN.1 tag and its value.

int

mbedtls_asn1_get_enum(unsigned char **p, const unsigned char *end, int *val)

Retrieve an enumerated ASN.1 tag and its value.

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.

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.

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>".

void

mbedtls_asn1_sequence_free(mbedtls_asn1_sequence *seq)

Free a heap-allocated linked list presentation of an ASN.1 sequence, including the first element.

int

mbedtls_asn1_traverse_sequence_of(unsigned char **p, const unsigned char *end, unsigned char tag_must_mask, unsigned char tag_must_val, unsigned char tag_may_mask, unsigned char tag_may_val, int(*cb)(void *ctx, int tag, unsigned char *start, size_t len), void *ctx)

Traverse an ASN.1 SEQUENCE container and call a callback for each entry.

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.

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.

const mbedtls_asn1_named_data *

mbedtls_asn1_find_named_data(const 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.

void

mbedtls_asn1_free_named_data(mbedtls_asn1_named_data *entry)

Free a mbedtls_asn1_named_data entry.

void

mbedtls_asn1_free_named_data_list(mbedtls_asn1_named_data **head)

Free all entries in a mbedtls_asn1_named_data list.

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.

#define

MBEDTLS_ERR_ASN1_UNEXPECTED_TAG -0x0062

ASN1 tag was of an unexpected value.

#define

MBEDTLS_ERR_ASN1_INVALID_LENGTH -0x0064

Error when trying to determine the length or invalid length.

#define

MBEDTLS_ERR_ASN1_LENGTH_MISMATCH -0x0066

Actual length differs from expected length.

#define

MBEDTLS_ERR_ASN1_INVALID_DATA -0x0068

Data is invalid.

#define

MBEDTLS_ERR_ASN1_ALLOC_FAILED -0x006A

Memory allocation failed.

#define

MBEDTLS_ERR_ASN1_BUF_TOO_SMALL -0x006C

Buffer too small when writing ASN.1 data structure.

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 INTEGER0x01 length in octets0x05 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_ENUMERATED 0x0A

#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_IS_STRING_TAG (tag)

#define

MBEDTLS_ASN1_TAG_CLASS_MASK 0xC0

#define

MBEDTLS_ASN1_TAG_PC_MASK 0x20

#define

MBEDTLS_ASN1_TAG_VALUE_MASK 0x1F

Macros#

#define

MBEDTLS_OID_SIZE (x)

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

#define

MBEDTLS_OID_CMP (oid_str, oid_buf)

Compares an mbedtls_asn1_buf structure to a reference OID.

#define

MBEDTLS_OID_CMP_RAW (oid_str, oid_buf, oid_buf_len)

Functions to parse ASN.1 data structures Documentation#

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the first byte of the length, i.e. immediately after the tag. On successful completion, `p` points to the first byte after the length, i.e. the first byte of the content. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
size_t *	N/A	len	On successful completion, `*len` contains the length read from the ASN.1 input.

Updates the pointer to immediately behind the length.

Returns

0 if successful.
MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element would end beyond end.
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.

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 element.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte after the length, i.e. the first byte of the content. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
size_t *	N/A	len	On successful completion, `*len` contains the length read from the ASN.1 input.
int	N/A	tag	The expected tag.

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

Returns

0 if successful.
MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start with the requested tag.
MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element would end beyond end.
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte beyond the ASN.1 element. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
int *	N/A	val	On success, the parsed value (`0` or `1`).

Updates the pointer to immediately behind the full tag.

Returns

0 if successful.
An ASN.1 error code if the input does not start with a valid ASN.1 BOOLEAN.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte beyond the ASN.1 element. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
int *	N/A	val	On success, the parsed value.

Updates the pointer to immediately behind the full tag.

Returns

0 if successful.
An ASN.1 error code if the input does not start with a valid ASN.1 INTEGER.
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does not fit in an int.

mbedtls_asn1_get_enum#

int mbedtls_asn1_get_enum (unsigned char ** p, const unsigned char * end, int * val)

Retrieve an enumerated ASN.1 tag and its value.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte beyond the ASN.1 element. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
int *	N/A	val	On success, the parsed value.

Updates the pointer to immediately behind the full tag.

Returns

0 if successful.
An ASN.1 error code if the input does not start with a valid ASN.1 ENUMERATED.
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does not fit in an int.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` is equal to `end`. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
mbedtls_asn1_bitstring *	N/A	bs	On success, mbedtls_asn1_bitstring information about the parsed value.

Updates the pointer to immediately behind the full tag.

Returns

0 if successful.
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid BIT STRING.
An ASN.1 error code if the input does not start with a valid ASN.1 BIT STRING.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte of the content of the BIT STRING. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
size_t *	N/A	len	On success, `*len` is the length of the content in bytes.

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

Returns

0 if successful.
MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with a valid BIT STRING with a nonzero number of unused bits.
An ASN.1 error code if the input does not start with a valid ASN.1 BIT STRING.

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>".

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` is equal to `end`. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
mbedtls_asn1_sequence *	N/A	cur	A mbedtls_asn1_sequence which this function fills. When this function returns, `cur` is the head of a linked list. Each node in this list is allocated with mbedtls_calloc() apart from `cur` itself, and should therefore be freed with mbedtls_free(). The list describes the content of the sequence. The head of the list (i.e. `cur` itself) describes the first element, `*cur->next` describes the second element, etc. For each element, `buf.tag == tag`, `buf.len` is the length of the content of the content of the element, and `buf.p` points to the first byte of the content (i.e. immediately past the length of the element). Note that list elements may be allocated even on error.
int	N/A	tag	Each element of the sequence must have this tag.

Updates the pointer to immediately behind the full sequence tag.

This function allocates memory for the sequence elements. You can free the allocated memory with mbedtls_asn1_sequence_free().

Note

On error, this function may return a partial list in cur. You must set cur->next = NULL before calling this function! Otherwise it is impossible to distinguish a previously non-null pointer from a pointer to an object allocated by this function.
If the sequence is empty, this function does not modify *cur. If the sequence is valid and non-empty, this function sets cur->buf.tag to tag. This allows callers to distinguish between an empty sequence and a one-element sequence.

Returns

0 if successful.
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid SEQUENCE OF tag.
MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with an ASN.1 SEQUENCE in which an element has a tag that is different from tag.
MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
An ASN.1 error code if the input does not start with a valid ASN.1 SEQUENCE.

mbedtls_asn1_sequence_free#

void mbedtls_asn1_sequence_free (mbedtls_asn1_sequence * seq)

Free a heap-allocated linked list presentation of an ASN.1 sequence, including the first element.

Parameters

Type	Direction	Argument Name	Description
mbedtls_asn1_sequence *	N/A	seq	The address of the first sequence component. This may be `NULL`, in which case this functions returns immediately.

There are two common ways to manage the memory used for the representation of a parsed ASN.1 sequence:

Allocate a head node mbedtls_asn1_sequence *head with mbedtls_calloc(). Pass this node as the cur argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() on head.
Allocate a head node mbedtls_asn1_sequence *head in any manner, for example on the stack. Make sure that head->next == NULL. Pass head as the cur argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() on head->cur, then free head itself in the appropriate manner.

mbedtls_asn1_traverse_sequence_of#

int mbedtls_asn1_traverse_sequence_of (unsigned char ** p, const unsigned char * end, unsigned char tag_must_mask, unsigned char tag_must_val, unsigned char tag_may_mask, unsigned char tag_may_val, int(*)(void *ctx, int tag, unsigned char *start, size_t len) cb, void * ctx)

Traverse an ASN.1 SEQUENCE container and call a callback for each entry.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	The address of the pointer to the beginning of the ASN.1 SEQUENCE header. This is updated to point to the end of the ASN.1 SEQUENCE container on a successful invocation.
const unsigned char *	N/A	end	The end of the ASN.1 SEQUENCE container.
unsigned char	N/A	tag_must_mask	A mask to be applied to the ASN.1 tags found within the SEQUENCE before comparing to `tag_must_value`.
unsigned char	N/A	tag_must_val	The required value of each ASN.1 tag found in the SEQUENCE, after masking with `tag_must_mask`. Mismatching tags lead to an error. For example, a value of `0` for both `tag_must_mask` and `tag_must_val` means that every tag is allowed, while a value of `0xFF` for `tag_must_mask` means that `tag_must_val` is the only allowed tag.
unsigned char	N/A	tag_may_mask	A mask to be applied to the ASN.1 tags found within the SEQUENCE before comparing to `tag_may_value`.
unsigned char	N/A	tag_may_val	The desired value of each ASN.1 tag found in the SEQUENCE, after masking with `tag_may_mask`. Mismatching tags will be silently ignored. For example, a value of `0` for `tag_may_mask` and `tag_may_val` means that any tag will be considered, while a value of `0xFF` for `tag_may_mask` means that all tags with value different from `tag_may_val` will be ignored.
int()(void ctx, int tag, unsigned char *start, size_t len)	N/A	cb	The callback to trigger for each component in the ASN.1 SEQUENCE that matches `tag_may_val`. The callback function is called with the following parameters: `ctx`. The tag of the current element. A pointer to the start of the current element's content inside the input. The length of the content of the current element. If the callback returns a non-zero value, the function stops immediately, forwarding the callback's return value.
void *	N/A	ctx	The context to be passed to the callback `cb`.

This function checks that the input is a SEQUENCE of elements that each have a "must" tag, and calls a callback function on the elements that have a "may" tag.

For example, to validate that the input is a SEQUENCE of tag1 and call cb on each element, use

mbedtls_asn1_traverse_sequence_of(&p, end, 0xff, tag1, 0, 0, cb, ctx);

To validate that the input is a SEQUENCE of ANY and call cb on each element, use

mbedtls_asn1_traverse_sequence_of(&p, end, 0, 0, 0, 0, cb, ctx);

To validate that the input is a SEQUENCE of CHOICE {NULL, OCTET STRING} and call cb on each element that is an OCTET STRING, use

mbedtls_asn1_traverse_sequence_of(&p, end, 0xfe, 0x04, 0xff, 0x04, cb, ctx);

The callback is called on the elements with a "may" tag from left to right. If the input is not a valid SEQUENCE of elements with a "must" tag, the callback is called on the elements up to the leftmost point where the input is invalid.

Warnings

This function is still experimental and may change at any time.

Returns

0 if successful the entire ASN.1 SEQUENCE was traversed without parsing or callback errors.
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid SEQUENCE of elements with an accepted tag.
MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the input starts with an ASN.1 SEQUENCE in which an element has a tag that is not accepted.
An ASN.1 error code if the input does not start with a valid ASN.1 SEQUENCE.
A non-zero error code forwarded from the callback cb in case the latter returns a non-zero value.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte beyond the AlgorithmIdentifier element. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
mbedtls_asn1_buf *	N/A	alg	The buffer to receive the OID.
mbedtls_asn1_buf *	N/A	params	The buffer to receive the parameters. This is zeroized if there are no parameters.

Updates the pointer to immediately behind the full AlgorithmIdentifier.

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.

Parameters

Type	Direction	Argument Name	Description
unsigned char **	N/A	p	On entry, `p` points to the start of the ASN.1 element. On successful completion, `p` points to the first byte beyond the AlgorithmIdentifier element. On error, the value of `*p` is undefined.
const unsigned char *	N/A	end	End of data.
mbedtls_asn1_buf *	N/A	alg	The buffer to receive the OID.

Updates the pointer to immediately behind the full AlgorithmIdentifier.

Returns

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

mbedtls_asn1_find_named_data#

const mbedtls_asn1_named_data * mbedtls_asn1_find_named_data (const 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

Type	Direction	Argument Name	Description
const mbedtls_asn1_named_data *	N/A	list	The list to seek through
const char *	N/A	oid	The OID to look for
size_t	N/A	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

Type	Direction	Argument Name	Description
mbedtls_asn1_named_data *	N/A	entry	The named data entry to free. This function calls mbedtls_free() on `entry->oid.p` and `entry->val.p`.

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.

Parameters

Type	Direction	Argument Name	Description
mbedtls_asn1_named_data **	N/A	head	Pointer to the head of the list of named data entries to free. This function calls mbedtls_asn1_free_named_data() and mbedtls_free() on each list element and sets `*head` to `NULL`.

Asn1_module#

Modules#

Functions to parse ASN.1 data structures#

ASN1 Error codes#

DER constants#

Macros#

Functions to parse ASN.1 data structures Documentation#

mbedtls_asn1_get_len#

mbedtls_asn1_get_tag#

mbedtls_asn1_get_bool#

mbedtls_asn1_get_int#

mbedtls_asn1_get_enum#

mbedtls_asn1_get_bitstring#

mbedtls_asn1_get_bitstring_null#

mbedtls_asn1_get_sequence_of#

mbedtls_asn1_sequence_free#

mbedtls_asn1_traverse_sequence_of#

mbedtls_asn1_get_alg#

mbedtls_asn1_get_alg_null#

mbedtls_asn1_find_named_data#

mbedtls_asn1_free_named_data#

mbedtls_asn1_free_named_data_list#

ASN1 Error codes Documentation#

DER constants Documentation#