From: Benjamin Kaduk <bkaduk@akamai.com>
Date: Mon, 22 Jun 2020 18:37:31 +0000 (-0700)
Subject: Document EVP_CIPHER_CTX IV accessors
X-Git-Tag: openssl-3.0.0-alpha7~597
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c76ffc78a513660b5f62bc32a64f44c62edede74;p=thirdparty%2Fopenssl.git

Document EVP_CIPHER_CTX IV accessors

Including the ones that were added in commit
83b06347023a573433b6aa23c8042f89df869f9e with a note that they "may go
away" and are now deprecated.

Remove the missingcrypto.txt entries for the now-deprecated functions.

[extended tests]

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/12233)
---

diff --git a/doc/man3/EVP_CIPHER_CTX_get_iv.pod b/doc/man3/EVP_CIPHER_CTX_get_iv.pod
new file mode 100644
index 00000000000..e099d96dec4
--- /dev/null
+++ b/doc/man3/EVP_CIPHER_CTX_get_iv.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+EVP_CIPHER_CTX_get_iv, EVP_CIPHER_CTX_get_iv_state, EVP_CIPHER_CTX_iv, EVP_CIPHER_CTX_original_iv, EVP_CIPHER_CTX_iv_noconst - Routines to inspect EVP_CIPHER_CTX IV data
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_CIPHER_CTX_get_iv(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+ int EVP_CIPHER_CTX_get_iv_state(EVP_CIPHER_CTX *ctx, void *buf, size_t len);
+ const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx);
+ const unsigned char *EVP_CIPHER_CTX_original_iv(const EVP_CIPHER_CTX *ctx);
+ unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx);
+
+=head1 DESCRIPTION
+
+EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() copy initialization
+vector (IV) information from the B<EVP_CIPHER_CTX> into the caller-supplied
+buffer.  L<EVP_CIPHER_CTX_iv_length(3)> can be used to determine an
+appropriate buffer size, and if the supplied buffer is too small, an error
+will be returned (and no data copied).  EVP_CIPHER_CTX_get_iv() accesses the
+("original") IV that was supplied when the B<EVP_CIPHER_CTX> was created, and
+EVP_CIPHER_CTX_get_iv_state() accesses the current "IV state" of the cipher,
+which is updated during cipher operation for certain cipher modes (e.g., CBC
+and OFB).
+
+The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
+EVP_CIPHER_CTX_iv_noconst() are deprecated functions that provide similar (at
+a conceptual level) functionality.  EVP_CIPHER_CTX_iv() returns a pointer to
+the beginning of the "IV state" as maintained internally in the
+B<EVP_CIPHER_CTX>; EVP_CIPHER_CTX_original_iv() returns a pointer to the
+beginning of the ("original") IV, as maintained by the B<EVP_CIPHER_CTX>, that
+was provided when the B<EVP_CIPHER_CTX> was initialized; and
+EVP_CIPHER_CTX_get_iv_noconst() is the same as EVP_CIPHER_CTX_iv() but has a
+different return type for the pointer.
+
+=head1 RETURN VALUES
+
+EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() return 1 on success
+and 0 on failure.
+
+The functions EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
+EVP_CIPHER_CTX_iv_noconst() return a pointer to an IV as an array of bytes on
+success, and NULL on failure.
+
+=head1 HISTORY
+
+EVP_CIPHER_CTX_get_iv() and EVP_CIPHER_CTX_get_iv_state() were added in
+OpenSSL 3.0.0.
+
+EVP_CIPHER_CTX_iv(), EVP_CIPHER_CTX_original_iv(), and
+EVP_CIPHER_CTX_iv_noconst() were added in OpenSSL 1.1.0, and were deprecated
+in OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt
index 3e8c62c6104..3aa3b5065b5 100644
--- a/util/missingcrypto.txt
+++ b/util/missingcrypto.txt
@@ -650,10 +650,7 @@ EVP_CIPHER_CTX_buf_noconst(3)
 EVP_CIPHER_CTX_clear_flags(3)
 EVP_CIPHER_CTX_copy(3)
 EVP_CIPHER_CTX_encrypting(3)
-EVP_CIPHER_CTX_iv(3)
-EVP_CIPHER_CTX_iv_noconst(3)
 EVP_CIPHER_CTX_num(3)
-EVP_CIPHER_CTX_original_iv(3)
 EVP_CIPHER_CTX_rand_key(3)
 EVP_CIPHER_CTX_set_flags(3)
 EVP_CIPHER_CTX_set_num(3)