4.2 ASN.1 field functions

asn1_array2tree

Function: int asn1_array2tree (const asn1_static_node * array, asn1_node * definitions, char * errorDescription)

array: specify the array that contains ASN.1 declarations

definitions: return the pointer to the structure created by *ARRAY ASN.1 declarations

errorDescription: return the error description.

Creates the structures needed to manage the ASN.1 definitions. array is a vector created by asn1_parser2array() .

Returns: ASN1_SUCCESS if structure was created correctly, ASN1_ELEMENT_NOT_EMPTY if * definitions not NULL, ASN1_IDENTIFIER_NOT_FOUND if in the file there is an identifier that is not defined (see errorDescription for more information), ASN1_ARRAY_ERROR if the array pointed by array is wrong.

asn1_delete_structure

Function: int asn1_delete_structure (asn1_node * structure)

structure: pointer to the structure that you want to delete.

Deletes the structure * structure . At the end, * structure is set to NULL.

Returns: ASN1_SUCCESS if successful, ASN1_ELEMENT_NOT_FOUND if * structure was NULL.

asn1_delete_structure2

Function: int asn1_delete_structure2 (asn1_node * structure, unsigned int flags)

structure: pointer to the structure that you want to delete.

flags: additional flags (see ASN1_DELETE_FLAG_ZEROIZE )

Deletes the structure * structure . At the end, * structure is set to NULL.

Returns: ASN1_SUCCESS if successful, ASN1_ELEMENT_NOT_FOUND if * structure was NULL.

asn1_delete_element

Function: int asn1_delete_element (asn1_node structure, const char * element_name)

structure: pointer to the structure that contains the element you want to delete.

element_name: element’s name you want to delete.

Deletes the element named * element_name inside * structure .

Returns: ASN1_SUCCESS if successful, ASN1_ELEMENT_NOT_FOUND if the element_name was not found.

asn1_create_element

Function: int asn1_create_element (asn1_node_const definitions, const char * source_name, asn1_node * element)

definitions: pointer to the structure returned by "parser_asn1" function

source_name: the name of the type of the new structure (must be inside p_structure).

element: pointer to the structure created.

Creates a structure of type source_name . Example using "pkix.asn":

rc = asn1_create_element(cert_def, "PKIX1.Certificate", certptr);

Returns: ASN1_SUCCESS if creation OK, ASN1_ELEMENT_NOT_FOUND if source_name is not known.

asn1_print_structure

Function: void asn1_print_structure (FILE * out, asn1_node_const structure, const char * name, int mode)

out: pointer to the output file (e.g. stdout).

structure: pointer to the structure that you want to visit.

name: an element of the structure

mode: specify how much of the structure to print, can be ASN1_PRINT_NAME , ASN1_PRINT_NAME_TYPE , ASN1_PRINT_NAME_TYPE_VALUE , or ASN1_PRINT_ALL .

Prints on the out file descriptor the structure’s tree starting from the name element inside the structure structure .

asn1_number_of_elements

Function: int asn1_number_of_elements (asn1_node_const element, const char * name, int * num)

element: pointer to the root of an ASN1 structure.

name: the name of a sub-structure of ROOT.

num: pointer to an integer where the result will be stored

Counts the number of elements of a sub-structure called NAME with names equal to "?1","?2", ...

Returns: ASN1_SUCCESS if successful, ASN1_ELEMENT_NOT_FOUND if name is not known, ASN1_GENERIC_ERROR if pointer num is NULL .

asn1_find_structure_from_oid

Function: const char * asn1_find_structure_from_oid (asn1_node_const definitions, const char * oidValue)

definitions: ASN1 definitions

oidValue: value of the OID to search (e.g. "1.2.3.4").

Search the structure that is defined just after an OID definition.

Returns: NULL when oidValue not found, otherwise the pointer to a constant string that contains the element name defined just after the OID.

asn1_copy_node

Function: int asn1_copy_node (asn1_node dst, const char * dst_name, asn1_node_const src, const char * src_name)

dst: Destination asn1 node.

dst_name: Field name in destination node.

src: Source asn1 node.

src_name: Field name in source node.

Create a deep copy of a asn1_node variable. That function requires dst to be expanded using asn1_create_element() .

Returns: Return ASN1_SUCCESS on success.

asn1_dup_node

Function: asn1_node asn1_dup_node (asn1_node_const src, const char * src_name)

src: Source asn1 node.

src_name: Field name in source node.

Create a deep copy of a asn1_node variable. This function will return an exact copy of the provided structure.

Returns: Return NULL on failure.

asn1_write_value

Function: int asn1_write_value (asn1_node node_root, const char * name, const void * ivalue, int len)

node_root: pointer to a structure

name: the name of the element inside the structure that you want to set.

ivalue: vector used to specify the value to set. If len is >0, VALUE must be a two’s complement form integer. if len=0 *VALUE must be a null terminated string with an integer value.

len: number of bytes of *value to use to set the value: value[0]..value[len-1] or 0 if value is a null terminated string

