LIBDER(3)

NAME
libder, libder_open, libder_close, libder_abort, libder_get_error, libder_has_error, libder_get_normalize, libder_set_normalize, libder_get_strict, libder_set_strict, libder_get_verbose, libder_set_verbose - DER encoding and decoding library

LIBRARY
libder

SYNOPSIS
#include <libder.h>
struct libder_ctx *
libder_open(void);
void
libder_close(struct libder_ctx *ctx);
void
libder_abort(struct libder_ctx *ctx);
const char *
libder_get_error(struct libder_ctx *ctx);
bool
libder_has_error(struct libder_ctx *ctx);
uint64_t
libder_get_normalize(struct libder_ctx *ctx);
uint64_t
libder_set_normalize(struct libder_ctx *ctx, uint64_t normalize);
bool
libder_get_strict(struct libder_ctx *ctx);
bool
libder_set_strict(struct libder_ctx *ctx, bool strict);
int
libder_get_verbose(struct libder_ctx *ctx);
int
libder_set_verbose(struct libder_ctx *ctx, int verbose);

DESCRIPTION
The libder library provides functionality for decoding BER and DER encoded data, and DER encoding data subjected to constraints outline in ITU-T Recommendation X.690. libder will apply relevant normalization rules on write, unless they've been disabled with libder_set_normalize, under the assumption that it may not be reading strictly DER encoded data.

Note that not all of the DER rules are currently implemented. libder will coalesce constructed types that DER specifies should be primitive. libder will primarily normalize bitstrings, booleans, and integers. This library was primarily written to be able to provide interoperability with OpenSSL keys and signatures, so the library was written with that in mind. Eventually it is intended that libder will support the full set of rules, but currently some responsibility is left to the library user.

Also note that libder does not necessarily provide “neat” ways to construct primitives. For example, even booleans and integers currently work just by providing a buffer that is expected to be formatted in a sane fashion. The library user is expected to build the object tree and generally provide the object data in a format reasonably encoded as the data for that type should be, then libder will provide the proper framing on write and do any transformations that may need to be done for strict conformance.

The libder_open() function allocates a new libder context. The context does not hold any state about any particular structure. All of the state held in the context is generally described in this manpage. The libder_close() function will free the context.

The libder_abort() function will abort an in-progress libder_read_fd(3) operation on the existing ctx if it is interrupted by a signal in the middle of a read(2) syscall. See libder_read_fd(3) for further discussion.

The libder_get_error() function will return an error string appropriate for the current error, if any. The libder_has_error() function can be used to check if an error was raised in a previous operation.

The libder_get_normalize() and libder_set_normalize() functions retrieve and manipulate any number of flags that detail how functions may be used to check or set the normalization flags given context, which dictates how libder will normalize data on write. The following normalization flags may be specified:
LIBDER_NORMALIZE_CONSTRUCTED | Coalesce types that may be primitive or constructed
LIBDER_NORMALIZE_TAGS | Pack tags into the lowest possible encoded value

The LIBDER_NORMALIZE_TYPE_FLAG(enum libder_ber_type) macaro may also be used to specify normalization of the given universal type. By default, every valid normalization flag is enabled.

The libder_get_strict() and libder_set_strict() functions may used to check or set the strict read state of the given libder context. By default, libder operates in strict mode and rejects various methods of expressing data that are valid looking but not strictly conformant. The LDE_STRICT_* constants in <libder.h> describe the various scenarios that strict mode may reject.

The libder_get_verbose() and libder_set_verbose() functions may be used to check or set the verbosity of the given libder context. This primarily controls how libder behaves when an error is encountered. By default, the library will silently set the error state and return. With a verbosity level of 1, an error will be printed when the error state is set that contains the string that would be returned by libder_get_error(). With a verbosity level of 2, the filename and line within libder that the error occurred in will be printed, which is primarily intended for debugging libder.

SEE ALSO
libder_obj(3), libder_read(3), libder_type(3), libder_write(3)