sync with OpenBSD -current

This commit is contained in:
purplerain 2023-12-01 13:02:08 +00:00
parent 9fbd947ba3
commit 8873eac723
Signed by: purplerain
GPG key ID: F42C07F07E2E35B7
33 changed files with 1109 additions and 413 deletions

View file

@ -0,0 +1,150 @@
.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.1 2023/12/01 10:40:21 schwarze Exp $
.\" full merge up to:
.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2018, 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-2001, 2015 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\" software must display the following acknowledgment:
.\" "This product includes software developed by the OpenSSL Project
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\" endorse or promote products derived from this software without
.\" prior written permission. For written permission, please contact
.\" openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\" nor may "OpenSSL" appear in their names without prior written
.\" permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\" acknowledgment:
.\" "This product includes software developed by the OpenSSL Project
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: December 1 2023 $
.Dt EVP_CIPHER_CTX_INIT 3
.Os
.Sh NAME
.Nm EVP_CIPHER_CTX_init ,
.Nm EVP_CIPHER_CTX_cleanup ,
.Nm EVP_Cipher
.Nd obsolete EVP cipher functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft void
.Fo EVP_CIPHER_CTX_init
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_CIPHER_CTX_cleanup
.Fa "EVP_CIPHER_CTX *ctx"
.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
.Sh DESCRIPTION
.Fn EVP_CIPHER_CTX_init
is a deprecated function to clear a cipher context on the stack
before use.
Do not use it on a cipher context returned from
.Xr EVP_CIPHER_CTX_new 3
or one that was already used.
.Pp
.Fn EVP_CIPHER_CTX_cleanup
is a deprecated alias for
.Xr EVP_CIPHER_CTX_reset 3 .
It clears all information from
.Fa ctx
and frees all allocated memory associated with it, except the
.Fa ctx
object itself.
.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
.Xr EVP_CipherUpdate 3
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
.Xr EVP_CipherUpdate 3
is minimal.
.Sh RETURN VALUES
.Fn EVP_CIPHER_CTX_cleanup
and
.Fn EVP_Cipher
return 1 for success or 0 for failure.
.Sh SEE ALSO
.Xr evp 3 ,
.Xr EVP_EncryptInit 3
.Sh HISTORY
.Fn EVP_Cipher
first appeared in SSLeay 0.6.5.
.Fn EVP_CIPHER_CTX_cleanup
first appeared in SSLeay 0.8.0.
.Fn EVP_CIPHER_CTX_init
first appeared in SSLeay 0.9.0.
All these functions have been available since
.Ox 2.4 .

View file

