OpenBSD manual page server

Manual Page Search Parameters
BIO_F_ASN1(3) Library Functions Manual BIO_F_ASN1(3)

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

#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);

() 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 (), 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 () 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.

() and () install and retrieve the prefix and prefix_free callback functions in and from the first asn1 BIO in the given chain. Similarly, () and () 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.

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.

ASN1_put_object(3), BIO_ctrl(3), BIO_new(3), BIO_new_NDEF(3), BIO_next(3), BIO_write(3), i2d_ASN1_OCTET_STRING(3)

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

OpenBSD-7.1 December 12, 2021 BIO_F_ASN1(3)