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

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