365 lines
12 KiB
Groff
365 lines
12 KiB
Groff
.lf 1 stdin
|
|
.TH LBER_DECODE 3 "2014/01/26" "OpenLDAP 2.4.39"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2014 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding
|
|
.SH LIBRARY
|
|
OpenLDAP LBER (liblber, \-llber)
|
|
.SH SYNOPSIS
|
|
.B #include <lber.h>
|
|
.LP
|
|
.BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_null(BerElement *" ber ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");"
|
|
.LP
|
|
.BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");"
|
|
.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. This man page
|
|
describes the decoding routines in the lber library. See
|
|
.BR lber-encode (3)
|
|
for details on the corresponding encoding routines.
|
|
Consult
|
|
.BR lber-types (3)
|
|
for information about types, allocators, and deallocators.
|
|
.LP
|
|
Normally, the only routines that need to be called by an application
|
|
are
|
|
.BR ber_get_next ()
|
|
to get the next BER element and
|
|
.BR ber_scanf ()
|
|
to do the actual decoding. In some cases,
|
|
.BR ber_peek_tag ()
|
|
may also need to be called in normal usage. The other routines are
|
|
provided for those applications that need more control than
|
|
.BR ber_scanf ()
|
|
provides. In
|
|
general, these routines return the tag of the element decoded, or
|
|
LBER_ERROR if an error occurred.
|
|
.LP
|
|
The
|
|
.BR ber_get_next ()
|
|
routine is used to read the next BER element from the given Sockbuf,
|
|
\fIsb\fP. It strips off and returns the leading tag, strips off and
|
|
returns the length of the entire element in \fIlen\fP, and sets up
|
|
\fIber\fP for subsequent calls to
|
|
.BR ber_scanf ()
|
|
et al to decode the element. See
|
|
.BR lber-sockbuf (3)
|
|
for details of the Sockbuf implementation of the \fIsb\fP parameter.
|
|
.LP
|
|
The
|
|
.BR ber_scanf ()
|
|
routine is used to decode a BER element in much the same way that
|
|
.BR scanf (3)
|
|
works. It reads from \fIber\fP, a pointer to a BerElement
|
|
such as returned by
|
|
.BR ber_get_next (),
|
|
interprets the bytes according to the format string \fIfmt\fP, and stores the
|
|
results in its additional arguments. The format string contains
|
|
conversion specifications which are used to direct the interpretation
|
|
of the BER element. The format string can contain the following
|
|
characters.
|
|
.RS
|
|
.LP
|
|
.TP 3
|
|
.B a
|
|
Octet string. A char ** should be supplied. Memory is allocated,
|
|
filled with the contents of the octet string, null-terminated, and
|
|
returned in the parameter. The caller should free the returned
|
|
string using
|
|
.BR ber_memfree ().
|
|
.TP
|
|
.B A
|
|
Octet string. A variant of "\fBa\fP". A char ** should be supplied.
|
|
Memory is allocated, filled with the contents of the octet string,
|
|
null-terminated, and returned in the parameter, unless a zero-length
|
|
string would result; in that case, the arg is set to NULL.
|
|
The caller should free the returned string using
|
|
.BR ber_memfree ().
|
|
.TP
|
|
.B s
|
|
Octet string. A char * buffer should be supplied, followed by a pointer to a
|
|
ber_len_t initialized to the size of the buffer. Upon return, the
|
|
null-terminated octet string is put into the buffer, and the
|
|
ber_len_t is set to the actual size of the octet string.
|
|
.TP
|
|
.B O
|
|
Octet string. A struct ber_val ** should be supplied, which upon
|
|
return points to a dynamically allocated struct berval
|
|
containing the octet string and its length.
|
|
The caller should free the returned structure using
|
|
.BR ber_bvfree ().
|
|
.TP
|
|
.B o
|
|
Octet string. A struct ber_val * should be supplied, which upon
|
|
return contains the dynamically allocated
|
|
octet string and its length. The caller should free the returned octet
|
|
string using
|
|
.BR ber_memfree ().
|
|
.TP
|
|
.B m
|
|
Octet string. A struct ber_val * should be supplied, which upon return
|
|
contains the octet string and its length. The string resides in memory
|
|
assigned to the BerElement, and must not be freed by the caller.
|
|
.TP
|
|
.B b
|
|
Boolean. A pointer to a ber_int_t should be supplied.
|
|
.TP
|
|
.B e
|
|
Enumeration. A pointer to a ber_int_t should be supplied.
|
|
.TP
|
|
.B i
|
|
Integer. A pointer to a ber_int_t should be supplied.
|
|
.TP
|
|
.B B
|
|
Bitstring. A char ** should be supplied which will point to the
|
|
dynamically allocated
|
|
bits, followed by a ber_len_t *, which will point to the length
|
|
(in bits) of the bitstring returned.
|
|
.TP
|
|
.B n
|
|
Null. No parameter is required. The element is simply skipped if
|
|
it is recognized.
|
|
.TP
|
|
.B v
|
|
Sequence of octet strings. A char *** should be supplied, which upon
|
|
return points to a dynamically allocated null-terminated array of char *'s
|
|
containing the octet strings. NULL is returned if the sequence is empty.
|
|
The caller should free the returned array and octet strings using
|
|
.BR ber_memvfree ().
|
|
.TP
|
|
.B V
|
|
Sequence of octet strings with lengths.
|
|
A struct berval *** should be supplied, which upon
|
|
return points to a dynamically allocated null-terminated array of
|
|
struct berval *'s
|
|
containing the octet strings and their lengths.
|
|
NULL is returned if the sequence is empty.
|
|
The caller should free the returned structures using
|
|
.BR ber_bvecfree ().
|
|
.TP
|
|
.B W
|
|
Sequence of octet strings with lengths.
|
|
A BerVarray * should be supplied, which upon
|
|
return points to a dynamically allocated array of
|
|
struct berval's
|
|
containing the octet strings and their lengths. The array is terminated
|
|
by a struct berval with a NULL bv_val string pointer.
|
|
NULL is returned if the sequence is empty.
|
|
The caller should free the returned structures using
|
|
.BR ber_bvarray_free ().
|
|
.TP
|
|
.B M
|
|
Sequence of octet strings with lengths. This is a generalized form
|
|
of the previous three formats.
|
|
A void ** (ptr) should be supplied, followed by a ber_len_t * (len)
|
|
and a ber_len_t (off).
|
|
Upon return (ptr) will point to a dynamically allocated array
|
|
whose elements are all of size (*len). A struct berval will be filled
|
|
starting at offset (off) in each element. The strings in each struct
|
|
berval reside in memory assigned to the BerElement and must not be
|
|
freed by the caller. The array is terminated by a struct berval
|
|
with a NULL bv_val string pointer. NULL is returned if the sequence
|
|
is empty. The number of elements in the array is also stored
|
|
in (*len) on return. The caller should free the returned array using
|
|
.BR ber_memfree ().
|
|
.TP
|
|
.B l
|
|
Length of the next element. A pointer to a ber_len_t should be supplied.
|
|
.TP
|
|
.B t
|
|
Tag of the next element. A pointer to a ber_tag_t should be supplied.
|
|
.TP
|
|
.B T
|
|
Skip element and return its tag. A pointer to a ber_tag_t should be supplied.
|
|
.TP
|
|
.B x
|
|
Skip element. The next element is skipped.
|
|
.TP
|
|
.B {
|
|
Begin sequence. No parameter is required. The initial sequence tag
|
|
and length are skipped.
|
|
.TP
|
|
.B }
|
|
End sequence. No parameter is required and no action is taken.
|
|
.TP
|
|
.B [
|
|
Begin set. No parameter is required. The initial set tag
|
|
and length are skipped.
|
|
.TP
|
|
.B ]
|
|
End set. No parameter is required and no action is taken.
|
|
.RE
|
|
.LP
|
|
The
|
|
.BR ber_get_int ()
|
|
routine tries to interpret the next element as an integer,
|
|
returning the result in \fInum\fP. The tag of whatever it finds is returned
|
|
on success, LBER_ERROR (\-1) on failure.
|
|
.LP
|
|
The
|
|
.BR ber_get_stringb ()
|
|
routine is used to read an octet string into a
|
|
preallocated buffer. The \fIlen\fP parameter should be initialized to
|
|
the size of the buffer, and will contain the length of the octet string
|
|
read upon return. The buffer should be big enough to take the octet
|
|
string value plus a terminating NULL byte.
|
|
.LP
|
|
The
|
|
.BR ber_get_stringa ()
|
|
routine is used to dynamically allocate space into
|
|
which an octet string is read.
|
|
The caller should free the returned string using
|
|
.BR ber_memfree().
|
|
.LP
|
|
The
|
|
.BR ber_get_stringal ()
|
|
routine is used to dynamically allocate space
|
|
into which an octet string and its length are read. It takes a
|
|
struct berval **, and returns the result in this parameter.
|
|
The caller should free the returned structure using
|
|
.BR ber_bvfree().
|
|
.LP
|
|
The
|
|
.BR ber_get_stringbv ()
|
|
routine is used to read an octet string and its length into the
|
|
provided struct berval *. If the \fIalloc\fP parameter is zero, the string
|
|
will reside in memory assigned to the BerElement, and must not be freed
|
|
by the caller. If the \fIalloc\fP parameter is non-zero, the string will be
|
|
copied into dynamically allocated space which should be returned using
|
|
.BR ber_memfree ().
|
|
.LP
|
|
The
|
|
.BR ber_get_null ()
|
|
routine is used to read a NULL element. It returns
|
|
the tag of the element it skips over.
|
|
.LP
|
|
The
|
|
.BR ber_get_boolean ()
|
|
routine is used to read a boolean value. It is called the same way that
|
|
.BR ber_get_int ()
|
|
is called.
|
|
.LP
|
|
The
|
|
.BR ber_get_enum ()
|
|
routine is used to read a enumeration value. It is called the same way that
|
|
.BR ber_get_int ()
|
|
is called.
|
|
.LP
|
|
The
|
|
.BR ber_get_bitstringa ()
|
|
routine is used to read a bitstring value. It
|
|
takes a char ** which will hold the dynamically allocated bits, followed by an
|
|
ber_len_t *, which will point to the length (in bits) of the bitstring returned.
|
|
The caller should free the returned string using
|
|
.BR ber_memfree ().
|
|
.LP
|
|
The
|
|
.BR 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
|
|
Assume the variable \fIber\fP contains a lightweight BER 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
|
|
The element can be decoded using
|
|
.BR ber_scanf ()
|
|
as follows.
|
|
.LP
|
|
.nf
|
|
ber_int_t scope, deref, size, time, attrsonly;
|
|
char *dn, **attrs;
|
|
ber_tag_t tag;
|
|
|
|
tag = ber_scanf( ber, "{aeeiib{v}}",
|
|
&dn, &scope, &deref,
|
|
&size, &time, &attrsonly, &attrs );
|
|
|
|
if( tag == LBER_ERROR ) {
|
|
/* error */
|
|
} else {
|
|
/* success */
|
|
}
|
|
|
|
ber_memfree( dn );
|
|
ber_memvfree( attrs );
|
|
.fi
|
|
.SH ERRORS
|
|
If an error occurs during decoding, generally these routines return
|
|
LBER_ERROR ((ber_tag_t)\-1).
|
|
.LP
|
|
.SH NOTES
|
|
.LP
|
|
The return values for all of these functions are declared in the
|
|
.B <lber.h>
|
|
header file. Some routines may dynamically allocate memory
|
|
which must be freed by the caller using supplied deallocation routines.
|
|
.SH SEE ALSO
|
|
.BR lber-encode (3),
|
|
.BR lber-memory (3),
|
|
.BR lber-sockbuf (3),
|
|
.BR lber-types (3)
|
|
.SH ACKNOWLEDGEMENTS
|
|
.lf 1 ./../Project
|
|
.\" Shared Project Acknowledgement Text
|
|
.B "OpenLDAP Software"
|
|
is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
|
|
.B "OpenLDAP Software"
|
|
is derived from University of Michigan LDAP 3.3 Release.
|
|
.lf 358 stdin
|