EVP_f_md() -- SSLeay 0.9.0b -- January 1999

NAME

BIO_f_md, BIO_f_base64, BIO_f_cipher, BIO_set_cipher -- EVP BIO filters

SYNOPSIS

#include "evp.h"

BIO_METHOD *BIO_f_md();

BIO_METHOD *BIO_f_base64();

BIO_METHOD *BIO_f_cipher();

void BIO_set_cipher(b, c, k, i, enc) BIO *b; EVP_CIPHER *c; unsigned char *k, *i; int enc;

DESCRIPTION

The EVP BIO routines all rely on the BIO_METHOD structure, which is defined in the BIO section.

BIO_f_type where type is one of md, base64, or cipher, sets up a BIO filter which operates on the data stream being read to/written from the BIO.

BIO_f_md just returns a pointer to the methods_md BIO_METHOD, which contains:

static BIO_METHOD methods_md=
        {
        BIO_TYPE_MD,"message digest",
        md_write,
        md_read,
        NULL, /* md_puts, */
        md_gets,
        md_ctrl,
        md_new,
        md_free,
        };

All data read or written via BIO_read() or BIO_write() to a BIO using this method will be added to the calculated digest.

Note that this BIO_method is only one directional; you cannot use one BIO with this method to both read and write.

The following macros are provided as convenience to the user:

#define BIO_set_md(b,md) BIO_ctrl(b,BIO_C_SET_MD,0,(char *)md) #define BIO_get_md(b,mdp) BIO_ctrl(b,BIO_C_GET_MD,0,(char *)mdp) #define BIO_get_md_ctx(b,mdcp) BIO_ctrl(b,BIO_C_GET_MD_CTX,0,(char *)mdcp)

BIO_set_md sets the message digest to use, and BIO_get_md returns the message digest in use or 0 if none has been set. BIO_get_md_ctx returns the EVP_MD_CTX of the digest in use, or 0 if none.

This function (BIO_f_md) is called in dgst.c (compiled into the ssleay app); this is a good example to see how to use the filter.

BIO_f_cipher returns a pointer to methods_enc which contains:

static BIO_METHOD methods_enc=
        {
        BIO_TYPE_CIPHER,"cipher",
        enc_write,
        enc_read,
        NULL, /* enc_puts, */
        NULL, /* enc_gets, */
        enc_ctrl,
        enc_new,
        enc_free,
        };

All data read or written via BIO_read() or BIO_write() to a BIO using this method will be encrypted or decrypted after data is read from or before data is written to the BIO.

Note that this BIO_method is only one directional; you cannot use one BIO with this method to both read and write.

BIO_set_cipher sets the cipher to use. k is the encryption key, i is the ivector, c is a pointer to the EVP_CIPHER structure for the particular cipher, and enc is 1 to encrypt and 0 to decrypt. See EVP handling for symmetric ciphers for a description of the EVP_CIPHER structure.

The following macro is provided for the convenience of the user:

#define BIO_get_cipher_status(b)    BIO_ctrl(b,BIO_C_GET_CIPHER_STATUS,0,NUL

BIO_get_cipher_status returns the ok flag from the BIO_ENC_CTX (a structure specific to the methods_enc BIO_METHOD); this flag is 0 if decryption was performed and failed. Decryption may fail for example if we are in the middle of reading from the BIO and the read fails; then we cannot continue with decryption of the data stream.

This function (BIO_f_cipher) is called in enc.c (compiled into the ssleay app); this is a good example to see how to use the filter.

BIO_f_base64 just returns a pointer to the methods_b4 BIO_METHOD, which contains:

static BIO_METHOD methods_b64=
        {
        BIO_TYPE_BASE64,"base64 encoding",
        b64_write,
        b64_read,
        NULL, /* b64_puts, */
        NULL, /* b64_gets, */
        b64_ctrl,
        b64_new,
        b64_free,
        };

All data read via BIO_read() from a BIO using this method will be base64 decoded after reading, and all data written to a BIO using this method will be base64 encoded before writing.

Note that this BIO_METHOD is only one directional; you cannot use one BIO with this method to both read and write.

See BIO routines for more information on the BIO structure and on using BIO_ calls.