Asn1_module

Data Structures
struct	mbedtls_asn1_bitstring
struct	mbedtls_asn1_buf
struct	mbedtls_asn1_named_data
struct	mbedtls_asn1_sequence

Variables
mbedtls_asn1_buf	mbedtls_asn1_sequence::buf
size_t	mbedtls_asn1_bitstring::len
size_t	mbedtls_asn1_buf::len
struct mbedtls_asn1_named_data *	mbedtls_asn1_named_data::next
struct mbedtls_asn1_sequence *	mbedtls_asn1_sequence::next
unsigned char	mbedtls_asn1_named_data::next_merged
mbedtls_asn1_buf	mbedtls_asn1_named_data::oid
unsigned char *	mbedtls_asn1_bitstring::p
unsigned char *	mbedtls_asn1_buf::p
int	mbedtls_asn1_buf::tag
unsigned char	mbedtls_asn1_bitstring::unused_bits
mbedtls_asn1_buf	mbedtls_asn1_named_data::val

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 Head will be set to NULL.

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_OID_SIZE(x)
#define	MBEDTLS_OID_CMP(oid_str, oid_buf)

Detailed Description

Macro Definition Documentation

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_ERR_ASN1_INVALID_DATA

#define MBEDTLS_ERR_ASN1_INVALID_DATA   -0x0068

Data is invalid. (not used)

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_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_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 )

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_SIZE

#define MBEDTLS_OID_SIZE

(

x

)

Value:

(sizeof(x) - 1)

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

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.

Variable Documentation

buf

mbedtls_asn1_buf mbedtls_asn1_sequence::buf

Buffer containing the given ASN.1 item.

len [1/2]

size_t mbedtls_asn1_bitstring::len

ASN1 length, in octets.

len [2/2]

size_t mbedtls_asn1_buf::len

ASN1 length, in octets.

next [1/2]

struct mbedtls_asn1_named_data* mbedtls_asn1_named_data::next

The next entry in the sequence.

next [2/2]

struct mbedtls_asn1_sequence* mbedtls_asn1_sequence::next

The next entry in the sequence.

next_merged

unsigned char mbedtls_asn1_named_data::next_merged

Merge next item into the current one?

oid

mbedtls_asn1_buf mbedtls_asn1_named_data::oid

The object identifier.

p [1/2]

unsigned char* mbedtls_asn1_bitstring::p

Raw ASN1 data for the bit string

p [2/2]

unsigned char* mbedtls_asn1_buf::p

ASN1 data, e.g. in ASCII.

tag

int mbedtls_asn1_buf::tag

ASN1 type, e.g. MBEDTLS_ASN1_UTF8_STRING.

unused_bits

unsigned char mbedtls_asn1_bitstring::unused_bits

Number of unused bits at the end of the string

val

mbedtls_asn1_buf mbedtls_asn1_named_data::val

The named value.