libtasn1: 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: buffer to hold the returned 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.
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_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.
ERRORDESCRIPTION: return the error description or an empty string
if success.
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: The length of the 'der' data to decode.
RET_LEN: Output variable containing the encoded 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 contents of
the OCTET SEQUENCE.
Extract an OCTET SEQUENCE from DER data. Note that this function
expects the DER data past the tag field, i.e., the length and
content octets.
*Returns:* Returns 'ASN1_SUCCESS' on success, or an error.
asn1_get_object_id_der
----------------------
-- Function: int asn1_get_object_id_der (const unsigned char * DER, int
DER_LEN, int * RET_LEN, char * STR, int STR_SIZE)
DER: DER data to decode containing the OBJECT IDENTIFIER
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 the textual object id in.
STR_SIZE: Length of pre-allocated output buffer.
Converts a DER encoded object identifier to its textual form.
*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:* 'ASN1_SUCCESS' on success, or an error.
asn1_der_decoding2
------------------
-- Function: int asn1_der_decoding2 (asn1_node * ELEMENT, const void *
IDER, int * MAX_IDER_LEN, unsigned int FLAGS, char *
ERRORDESCRIPTION)
ELEMENT: pointer to an ASN1 structure.
IDER: vector that contains the DER encoding.
MAX_IDER_LEN: pointer to an integer giving the information about
the maximal number of bytes occupied by * 'ider' . The real size
of the DER encoding is returned through this pointer.
FLAGS: flags controlling the behaviour of the function.
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 'ASN1_DECODE_FLAG_ALLOW_PADDING' flag is set then the function
will ignore padding after the decoded DER data. Upon a successful
return the value of * 'max_ider_len' will be set to the number of
bytes decoded.
If 'ASN1_DECODE_FLAG_STRICT_DER' flag is set then the function will
not decode any BER-encoded elements.
*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
-----------------
-- Function: int asn1_der_decoding (asn1_node * ELEMENT, const void *
IDER, int IDER_LEN, char * ERRORDESCRIPTION)
ELEMENT: pointer to an ASN1 structure.
IDER: vector that contains the DER encoding.
IDER_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()' .
Note that the * 'element' variable is provided as a pointer for
historical reasons.
*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' .
This function is deprecated and may just be an alias to
asn1_der_decoding in future versions. Use 'asn1_der_decoding()'
instead.
*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 IDER_LEN, const char * NAME_ELEMENT, int *
START, int * END)
ELEMENT: pointer to an ASN1 element
IDER: vector that contains the DER encoding.
IDER_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.
Note that since libtasn1 3.7 the 'ider' and 'ider_len' parameters
can be omitted, if the element is already decoded using
'asn1_der_decoding()' .
*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.
asn1_decode_simple_ber
----------------------
-- Function: int asn1_decode_simple_ber (unsigned int ETYPE, const
unsigned char * DER, unsigned int _DER_LEN, unsigned char **
STR, unsigned int * STR_LEN, unsigned int * BER_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
BER_LEN: the total length occupied by BER (may be 'NULL' )
Decodes a BER encoded type. The output is an allocated value of
the data. This decodes BER STRINGS only. Other types are decoded
as DER.
*Returns:* 'ASN1_SUCCESS' if successful or an error value.
Info Catalog
libtasn1: ASN
libtasn1: Function reference
libtasn1: Error handling functions