1 @subheading asn1_get_length_der
2 @anchor{asn1_get_length_der}
3 @deftypefun {signed long} {asn1_get_length_der} (const unsigned char * @var{der}, int @var{der_len}, int * @var{len})
4 @var{der}: DER data to decode.
6 @var{der_len}: Length of DER data to decode.
8 @var{len}: Output variable containing the length of the DER length field.
10 Extract a length field from DER data.
12 @strong{Returns:} Return the decoded length value, or -1 on indefinite
13 length, or -2 when the value was too big.
16 @subheading asn1_get_tag_der
17 @anchor{asn1_get_tag_der}
18 @deftypefun {int} {asn1_get_tag_der} (const unsigned char * @var{der}, int @var{der_len}, unsigned char * @var{cls}, int * @var{len}, unsigned long * @var{tag})
19 @var{der}: DER data to decode.
21 @var{der_len}: Length of DER data to decode.
23 @var{cls}: Output variable containing decoded class.
25 @var{len}: Output variable containing the length of the DER TAG data.
27 @var{tag}: Output variable containing the decoded tag.
29 Decode the class and TAG from DER code.
31 @strong{Returns:} Returns @code{ASN1_SUCCESS} on success, or an error.
34 @subheading asn1_get_length_ber
35 @anchor{asn1_get_length_ber}
36 @deftypefun {signed long} {asn1_get_length_ber} (const unsigned char * @var{ber}, int @var{ber_len}, int * @var{len})
37 @var{ber}: BER data to decode.
39 @var{ber_len}: Length of BER data to decode.
41 @var{len}: Output variable containing the length of the BER length field.
43 Extract a length field from BER data. The difference to
44 @code{asn1_get_length_der()} is that this function will return a length
45 even if the value has indefinite encoding.
47 @strong{Returns:} Return the decoded length value, or negative value when
48 the value was too big.
53 @subheading asn1_get_octet_der
54 @anchor{asn1_get_octet_der}
55 @deftypefun {int} {asn1_get_octet_der} (const unsigned char * @var{der}, int @var{der_len}, int * @var{ret_len}, unsigned char * @var{str}, int @var{str_size}, int * @var{str_len})
56 @var{der}: DER data to decode containing the OCTET SEQUENCE.
58 @var{der_len}: Length of DER data to decode.
60 @var{ret_len}: Output variable containing the length of the DER data.
62 @var{str}: Pre-allocated output buffer to put decoded OCTET SEQUENCE in.
64 @var{str_size}: Length of pre-allocated output buffer.
66 @var{str_len}: Output variable containing the length of the OCTET SEQUENCE.
68 Extract an OCTET SEQUENCE from DER data.
70 @strong{Returns:} Returns @code{ASN1_SUCCESS} on success, or an error.
73 @subheading asn1_get_bit_der
74 @anchor{asn1_get_bit_der}
75 @deftypefun {int} {asn1_get_bit_der} (const unsigned char * @var{der}, int @var{der_len}, int * @var{ret_len}, unsigned char * @var{str}, int @var{str_size}, int * @var{bit_len})
76 @var{der}: DER data to decode containing the BIT SEQUENCE.
78 @var{der_len}: Length of DER data to decode.
80 @var{ret_len}: Output variable containing the length of the DER data.
82 @var{str}: Pre-allocated output buffer to put decoded BIT SEQUENCE in.
84 @var{str_size}: Length of pre-allocated output buffer.
86 @var{bit_len}: Output variable containing the size of the BIT SEQUENCE.
88 Extract a BIT SEQUENCE from DER data.
90 @strong{Returns:} Return @code{ASN1_SUCCESS} on success, or an error.
93 @subheading asn1_der_decoding
94 @anchor{asn1_der_decoding}
95 @deftypefun {asn1_retCode} {asn1_der_decoding} (ASN1_TYPE * @var{element}, const void * @var{ider}, int @var{len}, char * @var{errorDescription})
96 @var{element}: pointer to an ASN1 structure.
98 @var{ider}: vector that contains the DER encoding.
100 @var{len}: number of bytes of *@code{ider}: @code{ider}[0]..@code{ider}[len-1].
102 @var{errorDescription}: null-terminated string contains details when an
105 Fill the structure *@code{ELEMENT} with values of a DER encoding
106 string. The structure must just be created with function
107 @code{asn1_create_element()}. If an error occurs during the decoding
108 procedure, the *@code{ELEMENT} is deleted and set equal to
109 @code{ASN1_TYPE_EMPTY}.
111 @strong{Returns:} @code{ASN1_SUCCESS} if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
112 if @code{ELEMENT} is @code{ASN1_TYPE_EMPTY}, and @code{ASN1_TAG_ERROR} or
113 @code{ASN1_DER_ERROR} if the der encoding doesn't match the structure
114 name (*@code{ELEMENT} deleted).
117 @subheading asn1_der_decoding_element
118 @anchor{asn1_der_decoding_element}
119 @deftypefun {asn1_retCode} {asn1_der_decoding_element} (ASN1_TYPE * @var{structure}, const char * @var{elementName}, const void * @var{ider}, int @var{len}, char * @var{errorDescription})
120 @var{structure}: pointer to an ASN1 structure
122 @var{elementName}: name of the element to fill
124 @var{ider}: vector that contains the DER encoding of the whole structure.
126 @var{len}: number of bytes of *der: der[0]..der[len-1]
128 @var{errorDescription}: null-terminated string contains details when an
131 Fill the element named @code{ELEMENTNAME} with values of a DER encoding
132 string. The structure must just be created with function
133 @code{asn1_create_element()}. The DER vector must contain the encoding
134 string of the whole @code{STRUCTURE}. If an error occurs during the
135 decoding procedure, the *@code{STRUCTURE} is deleted and set equal to
136 @code{ASN1_TYPE_EMPTY}.
138 @strong{Returns:} @code{ASN1_SUCCESS} if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
139 if ELEMENT is @code{ASN1_TYPE_EMPTY} or @code{elementName} == NULL, and
140 @code{ASN1_TAG_ERROR} or @code{ASN1_DER_ERROR} if the der encoding doesn't
141 match the structure @code{structure} (*ELEMENT deleted).
144 @subheading asn1_der_decoding_startEnd
145 @anchor{asn1_der_decoding_startEnd}
146 @deftypefun {asn1_retCode} {asn1_der_decoding_startEnd} (ASN1_TYPE @var{element}, const void * @var{ider}, int @var{len}, const char * @var{name_element}, int * @var{start}, int * @var{end})
147 @var{element}: pointer to an ASN1 element
149 @var{ider}: vector that contains the DER encoding.
151 @var{len}: number of bytes of *@code{ider}: @code{ider}[0]..@code{ider}[len-1]
153 @var{name_element}: an element of NAME structure.
155 @var{start}: the position of the first byte of NAME_ELEMENT decoding
156 (@code{ider}[*start])
158 @var{end}: the position of the last byte of NAME_ELEMENT decoding
161 Find the start and end point of an element in a DER encoding
162 string. I mean that if you have a der encoding and you have already
163 used the function @code{asn1_der_decoding()} to fill a structure, it may
164 happen that you want to find the piece of string concerning an
165 element of the structure.
167 One example is the sequence "tbsCertificate" inside an X509
170 @strong{Returns:} @code{ASN1_SUCCESS} if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
171 if ELEMENT is @code{ASN1_TYPE} EMPTY or @code{name_element} is not a valid
172 element, @code{ASN1_TAG_ERROR} or @code{ASN1_DER_ERROR} if the der encoding
173 doesn't match the structure ELEMENT.
176 @subheading asn1_expand_any_defined_by
177 @anchor{asn1_expand_any_defined_by}
178 @deftypefun {asn1_retCode} {asn1_expand_any_defined_by} (ASN1_TYPE @var{definitions}, ASN1_TYPE * @var{element})
179 @var{definitions}: ASN1 definitions
181 @var{element}: pointer to an ASN1 structure
183 Expands every "ANY DEFINED BY" element of a structure created from
184 a DER decoding process (asn1_der_decoding function). The element
185 ANY must be defined by an OBJECT IDENTIFIER. The type used to
186 expand the element ANY is the first one following the definition of
187 the actual value of the OBJECT IDENTIFIER.
189 @strong{Returns:} @code{ASN1_SUCCESS} if Substitution OK, @code{ASN1_ERROR_TYPE_ANY} if
190 some "ANY DEFINED BY" element couldn't be expanded due to a
191 problem in OBJECT_ID -> TYPE association, or other error codes
192 depending on DER decoding.
195 @subheading asn1_expand_octet_string
196 @anchor{asn1_expand_octet_string}
197 @deftypefun {asn1_retCode} {asn1_expand_octet_string} (ASN1_TYPE @var{definitions}, ASN1_TYPE * @var{element}, const char * @var{octetName}, const char * @var{objectName})
198 @var{definitions}: ASN1 definitions
200 @var{element}: pointer to an ASN1 structure
202 @var{octetName}: name of the OCTECT STRING field to expand.
204 @var{objectName}: name of the OBJECT IDENTIFIER field to use to define
205 the type for expansion.
207 Expands an "OCTET STRING" element of a structure created from a DER
208 decoding process (the @code{asn1_der_decoding()} function). The type used
209 for expansion is the first one following the definition of the
210 actual value of the OBJECT IDENTIFIER indicated by OBJECTNAME.
212 @strong{Returns:} @code{ASN1_SUCCESS} if substitution OK, @code{ASN1_ELEMENT_NOT_FOUND}
213 if @code{objectName} or @code{octetName} are not correct,
214 @code{ASN1_VALUE_NOT_VALID} if it wasn't possible to find the type to
215 use for expansion, or other errors depending on DER decoding.