asn1.h File Reference

Generic ASN.1 parsing. More...

#include "config.h"
#include <string.h>
Include dependency graph for asn1.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Defines

#define OID_SIZE(x)   (sizeof(x) - 1)
 Returns the size of the binary string, without the trailing \0.
#define OID_CMP(oid_str, oid_buf)
 Compares two asn1_buf structures for the same OID.
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.
#define POLARSSL_ERR_ASN1_UNEXPECTED_TAG   -0x0062
 ASN1 tag was of an unexpected value.
#define POLARSSL_ERR_ASN1_INVALID_LENGTH   -0x0064
 Error when trying to determine the length or invalid length.
#define POLARSSL_ERR_ASN1_LENGTH_MISMATCH   -0x0066
 Actual length differs from expected length.
#define POLARSSL_ERR_ASN1_INVALID_DATA   -0x0068
 Data is invalid.
#define POLARSSL_ERR_ASN1_MALLOC_FAILED   -0x006A
 Memory allocation failed.
#define POLARSSL_ERR_ASN1_BUF_TOO_SMALL   -0x006C
 Buffer too small when writing ASN.1 data structure.
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

Functions to parse ASN.1 data structures



typedef struct _asn1_buf asn1_buf
 Type-length-value structure that allows for ASN1 using DER.
typedef struct _asn1_bitstring asn1_bitstring
 Container for ASN1 bit strings.
typedef struct _asn1_sequence asn1_sequence
 Container for a sequence of ASN.1 items.
typedef struct _asn1_named_data asn1_named_data
 Container for a sequence or list of 'named' ASN.1 data items.
int asn1_get_len (unsigned char **p, const unsigned char *end, size_t *len)
 Get the length of an ASN.1 element.
int asn1_get_tag (unsigned char **p, const unsigned char *end, size_t *len, int tag)
 Get the tag and length of the tag.
int asn1_get_bool (unsigned char **p, const unsigned char *end, int *val)
 Retrieve a boolean ASN.1 tag and its value.
int asn1_get_int (unsigned char **p, const unsigned char *end, int *val)
 Retrieve an integer ASN.1 tag and its value.
int asn1_get_bitstring (unsigned char **p, const unsigned char *end, asn1_bitstring *bs)
 Retrieve a bitstring ASN.1 tag and its value.
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.
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.
int asn1_get_alg (unsigned char **p, const unsigned char *end, asn1_buf *alg, asn1_buf *params)
 Retrieve an AlgorithmIdentifier ASN.1 sequence.
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.
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.
void asn1_free_named_data (asn1_named_data *entry)
 Free a asn1_named_data entry.
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.

Detailed Description

Generic ASN.1 parsing.

Copyright (C) 2006-2013, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Definition in file asn1.h.

Define Documentation

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

Compares two asn1_buf structures for the same OID.

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

Definition at line 100 of file asn1.h.

Referenced by pk_parse_key_pkcs8_encrypted_der(), pkcs5_parse_pbkdf2_params(), pkcs5_pbes2(), and x509_crt_verify().

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

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

Definition at line 94 of file asn1.h.

Referenced by x509_write_name(), x509write_crt_set_authority_key_identifier(), x509write_crt_set_basic_constraints(), x509write_crt_set_key_usage(), x509write_crt_set_ns_cert_type(), x509write_crt_set_subject_key_identifier(), x509write_csr_der(), x509write_csr_set_key_usage(), and x509write_csr_set_ns_cert_type().

Typedef Documentation

typedef struct _asn1_bitstring asn1_bitstring

Container for ASN1 bit strings.

typedef struct _asn1_buf asn1_buf

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

typedef struct _asn1_named_data asn1_named_data

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

typedef struct _asn1_sequence asn1_sequence

Container for a sequence of ASN.1 items.

Function Documentation

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.

Definition at line 371 of file asn1parse.c.

References _asn1_buf::len, _asn1_named_data::next, _asn1_named_data::oid, and _asn1_buf::p.

Referenced by asn1_store_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

Definition at line 348 of file asn1parse.c.

References _asn1_named_data::oid, _asn1_buf::p, polarssl_free, and _asn1_named_data::val.

Referenced by 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

Definition at line 359 of file asn1parse.c.

References asn1_free_named_data(), _asn1_named_data::next, and polarssl_free.

Referenced by x509_string_to_names(), x509write_crt_free(), and x509write_csr_free().

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.

Definition at line 286 of file asn1parse.c.