Set the value of one element inside a structure.

If an element is OPTIONAL and you want to delete it, you must use the value=NULL and len=0. Using "pkix.asn":

result=asn1_write_value(cert, "tbsCertificate.issuerUniqueID", NULL, 0);

Description for each type:

INTEGER: VALUE must contain a two’s complement form integer.

value[0]=0xFF , len=1 -> integer=-1. value[0]=0xFF value[1]=0xFF , len=2 -> integer=-1. value[0]=0x01 , len=1 -> integer= 1. value[0]=0x00 value[1]=0x01 , len=2 -> integer= 1. value="123" , len=0 -> integer= 123.

ENUMERATED: As INTEGER (but only with not negative numbers).

BOOLEAN: VALUE must be the null terminated string "TRUE" or "FALSE" and LEN != 0.

value="TRUE" , len=1 -> boolean=TRUE. value="FALSE" , len=1 -> boolean=FALSE.

OBJECT IDENTIFIER: VALUE must be a null terminated string with each number separated by a dot (e.g. "1.2.3.543.1"). LEN != 0.

value="1 2 840 10040 4 3" , len=1 -> OID=dsa-with-sha.

UTCTime: VALUE must be a null terminated string in one of these formats: "YYMMDDhhmmssZ", "YYMMDDhhmmssZ", "YYMMDDhhmmss+hh’mm’", "YYMMDDhhmmss-hh’mm’", "YYMMDDhhmm+hh’mm’", or "YYMMDDhhmm-hh’mm’". LEN != 0.

value="9801011200Z" , len=1 -> time=Jannuary 1st, 1998 at 12h 00m Greenwich Mean Time

GeneralizedTime: VALUE must be in one of this format: "YYYYMMDDhhmmss.sZ", "YYYYMMDDhhmmss.sZ", "YYYYMMDDhhmmss.s+hh’mm’", "YYYYMMDDhhmmss.s-hh’mm’", "YYYYMMDDhhmm+hh’mm’", or "YYYYMMDDhhmm-hh’mm’" where ss.s indicates the seconds with any precision like "10.1" or "01.02". LEN != 0

value="2001010112001.12-0700" , len=1 -> time=Jannuary 1st, 2001 at 12h 00m 01.12s Pacific Daylight Time

OCTET STRING: VALUE contains the octet string and LEN is the number of octets.

value="$\backslash$x01$\backslash$x02$\backslash$x03" , len=3 -> three bytes octet string

GeneralString: VALUE contains the generalstring and LEN is the number of octets.

value="$\backslash$x01$\backslash$x02$\backslash$x03" , len=3 -> three bytes generalstring

BIT STRING: VALUE contains the bit string organized by bytes and LEN is the number of bits.

value="$\backslash$xCF" , len=6 -> bit string="110011" (six bits)

CHOICE: if NAME indicates a choice type, VALUE must specify one of the alternatives with a null terminated string. LEN != 0. Using "pkix.asn"\:

result=asn1_write_value(cert, "certificate1.tbsCertificate.subject", "rdnSequence", 1);

ANY: VALUE indicates the der encoding of a structure. LEN != 0.

SEQUENCE OF: VALUE must be the null terminated string "NEW" and LEN != 0. With this instruction another element is appended in the sequence. The name of this element will be "?1" if it’s the first one, "?2" for the second and so on.

Using "pkix.asn"\:

result=asn1_write_value(cert, "certificate1.tbsCertificate.subject.rdnSequence", "NEW", 1);

SET OF: the same as SEQUENCE OF. Using "pkix.asn":

result=asn1_write_value(cert, "tbsCertificate.subject.rdnSequence.?LAST", "NEW", 1);

Returns: ASN1_SUCCESS if the value was set, ASN1_ELEMENT_NOT_FOUND if name is not a valid element, and ASN1_VALUE_NOT_VALID if ivalue has a wrong format.

asn1_read_value

Function: int asn1_read_value (asn1_node_const root, const char * name, void * ivalue, int * len)

root: pointer to a structure.

name: the name of the element inside a structure that you want to read.

ivalue: vector that will contain the element’s content, must be a pointer to memory cells already allocated (may be NULL ).

len: number of bytes of *value: value[0]..value[len-1]. Initially holds the sizeof value.

Returns the value of one element inside a structure. If an element is OPTIONAL and this returns ASN1_ELEMENT_NOT_FOUND , it means that this element wasn’t present in the der encoding that created the structure. The first element of a SEQUENCE_OF or SET_OF is named "?1". The second one "?2" and so on. If the root provided is a node to specific sequence element, then the keyword "?CURRENT" is also acceptable and indicates the current sequence element of this node.

Note that there can be valid values with length zero. In these case this function will succeed and len will be zero.

INTEGER: VALUE will contain a two’s complement form integer.

integer=-1 -> value[0]=0xFF , len=1. integer=1 -> value[0]=0x01 , len=1.

ENUMERATED: As INTEGER (but only with not negative numbers).

BOOLEAN: VALUE will be the null terminated string "TRUE" or "FALSE" and LEN=5 or LEN=6.

