From 7fd26e6c254410d24011a4aa8691473fb6a69abf Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 5 Sep 2023 14:19:02 +0000 Subject: [PATCH] improve the descriptions of almost all flags, in particular saying which API functions each flag affects --- lib/libcrypto/man/EVP_CIPHER_meth_new.3 | 141 +++++++++++++++++------- 1 file 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 +.\" +.\" 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 .\" 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 -- 2.20.1