]>
Commit | Line | Data |
---|---|---|
b1ccd57b DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
8eec1389 | 5 | BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter |
b1ccd57b DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
b97fdb57 RL |
9 | =for comment multiple includes |
10 | ||
b1ccd57b DSH |
11 | #include <openssl/bio.h> |
12 | #include <openssl/evp.h> | |
13 | ||
1bc74519 | 14 | const BIO_METHOD *BIO_f_cipher(void); |
35d2e327 | 15 | void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, |
e9b77246 | 16 | unsigned char *key, unsigned char *iv, int enc); |
b1ccd57b DSH |
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 | ||
1bc74519 | 27 | Cipher BIOs do not support BIO_gets() or BIO_puts(). |
b1ccd57b DSH |
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 | ||
6ac26a5c | 33 | BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key> |
b1ccd57b DSH |
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 | |
1e4e5492 | 43 | BIO cipher context. The retrieved context can be used in conjunction |
b1ccd57b DSH |
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 | ||
186bb907 | 53 | When decrypting an error on the final block is signaled by a zero |
b1ccd57b DSH |
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() does not return a value. | |
66 | ||
67 | BIO_get_cipher_status() returns 1 for a successful decrypt and 0 | |
68 | for failure. | |
69 | ||
70 | BIO_get_cipher_ctx() currently always returns 1. | |
71 | ||
e2f92610 RS |
72 | =head1 COPYRIGHT |
73 | ||
74 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
75 | ||
4746f25a | 76 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |