1=pod
2
3=head1 NAME
4
5EVP_CIPHER_CTX_get_original_iv, EVP_CIPHER_CTX_get_updated_iv,
6EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv,
7EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data
8
9=head1 SYNOPSIS
10
11 #include <openssl/evp.h>
12
13 int EVP_CIPHER_CTX_get_original_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
14 int EVP_CIPHER_CTX_get_updated_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
15
16The following functions have been deprecated since OpenSSL 3.0, and can be
17hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
18see L<openssl_user_macros(7)>:
19
20 const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);
21 const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);
22 unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);
23
24=head1 DESCRIPTION
25
26EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() copy
27initialization vector (IV) information from the B<EVP_CIPHER_CTX> into the
28caller-supplied buffer. L<EVP_CIPHER_CTX_get_iv_length(3)> can be used to
29determine an appropriate buffer size, and if the supplied buffer is too small,
30an error will be returned (and no data copied).
31EVP_CIPHER_CTX_get_original_iv() accesses the ("original") IV that was
32supplied when the B<EVP_CIPHER_CTX> was initialized, and
33EVP_CIPHER_CTX_get_updated_iv() accesses the current "IV state"
34of the cipher, which is updated during cipher operation for certain cipher modes
35(e.g., CBC and OFB).
36
37The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
38EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at
39a conceptual level) functionality.  EVP_CIPHER_CTX_iv() returns a pointer to
40the beginning of the "IV state" as maintained internally in the
41B<EVP_CIPHER_CTX>; EVP_CIPHER_CTX_original_iv() returns a pointer to the
42beginning of the ("original") IV, as maintained by the B<EVP_CIPHER_CTX>, that
43was provided when the B<EVP_CIPHER_CTX> was initialized; and
44EVP_CIPHER_CTX_get_iv_noconst() is the same as EVP_CIPHER_CTX_iv() but has a
45different return type for the pointer.
46
47=head1 RETURN VALUES
48
49EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() return 1
50on success and 0 on failure.
51
52The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
53EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on
54success, and NULL on failure.
55
56=head1 HISTORY
57
58EVP_CIPHER_CTX_get_original_iv() and EVP_CIPHER_CTX_get_updated_iv() were added
59in OpenSSL 3.0.0.
60
61EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
62EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated
63in OpenSSL 3.0.0.
64
65=head1 COPYRIGHT
66
67Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
68
69Licensed under the Apache License 2.0 (the "License").  You may not use
70this file except in compliance with the License.  You can obtain a copy
71in the file LICENSE in the source distribution or at
72L<https://www.openssl.org/source/license.html>.
73
74=cut
75