Asn1_module#

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.

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.

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.

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.

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.

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.

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.

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

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.

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(*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.

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_mpi#

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

Retrieve an integer ASN.1 tag and its 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.

• An MPI error code if the parsed value is too large.

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.

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.

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.

Returns

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

mbedtls_asn1_free_named_data#

void MBEDTLS_DEPRECATED mbedtls_asn1_free_named_data (mbedtls_asn1_named_data *entry)

Free a mbedtls_asn1_named_data entry.

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.

mbedtls_asn1_free_named_data_list_shallow#

void mbedtls_asn1_free_named_data_list_shallow (mbedtls_asn1_named_data *name)

Free all shallow entries in a mbedtls_asn1_named_data list, but do not free internal pointer targets.

MBEDTLS_ERR_ASN1_OUT_OF_DATA#

#define MBEDTLS_ERR_ASN1_OUT_OF_DATA

-0x0060

Out of data when parsing an ASN1 data structure.

MBEDTLS_ERR_ASN1_UNEXPECTED_TAG#

#define MBEDTLS_ERR_ASN1_UNEXPECTED_TAG

-0x0062

ASN1 tag was of an unexpected value.

MBEDTLS_ERR_ASN1_INVALID_LENGTH#

#define MBEDTLS_ERR_ASN1_INVALID_LENGTH

-0x0064

Error when trying to determine the length or invalid length.

MBEDTLS_ERR_ASN1_LENGTH_MISMATCH#

#define MBEDTLS_ERR_ASN1_LENGTH_MISMATCH

-0x0066

Actual length differs from expected length.

MBEDTLS_ERR_ASN1_INVALID_DATA#

#define MBEDTLS_ERR_ASN1_INVALID_DATA

-0x0068

Data is invalid.

MBEDTLS_ERR_ASN1_ALLOC_FAILED#

#define MBEDTLS_ERR_ASN1_ALLOC_FAILED

-0x006A

Memory allocation failed.

MBEDTLS_ERR_ASN1_BUF_TOO_SMALL#

#define MBEDTLS_ERR_ASN1_BUF_TOO_SMALL

-0x006C

Buffer too small when writing ASN.1 data structure.

MBEDTLS_ASN1_BOOLEAN#

#define MBEDTLS_ASN1_BOOLEAN

0x01

MBEDTLS_ASN1_INTEGER#

#define MBEDTLS_ASN1_INTEGER

0x02

MBEDTLS_ASN1_BIT_STRING#

#define MBEDTLS_ASN1_BIT_STRING

0x03

MBEDTLS_ASN1_OCTET_STRING#

#define MBEDTLS_ASN1_OCTET_STRING

0x04

MBEDTLS_ASN1_NULL#

#define MBEDTLS_ASN1_NULL

0x05

MBEDTLS_ASN1_OID#

#define MBEDTLS_ASN1_OID

0x06

MBEDTLS_ASN1_ENUMERATED#

#define MBEDTLS_ASN1_ENUMERATED

0x0A

MBEDTLS_ASN1_UTF8_STRING#

#define MBEDTLS_ASN1_UTF8_STRING

0x0C

MBEDTLS_ASN1_SEQUENCE#

#define MBEDTLS_ASN1_SEQUENCE

0x10

MBEDTLS_ASN1_SET#

#define MBEDTLS_ASN1_SET

0x11

MBEDTLS_ASN1_PRINTABLE_STRING#

#define MBEDTLS_ASN1_PRINTABLE_STRING

0x13

MBEDTLS_ASN1_T61_STRING#

#define MBEDTLS_ASN1_T61_STRING

0x14

MBEDTLS_ASN1_IA5_STRING#

#define MBEDTLS_ASN1_IA5_STRING

0x16

MBEDTLS_ASN1_UTC_TIME#

#define MBEDTLS_ASN1_UTC_TIME

0x17

MBEDTLS_ASN1_GENERALIZED_TIME#

#define MBEDTLS_ASN1_GENERALIZED_TIME

0x18

MBEDTLS_ASN1_UNIVERSAL_STRING#

#define MBEDTLS_ASN1_UNIVERSAL_STRING

0x1C

MBEDTLS_ASN1_BMP_STRING#

#define MBEDTLS_ASN1_BMP_STRING

0x1E

MBEDTLS_ASN1_PRIMITIVE#

#define MBEDTLS_ASN1_PRIMITIVE

0x00

MBEDTLS_ASN1_CONSTRUCTED#

#define MBEDTLS_ASN1_CONSTRUCTED

0x20

MBEDTLS_ASN1_CONTEXT_SPECIFIC#

#define MBEDTLS_ASN1_CONTEXT_SPECIFIC

0x80

MBEDTLS_ASN1_IS_STRING_TAG#

#define MBEDTLS_ASN1_IS_STRING_TAG

MBEDTLS_ASN1_TAG_CLASS_MASK#

#define MBEDTLS_ASN1_TAG_CLASS_MASK

0xC0

MBEDTLS_ASN1_TAG_PC_MASK#

#define MBEDTLS_ASN1_TAG_PC_MASK

0x20

MBEDTLS_ASN1_TAG_VALUE_MASK#

#define MBEDTLS_ASN1_TAG_VALUE_MASK

0x1F

MBEDTLS_OID_SIZE#

#define MBEDTLS_OID_SIZE

(x)

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

MBEDTLS_OID_CMP#

#define MBEDTLS_OID_CMP

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!

MBEDTLS_OID_CMP_RAW#

#define MBEDTLS_OID_CMP_RAW