write documentation for EVP_CIPHER_CTX_copy(3)

and EVP_CIPHER_CTX_encrypting(3) from scratch

diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3
index 556b50c..b6d9080 100644 (file)
--- a/lib/libcrypto/man/EVP_EncryptInit.3
+++ b/lib/libcrypto/man/EVP_EncryptInit.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_EncryptInit.3,v 1.46 2023/08/16 13:50:05 schwarze Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.47 2023/08/26 15:01:56 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
@@ -6,7 +6,7 @@
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 2023 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
@@ -69,7 +69,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 16 2023 $
+.Dd $Mdocdate: August 26 2023 $
 .Dt EVP_ENCRYPTINIT 3
 .Os
 .Sh NAME
@@ -78,6 +78,7 @@
 .Nm EVP_CIPHER_CTX_cleanup ,
 .Nm EVP_CIPHER_CTX_init ,
 .Nm EVP_CIPHER_CTX_free ,
+.Nm EVP_CIPHER_CTX_copy ,
 .Nm EVP_EncryptInit_ex ,
 .Nm EVP_EncryptUpdate ,
 .Nm EVP_EncryptFinal_ex ,
@@ -94,6 +95,7 @@
 .Nm EVP_CipherInit ,
 .Nm EVP_CipherFinal ,
 .Nm EVP_Cipher ,
+.Nm EVP_CIPHER_CTX_encrypting ,
 .Nm EVP_CIPHER_CTX_set_flags ,
 .Nm EVP_CIPHER_CTX_clear_flags ,
 .Nm EVP_CIPHER_CTX_test_flags ,
@@ -170,6 +172,11 @@
 .Fa "EVP_CIPHER_CTX *ctx"
 .Fc
 .Ft int
+.Fo EVP_CIPHER_CTX_copy
+.Fa "EVP_CIPHER_CTX *out"
+.Fa "const EVP_CIPHER_CTX *in"
+.Fc
+.Ft int
 .Fo EVP_EncryptInit_ex
 .Fa "EVP_CIPHER_CTX *ctx"
 .Fa "const EVP_CIPHER *type"
@@ -283,6 +290,10 @@
 .Fa "const unsigned char *in"
 .Fa "unsigned int inl"
 .Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_encrypting
+.Fa "const EVP_CIPHER_CTX *ctx"
+.Fc
 .Ft void
 .Fo EVP_CIPHER_CTX_set_flags
 .Fa "EVP_CIPHER_CTX *ctx"
@@ -465,6 +476,55 @@ is a
 .Dv NULL
 pointer, no action occurs.
 .Pp
+.Fn EVP_CIPHER_CTX_copy
+calls
+.Fn EVP_CIPHER_CTX_reset
+on
+.Fa out
+and copies all the data from
+.Fa in
+to
+.Fa out ,
+except that the
+.Vt EVP_CIPHER
+and
+.Vt ENGINE
+objects used by
+.Fa in
+and any application specific data set with
+.Fn EVP_CIPHER_CTX_set_app_data
+are not copied and
+.Fa out
+will point to the same three objects.
+The algorithm- and implementation-specific cipher data described in
+.Xr EVP_CIPHER_CTX_get_cipher_data 3
+is copied with
+.Xr malloc 3
+and
+.Xr memcpy 3 ,
+i.e. assuming that it does not contain pointers to any sub-objects.
+If the bit
+.Dv EVP_CIPH_CUSTOM_COPY
+has been set with
+.Xr EVP_CIPHER_meth_set_flags 3 ,
+.Fn EVP_CIPHER_CTX_ctrl
+is called at the end with arguments
+.Fa in ,
+.Dv EVP_CTRL_COPY ,
+.No 0 ,
+and
+.Fa out
+such that the cipher implementation can perform further algorithm-
+and implementation-specific initializations after the algorithm-
+and implementation-specific cipher data has been copied.
+Among the cipher algorithms built into the library,
+.Dv EVP_CIPH_CUSTOM_COPY
+and
+.Dv EVP_CTRL_COPY
+are used by some of the ciphers documented in the
+.Xr EVP_aes_256_gcm 3
+manual page.
+.Pp
 .Fn EVP_EncryptInit_ex
 sets up the cipher context
 .Fa ctx
@@ -877,6 +937,7 @@ for failure.
 .Pp
 .Fn EVP_CIPHER_CTX_reset ,
 .Fn EVP_CIPHER_CTX_cleanup ,
+.Fn EVP_CIPHER_CTX_copy ,
 .Fn EVP_CIPHER_CTX_get_iv ,
 .Fn EVP_CIPHER_CTX_set_iv ,
 .Fn EVP_EncryptInit_ex ,
@@ -900,6 +961,12 @@ and
 .Fn EVP_CIPHER_CTX_rand_key
 return 1 for success or 0 for failure.
 .Pp
+.Fn EVP_CIPHER_CTX_encrypting
+returns 1 if
+.Fa ctx
+is initialized for encryption or 0 otherwise, in which case
+it may be uninitialized or initialized for decryption.
+.Pp
 .Fn EVP_CIPHER_CTX_set_padding
 always returns 1.
 .Pp
@@ -1243,6 +1310,7 @@ do_crypt(FILE *in, FILE *out, int do_encrypt)
 .Xr EVP_aes_128_cbc 3 ,
 .Xr EVP_camellia_128_cbc 3 ,
 .Xr EVP_chacha20 3 ,
+.Xr EVP_CIPHER_CTX_get_cipher_data 3 ,
 .Xr EVP_des_cbc 3 ,
 .Xr EVP_OpenInit 3 ,
 .Xr EVP_rc4 3 ,
@@ -1355,14 +1423,23 @@ first appeared in OpenSSL 0.9.8b.
 These functions have been available since
 .Ox 4.5 .
 .Pp
+.Fn EVP_CIPHER_CTX_copy
+first appeared in OpenSSL 1.0.0
+and has been available since
+.Ox 4.9 .
+.Pp
 .Fn EVP_CIPHER_CTX_reset
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .
 .Pp
+.Fn EVP_CIPHER_CTX_encrypting
+first appeared in OpenSSL 1.1.0 and has been available since
+.Ox 6.4 .
+.Pp
 .Fn EVP_CIPHER_CTX_get_iv
 and
 .Fn EVP_CIPHER_CTX_set_iv
-first appeared in LibreSSL 2.8.1 and has been available since
+first appeared in LibreSSL 2.8.1 and have been available since
 .Ox 6.4 .
 .Sh BUGS
 .Dv EVP_MAX_KEY_LENGTH
@@ -1378,3 +1455,8 @@ bytes.
 The ASN.1 code is incomplete (and sometimes inaccurate).
 It has only been tested for certain common S/MIME ciphers
 (RC2, DES, triple DES) in CBC mode.
+.Pp
+.Fn EVP_CIPHER_CTX_copy
+may already have cleared the data in
+.Fa out
+and copied some new data into it even if it fails and returns 0.