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