document but do not recommend EVP_Cipher(3);

jsing@ provided crucial help regarding the content;
tweaks and OK tb@

1 files changed, 52 insertions, 3 deletions

diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3
index 986f66a591d..873a09aa37b 100644
--- a/lib/libcrypto/man/EVP_EncryptInit.3
+++ b/lib/libcrypto/man/EVP_EncryptInit.3
@@ -1,11 +1,28 @@
-.\" $OpenBSD: EVP_EncryptInit.3,v 1.35 2019/06/06 01:06:58 schwarze Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.36 2019/08/15 09:36:29 schwarze Exp $
 .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800
 .\"   EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod
 .\"   7c6d372a Nov 20 13:20:01 2018 +0000
 .\" selective merge up to: OpenSSL 16cfc2c9 Mar 8 22:30:28 2018 +0100
 .\"   EVP_chacha20.pod 8fa4d95e Oct 21 11:59:09 2017 +0900
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
 .\" and Richard Levitte <levitte@openssl.org>.
 .\" Copyright (c) 2000-2002, 2005, 2012-2016 The OpenSSL Project.
 .\" All rights reserved.
@@ -54,7 +71,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: August 15 2019 $
 .Dt EVP_ENCRYPTINIT 3
 .Os
 .Sh NAME
@@ -78,6 +95,7 @@
 .Nm EVP_DecryptFinal ,
 .Nm EVP_CipherInit ,
 .Nm EVP_CipherFinal ,
+.Nm EVP_Cipher ,
 .Nm EVP_CIPHER_CTX_set_flags ,
 .Nm EVP_CIPHER_CTX_clear_flags ,
 .Nm EVP_CIPHER_CTX_test_flags ,
@@ -261,6 +279,13 @@
 .Fa "unsigned char *outm"
 .Fa "int *outl"
 .Fc
+.Ft int
+.Fo EVP_Cipher
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fa "unsigned char *out"
+.Fa "const unsigned char *in"
+.Fa "unsigned int inl"
+.Fc
 .Ft void
 .Fo EVP_CIPHER_CTX_set_flags
 .Fa "EVP_CIPHER_CTX *ctx"
@@ -583,6 +608,28 @@ or
 .Fn EVP_CIPHER_CTX_free
 must be called to free any context resources.
 .Pp
+.Fn EVP_Cipher
+encrypts or decrypts aligned blocks of data
+whose lengths match the cipher block size.
+It requires that the previous encryption or decryption operation
+using the same
+.Fa ctx ,
+if there was any, ended exactly on a block boundary and that
+.Fa inl
+is an integer multiple of the cipher block size.
+If either of these conditions is violated,
+.Fn EVP_Cipher
+silently produces incorrect results.
+For that reason, using the function
+.Fn EVP_CipherUpdate
+instead is strongly recommended.
+The latter can safely handle partial blocks, and even if
+.Fa inl
+actually is a multiple of the cipher block size for all calls,
+the overhead incurred by using
+.Fn EVP_CipherUpdate
+is minimal.
+.Pp
 .Fn EVP_get_cipherbyname ,
 .Fn EVP_get_cipherbynid ,
 and
@@ -857,6 +904,7 @@ for failure.
 .Fn EVP_DecryptFinal ,
 .Fn EVP_CipherInit ,
 .Fn EVP_CipherFinal ,
+.Fn EVP_Cipher ,
 .Fn EVP_CIPHER_CTX_set_key_length ,
 and
 .Fn EVP_CIPHER_CTX_rand_key
@@ -1226,6 +1274,7 @@ first appeared in SSLeay 0.5.1.
 and
 .Fn EVP_rc2_ofb
 first appeared in SSLeay 0.5.2.
+.Fn EVP_Cipher ,
 .Fn EVP_CIPHER_block_size ,
 .Fn EVP_CIPHER_key_length ,
 .Fn EVP_CIPHER_iv_length ,