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

   1 .TH LBER_ENCODE 3 "12 May 2000" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ber_alloc_t, ber_flush, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- LBER simplified Basic Encoding Rules library routines for encoding
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <lber.h>
  11 .ft
  12 .fi
  13 .LP
  14 .nf
  15 .ft B
  16 BerElement *ber_alloc_t( int options );
  17 .ft
  18 .fi
  19 .LP
  20 .nf
  21 .ft B
  22 int ber_flush(
  23         Sockbuf *sb,
  24         BerElement *ber,
  25         int freeit);
  26 .ft
  27 .fi
  28 .LP
  29 .nf
  30 .ft B
  31 int ber_printf(
  32         BerElement *ber,
  33         const char \(**fmt, ...);
  34 .ft
  35 .fi
  36 .LP
  37 .nf
  38 .ft B
  39 int ber_put_int(
  40         BerElement *ber,
  41         ber_int_t num,
  42         ber_tag_t tag);
  43 .ft
  44 .fi
  45 .LP
  46 .nf
  47 .ft B
  48 int ber_put_enum(
  49         BerElement *ber,
  50         ber_int_t num,
  51         ber_tag_t tag);
  52 .ft
  53 .fi
  54 .LP
  55 .nf
  56 .ft B
  57 int ber_put_ostring(
  58         BerElement *ber,
  59         const char \(**str,
  60         ber_len_t long len,
  61         ber_tag_t tag);
  62 .ft
  63 .fi
  64 .LP
  65 .nf
  66 .ft B
  67 int ber_put_string(
  68         BerElement *ber,
  69         const char \(**str,
  70         ber_tag_t tag);
  71 .ft
  72 .fi
  73 .LP
  74 .nf
  75 .ft B
  76 int ber_put_null(
  77         BerElement *ber;
  78         ber_tag_t tag);
  79 .ft
  80 .fi
  81 .LP
  82 .nf
  83 .ft B
  84 int ber_put_boolean(
  85         BerElement *ber;
  86         ber_int_t bool;
  87         ber_tag_t tag;
  88 .ft
  89 .fi
  90 .LP
  91 .nf
  92 .ft B
  93 int ber_put_bitstring(
  94         BerElement *ber,
  95         const char *str,
  96         ber_len_t blen,
  97         ber_tag_t tag);
  98 .ft
  99 .fi
 100 .LP
 101 .nf
 102 .ft B
 103 int ber_start_seq(
 104         BerElement *ber,
 105         ber_tag_t tag);
 106 .ft
 107 .fi
 108 .LP
 109 .nf
 110 .ft B
 111 int ber_start_set(
 112         BerElement *ber,
 113         ber_tag_t tag);
 114 .ft
 115 .fi
 116 .LP
 117 .nf
 118 .ft B
 119 int ber_put_seq(
 120         BerElement *ber);
 121 .ft
 122 .fi
 123 .LP
 124 .nf
 125 .ft B
 126 int ber_put_set(
 127         BerElement *ber);
 128 .SH DESCRIPTION
 129 .LP
 130 These routines provide a subroutine interface to a simplified
 131 implementation of the Basic Encoding Rules of ASN.1.  The version
 132 of BER these routines support is the one defined for the LDAP
 133 protocol.  The encoding rules are the same as BER, except that
 134 only definite form lengths are used, and bitstrings and octet strings
 135 are always encoded in primitive form.  In addition, these lightweight
 136 BER routines restrict tags and class to fit in a single octet (this
 137 means the actual tag must be less than 31).  When a "tag" is specified
 138 in the descriptions below, it refers to the tag, class, and primitive
 139 or constructed bit in the first octet of the encoding.  This
 140 man page describes the encoding routines in the lber library.  See
 141 lber-decode(3) for details on the corresponding decoding routines.
 142 Consult lber-types(3) for information about types, allocators, and deallocators.
 143 .LP
 144 Normally, the only routines that need be called by an application
 145 are ber_alloc_t() to allocate a BER element for encoding, ber_printf()
 146 to do the actual encoding, and ber_flush() to actually write the
 147 element.  The other routines are provided for those
 148 applications that need more control than ber_printf() provides.  In
 149 general, these routines return the length of the element encoded, or
 150 -1 if an error occurred.
 151 .LP
 152 The ber_alloc_t() routine is used to allocate a new BER element.  It
 153 should be called with an argument of LBER_USE_DER.  The
 154 ber_flush() routine is used to actually write the element to a socket
 155 (or file) descriptor, once it has been fully encoded (using ber_printf()
 156 and friends).  The \fIsb\fP structure contains the descriptor and a
 157 BerElement used for input buffering.  Only the \fIsb_sd\fP field is relevant
 158 to the ber_flush() routine.
 159 .LP
 160 The ber_printf() routine is used to encode a BER element in much the
 161 same way that sprintf(3) works.  One important difference, though, is
 162 that some state information is kept with the \fIber\fP parameter so
 163 that multiple calls can be made to ber_printf() to append things to
 164 the end of the BER element.  Ber_printf() writes to \fIber\fP, a pointer to a
 165 BerElement such as returned by ber_alloc().  It interprets and
 166 formats its arguments according to the format string \fIfmt\fP.
 167 The format string can contain the following characters:
 168 .RS
 169 .LP
 170 .TP 3
 171 .SM b
 172 Boolean.  An ber_int_t parameter should be supplied.  A boolean element
 173 is output.
 174 .TP
 175 .SM e
 176 Enumeration.  An ber_int_t parameter should be supplied.  An
 177 enumeration element is output.
 178 .TP
 179 .SM i
 180 Integer.  An ber_int_t parameter should be supplied.  An integer element
 181 is output.
 182 .TP
 183 .SM B
 184 Bitstring.  A char * pointer to the start of the bitstring is supplied,
 185 followed by the number of bits in the bitstring.  A bitstring element
 186 is output.
 187 .TP
 188 .SM n
 189 Null.  No parameter is required.  A null element is output.
 190 .TP
 191 .SM o
 192 Octet string.  A char * is supplied, followed by the length of the
 193 string pointed to.  An octet string element is output.
 194 .TP
 195 .SM O
 196 Octet string.  A struct berval * is supplied.
 197 An octet string element is output.
 198 .TP
 199 .SM s
 200 Octet string.  A null-terminated string is supplied.  An octet string
 201 element is output, not including the trailing NULL octet.
 202 .TP
 203 .SM t
 204 Tag.  A ber_tag_t specifying the tag to give the next element
 205 is provided.  This works across calls.
 206 .TP
 207 .SM v
 208 Several octet strings.  A null-terminated array of char *'s is
 209 supplied.  Note that a construct like '{v}' is required to get
 210 an actual SEQUENCE OF octet strings.
 211 .TP
 212 .SM V
 213 Several octet strings.  A null-terminated array of struct berval *'s
 214 is supplied.  Note that a construct like '{V}' is required to get
 215 an actual SEQUENCE OF octet strings.
 216 .TP
 217 .SM {
 218 Begin sequence.  No parameter is required.
 219 .TP
 220 .SM }
 221 End sequence.  No parameter is required.
 222 .TP
 223 .SM [
 224 Begin set.  No parameter is required.
 225 .TP
 226 .SM ]
 227 End set.  No parameter is required.
 228 .RE
 229 .LP
 230 The ber_put_int() routine writes the integer element \fInum\fP to
 231 the BER element \fIber\fP.
 232 .LP
 233 The ber_put_enum() routine writes the enumberation element
 234 \fInum\fP to the BER element \fIber\fP.
 235 .LP
 236 The ber_put_boolean() routine writes the boolean value given by
 237 \fIbool\fP to the BER element.
 238 .LP
 239 The ber_put_bitstring() routine writes \fIblen\fP bits starting
 240 at \fIstr\fP as a bitstring value to the given BER element.  Note
 241 that \fIblen\fP is the length \fIin bits\fP of the bitstring.
 242 .LP
 243 The ber_put_ostring() routine writes \fIlen\fP bytes starting at
 244 \fIstr\fP to the BER element as an octet string.
 245 .LP
 246 The ber_put_string() routine writes the null-terminated string (minus
 247 the terminating '\0') to the BER element as an octet string.
 248 .LP
 249 The ber_put_null() routine writes a NULL element to the BER element.
 250 .LP
 251 The ber_start_seq() routine is used to start a sequence in the BER
 252 element.  The ber_start_set() routine works similarly.
 253 The end of the sequence or set is marked by the nearest matching
 254 call to ber_put_seq() or ber_put_set(), respectively.
 255 .LP
 256 The ber_first_element() routine is used to return the tag and length
 257 of the first element in a set or sequence.  It also returns in \fIcookie\fP
 258 a magic cookie parameter that should be passed to subsequent calls to
 259 ber_next_element(), which returns similar information.
 260 .SH EXAMPLES
 261 Assuming the following variable declarations, and that the variables
 262 have been assigned appropriately, an lber encoding of
 263 the following ASN.1 object:
 264 .LP
 265 .nf
 266       AlmostASearchRequest := SEQUENCE {
 267           baseObject      DistinguishedName,
 268           scope           ENUMERATED {
 269               baseObject    (0),
 270               singleLevel   (1),
 271               wholeSubtree  (2)
 272           },
 273           derefAliases    ENUMERATED {
 274               neverDerefaliases   (0),
 275               derefInSearching    (1),
 276               derefFindingBaseObj (2),
 277               alwaysDerefAliases  (3)
 278           },
 279           sizelimit       INTEGER (0 .. 65535),
 280           timelimit       INTEGER (0 .. 65535),
 281           attrsOnly       BOOLEAN,
 282           attributes      SEQUENCE OF AttributeType
 283       }
 284 .fi
 285 .LP
 286 can be achieved like so:
 287 .LP
 288 .nf
 289       int rc;
 290       ber_int_t    scope, ali, size, time, attrsonly;
 291       char   *dn, **attrs;
 292       BerElement *ber;
 293
 294       /* ... fill in values ... */
 295
 296       ber = ber_alloc_t( LBER_USE_DER );
 297
 298       if ( ber == NULL ) {
 299                 /* error */
 300       }
 301
 302       rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
 303           size, time, attrsonly, attrs );
 304
 305       if( rc == -1 ) {
 306               /* error */
 307       } else {
 308               /* success */
 309       }
 310 .fi
 311 .SH ERRORS
 312 If an error occurs during encoding, generally these routines return -1.
 313 .LP
 314 .SH NOTES
 315 .LP
 316 The return values for all of these functions are declared in the
 317 <lber.h> header file.
 318 .SH SEE ALSO
 319 .BR lber-decode (3)
 320 .BR lber-memory (3)
 321 .BR lber-types (3)
 322 .BR ldap-async (3)
 323 .BR ldap-sync (3)
 324 .BR ldap-parse (3)
 325 .SH ACKNOWLEDGEMENTS
 326 .B      OpenLDAP
 327 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 328 .B      OpenLDAP
 329 is derived from University of Michigan LDAP 3.3 Release.