Data Structures
struct	_asn1_buf
	Type-length-value structure that allows for ASN1 using DER. More...

struct	_asn1_bitstring
	Container for ASN1 bit strings. More...

struct	_asn1_sequence
	Container for a sequence of ASN.1 items. More...

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

Variables
int	_asn1_buf::tag
	ASN1 type, e.g. More...

size_t	_asn1_buf::len
	ASN1 length, e.g. More...

unsigned char *	_asn1_buf::p
	ASN1 data, e.g. More...

size_t	_asn1_bitstring::len
	ASN1 length, e.g. More...

unsigned char	_asn1_bitstring::unused_bits
	Number of unused bits at the end of the string. More...

unsigned char *	_asn1_bitstring::p
	Raw ASN1 data for the bit string. More...

asn1_buf	_asn1_sequence::buf
	Buffer containing the given ASN.1 item. More...

struct _asn1_sequence *	_asn1_sequence::next
	The next entry in the sequence. More...

asn1_buf	_asn1_named_data::oid
	The object identifier. More...

asn1_buf	_asn1_named_data::val
	The named value. More...

struct _asn1_named_data *	_asn1_named_data::next
	The next entry in the sequence. More...

Functions to parse ASN.1 data structures
typedef struct _asn1_buf	asn1_buf
	Type-length-value structure that allows for ASN1 using DER. More...

typedef struct _asn1_bitstring	asn1_bitstring
	Container for ASN1 bit strings. More...

typedef struct _asn1_sequence	asn1_sequence
	Container for a sequence of ASN.1 items. More...

typedef struct _asn1_named_data	asn1_named_data
	Container for a sequence or list of 'named' ASN.1 data items. More...

int	asn1_get_len (unsigned char *p, const unsigned char end, size_t *len)
	Get the length of an ASN.1 element. More...

int	asn1_get_tag (unsigned char *p, const unsigned char end, size_t *len, int tag)
	Get the tag and length of the tag. More...

int	asn1_get_bool (unsigned char *p, const unsigned char end, int *val)
	Retrieve a boolean ASN.1 tag and its value. More...

int	asn1_get_int (unsigned char *p, const unsigned char end, int *val)
	Retrieve an integer ASN.1 tag and its value. More...

int	asn1_get_bitstring (unsigned char *p, const unsigned char end, asn1_bitstring *bs)
	Retrieve a bitstring ASN.1 tag and its value. More...

int	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. More...

