Sortix main manual

This manual documents Sortix main. You can instead view this document in the latest official manual.

NAME

BIO_f_asn1, asn1_ps_func, BIO_asn1_set_prefix, BIO_asn1_get_prefix, BIO_asn1_set_suffix, BIO_asn1_get_suffix — BER-encoding filter BIO

SYNOPSIS

#include <openssl/asn1.h>

const BIO_METHOD *
BIO_f_asn1(void);

#include <openssl/bio.h>

typedef int
asn1_ps_func(BIO *bio, unsigned char **pbuf, int *plen, void *parg);

int
BIO_asn1_set_prefix(BIO *chain, asn1_ps_func *prefix, asn1_ps_func *prefix_free);

int
BIO_asn1_get_prefix(BIO *chain, asn1_ps_func **pprefix, asn1_ps_func **pprefix_free);

int
BIO_asn1_set_suffix(BIO *chain, asn1_ps_func *suffix, asn1_ps_func *suffix_free);

int
BIO_asn1_get_suffix(BIO *chain, asn1_ps_func **psuffix, asn1_ps_func **psuffix_free);

DESCRIPTION

BIO_f_asn1() returns the “asn1” BIO method. BIOs created from it with BIO_new(3) are filter BIOs intended to BER-encode data written to them and pass the encoded data on to the next BIO in the chain. Such BIOs operate as follows:

BIO_method_type(3): returns BIO_TYPE_ASN1.
BIO_method_name(3): returns a pointer to the static string “asn1”.
BIO_write(3): writes the DER encoding of an ASN.1 OCTET STRING with the len content octets in buf to the next BIO in the chain.

If a prefix function was installed with BIO_asn1_set_prefix(), that function is called before writing the object. It may for example produce additional output. If it fails, writing fails.

If a prefix_free function was installed as well, that function is called after writing any output produced by prefix but before writing the object. Failure of prefix_free is silently ignored.
BIO_puts(3): operates like BIO_write(3) but uses the strlen(3) of buf instead of a len argument.
BIO_flush(3): calls the suffix callback function, if any. If that produces any output, it calls the suffix_free callback function, if any, silently ignoring failure. Finally, it calls BIO_flush(3) on the next BIO in the chain. It fails if no data was previously written or if the suffix callback, writing, or BIO_flush(3) on the next BIO fail.
BIO_ctrl(3): with a cmd of BIO_C_SET_EX_ARG stores the pointer parg internally such that it will be passed to the asn1_ps_func() callback functions. With a cmd of BIO_C_GET_EX_ARG, it retrieves that pointer, storing it in *parg. The commands BIO_C_SET_PREFIX, BIO_C_GET_PREFIX, BIO_C_SET_SUFFIX, BIO_C_GET_SUFFIX, and BIO_CTRL_FLUSH are used internally to implement BIO_asn1_set_prefix(), BIO_asn1_get_prefix(), BIO_asn1_set_suffix(), BIO_asn1_get_suffix() and BIO_flush(3) and are not intended for use by application programs. Other commands are merely forwarded to the next BIO in the chain.
BIO_read(3), BIO_gets(3), and BIO_callback_ctrl(3): merely call the same function on the next BIO in the chain.

If the above description of a function mentions the next BIO in the chain, that function fails if the asn1 BIO is the last BIO in the chain.

BIO_asn1_set_prefix() and BIO_asn1_get_prefix() install and retrieve the prefix and prefix_free callback functions in and from the first asn1 BIO in the given chain. Similarly, BIO_asn1_set_suffix() and BIO_asn1_get_suffix() install and retrieve the suffix and suffix_free callback functions. Passing a NULL pointer for any of the asn1_ps_func() arguments disables that particular callback.

RETURN VALUES

BIO_f_asn1() always returns a pointer to a static built-in object.

Functions of the type asn1_ps_func() are supposed to return 1 on success or 0 on failure.

BIO_asn1_set_prefix(), BIO_asn1_get_prefix(), BIO_asn1_set_suffix(), and BIO_asn1_get_suffix() return 1 on success or 0 if chain is a NULL pointer or does not contain any asn1 BIO. They may return -2 if a BIO is encountered in the chain that is not properly initialized.

HISTORY

These functions first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.