mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
339 lines
8.9 KiB
Groff
339 lines
8.9 KiB
Groff
.TH LBER_ENCODE 3 "12 May 2000" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <lber.h>
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
BerElement *ber_alloc_t( int options );
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_flush(
|
|
Sockbuf *sb,
|
|
BerElement *ber,
|
|
int freeit);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_printf(
|
|
BerElement *ber,
|
|
const char \(**fmt, ...);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_int(
|
|
BerElement *ber,
|
|
ber_int_t num,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_enum(
|
|
BerElement *ber,
|
|
ber_int_t num,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_ostring(
|
|
BerElement *ber,
|
|
const char \(**str,
|
|
ber_len_t long len,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_string(
|
|
BerElement *ber,
|
|
const char \(**str,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_null(
|
|
BerElement *ber;
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_boolean(
|
|
BerElement *ber;
|
|
ber_int_t bool;
|
|
ber_tag_t tag;
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_bitstring(
|
|
BerElement *ber,
|
|
const char *str,
|
|
ber_len_t blen,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_start_seq(
|
|
BerElement *ber,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_start_set(
|
|
BerElement *ber,
|
|
ber_tag_t tag);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_seq(
|
|
BerElement *ber);
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int ber_put_set(
|
|
BerElement *ber);
|
|
.SH DESCRIPTION
|
|
.LP
|
|
These routines provide a subroutine interface to a simplified
|
|
implementation of the Basic Encoding Rules of ASN.1. The version
|
|
of BER these routines support is the one defined for the LDAP
|
|
protocol. The encoding rules are the same as BER, except that
|
|
only definite form lengths are used, and bitstrings and octet strings
|
|
are always encoded in primitive form. In addition, these lightweight
|
|
BER routines restrict tags and class to fit in a single octet (this
|
|
means the actual tag must be less than 31). When a "tag" is specified
|
|
in the descriptions below, it refers to the tag, class, and primitive
|
|
or constructed bit in the first octet of the encoding. This
|
|
man page describes the encoding routines in the lber library. See
|
|
lber-decode(3) for details on the corresponding decoding routines.
|
|
Consult lber-types(3) for information about types, allocators, and deallocators.
|
|
.LP
|
|
Normally, the only routines that need be called by an application
|
|
are ber_alloc_t() to allocate a BER element for encoding, ber_printf()
|
|
to do the actual encoding, and ber_flush() to actually write the
|
|
element. The other routines are provided for those
|
|
applications that need more control than ber_printf() provides. In
|
|
general, these routines return the length of the element encoded, or
|
|
-1 if an error occurred.
|
|
.LP
|
|
The ber_alloc_t() routine is used to allocate a new BER element. It
|
|
should be called with an argument of LBER_USE_DER. The
|
|
ber_flush() routine is used to actually write the element to a socket
|
|
(or file) descriptor, once it has been fully encoded (using ber_printf()
|
|
and friends). The \fIsb\fP structure contains the descriptor and a
|
|
BerElement used for input buffering. Only the \fIsb_sd\fP field is relevant
|
|
to the ber_flush() routine.
|
|
.LP
|
|
The ber_printf() routine is used to encode a BER element in much the
|
|
same way that sprintf(3) works. One important difference, though, is
|
|
that some state information is kept with the \fIber\fP parameter so
|
|
that multiple calls can be made to ber_printf() to append things to
|
|
the end of the BER element. Ber_printf() writes to \fIber\fP, a pointer to a
|
|
BerElement such as returned by ber_alloc(). It interprets and
|
|
formats its arguments according to the format string \fIfmt\fP.
|
|
The format string can contain the following characters:
|
|
.RS
|
|
.LP
|
|
.TP 3
|
|
.SM b
|
|
Boolean. An ber_int_t parameter should be supplied. A boolean element
|
|
is output.
|
|
.TP
|
|
.SM e
|
|
Enumeration. An ber_int_t parameter should be supplied. An
|
|
enumeration element is output.
|
|
.TP
|
|
.SM i
|
|
Integer. An ber_int_t parameter should be supplied. An integer element
|
|
is output.
|
|
.TP
|
|
.SM B
|
|
Bitstring. A char * pointer to the start of the bitstring is supplied,
|
|
followed by the number of bits in the bitstring. A bitstring element
|
|
is output.
|
|
.TP
|
|
.SM n
|
|
Null. No parameter is required. A null element is output.
|
|
.TP
|
|
.SM o
|
|
Octet string. A char * is supplied, followed by the length of the
|
|
string pointed to. An octet string element is output.
|
|
.TP
|
|
.SM O
|
|
Octet string. A struct berval * is supplied.
|
|
An octet string element is output.
|
|
.TP
|
|
.SM s
|
|
Octet string. A null-terminated string is supplied. An octet string
|
|
element is output, not including the trailing NULL octet.
|
|
.TP
|
|
.SM t
|
|
Tag. A ber_tag_t specifying the tag to give the next element
|
|
is provided. This works across calls.
|
|
.TP
|
|
.SM v
|
|
Several octet strings. A null-terminated array of char *'s is
|
|
supplied. Note that a construct like '{v}' is required to get
|
|
an actual SEQUENCE OF octet strings.
|
|
.TP
|
|
.SM V
|
|
Several octet strings. A null-terminated array of struct berval *'s
|
|
is supplied. Note that a construct like '{V}' is required to get
|
|
an actual SEQUENCE OF octet strings.
|
|
.TP
|
|
.SM {
|
|
Begin sequence. No parameter is required.
|
|
.TP
|
|
.SM }
|
|
End sequence. No parameter is required.
|
|
.TP
|
|
.SM [
|
|
Begin set. No parameter is required.
|
|
.TP
|
|
.SM ]
|
|
End set. No parameter is required.
|
|
.RE
|
|
.LP
|
|
The ber_put_int() routine writes the integer element \fInum\fP to
|
|
the BER element \fIber\fP.
|
|
.LP
|
|
The ber_put_enum() routine writes the enumberation element
|
|
\fInum\fP to the BER element \fIber\fP.
|
|
.LP
|
|
The ber_put_boolean() routine writes the boolean value given by
|
|
\fIbool\fP to the BER element.
|
|
.LP
|
|
The ber_put_bitstring() routine writes \fIblen\fP bits starting
|
|
at \fIstr\fP as a bitstring value to the given BER element. Note
|
|
that \fIblen\fP is the length \fIin bits\fP of the bitstring.
|
|
.LP
|
|
The ber_put_ostring() routine writes \fIlen\fP bytes starting at
|
|
\fIstr\fP to the BER element as an octet string.
|
|
.LP
|
|
The ber_put_string() routine writes the null-terminated string (minus
|
|
the terminating '\0') to the BER element as an octet string.
|
|
.LP
|
|
The ber_put_null() routine writes a NULL element to the BER element.
|
|
.LP
|
|
The ber_start_seq() routine is used to start a sequence in the BER
|
|
element. The ber_start_set() routine works similarly.
|
|
The end of the sequence or set is marked by the nearest matching
|
|
call to ber_put_seq() or ber_put_set(), respectively.
|
|
.LP
|
|
The ber_first_element() routine is used to return the tag and length
|
|
of the first element in a set or sequence. It also returns in \fIcookie\fP
|
|
a magic cookie parameter that should be passed to subsequent calls to
|
|
ber_next_element(), which returns similar information.
|
|
.SH EXAMPLES
|
|
Assuming the following variable declarations, and that the variables
|
|
have been assigned appropriately, an lber encoding of
|
|
the following ASN.1 object:
|
|
.LP
|
|
.nf
|
|
AlmostASearchRequest := SEQUENCE {
|
|
baseObject DistinguishedName,
|
|
scope ENUMERATED {
|
|
baseObject (0),
|
|
singleLevel (1),
|
|
wholeSubtree (2)
|
|
},
|
|
derefAliases ENUMERATED {
|
|
neverDerefaliases (0),
|
|
derefInSearching (1),
|
|
derefFindingBaseObj (2),
|
|
alwaysDerefAliases (3)
|
|
},
|
|
sizelimit INTEGER (0 .. 65535),
|
|
timelimit INTEGER (0 .. 65535),
|
|
attrsOnly BOOLEAN,
|
|
attributes SEQUENCE OF AttributeType
|
|
}
|
|
.fi
|
|
.LP
|
|
can be achieved like so:
|
|
.LP
|
|
.nf
|
|
int rc;
|
|
ber_int_t scope, ali, size, time, attrsonly;
|
|
char *dn, **attrs;
|
|
BerElement *ber;
|
|
|
|
/* ... fill in values ... */
|
|
|
|
ber = ber_alloc_t( LBER_USE_DER );
|
|
|
|
if ( ber == NULL ) {
|
|
/* error */
|
|
}
|
|
|
|
rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
|
|
size, time, attrsonly, attrs );
|
|
|
|
if( rc == -1 ) {
|
|
/* error */
|
|
} else {
|
|
/* success */
|
|
}
|
|
.fi
|
|
.SH ERRORS
|
|
If an error occurs during encoding, generally these routines return -1.
|
|
.LP
|
|
.SH NOTES
|
|
.LP
|
|
The return values for all of these functions are declared in the
|
|
<lber.h> header file.
|
|
.SH SEE ALSO
|
|
.BR lber-decode (3)
|
|
.BR lber-types (3)
|
|
.BR ldap-async (3)
|
|
.BR ldap-sync (3)
|
|
.BR ldap-parse (3)
|
|
.LP
|
|
Yeong, W., Howes, T., and Hardcastle-Kille, S.,
|
|
"Lightweight Directory Access Protocol", OSI-DS-26, April 1992.
|
|
.LP
|
|
Information Processing - Open Systems Interconnection - Model and Notation -
|
|
Service Definition - Specification of Basic Encoding Rules for Abstract
|
|
Syntax Notation One, International Organization for Standardization,
|
|
International Standard 8825.
|
|
.SH AUTHOR
|
|
Tim Howes, University of Michigan
|
|
.SH ACKNOWLEDGEMENTS
|
|
.B OpenLDAP
|
|
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
|
|
.B OpenLDAP
|
|
is derived from University of Michigan LDAP 3.3 Release.
|