git.sur5r.net Git - openldap/blob - doc/man/man3/lber-decode.3

   1 .TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int,
   7 ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal,
   8 ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring,
   9 ber_first_element, ber_next_element
  10 \- LBER simplified Basic Encoding Rules library routines for decoding
  11 .SH LIBRARY
  12 OpenLDAP LBER (liblber, -llber)
  13 .SH SYNOPSIS
  14 .B #include <lber.h>
  15 .LP
  16 .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
  17 .LP
  18 .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
  19 .LP
  20 .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
  21 .LP
  22 .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
  23 .LP
  24 .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
  25 .LP
  26 .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
  27 .LP
  28 .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
  29 .LP
  30 .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
  31 .LP
  32 .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
  33 .LP
  34 .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
  35 .LP
  36 .BI "ber_tag_t ber_get_null(BerElement *" ber ");"
  37 .LP
  38 .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
  39 .LP
  40 .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
  41 .LP
  42 .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
  43 .LP
  44 .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
  45 .SH DESCRIPTION
  46 .LP
  47 These routines provide a subroutine interface to a simplified
  48 implementation of the Basic Encoding Rules of ASN.1.  The version
  49 of BER these routines support is the one defined for the LDAP
  50 protocol.  The encoding rules are the same as BER, except that
  51 only definite form lengths are used, and bitstrings and octet strings
  52 are always encoded in primitive form.  This man page
  53 describes the decoding routines in the lber library.  See
  54 .BR lber-encode (3)
  55 for details on the corresponding encoding routines.
  56 Consult
  57 .BR lber-types (3)
  58 for information about types, allocators, and deallocators.
  59 .LP
  60 Normally, the only routines that need to be called by an application
  61 are
  62 .BR ber_get_next ()
  63 to get the next BER element and
  64 .BR ber_scanf ()
  65 to do the actual decoding.  In some cases,
  66 .BR ber_peek_tag ()
  67 may also need to be called in normal usage.  The other routines are
  68 provided for those applications that need more control than
  69 .BR ber_scanf ()
  70 provides.  In
  71 general, these routines return the tag of the element decoded, or
  72 LBER_ERROR if an error occurred.
  73 .LP
  74 The
  75 .BR ber_get_next ()
  76 routine is used to read the next BER element from the given Sockbuf,
  77 \fIsb\fP.  It strips off and returns the leading tag, strips off and
  78 returns the length of the entire element in \fIlen\fP, and sets up
  79 \fIber\fP for subsequent calls to
  80 .BR ber_scanf ()
  81 et al to decode the element. See
  82 .BR lber-sockbuf (3)
  83 for details of the Sockbuf implementation of the \fIsb\fP parameter.
  84 .LP
  85 The
  86 .BR ber_scanf ()
  87 routine is used to decode a BER element in much the same way that
  88 .BR scanf (3)
  89 works.  It reads from \fIber\fP, a pointer to a BerElement
  90 such as returned by
  91 .BR ber_get_next (),
  92 interprets the bytes according to the format string \fIfmt\fP, and stores the
  93 results in its additional arguments.  The format string contains
  94 conversion specifications which are used to direct the interpretation
  95 of the BER element.  The format string can contain the following
  96 characters.
  97 .RS
  98 .LP
  99 .TP 3
 100 .B a
 101 Octet string.  A char ** should be supplied.  Memory is allocated,
 102 filled with the contents of the octet string, null-terminated, and
 103 returned in the parameter.  The caller should free the returned
 104 string using
 105 .BR ber_memfree ().
 106 .TP
 107 .B A
 108 Octet string.  A variant of "\fBa\fP".  A char ** should be supplied.
 109 Memory is allocated, filled with the contents of the octet string,
 110 null-terminated, and returned in the parameter, unless a zero-length
 111 string would result; in that case, the arg is set to NULL.
 112 The caller should free the returned string using
 113 .BR ber_memfree ().
 114 .TP
 115 .B s
 116 Octet string.  A char * buffer should be supplied, followed by a pointer to a
 117 ber_len_t initialized to the size of the buffer.  Upon return, the
 118 null-terminated octet string is put into the buffer, and the
 119 ber_len_t is set to the actual size of the octet string.
 120 .TP
 121 .B O
 122 Octet string.  A struct ber_val ** should be supplied, which upon
 123 return points to a dynamically allocated struct berval
 124 containing the octet string and its length.
 125 The caller should free the returned structure using
 126 .BR ber_bvfree ().
 127 .TP
 128 .B o
 129 Octet string.  A struct ber_val * should be supplied, which upon
 130 return contains the dynamically allocated
 131 octet string and its length.  The caller should free the returned octet
 132 string using
 133 .BR ber_memfree ().
 134 .TP
 135 .B m
 136 Octet string.  A struct ber_val * should be supplied, which upon return
 137 contains the octet string and its length.  The string resides in memory
 138 assigned to the BerElement, and must not be freed by the caller.
 139 .TP
 140 .B b
 141 Boolean.  A pointer to a ber_int_t should be supplied.
 142 .TP
 143 .B e
 144 Enumeration.  A pointer to a ber_int_t should be supplied.
 145 .TP
 146 .B i
 147 Integer.  A pointer to a ber_int_t should be supplied.
 148 .TP
 149 .B B
 150 Bitstring.  A char ** should be supplied which will point to the
 151 dynamically allocated
 152 bits, followed by a ber_len_t *, which will point to the length
 153 (in bits) of the bitstring returned.
 154 .TP
 155 .B n
 156 Null.  No parameter is required.  The element is simply skipped if
 157 it is recognized.
 158 .TP
 159 .B v
 160 Sequence of octet strings.  A char *** should be supplied, which upon
 161 return points to a dynamically allocated null-terminated array of char *'s
 162 containing the octet strings.  NULL is returned if the sequence is empty.
 163 The caller should free the returned array and octet strings using
 164 .BR ber_memvfree ().
 165 .TP
 166 .B V
 167 Sequence of octet strings with lengths.
 168 A struct berval *** should be supplied, which upon
 169 return points to a dynamically allocated null-terminated array of
 170 struct berval *'s
 171 containing the octet strings and their lengths.
 172 NULL is returned if the sequence is empty.
 173 The caller should free the returned structures using
 174 .BR ber_bvecfree ().
 175 .TP
 176 .B W
 177 Sequence of octet strings with lengths.
 178 A BerVarray * should be supplied, which upon
 179 return points to a dynamically allocated array of
 180 struct berval's
 181 containing the octet strings and their lengths. The array is terminated
 182 by a struct berval with a NULL bv_val string pointer.
 183 NULL is returned if the sequence is empty.
 184 The caller should free the returned structures using
 185 .BR ber_bvarray_free ().
 186 .TP
 187 .B M
 188 Sequence of octet strings with lengths.  This is a generalized form
 189 of the previous three formats.
 190 A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
 191 and a ber_len_t (off).
 192 Upon return (ptr) will point to a dynamically allocated array
 193 whose elements are all of size (*len).  A struct berval will be filled
 194 starting at offset (off) in each element.  The strings in each struct
 195 berval reside in memory assigned to the BerElement and must not be
 196 freed by the caller.  The array is terminated by a struct berval
 197 with a NULL bv_val string pointer.  NULL is returned if the sequence
 198 is empty.  The number of elements in the array is also stored
 199 in (*len) on return.  The caller should free the returned array using
 200 .BR ber_memfree ().
 201 .TP
 202 .B l
 203 Length of the next element.  A pointer to a ber_len_t should be supplied.
 204 .TP
 205 .B t
 206 Tag of the next element.  A pointer to a ber_tag_t should be supplied.
 207 .TP
 208 .B T
 209 Skip element and return its tag.  A pointer to a ber_tag_t should be supplied.
 210 .TP
 211 .B x
 212 Skip element.  The next element is skipped.
 213 .TP
 214 .B {
 215 Begin sequence.  No parameter is required.  The initial sequence tag
 216 and length are skipped.
 217 .TP
 218 .B }
 219 End sequence.  No parameter is required and no action is taken.
 220 .TP
 221 .B [
 222 Begin set.  No parameter is required.  The initial set tag
 223 and length are skipped.
 224 .TP
 225 .B ]
 226 End set.  No parameter is required and no action is taken.
 227 .RE
 228 .LP
 229 The
 230 .BR ber_get_int ()
 231 routine tries to interpret the next element as an integer,
 232 returning the result in \fInum\fP.  The tag of whatever it finds is returned
 233 on success, LBER_ERROR (\-1) on failure.
 234 .LP
 235 The
 236 .BR ber_get_stringb ()
 237 routine is used to read an octet string into a
 238 preallocated buffer.  The \fIlen\fP parameter should be initialized to
 239 the size of the buffer, and will contain the length of the octet string
 240 read upon return.  The buffer should be big enough to take the octet
 241 string value plus a terminating NULL byte.
 242 .LP
 243 The
 244 .BR ber_get_stringa ()
 245 routine is used to dynamically allocate space into
 246 which an octet string is read.
 247 The caller should free the returned string using
 248 .BR ber_memfree().
 249 .LP
 250 The
 251 .BR ber_get_stringal ()
 252 routine is used to dynamically allocate space
 253 into which an octet string and its length are read.  It takes a
 254 struct berval **, and returns the result in this parameter.
 255 The caller should free the returned structure using
 256 .BR ber_bvfree().
 257 .LP
 258 The
 259 .BR ber_get_stringbv ()
 260 routine is used to read an octet string and its length into the
 261 provided struct berval *. If the \fIalloc\fP parameter is zero, the string
 262 will reside in memory assigned to the BerElement, and must not be freed
 263 by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
 264 copied into dynamically allocated space which should be returned using
 265 .BR ber_memfree ().
 266 .LP
 267 The
 268 .BR ber_get_null ()
 269 routine is used to read a NULL element.  It returns
 270 the tag of the element it skips over.
 271 .LP
 272 The
 273 .BR ber_get_boolean ()
 274 routine is used to read a boolean value.  It is called the same way that
 275 .BR ber_get_int ()
 276 is called.
 277 .LP
 278 The
 279 .BR ber_get_enum ()
 280 routine is used to read a enumeration value.  It is called the same way that
 281 .BR ber_get_int ()
 282 is called.
 283 .LP
 284 The
 285 .BR ber_get_bitstringa ()
 286 routine is used to read a bitstring value.  It
 287 takes a char ** which will hold the dynamically allocated bits, followed by an
 288 ber_len_t *, which will point to the length (in bits) of the bitstring returned.
 289 The caller should free the returned string using
 290 .BR ber_memfree ().
 291 .LP
 292 The
 293 .BR ber_first_element ()
 294 routine is used to return the tag and length
 295 of the first element in a set or sequence.  It also returns in \fIcookie\fP
 296 a magic cookie parameter that should be passed to subsequent calls to
 297 ber_next_element(), which returns similar information.
 298 .SH EXAMPLES
 299 Assume the variable \fIber\fP contains a lightweight BER encoding of
 300 the following ASN.1 object:
 301 .LP
 302 .nf
 303       AlmostASearchRequest := SEQUENCE {
 304           baseObject      DistinguishedName,
 305           scope           ENUMERATED {
 306               baseObject    (0),
 307               singleLevel   (1),
 308               wholeSubtree  (2)
 309           },
 310           derefAliases    ENUMERATED {
 311               neverDerefaliases   (0),
 312               derefInSearching    (1),
 313               derefFindingBaseObj (2),
 314               alwaysDerefAliases  (3)
 315           },
 316           sizelimit       INTEGER (0 .. 65535),
 317           timelimit       INTEGER (0 .. 65535),
 318           attrsOnly       BOOLEAN,
 319           attributes      SEQUENCE OF AttributeType
 320       }
 321 .fi
 322 .LP
 323 The element can be decoded using
 324 .BR ber_scanf ()
 325 as follows.
 326 .LP
 327 .nf
 328       ber_int_t    scope, deref, size, time, attrsonly;
 329       char   *dn, **attrs;
 330       ber_tag_t tag;
 331
 332       tag = ber_scanf( ber, "{aeeiib{v}}",
 333           &dn, &scope, &deref,
 334           &size, &time, &attrsonly, &attrs );
 335
 336       if( tag == LBER_ERROR ) {
 337               /* error */
 338       } else {
 339               /* success */
 340       }
 341
 342       ber_memfree( dn );
 343       ber_memvfree( attrs );
 344 .fi
 345 .SH ERRORS
 346 If an error occurs during decoding, generally these routines return
 347 LBER_ERROR ((ber_tag_t)\-1).
 348 .LP
 349 .SH NOTES
 350 .LP
 351 The return values for all of these functions are declared in the
 352 .B <lber.h>
 353 header file.  Some routines may dynamically allocate memory
 354 which must be freed by the caller using supplied deallocation routines.
 355 .SH SEE ALSO
 356 .BR lber-encode (3),
 357 .BR lber-memory (3),
 358 .BR lber-sockbuf (3),
 359 .BR lber-types (3)
 360 .SH ACKNOWLEDGEMENTS
 361 .B OpenLDAP
 362 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 363 .B OpenLDAP
 364 is derived from University of Michigan LDAP 3.3 Release.