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.

SEE ALSO

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)

HISTORY

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