GNU Libtasn1 3.1: DER functions

4.3 DER functions

asn1_length_der

Function: void asn1_length_der (unsigned long int len, unsigned char * der, int * der_len)

len: value to convert.

der: the encoding (may be NULL).

der_len: number of meaningful bytes of ANS (der[0]..der[der_len-1]).

Creates the DER encoding of the provided length value. The der buffer must have enough room for the output. The maximum length this function will encode is ASN1_MAX_LENGTH_SIZE.

To know the size of the DER encoding use a NULL value for der.

asn1_octet_der

Function: void asn1_octet_der (const unsigned char * str, int str_len, unsigned char * der, int * der_len)

str: the input data.

str_len: STR length (str[0]..str[*str_len-1]).

der: encoded string returned.

der_len: number of meaningful bytes of DER (der[0]..der[der_len-1]).

Creates a length-value DER encoding for the input data. The DER encoding of the input data will be placed in the der variable.

Note that the OCTET STRING tag is not included in the output.

This function does not return any value because it is expected that der_len will contain enough bytes to store the string plus the DER encoding. The DER encoding size can be obtained using asn1_length_der().

asn1_encode_simple_der

Function: int asn1_encode_simple_der (unsigned int etype, const unsigned char * str, unsigned int str_len, unsigned char * tl, unsigned int * tl_len)

etype: The type of the string to be encoded (ASN1_ETYPE_)

str: the string data.

str_len: the string length

tl: the encoded tag and length

tl_len: the bytes of the tl field

Creates the DER encoding for various simple ASN.1 types like strings etc. It stores the tag and length in tl, which should have space for at least ASN1_MAX_TL_SIZE bytes. Initially tl_len should contain the size of tl.

The complete DER encoding should consist of the value in tl appended with the provided str.

Returns: ASN1_SUCCESS if successful or an error value.

asn1_bit_der

Function: void asn1_bit_der (const unsigned char * str, int bit_len, unsigned char * der, int * der_len)

str: BIT string.

bit_len: number of meaningful bits in STR.

der: string returned.

der_len: number of meaningful bytes of DER (der[0]..der[ans_len-1]).

Creates a length-value DER encoding for the input data as it would have been for a BIT STRING. The DER encoded data will be copied in der.

Note that the BIT STRING tag is not included in the output.

asn1_der_coding

Function: int asn1_der_coding (asn1_node element, const char * name, void * ider, int * len, char * ErrorDescription)

element: pointer to an ASN1 element

name: the name of the structure you want to encode (it must be inside *POINTER).

ider: vector that will contain the DER encoding. DER must be a pointer to memory cells already allocated.

len: number of bytes of *ider: ider[0]..ider[len-1], Initialy holds the sizeof of der vector.

Creates the DER encoding for the NAME structure (inside *POINTER structure).

Returns: ASN1_SUCCESS if DER encoding OK, ASN1_ELEMENT_NOT_FOUND if name is not a valid element, ASN1_VALUE_NOT_FOUND if there is an element without a value, ASN1_MEM_ERROR if the ider vector isn’t big enough and in this case len will contain the length needed.

asn1_get_length_der

Function: long asn1_get_length_der (const unsigned char * der, int der_len, int * len)

der: DER data to decode.

der_len: Length of DER data to decode.

len: Output variable containing the length of the DER length field.

Extract a length field from DER data.

Returns: Return the decoded length value, or -1 on indefinite length, or -2 when the value was too big to fit in a int, or -4 when the decoded length value plus len would exceed der_len.

asn1_get_tag_der

Function: int asn1_get_tag_der (const unsigned char * der, int der_len, unsigned char * cls, int * len, unsigned long * tag)

der: DER data to decode.

der_len: Length of DER data to decode.

cls: Output variable containing decoded class.

len: Output variable containing the length of the DER TAG data.

tag: Output variable containing the decoded tag.

Decode the class and TAG from DER code.

Returns: Returns ASN1_SUCCESS on success, or an error.

asn1_get_length_ber

Function: long asn1_get_length_ber (const unsigned char * ber, int ber_len, int * len)

ber: BER data to decode.

ber_len: Length of BER data to decode.

len: Output variable containing the length of the BER length field.

Extract a length field from BER data. The difference to asn1_get_length_der() is that this function will return a length even if the value has indefinite encoding.

Returns: Return the decoded length value, or negative value when the value was too big.

Since: 2.0

asn1_get_octet_der

Function: int asn1_get_octet_der (const unsigned char * der, int der_len, int * ret_len, unsigned char * str, int str_size, int * str_len)

der: DER data to decode containing the OCTET SEQUENCE.

der_len: Length of DER data to decode.

ret_len: Output variable containing the length of the DER data.

str: Pre-allocated output buffer to put decoded OCTET SEQUENCE in.

str_size: Length of pre-allocated output buffer.

str_len: Output variable containing the length of the OCTET SEQUENCE.

Extract an OCTET SEQUENCE from DER data.

Returns: Returns ASN1_SUCCESS on success, or an error.

asn1_get_bit_der

Function: int asn1_get_bit_der (const unsigned char * der, int der_len, int * ret_len, unsigned char * str, int str_size, int * bit_len)

der: DER data to decode containing the BIT SEQUENCE.

der_len: Length of DER data to decode.

