improve the descriptions of almost all flags,

in particular saying which API functions each flag affects

1 files changed, 101 insertions, 40 deletions

diff --git a/lib/libcrypto/man/EVP_CIPHER_meth_new.3 b/lib/libcrypto/man/EVP_CIPHER_meth_new.3
index 0ecb87340e0..c9e1d3ed663 100644
--- a/lib/libcrypto/man/EVP_CIPHER_meth_new.3
+++ b/lib/libcrypto/man/EVP_CIPHER_meth_new.3
@@ -1,6 +1,23 @@
-.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.2 2023/08/26 15:14:28 schwarze Exp $
+.\" $OpenBSD: EVP_CIPHER_meth_new.3,v 1.3 2023/09/05 14:19:02 schwarze Exp $
 .\" selective merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000
 .\"
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 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
+.\" 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 Richard Levitte <levitte@openssl.org>
 .\" Copyright (c) 2015 The OpenSSL Project.
 .\" All rights reserved.
@@ -49,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 26 2023 $
+.Dd $Mdocdate: September 5 2023 $
 .Dt EVP_CIPHER_METH_NEW 3
 .Os
 .Sh NAME
@@ -185,73 +202,114 @@ Zero or more of the following flags can be OR'ed into the
 argument:
 .Bl -tag -width Ds
 .It EVP_CIPH_VARIABLE_LENGTH
-This cipher is of variable length.
+This cipher has a variable key length, and the function
+.Xr EVP_CIPHER_CTX_set_key_length 3
+can be used with it.
 .It EVP_CIPH_CUSTOM_IV
-Storing and initialising the IV is left entirely to the implementation.
+Instruct
+.Xr EVP_CipherInit_ex 3
+and similar initialization functions to leave storing and initialising
+the IV entirely to the implementation.
+If this flag is set,
+the implementation is typically expected to do that in its
+.Fa init
+function.
 .It EVP_CIPH_ALWAYS_CALL_INIT
-Set this if the implementation's
-.Fn init
-function should be called even if
+Instruct
+.Xr EVP_CipherInit_ex 3
+and similar initialization functions to call the implementation's
+.Fa init
+function even if the
 .Fa key
-is
+argument is
 .Dv NULL .
 .It EVP_CIPH_CTRL_INIT
-Set this to have the implementation's
-.Fn ctrl
-function called with command code
+Instruct
+.Xr EVP_CipherInit_ex 3
+and similar initialization functions to call the implementation's
+.Fa ctrl
+function with a command
+.Fa type
+of
 .Dv EVP_CTRL_INIT
-early in its setup.
+early during the setup.
 .It EVP_CIPH_CUSTOM_KEY_LENGTH
-Checking and setting the key length after creating the
-.Vt EVP_CIPHER
-is left to the implementation.
-Whenever someone uses
+Instruct
 .Xr EVP_CIPHER_CTX_set_key_length 3
-on a
-.Vt EVP_CIPHER
-with this flag set, the implementation's
-.Fn ctrl
-function will be called with the control code
+to not check and set the key length itself,
+but to leave that to the implementation by instead calling its
+.Fa ctrl
+function with a command
+.Fa type
+of
 .Dv EVP_CTRL_SET_KEY_LENGTH
 and the key length in
 .Fa arg .
 .It EVP_CIPH_NO_PADDING
-Don't use standard block padding.
+Instruct
+.Xr EVP_CipherFinal_ex 3
+and similar finalization functions to not use standard block padding
+but instead report an error if the total amount of data
+to be encrypted or decrypted is not a multiple of the block size.
 .It EVP_CIPH_RAND_KEY
-Making a key with random content is left to the implementation.
-This is done by calling the implementation's
-.Fn ctrl
-function with the control code
+Instruct
+.Xr EVP_CIPHER_CTX_rand_key 3
+to not generate a random key using
+.Xr arc4random_buf 3
+but instead leave that to the implementation by calling the
+.Fa ctrl
+function with a command
+.Fa type
+of
 .Dv EVP_CTRL_RAND_KEY
 and the pointer to the key memory storage in
 .Fa ptr .
 .It EVP_CIPH_CUSTOM_COPY
-Set this to have the implementation's
-.Fn ctrl
-function called with command code
+Instruct
+.Xr EVP_CIPHER_CTX_copy 3
+to call the implementation's
+.Fa ctrl
+function with a command
+.Fa type
+of
 .Dv EVP_CTRL_COPY
-at the end of
-.Xr EVP_CIPHER_CTX_copy 3 .
+and the destination
+.Fa "EVP_CIPHER_CTX *out"
+in the
+.Fa ptr
+argument immediately before returning successfully.
 The intended use is for further things to deal with after the
 implementation specific data block has been copied.
-The destination
-.Vt EVP_CIPHER_CTX
-object is passed to the control with the
-.Fa ptr
-parameter.
 The implementation-specific data block is reached with
 .Xr EVP_CIPHER_CTX_get_cipher_data 3 .
 .It EVP_CIPH_FLAG_DEFAULT_ASN1
-Use the default EVP routines to pass IV to and from ASN.1.
+Instruct
+.Xr EVP_CIPHER_param_to_asn1 3
+to use
+.Xr ASN1_TYPE_set_octetstring 3
+if no
+.Fa set_asn1_parameters
+function is installed, and instruct
+.Xr EVP_CIPHER_asn1_to_param 3
+to use
+.Xr ASN1_TYPE_get_octetstring 3
+if no
+.Fa get_asn1_parameters
+function is installed.
 .It EVP_CIPH_FLAG_LENGTH_BITS
 Signals that the length of the input buffer for encryption / decryption
 is to be understood as the number of bits instead of bytes for this
 implementation.
 This is only useful for CFB1 ciphers.
 .It EVP_CIPH_FLAG_CUSTOM_CIPHER
-This indicates that the implementation takes care of everything,
+Instruct
+.Xr EVP_CipherUpdate 3 ,
+.Xr EVP_CipherFinal_ex 3 ,
+and similar encryption, decryption, and finalization functions
+that the implementation's
+.Fa do_cipher
+function takes care of everything,
 including padding, buffering and finalization.
-The EVP routines will simply give them control and do nothing more.
 .It EVP_CIPH_FLAG_AEAD_CIPHER
 This indicates that this is an AEAD cipher implementation.
 .El
@@ -261,7 +319,9 @@ sets the size of the EVP_CIPHER's implementation context so that it can
 be automatically allocated.
 .Pp
 .Fn EVP_CIPHER_meth_set_init
-sets the cipher init function for
+sets the
+.Fa init
+function for
 .Fa cipher .
 The cipher init function is called by
 .Xr EVP_CipherInit 3 ,
@@ -269,6 +329,7 @@ The cipher init function is called by
 .Xr EVP_EncryptInit 3 ,
 .Xr EVP_EncryptInit_ex 3 ,
 .Xr EVP_DecryptInit 3 ,
+and
 .Xr EVP_DecryptInit_ex 3 .
 .Pp
 .Fn EVP_CIPHER_meth_set_do_cipher