OBJECT IDENTIFIER: VALUE will be a null terminated string with each number separated by a dot (i.e. "1.2.3.543.1").

LEN = strlen(VALUE)+1

UTCTime: VALUE will be a null terminated string in one of these formats: "YYMMDDhhmmss+hh’mm’" or "YYMMDDhhmmss-hh’mm’". LEN=strlen(VALUE)+1.

GeneralizedTime: VALUE will be a null terminated string in the same format used to set the value.

OCTET STRING: VALUE will contain the octet string and LEN will be the number of octets.

GeneralString: VALUE will contain the generalstring and LEN will be the number of octets.

BIT STRING: VALUE will contain the bit string organized by bytes and LEN will be the number of bits.

CHOICE: If NAME indicates a choice type, VALUE will specify the alternative selected.

ANY: If NAME indicates an any type, VALUE will indicate the DER encoding of the structure actually used.

Returns: ASN1_SUCCESS if value is returned, ASN1_ELEMENT_NOT_FOUND if name is not a valid element, ASN1_VALUE_NOT_FOUND if there isn’t any value for the element selected, and ASN1_MEM_ERROR if The value vector isn’t big enough to store the result, and in this case len will contain the number of bytes needed. On the occasion that the stored data are of zero-length this function may return ASN1_SUCCESS even if the provided len is zero.

asn1_read_value_type

Function: int asn1_read_value_type (asn1_node_const root, const char * name, void * ivalue, int * len, unsigned int * etype)

root: pointer to a structure.

name: the name of the element inside a structure that you want to read.

ivalue: vector that will contain the element’s content, must be a pointer to memory cells already allocated (may be NULL ).

len: number of bytes of *value: value[0]..value[len-1]. Initially holds the sizeof value.

etype: The type of the value read (ASN1_ETYPE)

Returns the type and value of one element inside a structure. If an element is OPTIONAL and this returns ASN1_ELEMENT_NOT_FOUND , it means that this element wasn’t present in the der encoding that created the structure. The first element of a SEQUENCE_OF or SET_OF is named "?1". The second one "?2" and so on. If the root provided is a node to specific sequence element, then the keyword "?CURRENT" is also acceptable and indicates the current sequence element of this node.

Note that there can be valid values with length zero. In these case this function will succeed and len will be zero.

INTEGER: VALUE will contain a two’s complement form integer.

integer=-1 -> value[0]=0xFF , len=1. integer=1 -> value[0]=0x01 , len=1.

ENUMERATED: As INTEGER (but only with not negative numbers).

BOOLEAN: VALUE will be the null terminated string "TRUE" or "FALSE" and LEN=5 or LEN=6.

OBJECT IDENTIFIER: VALUE will be a null terminated string with each number separated by a dot (i.e. "1.2.3.543.1").

LEN = strlen(VALUE)+1

UTCTime: VALUE will be a null terminated string in one of these formats: "YYMMDDhhmmss+hh’mm’" or "YYMMDDhhmmss-hh’mm’". LEN=strlen(VALUE)+1.

GeneralizedTime: VALUE will be a null terminated string in the same format used to set the value.

OCTET STRING: VALUE will contain the octet string and LEN will be the number of octets.

GeneralString: VALUE will contain the generalstring and LEN will be the number of octets.

BIT STRING: VALUE will contain the bit string organized by bytes and LEN will be the number of bits.

CHOICE: If NAME indicates a choice type, VALUE will specify the alternative selected.

ANY: If NAME indicates an any type, VALUE will indicate the DER encoding of the structure actually used.

Returns: ASN1_SUCCESS if value is returned, ASN1_ELEMENT_NOT_FOUND if name is not a valid element, ASN1_VALUE_NOT_FOUND if there isn’t any value for the element selected, and ASN1_MEM_ERROR if The value vector isn’t big enough to store the result, and in this case len will contain the number of bytes needed. On the occasion that the stored data are of zero-length this function may return ASN1_SUCCESS even if the provided len is zero.

asn1_read_tag

Function: int asn1_read_tag (asn1_node_const root, const char * name, int * tagValue, int * classValue)

root: pointer to a structure

name: the name of the element inside a structure.

tagValue: variable that will contain the TAG value.

classValue: variable that will specify the TAG type.

Returns the TAG and the CLASS of one element inside a structure. CLASS can have one of these constants: ASN1_CLASS_APPLICATION , ASN1_CLASS_UNIVERSAL , ASN1_CLASS_PRIVATE or ASN1_CLASS_CONTEXT_SPECIFIC .

Returns: ASN1_SUCCESS if successful, ASN1_ELEMENT_NOT_FOUND if name is not a valid element.

asn1_read_node_value

Function: int asn1_read_node_value (asn1_node_const node, asn1_data_node_st * data)

node: pointer to a node.

data: a point to a asn1_data_node_st

Returns the value a data node inside a asn1_node structure. The data returned should be handled as constant values.

Returns: ASN1_SUCCESS if the node exists.