From: schwarze Date: Sat, 26 Aug 2023 15:01:56 +0000 (+0000) Subject: write documentation for EVP_CIPHER_CTX_copy(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=a934d56a2727556a771214b36a176e17b60cc214;p=openbsd 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 556b50c925d..b6d9080bea3 100644 --- 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 +.\" Copyright (c) 2019, 2023 Ingo Schwarze .\" .\" 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.