---
name: "libressl-BIO_f_cipher"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-BIO_f_cipher"
---

# libressl-BIO\_f\_cipher(3)

cipher BIO filter

## NAME

**BIO\_f\_cipher**, **BIO\_set\_cipher**, **BIO\_get\_cipher\_status**, **BIO\_get\_cipher\_ctx** – cipher BIO filter

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/bio.h\>**

**#include \<openssl/evp.h\>**

*const* *BIO\_METHOD* *\**\

**BIO\_f\_cipher**(*void*);

*int*\

**BIO\_set\_cipher**(*BIO \*b*, *const EVP\_CIPHER \*cipher*, *unsigned char \*key*, *unsigned char \*iv*, *int enc*);

*long*\

**BIO\_get\_cipher\_status**(*BIO \*b*);

*long*\

**BIO\_get\_cipher\_ctx**(*BIO \*b*, *EVP\_CIPHER\_CTX \*\*pctx*);

## DESCRIPTION

**BIO\_f\_cipher**() returns the cipher BIO method. This is a filter BIO that encrypts any data written through it, and decrypts any data read from it. It is a BIO wrapper for the cipher routines EVP\_CipherInit(3), EVP\_CipherUpdate(3), and EVP\_CipherFinal(3).

Cipher BIOs do not support BIO\_gets(3) or BIO\_puts(3).

BIO\_flush(3) on an encryption BIO that is being written through is used to signal that no more data is to be encrypted: this is used to flush and possibly pad the final block through the BIO.

**BIO\_set\_cipher**() sets the cipher of BIO *b* to *cipher* using key *key* and IV *iv*. *enc* should be set to 1 for encryption and zero for decryption.

When reading from an encryption BIO, the final block is automatically decrypted and checked when EOF is detected. **BIO\_get\_cipher\_status**() is a BIO\_ctrl(3) macro which can be called to determine whether the decryption operation was successful.

**BIO\_get\_cipher\_ctx**() is a BIO\_ctrl(3) macro which retrieves the internal BIO cipher context. The retrieved context can be used in conjunction with the standard cipher routines to set it up. This is useful when **BIO\_set\_cipher**() is not flexible enough for the applications needs.

When a chain containing a cipher BIO is copied with BIO\_dup\_chain(3), the cipher context is automatically copied from the existing BIO object to the new one and the init flag that can be retrieved with BIO\_get\_init(3) is set to 1.

When encrypting, BIO\_flush(3) must be called to flush the final block through the BIO. If it is not, then the final block will fail a subsequent decrypt.

When decrypting, an error on the final block is signalled by a zero return value from the read operation. A successful decrypt followed by EOF will also return zero for the final read. **BIO\_get\_cipher\_status**() should be called to determine if the decrypt was successful.

As always, if BIO\_gets(3) or BIO\_puts(3) support is needed, then it can be achieved by preceding the cipher BIO with a buffering BIO.

BIO\_ctrl(3) *cmd* arguments correspond to macros as follows:

| | |
| --- | --- |
| *cmd* constant | corresponding macro |
| BIO\_C\_GET\_CIPHER\_CTX | **BIO\_get\_cipher\_ctx**() |
| BIO\_C\_GET\_CIPHER\_STATUS | **BIO\_get\_cipher\_status**() |
| BIO\_CTRL\_FLUSH | BIO\_flush(3) |
| BIO\_CTRL\_PENDING | BIO\_pending(3) |
| BIO\_CTRL\_RESET | BIO\_reset(3) |
| BIO\_CTRL\_WPENDING | BIO\_wpending(3) |

## RETURN VALUES

**BIO\_f\_cipher**() returns the cipher BIO method.

When called on a cipher BIO object, BIO\_method\_type(3) returns the constant BIO\_TYPE\_CIPHER and BIO\_method\_name(3) returns a pointer to the static string "cipher".

**BIO\_set\_cipher**() returns 1 on success and 0 on error.

**BIO\_get\_cipher\_status**() returns 1 for a successful decrypt and 0 for failure.

**BIO\_get\_cipher\_ctx**() currently always returns 1.

## SEE ALSO

BIO\_new(3), EVP\_EncryptInit(3)

## HISTORY

**BIO\_f\_cipher**(), **BIO\_set\_cipher**(), and **BIO\_get\_cipher\_status**() first appeared in SSLeay 0.6.5 and have been available since OpenBSD 2.4.

**BIO\_get\_cipher\_ctx**() first appeared in SSLeay 0.9.1 and has been available since OpenBSD 2.6.