@ -1,4 +1,4 @@
.\" $OpenBSD: EVP_EncryptInit.3,v 1.48 2023/08/31 17:27:41 schwarze Exp $
.\" $OpenBSD: EVP_EncryptInit.3,v 1.50 2023/12/01 13:43:37 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
@ -69,14 +69,12 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: August 31 2023 $
.Dd $Mdocdate: December 1 2023 $
.Dt EVP_ENCRYPTINIT 3
.Os
.Sh NAME
.Nm EVP_CIPHER_CTX_new ,
.Nm EVP_CIPHER_CTX_reset ,
.Nm EVP_CIPHER_CTX_cleanup ,
.Nm EVP_CIPHER_CTX_init ,
.Nm EVP_CIPHER_CTX_free ,
.Nm EVP_CIPHER_CTX_copy ,
.Nm EVP_EncryptInit_ex ,
@ -94,7 +92,6 @@
.Nm EVP_DecryptFinal ,
.Nm EVP_CipherInit ,
.Nm EVP_CipherFinal ,
.Nm EVP_Cipher ,
.Nm EVP_CIPHER_CTX_encrypting ,
.Nm EVP_get_cipherbyname ,
.Nm EVP_get_cipherbynid ,
@ -132,14 +129,6 @@
.Fo EVP_CIPHER_CTX_reset
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_CIPHER_CTX_cleanup
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft void
.Fo EVP_CIPHER_CTX_init
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft void
.Fo EVP_CIPHER_CTX_free
.Fa "EVP_CIPHER_CTX *ctx"
@ -257,13 +246,6 @@
.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 int
.Fo EVP_CIPHER_CTX_encrypting
.Fa "const EVP_CIPHER_CTX *ctx"
.Fc
@ -300,16 +282,6 @@ object itself, such that it can be reused for another series of calls to
.Fn EVP_CipherUpdate ,
and
.Fn EVP_CipherFinal .
.Fn EVP_CIPHER_CTX_cleanup
is a deprecated alias for
.Fn EVP_CIPHER_CTX_reset .
.Pp
.Fn EVP_CIPHER_CTX_init
is a deprecated function to clear a cipher context on the stack
before use.
Do not use it on a cipher context returned from
.Fn EVP_CIPHER_CTX_new
or one that was already used.
.Pp
.Fn EVP_CIPHER_CTX_free
clears all information from
@ -336,15 +308,13 @@ to
.Fa out ,
except that the
.Vt EVP_CIPHER
and
.Vt ENGINE
objects used by
object used by
.Fa in
and any application specific data set with
.Xr EVP_CIPHER_CTX_set_app_data 3
are not copied and
.Fa out
will point to the same three objects.
will point to the same two objects.
The algorithm- and implementation-specific cipher data described in
.Xr EVP_CIPHER_CTX_get_cipher_data 3
is copied with
@ -374,28 +344,27 @@ are used by some of the ciphers documented in the
.Xr EVP_aes_256_gcm 3
manual page.
.Pp
.Fn EVP_EncryptInit
and
.Fn EVP_EncryptInit_ex
sets up the cipher context
set up the cipher context
.Fa ctx
for encryption with cipher
.Fa type
from
.Vt ENGINE
.Fa impl .
.Fa type .
.Fa type
is normally supplied by a function such as
.Xr EVP_aes_256_cbc 3 .
If
.Fa impl
is
.Dv NULL ,
then the default implementation is used.
.Fa key
is the symmetric key to use and
.Fa iv
is the IV to use (if necessary).
The actual number of bytes used for the
key and IV depends on the cipher.
The
.Fa ENGINE *impl
argument is always ignored and passing
.Dv NULL
is recommended.
It is possible to set all parameters to
.Dv NULL
except
@ -425,8 +394,11 @@ The actual number of bytes written is placed in
.Fa outl .
.Pp
If padding is enabled (the default) then
.Fn EVP_EncryptFinal_ex
encrypts the "final" data, that is any data that remains in a partial
.Fn EVP_EncryptFinal
and
.Fn EVP_EncryptFinal_ex ,
which behave identically,
encrypt the "final" data, that is any data that remains in a partial
block.
It uses NOTES (aka PKCS padding).
The encrypted final data is written to
@ -440,18 +412,24 @@ no further calls to
should be made.
.Pp
If padding is disabled then
.Fn EVP_EncryptFinal
and
.Fn EVP_EncryptFinal_ex
will not encrypt any more data and it will return an error if any data
do not encrypt any more data and return an error if any data
remains in a partial block: that is if the total data length is not a
multiple of the block size.
.Pp
.Fn EVP_DecryptInit ,
.Fn EVP_DecryptInit_ex ,
.Fn EVP_DecryptUpdate ,
.Fn EVP_DecryptFinal ,
and
.Fn EVP_DecryptFinal_ex
are the corresponding decryption operations.
.Fn EVP_DecryptFinal
will return an error code if padding is enabled and the final block is
and
.Fn EVP_DecryptFinal_ex
return an error code if padding is enabled and the final block is
not correctly formatted.
The parameters and restrictions are identical to the encryption
operations except that if padding is enabled the decrypted data buffer
@ -463,8 +441,10 @@ unless the cipher block size is 1 in which case
.Fa inl
bytes is sufficient.
.Pp
.Fn EVP_CipherInit ,
.Fn EVP_CipherInit_ex ,
.Fn EVP_CipherUpdate ,
.Fn EVP_CipherFinal ,
and
.Fn EVP_CipherFinal_ex
are functions that can be used for decryption or encryption.
@ -476,59 +456,6 @@ the value unchanged (the actual value of
.Fa enc
being supplied in a previous call).
.Pp
.Fn EVP_EncryptInit ,
.Fn EVP_DecryptInit ,
and
.Fn EVP_CipherInit
are deprecated functions behaving like
.Fn EVP_EncryptInit_ex ,
.Fn EVP_DecryptInit_ex ,
and
.Fn EVP_CipherInit_ex
except that they always use the default cipher implementation
and that they require
.Fn EVP_CIPHER_CTX_reset
before they can be used on a context that was already used.
.Pp
.Fn EVP_EncryptFinal ,
.Fn EVP_DecryptFinal ,
and
.Fn EVP_CipherFinal
are identical to
.Fn EVP_EncryptFinal_ex ,
.Fn EVP_DecryptFinal_ex ,
and
.Fn EVP_CipherFinal_ex .
In previous releases of OpenSSL, they also used to clean up the
.Fa ctx ,
but this is no longer done and
.Fn EVP_CIPHER_CTX_reset
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
@ -570,25 +497,6 @@ final decrypt error.
If padding is disabled then the decryption operation will always succeed
if the total amount of data decrypted is a multiple of the block size.
.Pp
The functions
.Fn EVP_EncryptInit ,
.Fn EVP_EncryptFinal ,
.Fn EVP_DecryptInit ,
.Fn EVP_CipherInit ,
and
.Fn EVP_CipherFinal
are obsolete but are retained for compatibility with existing code.
New code should use
.Fn EVP_EncryptInit_ex ,
.Fn EVP_EncryptFinal_ex ,
.Fn EVP_DecryptInit_ex ,
.Fn EVP_DecryptFinal_ex ,
.Fn EVP_CipherInit_ex ,
and
.Fn EVP_CipherFinal_ex
because they can reuse an existing context without allocating and
freeing it up on each call.
.Pp
.Fn EVP_get_cipherbynid
and
.Fn EVP_get_cipherbyobj
@ -602,7 +510,6 @@ for success or
for failure.
.Pp
.Fn EVP_CIPHER_CTX_reset ,
.Fn EVP_CIPHER_CTX_cleanup ,
.Fn EVP_CIPHER_CTX_copy ,
.Fn EVP_EncryptInit_ex ,
.Fn EVP_EncryptUpdate ,
@ -618,9 +525,8 @@ for failure.
.Fn EVP_DecryptInit ,
.Fn EVP_DecryptFinal ,
.Fn EVP_CipherInit ,
.Fn EVP_CipherFinal ,
and
.Fn EVP_Cipher
.Fn EVP_CipherFinal
return 1 for success or 0 for failure.
.Pp
.Fn EVP_CIPHER_CTX_encrypting
@ -729,13 +635,17 @@ To specify any additional authenticated data (AAD), a call to
.Fn EVP_EncryptUpdate ,
or
.Fn EVP_DecryptUpdate
should be made with the output parameter out set to
should be made with the output parameter
.Fa out
set to
.Dv NULL .
.Pp
When decrypting, the return value of
.Fn EVP_DecryptFinal
.Fn EVP_DecryptFinal ,
.Fn EVP_DecryptFinal_ex ,
.Fn EVP_CipherFinal ,
or
.Fn EVP_CipherFinal
.Fn EVP_CipherFinal_ex
indicates if the operation was successful.
If it does not indicate success, the authentication operation has
failed and any output data MUST NOT be used as it is corrupted.
@ -754,6 +664,8 @@ bytes of the tag value to the buffer indicated by
This call can only be made when encrypting data and after all data has
been processed, e.g. after an
.Fn EVP_EncryptFinal
or
.Fn EVP_EncryptFinal_ex
call.
.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag
Sets the expected tag to
@ -775,7 +687,9 @@ by calling
.Fn EVP_EncryptUpdate ,
or
.Fn EVP_DecryptUpdate
with the output parameter out set to
with the output parameter
.Fa out
set to
.Dv NULL .
Additionally, the total
plaintext or ciphertext length MUST be passed to
@ -929,6 +843,7 @@ do_crypt(FILE *in, FILE *out, int do_encrypt)
.Xr EVP_chacha20 3 ,
.Xr EVP_CIPHER_CTX_ctrl 3 ,
.Xr EVP_CIPHER_CTX_get_cipher_data 3 ,
.Xr EVP_CIPHER_CTX_init 3 ,
.Xr EVP_CIPHER_CTX_set_flags 3 ,
.Xr EVP_CIPHER_nid 3 ,
.Xr EVP_des_cbc 3 ,
@ -959,15 +874,12 @@ first appeared in SSLeay 0.5.1.
and
.Fn EVP_rc2_ofb
first appeared in SSLeay 0.5.2.
.Fn EVP_Cipher
first appeared in SSLeay 0.6.5.
.Fn EVP_bf_cbc ,
.Fn EVP_bf_ecb ,
.Fn EVP_bf_cfb ,
and
.Fn EVP_bf_ofb
first appeared in SSLeay 0.6.6.
.Fn EVP_CIPHER_CTX_cleanup ,
.Fn EVP_get_cipherbyobj ,
.Fn EVP_CIPHER_CTX_cipher ,
and
@ -975,8 +887,6 @@ and
first appeared in SSLeay 0.8.0.
.Fn EVP_get_cipherbynid
first appeared in SSLeay 0.8.1.
.Fn EVP_CIPHER_CTX_init
first appeared in SSLeay 0.9.0.
All these functions have been available since
.Ox 2.4 .
.Pp

