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

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