References ASN1_CONSTRUCTED, asn1_get_len(), asn1_get_tag(), ASN1_OID, ASN1_SEQUENCE, _asn1_buf::len, _asn1_buf::p, POLARSSL_ERR_ASN1_LENGTH_MISMATCH, POLARSSL_ERR_ASN1_OUT_OF_DATA, and _asn1_buf::tag.

Referenced by asn1_get_alg_null(), pk_get_pk_alg(), pk_parse_key_pkcs8_encrypted_der(), and pkcs5_pbes2().

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.

Definition at line 330 of file asn1parse.c.

References asn1_get_alg(), ASN1_NULL, _asn1_buf::len, POLARSSL_ERR_ASN1_INVALID_DATA, and _asn1_buf::tag.

Referenced by pkcs5_parse_pbkdf2_params(), and x509_get_alg_null().

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.

Definition at line 182 of file asn1parse.c.

References ASN1_BIT_STRING, asn1_get_tag(), _asn1_bitstring::len, _asn1_bitstring::p, POLARSSL_ERR_ASN1_INVALID_LENGTH, POLARSSL_ERR_ASN1_LENGTH_MISMATCH, POLARSSL_ERR_ASN1_OUT_OF_DATA, and _asn1_bitstring::unused_bits.

Referenced by x509_get_key_usage(), and x509_get_ns_cert_type().

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.

Definition at line 215 of file asn1parse.c.

References ASN1_BIT_STRING, asn1_get_tag(), and POLARSSL_ERR_ASN1_INVALID_DATA.

Referenced by pk_parse_key_sec1_der(), pk_parse_subpubkey(), and x509_get_sig().

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.

Definition at line 120 of file asn1parse.c.

References ASN1_BOOLEAN, asn1_get_tag(), and POLARSSL_ERR_ASN1_INVALID_LENGTH.

Referenced by x509_get_basic_constraints(), and x509_get_crt_ext().

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.

Definition at line 139 of file asn1parse.c.

References asn1_get_tag(), ASN1_INTEGER, and POLARSSL_ERR_ASN1_INVALID_LENGTH.

Referenced by pk_parse_key_pkcs1_der(), pk_parse_key_pkcs8_unencrypted_der(), pk_parse_key_sec1_der(), pkcs12_parse_pbe_params(), pkcs5_parse_pbkdf2_params(), x509_crl_get_version(), x509_csr_get_version(), x509_get_basic_constraints(), and x509_get_version().

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.

Definition at line 49 of file asn1parse.c.

References POLARSSL_ERR_ASN1_INVALID_LENGTH, and POLARSSL_ERR_ASN1_OUT_OF_DATA.

Referenced by asn1_get_alg(), asn1_get_tag(), x509_get_attr_type_value(), x509_get_serial(), x509_get_subject_alt_name(), and x509_get_time().

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.

Definition at line 234 of file asn1parse.c.

References ASN1_CONSTRUCTED, asn1_get_tag(), ASN1_SEQUENCE, _asn1_sequence::buf, _asn1_buf::len, _asn1_sequence::next, _asn1_buf::p, POLARSSL_ERR_ASN1_LENGTH_MISMATCH, POLARSSL_ERR_ASN1_MALLOC_FAILED, polarssl_malloc, and _asn1_buf::tag.

Referenced by x509_get_ext_key_usage().

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.

Definition at line 105 of file asn1parse.c.

References asn1_get_len(), POLARSSL_ERR_ASN1_OUT_OF_DATA, and POLARSSL_ERR_ASN1_UNEXPECTED_TAG.

Referenced by asn1_get_alg(), asn1_get_bitstring(), asn1_get_bitstring_null(), asn1_get_bool(), asn1_get_int(), asn1_get_mpi(), asn1_get_sequence_of(), dhm_parse_dhm(), ecdsa_read_signature(), pk_get_ecparams(), pk_get_rsapubkey(), pk_parse_key_pkcs1_der(), pk_parse_key_pkcs8_encrypted_der(), pk_parse_key_pkcs8_unencrypted_der(), pk_parse_key_sec1_der(), pk_parse_subpubkey(), pkcs12_parse_pbe_params(), pkcs5_parse_pbkdf2_params(), rsa_rsassa_pkcs1_v15_verify(), x509_crl_parse(), x509_crt_parse_der_core(), x509_csr_parse(), x509_get_attr_type_value(), x509_get_basic_constraints(), x509_get_crl_entry_ext(), x509_get_crl_ext(), x509_get_crt_ext(), x509_get_dates(), x509_get_entries(), x509_get_ext(), x509_get_name(), x509_get_subject_alt_name(), x509_get_uid(), and x509_get_version().

Generated on 20 Jan 2015 for PolarSSL v1.3.2 by  doxygen 1.6.1