| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | =for openssl multiple includes
|
|---|
| 10 |
|
|---|
| 11 | #include <openssl/bio.h>
|
|---|
| 12 | #include <openssl/evp.h>
|
|---|
| 13 |
|
|---|
| 14 | const BIO_METHOD *BIO_f_cipher(void);
|
|---|
| 15 | int BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
|
|---|
| 16 | const unsigned char *key, const unsigned char *iv, int enc);
|
|---|
| 17 | int BIO_get_cipher_status(BIO *b);
|
|---|
| 18 | int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx);
|
|---|
| 19 |
|
|---|
| 20 | =head1 DESCRIPTION
|
|---|
| 21 |
|
|---|
| 22 | BIO_f_cipher() returns the cipher BIO method. This is a filter
|
|---|
| 23 | BIO that encrypts any data written through it, and decrypts any data
|
|---|
| 24 | read from it. It is a BIO wrapper for the cipher routines
|
|---|
| 25 | EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
|
|---|
| 26 |
|
|---|
| 27 | Cipher BIOs do not support BIO_gets() or BIO_puts().
|
|---|
| 28 |
|
|---|
| 29 | BIO_flush() on an encryption BIO that is being written through is
|
|---|
| 30 | used to signal that no more data is to be encrypted: this is used
|
|---|
| 31 | to flush and possibly pad the final block through the BIO.
|
|---|
| 32 |
|
|---|
| 33 | BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
|
|---|
| 34 | and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
|
|---|
| 35 | decryption.
|
|---|
| 36 |
|
|---|
| 37 | When reading from an encryption BIO the final block is automatically
|
|---|
| 38 | decrypted and checked when EOF is detected. BIO_get_cipher_status()
|
|---|
| 39 | is a BIO_ctrl() macro which can be called to determine whether the
|
|---|
| 40 | decryption operation was successful.
|
|---|
| 41 |
|
|---|
| 42 | BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
|
|---|
| 43 | BIO cipher context. The retrieved context can be used in conjunction
|
|---|
| 44 | with the standard cipher routines to set it up. This is useful when
|
|---|
| 45 | BIO_set_cipher() is not flexible enough for the applications needs.
|
|---|
| 46 |
|
|---|
| 47 | =head1 NOTES
|
|---|
| 48 |
|
|---|
| 49 | When encrypting BIO_flush() B<must> be called to flush the final block
|
|---|
| 50 | through the BIO. If it is not then the final block will fail a subsequent
|
|---|
| 51 | decrypt.
|
|---|
| 52 |
|
|---|
| 53 | When decrypting an error on the final block is signaled by a zero
|
|---|
| 54 | return value from the read operation. A successful decrypt followed
|
|---|
| 55 | by EOF will also return zero for the final read. BIO_get_cipher_status()
|
|---|
| 56 | should be called to determine if the decrypt was successful.
|
|---|
| 57 |
|
|---|
| 58 | As always, if BIO_gets() or BIO_puts() support is needed then it can
|
|---|
| 59 | be achieved by preceding the cipher BIO with a buffering BIO.
|
|---|
| 60 |
|
|---|
| 61 | =head1 RETURN VALUES
|
|---|
| 62 |
|
|---|
| 63 | BIO_f_cipher() returns the cipher BIO method.
|
|---|
| 64 |
|
|---|
| 65 | BIO_set_cipher() returns 1 for success and 0 for failure.
|
|---|
| 66 |
|
|---|
| 67 | BIO_get_cipher_status() returns 1 for a successful decrypt and <=0
|
|---|
| 68 | for failure.
|
|---|
| 69 |
|
|---|
| 70 | BIO_get_cipher_ctx() returns 1 for success and <=0 for failure.
|
|---|
| 71 |
|
|---|
| 72 | =head1 COPYRIGHT
|
|---|
| 73 |
|
|---|
| 74 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 75 |
|
|---|
| 76 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 77 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 78 | in the file LICENSE in the source distribution or at
|
|---|
| 79 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 80 |
|
|---|
| 81 | =cut
|
|---|
