usr/src/man/man3ldap/ber_decode.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH BER_DECODE 3LDAP "May 15, 2009"
   8 .SH NAME
   9 ber_decode, ber_alloc_t, ber_free, ber_bvdup, ber_init, ber_flatten,
  10 ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int,
  11 ber_get_stringa, ber_get_stringal, ber_get_stringb, ber_get_null,
  12 ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element,
  13 ber_bvfree, ber_bvecfree \- Basic Encoding Rules library decoding functions
  14 .SH SYNOPSIS
  15 .LP
  16 .nf
  17 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  18 #include <lber.h>
  19
  20 \fBBerElement *\fR\fBber_alloc_t\fR(\fBint\fR \fIoptions\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBstruct berval *\fR\fBber_bvdup\fR(\fBconst struct berval *\fR\fIbv\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBvoid\fR \fBber_free\fR(\fBBerElement *\fR\fIber\fR, \fBint\fR \fIfreebuf\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBBerElement *\fR\fBber_init\fR(\fBconst struct berval *\fR\fIbv\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBber_flatten\fR(\fBBerElement *\fR\fIber\fR, \fBstruct berval **\fR\fIbvPtr\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBber_tag_t\fR\fBber_get_next\fR(\fBSockbuf *\fR\fIsb\fR, \fBber_len_t *\fR\fIlen\fR, \fBBerElement *\fR\fIber\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBber_tag_t\fR \fBber_skip_tag\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBber_tag_t\fR \fBber_peek_tag\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBber_tag_t\fR \fBber_get_int\fR(\fBBerElement *\fR\fIber\fR, \fBber_int_t *\fR\fInum\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBber_tag_t\fR \fBber_get_stringb\fR(\fBBerElement *\fR\fIber\fR, \fBchar *\fR\fIbuf\fR,
  66      \fBber_len_t *\fR\fIlen\fR);
  67 .fi
  68
  69 .LP
  70 .nf
  71 \fBber_tag_t\fR \fBber_get_stringa\fR(\fBBerElement *\fR\fIber\fR, \fBchar **\fR\fIbuf\fR);
  72 .fi
  73
  74 .LP
  75 .nf
  76 \fBber_tag_t\fR \fBber_get_stringal\fR(\fBBerElement *\fR\fIber\fR, \fBstruct berval **\fR\fIbv\fR);
  77 .fi
  78
  79 .LP
  80 .nf
  81 \fBber_tag_t\fR \fBber_get_null\fR(\fBBerElement *\fR\fIber\fR);
  82 .fi
  83
  84 .LP
  85 .nf
  86 \fBber_tag_t\fR \fBber_get_boolean\fR(\fBBerElement *\fR\fIber\fR, \fBint *\fR\fIboolval\fR);
  87 .fi
  88
  89 .LP
  90 .nf
  91 \fBber_tag_t\fR \fBber_get_bitstringa\fR(\fBBerElement *\fR\fIber\fR, \fBchar **\fR\fIbuf\fR,
  92      \fBber_len_t *\fR\fIlen\fR);
  93 .fi
  94
  95 .LP
  96 .nf
  97 \fBber_tag_t\fR \fBber_first_element\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR,
  98      \fBchar **\fR\fIlast\fR);
  99 .fi
 100
 101 .LP
 102 .nf
 103 \fBber_tag_t\fR \fBber_next_element\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR,
 104      \fBchar *\fR\fIlast\fR);
 105 .fi
 106
 107 .LP
 108 .nf
 109 \fBber_tag_t\fR \fBber_scanf\fR(\fBBerElement *\fR\fIber\fR, \fBconst char *\fR\fIfmt\fR [, arg...]);
 110 .fi
 111
 112 .LP
 113 .nf
 114 \fBvoid\fR \fBber_bvfree\fR(\fBstruct berval *\fR\fIbv\fR);
 115 .fi
 116
 117 .LP
 118 .nf
 119 \fBvoid\fR \fBber_bvecfree\fR(\fBstruct berval **\fR\fIbvec\fR);
 120 .fi
 121
 122 .SH DESCRIPTION
 123 .sp
 124 .LP
 125 These functions provide a subfunction interface to a simplified implementation
 126 of the Basic Encoding Rules of ASN.1.  The version of BER these functions
 127 support is the one defined for the LDAP protocol.  The encoding rules are the
 128 same as BER, except that  only definite form lengths are used, and bitstrings
 129 and octet strings are always encoded in primitive form.  In addition, these
 130 lightweight BER functions restrict tags and class to fit in a single octet
 131 (this means the actual tag must be less than 31). When a "tag"is specified in
 132 the descriptions below, it refers to the tag, class, and primitive or
 133 constructed bit in the first octet of the encoding.  This man page describes
 134 the decoding functions in the lber library.  See  \fBber_encode\fR(3LDAP) for
 135 details on the corresponding encoding functions.
 136 .sp
 137 .LP
 138 Normally, the only functions that need be called by an application are
 139 \fBber_get_next()\fR to get the next BER element and  \fBber_scanf()\fR to do
 140 the actual decoding.  In some cases,  \fBber_peek_tag()\fR may also need to be
 141 called in normal usage. The other functions are provided for those applications
 142 that need more control than  \fBber_scanf()\fR provides. In general, these
 143 functions return the tag of the element decoded, or \fB\(mi1\fR if an error
 144 occurred.
 145 .sp
 146 .LP
 147 The  \fBber_get_next()\fR function is used to read the next BER element from
 148 the given \fBSockbuf\fR, \fIsb\fR.  A \fBSockbuf\fR consists of the descriptor
 149 (usually socket, but a file descriptor works just as well) from which to read,
 150 and a \fBBerElement\fR structure used to maintain a buffer.  On the first call,
 151 the \fIsb_ber\fR struct should be zeroed.  It strips off and returns the
 152 leading tag byte, strips off and returns the length of the entire element in
 153 \fIlen\fR, and sets up \fIber\fR for subsequent calls to  \fBber_scanf()\fR,
 154 and all to decode the element.
 155 .sp
 156 .LP
 157 The \fBber_peek_tag()\fR function returns the tag of the next element to be
 158 parsed in the \fBBerElement\fR argument. The length of this element is stored
 159 in the *\fIlenPtr\fR argument. \fBLBER_DEFAULT\fR is returned if there is no
 160 further data to be read. The decoding position within the \fIber\fR argument is
 161 unchanged by this call; that is, the fact that \fBber_peek_tag()\fR has been
 162 called does not affect future use of \fIber\fR.
 163 .sp
 164 .LP
 165 The \fBber_skip_tag()\fR function is similar to \fBber_peek_tag()\fR, except
 166 that the state pointer in the \fBBerElement\fR argument is advanced past the
 167 first tag and length, and is pointed to the value part of the next element.
 168 This function should only be used with constructed types and situations when a
 169 BER encoding is used as the value of an OCTET STRING.  The length of the value
 170 is stored in *\fIlenPtr\fR.
 171 .sp
 172 .LP
 173 The  \fBber_scanf()\fR function is used to decode a BER element in much the
 174 same way that  \fBscanf\fR(3C) works.  It reads from \fIber\fR, a pointer to a
 175 \fBBerElement\fR such as returned by \fBber_get_next()\fR, interprets the bytes
 176 according to the format string \fBfmt\fR, and stores the results in its
 177 additional arguments.  The format string contains conversion specifications
 178 which are used to direct the interpretation of the BER element.  The format
 179 string can contain the following characters.
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBa\fR\fR
 184 .ad
 185 .RS 5n
 186 Octet string.  A char ** should be supplied.  Memory is allocated, filled with
 187 the contents of the octet string, null-terminated, and returned in the
 188 parameter.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fBs\fR\fR
 195 .ad
 196 .RS 5n
 197 Octet string.  A char * buffer should be supplied, followed by a pointer to an
 198 integer initialized to the size of the buffer.  Upon return, the
 199 null-terminated octet string is put into the buffer, and the integer is set to
 200 the actual size of the octet string.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBO\fR\fR
 207 .ad
 208 .RS 5n
 209 Octet string.  A struct ber_val ** should be supplied, which upon return points
 210 to a memory allocated struct berval containing the octet string and its length.
 211 \fBber_bvfree()\fR can be called to free the allocated memory.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBb\fR\fR
 218 .ad
 219 .RS 5n
 220 Boolean.  A pointer to an integer should be supplied.
 221 .RE
 222
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBi\fR\fR
 227 .ad
 228 .RS 5n
 229 Integer.  A pointer to an integer should be supplied.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBB\fR\fR
 236 .ad
 237 .RS 5n
 238 Bitstring.  A char ** should be supplied which will point to the  memory
 239 allocated bits, followed by an unsigned long *, which will point to the length
 240 (in bits) of the bitstring returned.
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fBn\fR\fR
 247 .ad
 248 .RS 5n
 249 Null.  No parameter is required.  The element is simply skipped if it is
 250 recognized.
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBv\fR\fR
 257 .ad
 258 .RS 5n
 259 Sequence of octet strings.  A char *** should be supplied, which upon return
 260 points to a memory allocated null-terminated array of char *'s containing the
 261 octet strings.   \fINULL\fR is returned if the sequence is empty.
 262 .RE
 263
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fBV\fR\fR
 268 .ad
 269 .RS 5n
 270 Sequence of octet strings with lengths. A struct berval *** should be supplied,
 271 which upon return points to a memory allocated, null-terminated array of struct
 272 berval *'s containing the octet strings and their lengths. \fINULL\fR is
 273 returned if the sequence is empty.   \fBber_bvecfree()\fR can be called to free
 274 the allocated memory.
 275 .RE
 276
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBx\fR\fR
 281 .ad
 282 .RS 5n
 283 Skip element.  The next element is skipped.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fB{\fR\fR
 290 .ad
 291 .RS 5n
 292 Begin sequence.  No parameter is required.  The initial sequence tag and length
 293 are skipped.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fB}\fR\fR
 300 .ad
 301 .RS 5n
 302 End sequence.  No parameter is required and no action is taken.
 303 .RE
 304
 305 .sp
 306 .ne 2
 307 .na
 308 \fB\fB[\fR\fR
 309 .ad
 310 .RS 5n
 311 Begin set.  No parameter is required.  The initial set tag and length are
 312 skipped.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fB]\fR\fR
 319 .ad
 320 .RS 5n
 321 End set.  No parameter is required and no action is taken.
 322 .RE
 323
 324 .sp
 325 .LP
 326 The \fBber_get_int()\fR function tries to interpret the next element as an
 327 integer, returning the result in \fInum\fR. The tag of whatever it finds is
 328 returned on success, \fB-1\fR on failure.
 329 .sp
 330 .LP
 331 The \fBber_get_stringb()\fR function is used to read an octet string into a
 332 pre-allocated buffer. The \fIlen\fR parameter should be initialized to the size
 333 of the buffer, and will contain the length of the octet string read upon
 334 return.  The buffer should be big enough to take the octet string value plus a
 335 terminating \fINULL\fR byte.
 336 .sp
 337 .LP
 338 The \fBber_get_stringa()\fR function is used to allocate memory space into
 339 which an octet string is read.
 340 .sp
 341 .LP
 342 The \fBber_get_stringal()\fR function is used to allocate memory space into
 343 which an octet string and its length are read.  It takes a \fBstruct berval
 344 **\fR, and returns the result in this parameter.
 345 .sp
 346 .LP
 347 The \fBber_get_null()\fR function is used to read a \fINULL\fR element.  It
 348 returns the tag of the element it skips over.
 349 .sp
 350 .LP
 351 The \fBber_get_boolean()\fR function is used to read a boolean value. It is
 352 called the same way that \fBber_get_int()\fR is called.
 353 .sp
 354 .LP
 355 The \fBber_get_bitstringa()\fR function is used to read a bitstring value. It
 356 takes a \fBchar **\fR which will hold the allocated memory bits, followed by an
 357 \fBunsigned long *\fR, which will point to the length (in bits) of the
 358 bitstring returned.
 359 .sp
 360 .LP
 361 The \fBber_first_element()\fR function is used to return the tag and length of
 362 the first element in a set or sequence. It also returns in \fIlast\fR a magic
 363 cookie parameter that should be passed to subsequent calls to
 364 \fBber_next_element()\fR, which returns similar information.
 365 .sp
 366 .LP
 367 The \fBber_alloc_t()\fR function constructs and returns \fBBerElement\fR. A
 368 null pointer  is returned on error. The options field contains a bitwise-OR of
 369 options which are to be used when generating the encoding of this
 370 \fBBerElement\fR. One option is defined and must always be supplied:
 371 .sp
 372 .in +2
 373 .nf
 374 #define LBER_USE_DER 0x01
 375 .fi
 376 .in -2
 377
 378 .sp
 379 .LP
 380 When this option is present, lengths will always be encoded in the minimum
 381 number of octets. Note that this option does not cause values of sets and
 382 sequences to be rearranged in tag and byte order, so these functions are not
 383 suitable for generating DER output as defined in  X.509 and X.680
 384 .sp
 385 .LP
 386 The \fBber_init\fR function constructs a \fBBerElement\fR and returns a new
 387 \fBBerElement\fR containing a copy of the data in the \fIbv\fR argument. The
 388 \fBber_init\fR function returns the null pointer on error.
 389 .sp
 390 .LP
 391 The \fBber_free()\fR function frees a \fBBerElement\fR which is returned from
 392 the API calls \fBber_alloc_t()\fR or \fBber_init()\fR. Each \fBBerElement\fR
 393 must be freed by the caller. The second argument \fIfreebuf\fR should always be
 394 set to 1 to ensure that the internal buffer used by the BER functions is freed
 395 as well as the \fBBerElement\fR container itself.
 396 .sp
 397 .LP
 398 The \fBber_bvdup()\fR function returns a copy of a \fIberval\fR. The
 399 \fIbv_val\fR field in the returned \fIberval\fR points to a different area of
 400 memory as the \fIbv_val\fR field in the argument \fIberval\fR. The null pointer
 401 is returned on  error (that is, is out of memory).
 402 .sp
 403 .LP
 404 The \fBber_flatten()\fR function allocates a \fBstruct  berval\fR whose
 405 contents are BER encoding taken from the  \fIber\fR argument. The \fIbvPtr\fR
 406 pointer points to the returned \fIberval\fR, which must be freed using
 407 \fBber_bvfree()\fR. This  function returns \fB0\fR on success and  \fB\(mi1\fR
 408 on error.
 409 .SH EXAMPLES
 410 .LP
 411 \fBExample 1 \fRAssume the variable \fIber\fR contains a lightweight BER
 412 encoding of the following ASN.1 object:
 413 .sp
 414 .in +2
 415 .nf
 416       AlmostASearchRequest := SEQUENCE {
 417           baseObject      DistinguishedName,
 418           scope           ENUMERATED {
 419               baseObject    (0),
 420               singleLevel   (1),
 421               wholeSubtree  (2)
 422           },
 423           derefAliases    ENUMERATED {
 424               neverDerefaliases   (0),
 425               derefInSearching    (1),
 426               derefFindingBaseObj (2),
 427               alwaysDerefAliases  (3N)
 428           },
 429           sizelimit       INTEGER (0 .. 65535),
 430           timelimit       INTEGER (0 .. 65535),
 431           attrsOnly       BOOLEAN,
 432           attributes      SEQUENCE OF AttributeType
 433       }
 434 .fi
 435 .in -2
 436
 437 .LP
 438 \fBExample 2 \fRThe element can be decoded using \fBber_scanf()\fR as follows.
 439 .sp
 440 .in +2
 441 .nf
 442       int    scope, ali, size, time, attrsonly;
 443       char   *dn, **attrs;
 444       if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,
 445           &size, &time, &attrsonly, &attrs ) == -1 )
 446               /* error */
 447       else
 448               /* success */
 449 .fi
 450 .in -2
 451
 452 .SH ERRORS
 453 .sp
 454 .LP
 455 If an error occurs during decoding, generally these functions return
 456 \fB\(mi1\fR\&.
 457 .SH NOTES
 458 .sp
 459 .LP
 460 The return values for all of these functions are declared in the \fB<lber.h>\fR
 461 header.  Some functions may allocate memory which must be freed by the calling
 462 application.
 463 .SH ATTRIBUTES
 464 .sp
 465 .LP
 466 See \fBattributes\fR(5) for a description of the following attributes:
 467 .sp
 468
 469 .sp
 470 .TS
 471 box;
 472 c | c
 473 l | l .
 474 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 475 _
 476 Interface Stability     Committed
 477 .TE
 478
 479 .SH SEE ALSO
 480 .sp
 481 .LP
 482 \fBber_encode\fR(3LDAP), \fBattributes\fR(5)
 483 .sp
 484 .LP
 485 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
 486 Protocol", OSI-DS-26, April 1992.
 487 .sp
 488 .LP
 489 Information Processing - Open Systems Interconnection - Model and Notation -
 490 Service Definition - Specification of Basic Encoding Rules for Abstract Syntax
 491 Notation One, International Organization for Standardization, International
 492 Standard 8825.