summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/lber-decode.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/man3/lber-decode.3')
-rw-r--r--doc/man/man3/lber-decode.3357
1 files changed, 357 insertions, 0 deletions
diff --git a/doc/man/man3/lber-decode.3 b/doc/man/man3/lber-decode.3
new file mode 100644
index 0000000..65e0ea7
--- /dev/null
+++ b/doc/man/man3/lber-decode.3
@@ -0,0 +1,357 @@
+.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2021 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
+.so ../Project