ret_len: Output variable containing the length of the DER data.

str: Pre-allocated output buffer to put decoded BIT SEQUENCE in.

str_size: Length of pre-allocated output buffer.

bit_len: Output variable containing the size of the BIT SEQUENCE.

Extract a BIT SEQUENCE from DER data.

Returns: Return ASN1_SUCCESS on success, or an error.

asn1_der_decoding

Function: int asn1_der_decoding (asn1_node * element, const void * ider, int len, char * errorDescription)

element: pointer to an ASN1 structure.

ider: vector that contains the DER encoding.

len: number of bytes of *ider: ider[0]..ider[len-1].

errorDescription: null-terminated string contains details when an error occurred.

Fill the structure *ELEMENT with values of a DER encoding string. The structure must just be created with function asn1_create_element(). If an error occurs during the decoding procedure, the *ELEMENT is deleted and set equal to NULL.

Returns: ASN1_SUCCESS if DER encoding OK, ASN1_ELEMENT_NOT_FOUND if ELEMENT is NULL, and ASN1_TAG_ERROR or ASN1_DER_ERROR if the der encoding doesn’t match the structure name (*ELEMENT deleted).

asn1_der_decoding_element

Function: int asn1_der_decoding_element (asn1_node * structure, const char * elementName, const void * ider, int len, char * errorDescription)

structure: pointer to an ASN1 structure

elementName: name of the element to fill

ider: vector that contains the DER encoding of the whole structure.

len: number of bytes of *der: der[0]..der[len-1]

errorDescription: null-terminated string contains details when an error occurred.

Fill the element named ELEMENTNAME with values of a DER encoding string. The structure must just be created with function asn1_create_element(). The DER vector must contain the encoding string of the whole STRUCTURE. If an error occurs during the decoding procedure, the *STRUCTURE is deleted and set equal to NULL.

Returns: ASN1_SUCCESS if DER encoding OK, ASN1_ELEMENT_NOT_FOUND if ELEMENT is NULL or elementName == NULL, and ASN1_TAG_ERROR or ASN1_DER_ERROR if the der encoding doesn’t match the structure structure (*ELEMENT deleted).

asn1_der_decoding_startEnd

Function: int asn1_der_decoding_startEnd (asn1_node element, const void * ider, int len, const char * name_element, int * start, int * end)

element: pointer to an ASN1 element

ider: vector that contains the DER encoding.

len: number of bytes of *ider: ider[0]..ider[len-1]

name_element: an element of NAME structure.

start: the position of the first byte of NAME_ELEMENT decoding (ider[*start])

end: the position of the last byte of NAME_ELEMENT decoding (ider[*end])

Find the start and end point of an element in a DER encoding string. I mean that if you have a der encoding and you have already used the function asn1_der_decoding() to fill a structure, it may happen that you want to find the piece of string concerning an element of the structure.

One example is the sequence "tbsCertificate" inside an X509 certificate.

Returns: ASN1_SUCCESS if DER encoding OK, ASN1_ELEMENT_NOT_FOUND if ELEMENT is asn1_node EMPTY or name_element is not a valid element, ASN1_TAG_ERROR or ASN1_DER_ERROR if the der encoding doesn’t match the structure ELEMENT.

asn1_expand_any_defined_by

Function: int asn1_expand_any_defined_by (asn1_node definitions, asn1_node * element)

definitions: ASN1 definitions

element: pointer to an ASN1 structure

Expands every "ANY DEFINED BY" element of a structure created from a DER decoding process (asn1_der_decoding function). The element ANY must be defined by an OBJECT IDENTIFIER. The type used to expand the element ANY is the first one following the definition of the actual value of the OBJECT IDENTIFIER.

Returns: ASN1_SUCCESS if Substitution OK, ASN1_ERROR_TYPE_ANY if some "ANY DEFINED BY" element couldn’t be expanded due to a problem in OBJECT_ID -> TYPE association, or other error codes depending on DER decoding.

asn1_expand_octet_string

Function: int asn1_expand_octet_string (asn1_node definitions, asn1_node * element, const char * octetName, const char * objectName)

definitions: ASN1 definitions

element: pointer to an ASN1 structure

octetName: name of the OCTECT STRING field to expand.

objectName: name of the OBJECT IDENTIFIER field to use to define the type for expansion.

Expands an "OCTET STRING" element of a structure created from a DER decoding process (the asn1_der_decoding() function). The type used for expansion is the first one following the definition of the actual value of the OBJECT IDENTIFIER indicated by OBJECTNAME.

Returns: ASN1_SUCCESS if substitution OK, ASN1_ELEMENT_NOT_FOUND if objectName or octetName are not correct, ASN1_VALUE_NOT_VALID if it wasn’t possible to find the type to use for expansion, or other errors depending on DER decoding.

asn1_decode_simple_der

Function: int asn1_decode_simple_der (unsigned int etype, const unsigned char * der, unsigned int der_len, const unsigned char ** str, unsigned int * str_len)

etype: The type of the string to be encoded (ASN1_ETYPE_)

der: the encoded string

der_len: the bytes of the encoded string

str: a pointer to the data

str_len: the length of the data

Decodes a simple DER encoded type (e.g. a string, which is not constructed). The output is a pointer inside the der.

Returns: ASN1_SUCCESS if successful or an error value.