doc/texi/decoding.c.texi

   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.
   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.
  14 @end deftypefun
  15
  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.
  20
  21 @var{der_len}: Length of DER data to decode.
  22
  23 @var{cls}: Output variable containing decoded class.
  24
  25 @var{len}: Output variable containing the length of the DER TAG data.
  26
  27 @var{tag}: Output variable containing the decoded tag.
  28
  29 Decode the class and TAG from DER code.
  30
  31 @strong{Returns:} Returns @code{ASN1_SUCCESS} on success, or an error.
  32 @end deftypefun
  33
  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.
  38
  39 @var{ber_len}: Length of BER data to decode.
  40
  41 @var{len}: Output variable containing the length of the BER length field.
  42
  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.
  46
  47 @strong{Returns:} Return the decoded length value, or negative value when
  48 the value was too big.
  49
  50 @strong{Since:} 2.0
  51 @end deftypefun
  52
  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.
  57
  58 @var{der_len}: Length of DER data to decode.
  59
  60 @var{ret_len}: Output variable containing the length of the DER data.
  61
  62 @var{str}: Pre-allocated output buffer to put decoded OCTET SEQUENCE in.
  63
  64 @var{str_size}: Length of pre-allocated output buffer.
  65
  66 @var{str_len}: Output variable containing the length of the OCTET SEQUENCE.
  67
  68 Extract an OCTET SEQUENCE from DER data.
  69
  70 @strong{Returns:} Returns @code{ASN1_SUCCESS} on success, or an error.
  71 @end deftypefun
  72
  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.
  77
  78 @var{der_len}: Length of DER data to decode.
  79
  80 @var{ret_len}: Output variable containing the length of the DER data.
  81
  82 @var{str}: Pre-allocated output buffer to put decoded BIT SEQUENCE in.
  83
  84 @var{str_size}: Length of pre-allocated output buffer.
  85
  86 @var{bit_len}: Output variable containing the size of the BIT SEQUENCE.
  87
  88 Extract a BIT SEQUENCE from DER data.
  89
  90 @strong{Returns:} Return @code{ASN1_SUCCESS} on success, or an error.
  91 @end deftypefun
  92
  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.
  97
  98 @var{ider}: vector that contains the DER encoding.
  99
 100 @var{len}: number of bytes of *@code{ider}: @code{ider}[0]..@code{ider}[len-1].
 101
 102 @var{errorDescription}: null-terminated string contains details when an
 103 error occurred.
 104
 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}.
 110
 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).
 115 @end deftypefun
 116
 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
 121
 122 @var{elementName}: name of the element to fill
 123
 124 @var{ider}: vector that contains the DER encoding of the whole structure.
 125
 126 @var{len}: number of bytes of *der: der[0]..der[len-1]
 127
 128 @var{errorDescription}: null-terminated string contains details when an
 129 error occurred.
 130
 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}.
 137
 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).
 142 @end deftypefun
 143
 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
 148
 149 @var{ider}: vector that contains the DER encoding.
 150
 151 @var{len}: number of bytes of *@code{ider}: @code{ider}[0]..@code{ider}[len-1]
 152
 153 @var{name_element}: an element of NAME structure.
 154
 155 @var{start}: the position of the first byte of NAME_ELEMENT decoding
 156 (@code{ider}[*start])
 157
 158 @var{end}: the position of the last byte of NAME_ELEMENT decoding
 159 (@code{ider}[*end])
 160
 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.
 166
 167 One example is the sequence "tbsCertificate" inside an X509
 168 certificate.
 169
 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.
 174 @end deftypefun
 175
 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
 180
 181 @var{element}: pointer to an ASN1 structure
 182
 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.
 188
 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.
 193 @end deftypefun
 194
 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
 199
 200 @var{element}: pointer to an ASN1 structure
 201
 202 @var{octetName}: name of the OCTECT STRING field to expand.
 203
 204 @var{objectName}: name of the OBJECT IDENTIFIER field to use to define
 205 the type for expansion.
 206
 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.
 211
 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.
 216 @end deftypefun
 217