View file

@ -1,4 +1,4 @@
# $OpenBSD: Makefile,v 1.277 2023/11/19 10:36:14 tb Exp $
# $OpenBSD: Makefile,v 1.278 2023/12/01 10:40:21 schwarze Exp $
.include <bsd.own.mk>
@ -158,6 +158,7 @@ MAN= \
EVP_BytesToKey.3 \
EVP_CIPHER_CTX_ctrl.3 \
EVP_CIPHER_CTX_get_cipher_data.3 \
EVP_CIPHER_CTX_init.3 \
EVP_CIPHER_CTX_set_flags.3 \
EVP_CIPHER_do_all.3 \
EVP_CIPHER_meth_new.3 \

View file

@ -1,4 +1,4 @@
.\" $OpenBSD: evp.3,v 1.25 2023/11/19 10:25:28 tb Exp $
.\" $OpenBSD: evp.3,v 1.26 2023/12/01 10:40:21 schwarze Exp $
.\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100
.\"
.\" This file was written by Ulf Moeller <ulf@openssl.org>,
@ -51,7 +51,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: November 19 2023 $
.Dd $Mdocdate: December 1 2023 $
.Dt EVP 3
.Os
.Sh NAME
@ -175,6 +175,7 @@ family of functions provides base64 encoding and decoding.
.Xr EVP_chacha20 3 ,
.Xr EVP_CIPHER_CTX_ctrl 3 ,
.Xr EVP_CIPHER_CTX_get_cipher_data 3 ,
.Xr EVP_CIPHER_CTX_init 3 ,
.Xr EVP_CIPHER_CTX_set_flags 3 ,
.Xr EVP_CIPHER_do_all 3 ,
.Xr EVP_CIPHER_meth_new 3 ,