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

   1 .TH LBER-ENCODE 3  "15 June 1992"
   2 .SH NAME
   3 ber_alloc, ber_flush, ber_printf, ber_put_int, 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
   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 BerElement *ber_alloc()
  36 .ft
  37 .fi
  38 .LP
  39 .nf
  40 .ft B
  41 ber_flush(sb, ber, freeit)
  42 Sockbuf *sb;
  43 BerElement *ber;
  44 int freeit;
  45 .ft
  46 .fi
  47 .LP
  48 .nf
  49 .ft B
  50 ber_printf(ber, fmt [, arg... ] )
  51 BerElement *ber;
  52 char \(**fmt;
  53 .ft
  54 .fi
  55 .LP
  56 .nf
  57 .ft B
  58 ber_put_int(ber, num, tag)
  59 BerElement *ber;
  60 long num;
  61 char tag;
  62 .ft
  63 .fi
  64 .LP
  65 .nf
  66 .ft B
  67 ber_put_ostring(ber, str, len, tag)
  68 BerElement *ber;
  69 char \(**str;
  70 unsigned long len;
  71 char tag;
  72 .ft
  73 .fi
  74 .LP
  75 .nf
  76 .ft B
  77 ber_put_string(ber, str, tag)
  78 BerElement *ber;
  79 char \(**str;
  80 char tag;
  81 .ft
  82 .fi
  83 .LP
  84 .nf
  85 .ft B
  86 ber_put_null(ber, tag)
  87 BerElement *ber;
  88 char tag;
  89 .ft
  90 .fi
  91 .LP
  92 .nf
  93 .ft B
  94 ber_put_boolean(ber, bool, tag)
  95 BerElement *ber;
  96 int bool;
  97 char tag;
  98 .ft
  99 .fi
 100 .LP
 101 .nf
 102 .ft B
 103 ber_put_bitstring(ber, str, blen, tag)
 104 BerElement *ber;
 105 char *str;
 106 int blen;
 107 char tag;
 108 .ft
 109 .fi
 110 .LP
 111 .nf
 112 .ft B
 113 ber_start_seq(ber, tag)
 114 BerElement *ber;
 115 char tag;
 116 .ft
 117 .fi
 118 .LP
 119 .nf
 120 .ft B
 121 ber_start_set(ber, tag)
 122 BerElement *ber;
 123 char tag;
 124 .ft
 125 .fi
 126 .LP
 127 .nf
 128 .ft B
 129 ber_put_seq(ber)
 130 BerElement *ber;
 131 .ft
 132 .fi
 133 .LP
 134 .nf
 135 .ft B
 136 ber_put_set(ber)
 137 BerElement *ber;
 138 .SH DESCRIPTION
 139 .LP
 140 These routines provide a subroutine interface to a simplified
 141 implementation of the Basic Encoding Rules of ASN.1.  The version
 142 of BER these routines support is the one defined for the LDAP
 143 protocol.  The encoding rules are the same as BER, except that
 144 only definite form lengths are used, and bitstrings and octet strings
 145 are always encoded in primitive form.  In addition, these lightweight
 146 BER routines restrict tags and class to fit in a single octet (this
 147 means the actual tag must be less than 31).  When a "tag" is specified
 148 in the descriptions below, it refers to the tag, class, and primitive
 149 or constructed bit in the first octet of the encoding.  This
 150 man page describes the encoding routines in the lber library.  See
 151 lber-decode(3) for details on the corresponding decoding routines.
 152 .LP
 153 Normally, the only routines that need be called by an application
 154 are ber_alloc() to allocate a BER element for encoding, ber_printf()
 155 to do the actual encoding, and ber_flush() to actually write the
 156 element.  The other routines are provided for those
 157 applications that need more control than ber_printf() provides.  In
 158 general, these routines return the length of the element encoded, or
 159 -1 if an error occurred.
 160 .LP
 161 The ber_alloc() routine is used to allocate a new BER element.  The
 162 ber_flush() routine is used to actually write the element to a socket
 163 (or file) descriptor, once it has been fully encoded (using ber_printf()
 164 and friends).  The \fIsb\fP structure contains the descriptor and a
 165 BerElement used for input buffering.  Only the \fIsb_sd\fP field is relevant
 166 to the ber_flush() routine.
 167 .LP
 168 The ber_printf() routine is used to encode a BER element in much the
 169 same way that sprintf(3) works.  One important difference, though, is
 170 that some state information is kept with the \fIber\fP parameter so
 171 that multiple calls can be made to ber_printf() to append things to
 172 the end of the BER element.  Ber_printf() writes to \fIber\fP, a pointer to a
 173 BerElement such as returned by ber_alloc().  It interprets and
 174 formats its arguments according to the format string \fIfmt\fP.
 175 The format string can contain the following characters:
 176 .RS
 177 .LP
 178 .TP 3
 179 .SM b
 180 Boolean.  An integer parameter should be supplied.  A boolean element
 181 is output.
 182 .TP
 183 .SM i
 184 Integer.  An integer parameter should be supplied.  An integer element
 185 is output.
 186 .TP
 187 .SM B
 188 Bitstring.  A char * pointer to the start of the bitstring is supplied,
 189 followed by the number of bits in the bitstring.  A bitstring element
 190 is output.
 191 .TP
 192 .SM n
 193 Null.  No parameter is required.  A null element is output.
 194 .TP
 195 .SM o
 196 Octet string.  A char * is supplied, followed by the length of the
 197 string pointed to.  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.  An int specifying the tag to give the next element is provided.
 205 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 {
 213 Begin sequence.  No parameter is required.
 214 .TP
 215 .SM }
 216 End sequence.  No parameter is required.
 217 .TP
 218 .SM [
 219 Begin set.  No parameter is required.
 220 .TP
 221 .SM ]
 222 End set.  No parameter is required.
 223 .RE
 224 .LP
 225 The ber_put_int() routine writes the integer element \fInum\fP to
 226 the BER element \fIber\fP.
 227 .LP
 228 The ber_put_boolean() routine writes the boolean value given by
 229 \fIbool\fP to the BER element.
 230 .LP
 231 The ber_put_bitstring() routine writes \fIblen\fP bits starting
 232 at \fIstr\fP as a bitstring value to the given BER element.  Note
 233 that \fIblen\fP is the length \fIin bits\fP of the bitstring.
 234 .LP
 235 The ber_put_ostring() routine writes \fIlen\fP bytes starting at
 236 \fIstr\fP to the BER element as an octet string.
 237 .LP
 238 The ber_put_string() routine writes the null-terminated string (minus
 239 the terminating '\0') to the BER element as an octet string.
 240 .LP
 241 The ber_put_null() routine writes a NULL element to the BER element.
 242 .LP
 243 The ber_start_seq() routine is used to start a sequence in the BER
 244 element.  The ber_start_set() routine works similarly.
 245 The end of the sequence or set is marked by the nearest matching
 246 call to ber_put_seq() or ber_put_set(), respectively.
 247 .LP
 248 The ber_first_element() routine is used to return the tag and length
 249 of the first element in a set or sequence.  It also returns in \fIcookie\fP
 250 a magic cookie parameter that should be passed to subsequent calls to
 251 ber_next_element(), which returns similar information.
 252 .SH EXAMPLES
 253 Assuming the following variable declarations, and that the variables
 254 have been assigned appropriately, an lber encoding of
 255 the following ASN.1 object:
 256 .LP
 257 .nf
 258       AlmostASearchRequest := SEQUENCE {
 259           baseObject      DistinguishedName,
 260           scope           ENUMERATED {
 261               baseObject    (0),
 262               singleLevel   (1),
 263               wholeSubtree  (2)
 264           },
 265           derefAliases    ENUMERATED {
 266               neverDerefaliases   (0),
 267               derefInSearching    (1),
 268               derefFindingBaseObj (2),
 269               alwaysDerefAliases  (3)
 270           },
 271           sizelimit       INTEGER (0 .. 65535),
 272           timelimit       INTEGER (0 .. 65535),
 273           attrsOnly       BOOLEAN,
 274           attributes      SEQUENCE OF AttributeType
 275       }
 276 .fi
 277 .LP
 278 can be achieved like so:
 279 .LP
 280 .nf
 281       int    scope, ali, size, time, attrsonly;
 282       char   *dn, **attrs;
 283
 284       /* ... fill in values ... */
 285       if ( (ber = ber_alloc()) == NULLBER )
 286                 /* error */
 287
 288       if ( ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
 289           size, time, attrsonly, attrs ) == -1 )
 290               /* error */
 291       else
 292               /* success */
 293 .fi
 294 .SH ERRORS
 295 If an error occurs during encoding, generally these routines return -1.
 296 .LP
 297 .SH NOTES
 298 .LP
 299 The return values for all of these functions are declared in the
 300 <lber.h> header file.
 301 .SH SEE ALSO
 302 .BR ldap-async (3)
 303 .BR ldap-sync (3)
 304 .BR ldap-parse (3)
 305 .BR lber-decode (3)
 306 .LP
 307 Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
 308 Protocol", OSI-DS-26, April 1992.
 309 .LP
 310 Information Processing - Open Systems Interconnection - Model and Notation -
 311 Service Definition - Specification of Basic Encoding Rules for Abstract
 312 Syntax Notation One, International Organization for Standardization,
 313 International Standard 8825.
 314 .SH AUTHOR
 315 Tim Howes, University of Michigan