diff options
Diffstat (limited to 'doc/man/man3/lber-decode.3')
| -rw-r--r-- | doc/man/man3/lber-decode.3 | 357 |
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..97d4932 --- /dev/null +++ b/doc/man/man3/lber-decode.3 @@ -0,0 +1,357 @@ +.TH LBER_DECODE 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2022 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 |