int	asn1_get_sequence_of (unsigned char *p, const unsigned char end, 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	asn1_get_mpi (unsigned char *p, const unsigned char end, mpi *X)
	Retrieve a MPI value from an integer ASN.1 tag. More...

int	asn1_get_alg (unsigned char *p, const unsigned char end, asn1_buf alg, asn1_buf params)
	Retrieve an AlgorithmIdentifier ASN.1 sequence. More...

int	asn1_get_alg_null (unsigned char *p, const unsigned char end, asn1_buf *alg)
	Retrieve an AlgorithmIdentifier ASN.1 sequence with NULL or no params. More...

asn1_named_data *	asn1_find_named_data (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	asn1_free_named_data (asn1_named_data *entry)
	Free a asn1_named_data entry. More...

void	asn1_free_named_data_list (asn1_named_data **head)
	Free all entries in a asn1_named_data list Head will be set to NULL. More...

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	POLARSSL_ERR_ASN1_OUT_OF_DATA -0x0060
	Out of data when parsing an ASN1 data structure. More...

#define	POLARSSL_ERR_ASN1_UNEXPECTED_TAG -0x0062
	ASN1 tag was of an unexpected value. More...

#define	POLARSSL_ERR_ASN1_INVALID_LENGTH -0x0064
	Error when trying to determine the length or invalid length. More...

#define	POLARSSL_ERR_ASN1_LENGTH_MISMATCH -0x0066
	Actual length differs from expected length. More...

#define	POLARSSL_ERR_ASN1_INVALID_DATA -0x0068
	Data is invalid. More...

#define	POLARSSL_ERR_ASN1_MALLOC_FAILED -0x006A
	Memory allocation failed. More...

#define	POLARSSL_ERR_ASN1_BUF_TOO_SMALL -0x006C
	Buffer too small when writing ASN.1 data structure. More...

DER constants
These constants comply with DER encoded the ANS1 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 `x509_buf`.
#define	ASN1_BOOLEAN 0x01

#define	ASN1_INTEGER 0x02

#define	ASN1_BIT_STRING 0x03

#define	ASN1_OCTET_STRING 0x04

#define	ASN1_NULL 0x05

#define	ASN1_OID 0x06

#define	ASN1_UTF8_STRING 0x0C

#define	ASN1_SEQUENCE 0x10

#define	ASN1_SET 0x11

#define	ASN1_PRINTABLE_STRING 0x13

#define	ASN1_T61_STRING 0x14

#define	ASN1_IA5_STRING 0x16

#define	ASN1_UTC_TIME 0x17

#define	ASN1_GENERALIZED_TIME 0x18

#define	ASN1_UNIVERSAL_STRING 0x1C

#define	ASN1_BMP_STRING 0x1E

#define	ASN1_PRIMITIVE 0x00

#define	ASN1_CONSTRUCTED 0x20

#define	ASN1_CONTEXT_SPECIFIC 0x80

#define	OID_SIZE(x) (sizeof(x) - 1)
	Returns the size of the binary string, without the trailing \0. More...

#define	OID_CMP(oid_str, oid_buf)
	Compares an asn1_buf structure to a reference OID. More...

Detailed Description

Macro Definition Documentation

◆ ASN1_BIT_STRING

#define ASN1_BIT_STRING 0x03

Definition at line 77 of file asn1.h.

◆ ASN1_BMP_STRING

#define ASN1_BMP_STRING 0x1E

Definition at line 90 of file asn1.h.

◆ ASN1_BOOLEAN

#define ASN1_BOOLEAN 0x01

Definition at line 75 of file asn1.h.

◆ ASN1_CONSTRUCTED

#define ASN1_CONSTRUCTED 0x20

Definition at line 92 of file asn1.h.

◆ ASN1_CONTEXT_SPECIFIC

#define ASN1_CONTEXT_SPECIFIC 0x80

Definition at line 93 of file asn1.h.

◆ ASN1_GENERALIZED_TIME

#define ASN1_GENERALIZED_TIME 0x18

Definition at line 88 of file asn1.h.

◆ ASN1_IA5_STRING

#define ASN1_IA5_STRING 0x16

Definition at line 86 of file asn1.h.

◆ ASN1_INTEGER

#define ASN1_INTEGER 0x02

Definition at line 76 of file asn1.h.

◆ ASN1_NULL

#define ASN1_NULL 0x05

Definition at line 79 of file asn1.h.

◆ ASN1_OCTET_STRING

#define ASN1_OCTET_STRING 0x04

Definition at line 78 of file asn1.h.

◆ ASN1_OID

#define ASN1_OID 0x06

Definition at line 80 of file asn1.h.

◆ ASN1_PRIMITIVE

#define ASN1_PRIMITIVE 0x00

Definition at line 91 of file asn1.h.

◆ ASN1_PRINTABLE_STRING

#define ASN1_PRINTABLE_STRING 0x13

Definition at line 84 of file asn1.h.

◆ ASN1_SEQUENCE

#define ASN1_SEQUENCE 0x10

Definition at line 82 of file asn1.h.

◆ ASN1_SET

#define ASN1_SET 0x11

Definition at line 83 of file asn1.h.

◆ ASN1_T61_STRING

#define ASN1_T61_STRING 0x14

Definition at line 85 of file asn1.h.

◆ ASN1_UNIVERSAL_STRING

#define ASN1_UNIVERSAL_STRING 0x1C

Definition at line 89 of file asn1.h.

◆ ASN1_UTC_TIME

#define ASN1_UTC_TIME 0x17

Definition at line 87 of file asn1.h.

◆ ASN1_UTF8_STRING

#define ASN1_UTF8_STRING 0x0C

Definition at line 81 of file asn1.h.

◆ OID_CMP

#define OID_CMP	(	oid_str,
		oid_buf
	)

Value:

( ( OID_SIZE(oid_str) == (oid_buf)->len ) && \

memcmp( (oid_str), (oid_buf)->p, (oid_buf)->len) == 0 )

OID_SIZE

#define OID_SIZE(x)

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

Definition: asn1.h:98

Compares an asn1_buf structure to a reference OID.

Only works for 'defined' oid_str values (OID_HMAC_SHA1), you cannot use a 'unsigned char *oid' here!

Warning: returns true when the OIDs are equal (unlike memcmp)!

Definition at line 108 of file asn1.h.

◆ OID_SIZE

#define OID_SIZE ( x ) (sizeof(x) - 1)

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

Definition at line 98 of file asn1.h.

◆ POLARSSL_ERR_ASN1_BUF_TOO_SMALL

#define POLARSSL_ERR_ASN1_BUF_TOO_SMALL -0x006C

Buffer too small when writing ASN.1 data structure.

Definition at line 60 of file asn1.h.

◆ POLARSSL_ERR_ASN1_INVALID_DATA

#define POLARSSL_ERR_ASN1_INVALID_DATA -0x0068

Data is invalid.

(not used)

Definition at line 58 of file asn1.h.

◆ POLARSSL_ERR_ASN1_INVALID_LENGTH

#define POLARSSL_ERR_ASN1_INVALID_LENGTH -0x0064

Error when trying to determine the length or invalid length.

Definition at line 56 of file asn1.h.

◆ POLARSSL_ERR_ASN1_LENGTH_MISMATCH

#define POLARSSL_ERR_ASN1_LENGTH_MISMATCH -0x0066

Actual length differs from expected length.

Definition at line 57 of file asn1.h.

◆ POLARSSL_ERR_ASN1_MALLOC_FAILED

#define POLARSSL_ERR_ASN1_MALLOC_FAILED -0x006A

Memory allocation failed.

Definition at line 59 of file asn1.h.

◆ POLARSSL_ERR_ASN1_OUT_OF_DATA

#define POLARSSL_ERR_ASN1_OUT_OF_DATA -0x0060

Out of data when parsing an ASN1 data structure.

Definition at line 54 of file asn1.h.

◆ POLARSSL_ERR_ASN1_UNEXPECTED_TAG

#define POLARSSL_ERR_ASN1_UNEXPECTED_TAG -0x0062

ASN1 tag was of an unexpected value.

Definition at line 55 of file asn1.h.

Typedef Documentation

◆ asn1_bitstring

typedef struct _asn1_bitstring asn1_bitstring

Container for ASN1 bit strings.

◆ asn1_buf

typedef struct _asn1_buf asn1_buf

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

◆ asn1_named_data

typedef struct _asn1_named_data asn1_named_data

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

◆ asn1_sequence

typedef struct _asn1_sequence asn1_sequence

Container for a sequence of ASN.1 items.

Function Documentation

◆ asn1_find_named_data()

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

◆ asn1_free_named_data()

void asn1_free_named_data ( asn1_named_data * entry )

Free a asn1_named_data entry.

Parameters

entry The named data entry to free

◆ asn1_free_named_data_list()

void asn1_free_named_data_list ( asn1_named_data ** head )

Free all entries in a 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

◆ asn1_get_alg()

int asn1_get_alg	(	unsigned char **	p,
		const unsigned char *	end,
		asn1_buf *	alg,
		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.

◆ asn1_get_alg_null()

int asn1_get_alg_null	(	unsigned char **	p,
		const unsigned char *	end,
		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.

◆ asn1_get_bitstring()

int asn1_get_bitstring	(	unsigned char **	p,
		const unsigned char *	end,
		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.

◆ asn1_get_bitstring_null()

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

◆ asn1_get_bool()

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

◆ asn1_get_int()

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

◆ asn1_get_len()

int 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, POLARSSL_ERR_ASN1_OUT_OF_DATA on reaching end of data, POLARSSL_ERR_ASN1_INVALID_LENGTH if length is unparseable.

◆ asn1_get_mpi()

int asn1_get_mpi	(	unsigned char **	p,
		const unsigned char *	end,
		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.

◆ asn1_get_sequence_of()

int asn1_get_sequence_of	(	unsigned char **	p,
		const unsigned char *	end,
		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.

◆ asn1_get_tag()

int 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, POLARSSL_ERR_ASN1_UNEXPECTED_TAG if tag did not match requested tag, or another specific ASN.1 error code.

Variable Documentation

◆ buf

asn1_buf _asn1_sequence::buf

Buffer containing the given ASN.1 item.

Definition at line 148 of file asn1.h.

◆ len [1/2]

size_t _asn1_buf::len

ASN1 length, e.g.

in octets.

Definition at line 127 of file asn1.h.

◆ len [2/2]

size_t _asn1_bitstring::len

ASN1 length, e.g.

in octets.

Definition at line 137 of file asn1.h.

◆ next [1/2]

struct _asn1_sequence* _asn1_sequence::next

The next entry in the sequence.

Definition at line 149 of file asn1.h.

◆ next [2/2]

struct _asn1_named_data* _asn1_named_data::next

The next entry in the sequence.

Definition at line 160 of file asn1.h.

◆ oid

asn1_buf _asn1_named_data::oid

The object identifier.

Definition at line 158 of file asn1.h.

◆ p [1/2]

unsigned char* _asn1_buf::p

ASN1 data, e.g.

in ASCII.

Definition at line 128 of file asn1.h.

◆ p [2/2]

unsigned char* _asn1_bitstring::p

Raw ASN1 data for the bit string.

Definition at line 139 of file asn1.h.

◆ tag

int _asn1_buf::tag

ASN1 type, e.g.

ASN1_UTF8_STRING.

Definition at line 126 of file asn1.h.

◆ unused_bits

unsigned char _asn1_bitstring::unused_bits

Number of unused bits at the end of the string.

Definition at line 138 of file asn1.h.

◆ val

asn1_buf _asn1_named_data::val

The named value.

Definition at line 159 of file asn1.h.

Data Structures

Variables

Functions to parse ASN.1 data structures

ASN1 Error codes

DER constants

Detailed Description

Macro Definition Documentation

◆ ASN1_BIT_STRING

◆ ASN1_BMP_STRING

◆ ASN1_BOOLEAN

◆ ASN1_CONSTRUCTED

◆ ASN1_CONTEXT_SPECIFIC

◆ ASN1_GENERALIZED_TIME

◆ ASN1_IA5_STRING

◆ ASN1_INTEGER

◆ ASN1_NULL

◆ ASN1_OCTET_STRING

◆ ASN1_OID

◆ ASN1_PRIMITIVE

◆ ASN1_PRINTABLE_STRING

◆ ASN1_SEQUENCE

◆ ASN1_SET

◆ ASN1_T61_STRING

◆ ASN1_UNIVERSAL_STRING

◆ ASN1_UTC_TIME

◆ ASN1_UTF8_STRING

◆ OID_CMP

◆ OID_SIZE

◆ POLARSSL_ERR_ASN1_BUF_TOO_SMALL

◆ POLARSSL_ERR_ASN1_INVALID_DATA

◆ POLARSSL_ERR_ASN1_INVALID_LENGTH

◆ POLARSSL_ERR_ASN1_LENGTH_MISMATCH

◆ POLARSSL_ERR_ASN1_MALLOC_FAILED

◆ POLARSSL_ERR_ASN1_OUT_OF_DATA

◆ POLARSSL_ERR_ASN1_UNEXPECTED_TAG

Typedef Documentation

◆ asn1_bitstring

◆ asn1_buf

◆ asn1_named_data

◆ asn1_sequence

Function Documentation

◆ asn1_find_named_data()

◆ asn1_free_named_data()

◆ asn1_free_named_data_list()

◆ asn1_get_alg()

◆ asn1_get_alg_null()

◆ asn1_get_bitstring()

◆ asn1_get_bitstring_null()

◆ asn1_get_bool()

◆ asn1_get_int()

◆ asn1_get_len()

◆ asn1_get_mpi()

◆ asn1_get_sequence_of()

◆ asn1_get_tag()

Variable Documentation

◆ buf

◆ len [1/2]

◆ len [2/2]

◆ next [1/2]

◆ next [2/2]

◆ oid

◆ p [1/2]

◆ p [2/2]

◆ tag

◆ unused_bits

◆ val