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

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