File asn1.h
Generic ASN.1 parsing.
ASN1 Error codes
These error codes are combined with other error codes for higher error granularity. e.g. X.509 and PKCS #7 error codes ASN1 is a standard to specify data structures.
-
MBEDTLS_ERR_ASN1_OUT_OF_DATA
Out of data when parsing an ASN1 data structure.
-
MBEDTLS_ERR_ASN1_UNEXPECTED_TAG
ASN1 tag was of an unexpected value.
-
MBEDTLS_ERR_ASN1_INVALID_LENGTH
Error when trying to determine the length or invalid length.
-
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH
Actual length differs from expected length.
-
MBEDTLS_ERR_ASN1_INVALID_DATA
Data is invalid.
-
MBEDTLS_ERR_ASN1_ALLOC_FAILED
Memory allocation failed
-
MBEDTLS_ERR_ASN1_BUF_TOO_SMALL
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 INTEGER
0x01 — length in octets
0x05 — value Such sequences are typically read into
mbedtls_x509_buf
.
-
MBEDTLS_ASN1_BOOLEAN
-
MBEDTLS_ASN1_INTEGER
-
MBEDTLS_ASN1_BIT_STRING
-
MBEDTLS_ASN1_OCTET_STRING
-
MBEDTLS_ASN1_NULL
-
MBEDTLS_ASN1_OID
-
MBEDTLS_ASN1_ENUMERATED
-
MBEDTLS_ASN1_UTF8_STRING
-
MBEDTLS_ASN1_SEQUENCE
-
MBEDTLS_ASN1_SET
-
MBEDTLS_ASN1_PRINTABLE_STRING
-
MBEDTLS_ASN1_T61_STRING
-
MBEDTLS_ASN1_IA5_STRING
-
MBEDTLS_ASN1_UTC_TIME
-
MBEDTLS_ASN1_GENERALIZED_TIME
-
MBEDTLS_ASN1_UNIVERSAL_STRING
-
MBEDTLS_ASN1_BMP_STRING
-
MBEDTLS_ASN1_PRIMITIVE
-
MBEDTLS_ASN1_CONSTRUCTED
-
MBEDTLS_ASN1_CONTEXT_SPECIFIC
-
MBEDTLS_ASN1_IS_STRING_TAG(tag)
-
MBEDTLS_ASN1_TAG_CLASS_MASK
-
MBEDTLS_ASN1_TAG_PC_MASK
-
MBEDTLS_ASN1_TAG_VALUE_MASK
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.
-
typedef struct mbedtls_asn1_bitstring mbedtls_asn1_bitstring
Container for ASN1 bit strings.
-
typedef struct mbedtls_asn1_sequence mbedtls_asn1_sequence
Container for a sequence of ASN.1 items
-
typedef struct mbedtls_asn1_named_data mbedtls_asn1_named_data
Container for a sequence or list of ‘named’ ASN.1 data items
-
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 – 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.end – End of data.
len – On successful completion,
*len
contains the length read from the ASN.1 input.
- Returns:
0 if successful.
- Returns:
MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element would end beyond
end
.- Returns:
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
-
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.
- Parameters:
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.end – End of data.
len – On successful completion,
*len
contains the length read from the ASN.1 input.tag – The expected tag.
- Returns:
0 if successful.
- Returns:
MBEDTLS_ERR_ASN1_UNEXPECTED_TAG if the data does not start with the requested tag.
- Returns:
MBEDTLS_ERR_ASN1_OUT_OF_DATA if the ASN.1 element would end beyond
end
.- Returns:
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the length is unparsable.
-
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 – 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.end – End of data.
val – On success, the parsed value (
0
or1
).
- Returns:
0 if successful.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 BOOLEAN.
-
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 – 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.end – End of data.
val – On success, the parsed value.
- Returns:
0 if successful.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 INTEGER.
- Returns:
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does not fit in an
int
.
-
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.
- Parameters:
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.end – End of data.
val – On success, the parsed value.
- Returns:
0 if successful.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 ENUMERATED.
- Returns:
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does not fit in an
int
.
-
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 – On entry,
*p
points to the start of the ASN.1 element. On successful completion,*p
is equal toend
. On error, the value of*p
is undefined.end – End of data.
bs – On success, mbedtls_asn1_bitstring information about the parsed value.
- Returns:
0 if successful.
- Returns:
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid BIT STRING.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 BIT STRING.
-
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 – 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.end – End of data.
len – On success,
*len
is the length of the content in bytes.
- Returns:
0 if successful.
- Returns:
MBEDTLS_ERR_ASN1_INVALID_DATA if the input starts with a valid BIT STRING with a nonzero number of unused bits.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 BIT STRING.
-
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 setcur->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.Note
If the sequence is empty, this function does not modify
*cur
. If the sequence is valid and non-empty, this function setscur->buf.tag
totag
. This allows callers to distinguish between an empty sequence and a one-element sequence.- Parameters:
p – On entry,
*p
points to the start of the ASN.1 element. On successful completion,*p
is equal toend
. On error, the value of*p
is undefined.end – End of data.
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 fromcur
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, andbuf.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.tag – Each element of the sequence must have this tag.
- Returns:
0 if successful.
- Returns:
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid SEQUENCE OF
tag
.- Returns:
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
.- Returns:
MBEDTLS_ERR_ASN1_ALLOC_FAILED if a memory allocation failed.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 SEQUENCE.
-
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 thecur
argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() onhead
.Allocate a head node
mbedtls_asn1_sequence *head
in any manner, for example on the stack. Make sure thathead->next == NULL
. Passhead
as thecur
argument to mbedtls_asn1_get_sequence_of(). When you have finished processing the sequence, call mbedtls_asn1_sequence_free() onhead->cur
, then freehead
itself in the appropriate manner.
- Parameters:
seq – The address of the first sequence component. This may be
NULL
, in which case this functions returns immediately.
-
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 callcb
on each element, usembedtls_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, usembedtls_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, usembedtls_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.
Warning
This function is still experimental and may change at any time.
- Parameters:
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.
end – The end of the ASN.1 SEQUENCE container.
tag_must_mask – A mask to be applied to the ASN.1 tags found within the SEQUENCE before comparing to
tag_must_val
.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 of0
for bothtag_must_mask
andtag_must_val
means that every tag is allowed, while a value of0xFF
fortag_must_mask
means thattag_must_val
is the only allowed tag.tag_may_mask – A mask to be applied to the ASN.1 tags found within the SEQUENCE before comparing to
tag_may_val
.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 of0
fortag_may_mask
andtag_may_val
means that any tag will be considered, while a value of0xFF
fortag_may_mask
means that all tags with value different fromtag_may_val
will be ignored.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.
ctx – The context to be passed to the callback
cb
.
- Returns:
0
if successful the entire ASN.1 SEQUENCE was traversed without parsing or callback errors.- Returns:
MBEDTLS_ERR_ASN1_LENGTH_MISMATCH if the input contains extra data after a valid SEQUENCE of elements with an accepted tag.
- Returns:
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.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 SEQUENCE.
- Returns:
A non-zero error code forwarded from the callback
cb
in case the latter returns a non-zero value.
-
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.
- Parameters:
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.end – End of data.
X – On success, the parsed value.
- Returns:
0 if successful.
- Returns:
An ASN.1 error code if the input does not start with a valid ASN.1 INTEGER.
- Returns:
MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does not fit in an
int
.- Returns:
An MPI error code if the parsed value is too large.
-
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 – 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.end – End of data.
alg – The buffer to receive the OID.
params – The buffer to receive the parameters. This is zeroized if there are no parameters.
- 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 – 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.end – End of data.
alg – The buffer to receive the OID.
- Returns:
0 if successful or a specific ASN.1 or MPI error code.
-
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:
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_list(mbedtls_asn1_named_data **head)
Free all entries in a mbedtls_asn1_named_data list.
- Parameters:
head – Pointer to the head of the list of named data entries to free. This function calls mbedtls_free() on
entry->oid.p
andentry->val.p
and then onentry
for each list entry, and sets*head
toNULL
.
-
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.
- Parameters:
name – Head of the list of named data entries to free. This function calls mbedtls_free() on each list element.
Defines
-
MBEDTLS_OID_SIZE(x)
Returns the size of the binary string, without the trailing \0
-
MBEDTLS_OID_CMP(oid_str, oid_buf)
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(oid_str, oid_buf, oid_buf_len)
-
struct mbedtls_asn1_buf
- #include <asn1.h>
Type-length-value structure that allows for ASN1 using DER.
-
struct mbedtls_asn1_bitstring
- #include <asn1.h>
Container for ASN1 bit strings.
-
struct mbedtls_asn1_sequence
- #include <asn1.h>
Container for a sequence of ASN.1 items
Public Members
-
mbedtls_asn1_buf buf
Buffer containing the given ASN.1 item.
-
struct mbedtls_asn1_sequence *next
The next entry in the sequence.
The details of memory management for sequences are not documented and may change in future versions. Set this field to
NULL
when initializing a structure, and do not modify it except via Mbed TLS library functions.
-
mbedtls_asn1_buf buf
-
struct mbedtls_asn1_named_data
- #include <asn1.h>
Container for a sequence or list of ‘named’ ASN.1 data items
Public Members
-
mbedtls_asn1_buf oid
The object identifier.
-
mbedtls_asn1_buf val
The named value.
-
struct mbedtls_asn1_named_data *next
The next entry in the sequence.
The details of memory management for named data sequences are not documented and may change in future versions. Set this field to
NULL
when initializing a structure, and do not modify it except via Mbed TLS library functions.
-
unsigned char private_next_merged
Merge next item into the current one?
This field exists for the sake of Mbed TLS’s X.509 certificate parsing code and may change in future versions of the library.
-
mbedtls_asn1_buf oid