doc/texi/decoding.c.texi

   1 @subheading asn1_get_length_der
   2 @anchor{asn1_get_length_der}
   3 @deftypefun {long} {asn1_get_length_der} (const unsigned char * @var{der}, int @var{der_len}, int * @var{len})
   4 @var{der}: DER data to decode.
   5
   6 @var{der_len}: Length of DER data to decode.
   7
   8 @var{len}: Output variable containing the length of the DER length field.
   9
  10 Extract a length field from DER data.
  11
  12 @strong{Returns:} Return the decoded length value, or -1 on indefinite
  13 length, or -2 when the value was too big to fit in a int, or -4
  14 when the decoded length value plus  @code{len} would exceed  @code{der_len} .
  15 @end deftypefun
  16
  17 @subheading asn1_get_tag_der
  18 @anchor{asn1_get_tag_der}
  19 @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})
  20 @var{der}: DER data to decode.
  21
  22 @var{der_len}: Length of DER data to decode.
  23
  24 @var{cls}: Output variable containing decoded class.
  25
  26 @var{len}: Output variable containing the length of the DER TAG data.
  27
  28 @var{tag}: Output variable containing the decoded tag.
  29
  30 Decode the class and TAG from DER code.
  31
  32 @strong{Returns:} Returns @code{ASN1_SUCCESS}  on success, or an error.
  33 @end deftypefun
  34
  35 @subheading asn1_get_length_ber
  36 @anchor{asn1_get_length_ber}
  37 @deftypefun {long} {asn1_get_length_ber} (const unsigned char * @var{ber}, int @var{ber_len}, int * @var{len})
  38 @var{ber}: BER data to decode.
  39
  40 @var{ber_len}: Length of BER data to decode.
  41
  42 @var{len}: Output variable containing the length of the BER length field.
  43
  44 Extract a length field from BER data.  The difference to
  45 @code{asn1_get_length_der()}  is that this function will return a length
  46 even if the value has indefinite encoding.
  47
  48 @strong{Returns:} Return the decoded length value, or negative value when
  49 the value was too big.
  50
  51 @strong{Since:} 2.0
  52 @end deftypefun
  53
  54 @subheading asn1_get_octet_der
  55 @anchor{asn1_get_octet_der}
  56 @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})
  57 @var{der}: DER data to decode containing the OCTET SEQUENCE.
  58
  59 @var{der_len}: The length of the  @code{der} data to decode.
  60
  61 @var{ret_len}: Output variable containing the encoded length of the DER data.
  62
  63 @var{str}: Pre-allocated output buffer to put decoded OCTET SEQUENCE in.
  64
  65 @var{str_size}: Length of pre-allocated output buffer.
  66
  67 @var{str_len}: Output variable containing the length of the contents of the OCTET SEQUENCE.
  68
  69 Extract an OCTET SEQUENCE from DER data. Note that this function
  70 expects the DER data past the tag field, i.e., the length and
  71 content octets.
  72
  73 @strong{Returns:} Returns @code{ASN1_SUCCESS}  on success, or an error.
  74 @end deftypefun
  75
  76 @subheading asn1_get_object_id_der
  77 @anchor{asn1_get_object_id_der}
  78 @deftypefun {int} {asn1_get_object_id_der} (const unsigned char * @var{der}, int @var{der_len}, int * @var{ret_len}, char * @var{str}, int @var{str_size})
  79 @var{der}: DER data to decode containing the OBJECT IDENTIFIER
  80
  81 @var{der_len}: Length of DER data to decode.
  82
  83 @var{ret_len}: Output variable containing the length of the DER data.
  84
  85 @var{str}: Pre-allocated output buffer to put the textual object id in.
  86
  87 @var{str_size}: Length of pre-allocated output buffer.
  88
  89 Converts a DER encoded object identifier to its textual form.
  90
  91 @strong{Returns:} @code{ASN1_SUCCESS}  on success, or an error.
  92 @end deftypefun
  93
  94 @subheading asn1_get_bit_der
  95 @anchor{asn1_get_bit_der}
  96 @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})
  97 @var{der}: DER data to decode containing the BIT SEQUENCE.
  98
  99 @var{der_len}: Length of DER data to decode.
 100
 101 @var{ret_len}: Output variable containing the length of the DER data.
 102
 103 @var{str}: Pre-allocated output buffer to put decoded BIT SEQUENCE in.
 104
 105 @var{str_size}: Length of pre-allocated output buffer.
 106
 107 @var{bit_len}: Output variable containing the size of the BIT SEQUENCE.
 108
 109 Extract a BIT SEQUENCE from DER data.
 110
 111 @strong{Returns:} @code{ASN1_SUCCESS}  on success, or an error.
 112 @end deftypefun
 113
 114 @subheading asn1_der_decoding2
 115 @anchor{asn1_der_decoding2}
 116 @deftypefun {int} {asn1_der_decoding2} (asn1_node * @var{element}, const void * @var{ider}, int * @var{max_ider_len}, unsigned int @var{flags}, char * @var{errorDescription})
 117 @var{element}: pointer to an ASN1 structure.
 118
 119 @var{ider}: vector that contains the DER encoding.
 120
 121 @var{max_ider_len}: pointer to an integer giving the information about the
 122 maximal number of bytes occupied by * @code{ider} . The real size of the DER
 123 encoding is returned through this pointer.
 124
 125 @var{flags}: flags controlling the behaviour of the function.
 126
 127 @var{errorDescription}: null-terminated string contains details when an
 128 error occurred.
 129
 130 Fill the structure * @code{element} with values of a DER encoding string. The
 131 structure must just be created with function @code{asn1_create_element()} .
 132
 133 If @code{ASN1_DECODE_FLAG_ALLOW_PADDING}  flag is set then the function will ignore
 134 padding after the decoded DER data. Upon a successful return the value of
 135 * @code{max_ider_len} will be set to the number of bytes decoded.
 136
 137 If @code{ASN1_DECODE_FLAG_STRICT_DER}  flag is set then the function will
 138 not decode any BER-encoded elements.
 139
 140 @strong{Returns:} @code{ASN1_SUCCESS}  if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
 141 if  @code{ELEMENT} is @code{NULL} , and @code{ASN1_TAG_ERROR}  or
 142 @code{ASN1_DER_ERROR}  if the der encoding doesn't match the structure
 143 name (* @code{ELEMENT} deleted).
 144 @end deftypefun
 145
 146 @subheading asn1_der_decoding
 147 @anchor{asn1_der_decoding}
 148 @deftypefun {int} {asn1_der_decoding} (asn1_node * @var{element}, const void * @var{ider}, int @var{ider_len}, char * @var{errorDescription})
 149 @var{element}: pointer to an ASN1 structure.
 150
 151 @var{ider}: vector that contains the DER encoding.
 152
 153 @var{ider_len}: number of bytes of * @code{ider} :  @code{ider} [0].. @code{ider} [len-1].
 154
 155 @var{errorDescription}: null-terminated string contains details when an
 156 error occurred.
 157
 158 Fill the structure * @code{element} with values of a DER encoding
 159 string. The structure must just be created with function
 160 @code{asn1_create_element()} .
 161
 162 Note that the * @code{element} variable is provided as a pointer for
 163 historical reasons.
 164
 165 @strong{Returns:} @code{ASN1_SUCCESS}  if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
 166 if  @code{ELEMENT} is @code{NULL} , and @code{ASN1_TAG_ERROR}  or
 167 @code{ASN1_DER_ERROR}  if the der encoding doesn't match the structure
 168 name (* @code{ELEMENT} deleted).
 169 @end deftypefun
 170
 171 @subheading asn1_der_decoding_element
 172 @anchor{asn1_der_decoding_element}
 173 @deftypefun {int} {asn1_der_decoding_element} (asn1_node * @var{structure}, const char * @var{elementName}, const void * @var{ider}, int @var{len}, char * @var{errorDescription})
 174 @var{structure}: pointer to an ASN1 structure
 175
 176 @var{elementName}: name of the element to fill
 177
 178 @var{ider}: vector that contains the DER encoding of the whole structure.
 179
 180 @var{len}: number of bytes of *der: der[0]..der[len-1]
 181
 182 @var{errorDescription}: null-terminated string contains details when an
 183 error occurred.
 184
 185 Fill the element named  @code{ELEMENTNAME} with values of a DER encoding
 186 string.  The structure must just be created with function
 187 @code{asn1_create_element()} .  The DER vector must contain the encoding
 188 string of the whole  @code{STRUCTURE} .  If an error occurs during the
 189 decoding procedure, the * @code{STRUCTURE} is deleted and set equal to
 190 @code{NULL} .
 191
 192 This function is deprecated and may just be an alias to asn1_der_decoding
 193 in future versions. Use @code{asn1_der_decoding()}  instead.
 194
 195 @strong{Returns:} @code{ASN1_SUCCESS}  if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
 196 if ELEMENT is @code{NULL}  or  @code{elementName} == NULL, and
 197 @code{ASN1_TAG_ERROR}  or @code{ASN1_DER_ERROR}  if the der encoding doesn't
 198 match the structure  @code{structure} (*ELEMENT deleted).
 199 @end deftypefun
 200
 201 @subheading asn1_der_decoding_startEnd
 202 @anchor{asn1_der_decoding_startEnd}
 203 @deftypefun {int} {asn1_der_decoding_startEnd} (asn1_node @var{element}, const void * @var{ider}, int @var{ider_len}, const char * @var{name_element}, int * @var{start}, int * @var{end})
 204 @var{element}: pointer to an ASN1 element
 205
 206 @var{ider}: vector that contains the DER encoding.
 207
 208 @var{ider_len}: number of bytes of * @code{ider} :  @code{ider} [0].. @code{ider} [len-1]
 209
 210 @var{name_element}: an element of NAME structure.
 211
 212 @var{start}: the position of the first byte of NAME_ELEMENT decoding
 213 ( @code{ider} [*start])
 214
 215 @var{end}: the position of the last byte of NAME_ELEMENT decoding
 216 ( @code{ider} [*end])
 217
 218 Find the start and end point of an element in a DER encoding
 219 string. I mean that if you have a der encoding and you have already
 220 used the function @code{asn1_der_decoding()}  to fill a structure, it may
 221 happen that you want to find the piece of string concerning an
 222 element of the structure.
 223
 224 One example is the sequence "tbsCertificate" inside an X509
 225 certificate.
 226
 227 Note that since libtasn1 3.7 the  @code{ider} and  @code{ider_len} parameters
 228 can be omitted, if the element is already decoded using @code{asn1_der_decoding()} .
 229
 230 @strong{Returns:} @code{ASN1_SUCCESS}  if DER encoding OK, @code{ASN1_ELEMENT_NOT_FOUND}
 231 if ELEMENT is @code{asn1_node}  EMPTY or  @code{name_element} is not a valid
 232 element, @code{ASN1_TAG_ERROR}  or @code{ASN1_DER_ERROR}  if the der encoding
 233 doesn't match the structure ELEMENT.
 234 @end deftypefun
 235
 236 @subheading asn1_expand_any_defined_by
 237 @anchor{asn1_expand_any_defined_by}
 238 @deftypefun {int} {asn1_expand_any_defined_by} (asn1_node @var{definitions}, asn1_node * @var{element})
 239 @var{definitions}: ASN1 definitions
 240
 241 @var{element}: pointer to an ASN1 structure
 242
 243 Expands every "ANY DEFINED BY" element of a structure created from
 244 a DER decoding process (asn1_der_decoding function). The element
 245 ANY must be defined by an OBJECT IDENTIFIER. The type used to
 246 expand the element ANY is the first one following the definition of
 247 the actual value of the OBJECT IDENTIFIER.
 248
 249 @strong{Returns:} @code{ASN1_SUCCESS}  if Substitution OK, @code{ASN1_ERROR_TYPE_ANY}  if
 250 some "ANY DEFINED BY" element couldn't be expanded due to a
 251 problem in OBJECT_ID -> TYPE association, or other error codes
 252 depending on DER decoding.
 253 @end deftypefun
 254
 255 @subheading asn1_expand_octet_string
 256 @anchor{asn1_expand_octet_string}
 257 @deftypefun {int} {asn1_expand_octet_string} (asn1_node @var{definitions}, asn1_node * @var{element}, const char * @var{octetName}, const char * @var{objectName})
 258 @var{definitions}: ASN1 definitions
 259
 260 @var{element}: pointer to an ASN1 structure
 261
 262 @var{octetName}: name of the OCTECT STRING field to expand.
 263
 264 @var{objectName}: name of the OBJECT IDENTIFIER field to use to define
 265 the type for expansion.
 266
 267 Expands an "OCTET STRING" element of a structure created from a DER
 268 decoding process (the @code{asn1_der_decoding()}  function).  The type used
 269 for expansion is the first one following the definition of the
 270 actual value of the OBJECT IDENTIFIER indicated by OBJECTNAME.
 271
 272 @strong{Returns:} @code{ASN1_SUCCESS}  if substitution OK, @code{ASN1_ELEMENT_NOT_FOUND}
 273 if  @code{objectName} or  @code{octetName} are not correct,
 274 @code{ASN1_VALUE_NOT_VALID}  if it wasn't possible to find the type to
 275 use for expansion, or other errors depending on DER decoding.
 276 @end deftypefun
 277
 278 @subheading asn1_decode_simple_der
 279 @anchor{asn1_decode_simple_der}
 280 @deftypefun {int} {asn1_decode_simple_der} (unsigned int @var{etype}, const unsigned char * @var{der}, unsigned int @var{_der_len}, const unsigned char ** @var{str}, unsigned int * @var{str_len})
 281 @var{etype}: The type of the string to be encoded (ASN1_ETYPE_)
 282
 283 @var{der}: the encoded string
 284
 285 @var{_der_len}: the bytes of the encoded string
 286
 287 @var{str}: a pointer to the data
 288
 289 @var{str_len}: the length of the data
 290
 291 Decodes a simple DER encoded type (e.g. a string, which is not constructed).
 292 The output is a pointer inside the  @code{der} .
 293
 294 @strong{Returns:} @code{ASN1_SUCCESS}  if successful or an error value.
 295 @end deftypefun
 296
 297 @subheading asn1_decode_simple_ber
 298 @anchor{asn1_decode_simple_ber}
 299 @deftypefun {int} {asn1_decode_simple_ber} (unsigned int @var{etype}, const unsigned char * @var{der}, unsigned int @var{_der_len}, unsigned char ** @var{str}, unsigned int * @var{str_len}, unsigned int * @var{ber_len})
 300 @var{etype}: The type of the string to be encoded (ASN1_ETYPE_)
 301
 302 @var{der}: the encoded string
 303
 304 @var{_der_len}: the bytes of the encoded string
 305
 306 @var{str}: a pointer to the data
 307
 308 @var{str_len}: the length of the data
 309
 310 @var{ber_len}: the total length occupied by BER (may be @code{NULL} )
 311
 312 Decodes a BER encoded type. The output is an allocated value
 313 of the data. This decodes BER STRINGS only. Other types are
 314 decoded as DER.
 315
 316 @strong{Returns:} @code{ASN1_SUCCESS}  if successful or an error value.
 317 @end deftypefun
 318