From 4a9745e0601bb90758252ed1f1a586d4f012da45 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 27 Aug 2023 15:33:08 +0000 Subject: [PATCH] Move the weak SHA-1 and MD5 hashes out of EVP_DigestInit(3) into a new EVP_sha1(3) manual page, and also mention EVP_md4(3) there. Using input from tb@ and jsing@, who like the general direction. --- lib/libcrypto/man/EVP_DigestInit.3 | 55 +++---------- lib/libcrypto/man/EVP_sha1.3 | 121 +++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/evp.3 | 5 +- 4 files changed, 138 insertions(+), 46 deletions(-) create mode 100644 lib/libcrypto/man/EVP_sha1.3 diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3 index 2d790cb2c01..54cc771b107 100644 --- a/lib/libcrypto/man/EVP_DigestInit.3 +++ b/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_DigestInit.3,v 1.28 2023/08/14 14:22:32 schwarze Exp $ +.\" $OpenBSD: EVP_DigestInit.3,v 1.29 2023/08/27 15:33:08 schwarze Exp $ .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 .\" @@ -70,7 +70,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 14 2023 $ +.Dd $Mdocdate: August 27 2023 $ .Dt EVP_DIGESTINIT 3 .Os .Sh NAME @@ -107,9 +107,6 @@ .Nm EVP_MD_CTX_pkey_ctx , .Nm EVP_MD_CTX_set_pkey_ctx , .Nm EVP_md_null , -.Nm EVP_md5 , -.Nm EVP_md5_sha1 , -.Nm EVP_sha1 , .Nm EVP_sha224 , .Nm EVP_sha256 , .Nm EVP_sha384 , @@ -270,12 +267,6 @@ .Ft const EVP_MD * .Fn EVP_md_null void .Ft const EVP_MD * -.Fn EVP_md5 void -.Ft const EVP_MD * -.Fn EVP_md5_sha1 void -.Ft const EVP_MD * -.Fn EVP_sha1 void -.Ft const EVP_MD * .Fn EVP_sha224 void .Ft const EVP_MD * .Fn EVP_sha256 void @@ -413,7 +404,7 @@ from The .Fa type will typically be supplied by a function such as -.Fn EVP_sha1 . +.Fn EVP_sha512 . If .Fa impl is @@ -537,9 +528,9 @@ and .Fn EVP_MD_CTX_type return the NID of the OBJECT IDENTIFIER representing the message digest. For example -.Fn EVP_MD_type EVP_sha1() +.Fn EVP_MD_type EVP_sha512() returns -.Dv NID_sha1 . +.Dv NID_sha512 . These functions are normally used when setting ASN.1 OIDs. .Pp .Fn EVP_MD_CTX_md_data @@ -563,9 +554,9 @@ for more information. returns the NID of the public key signing algorithm associated with this digest. For example -.Fn EVP_sha1 +.Fn EVP_sha512 is associated with RSA so this will return -.Dv NID_sha1WithRSAEncryption . +.Dv NID_sha512WithRSAEncryption . Since digests and signature algorithms are no longer linked, this function is only retained for compatibility reasons. .Pp @@ -619,8 +610,6 @@ is dissociated from it as described above, but no new .Vt EVP_PKEY_CTX is assigned. .Pp -.Fn EVP_md5 , -.Fn EVP_sha1 , .Fn EVP_sha224 , .Fn EVP_sha256 , .Fn EVP_sha384 , @@ -629,7 +618,7 @@ and .Fn EVP_ripemd160 return .Vt EVP_MD -structures for the MD5, SHA1, SHA224, SHA256, SHA384, SHA512 and +structures for the SHA224, SHA256, SHA384, SHA512 and RIPEMD160 digest algorithms respectively. .Pp .Fn EVP_sha512_224 @@ -640,11 +629,6 @@ return an structure that provides the truncated SHA512 variants SHA512/224 and SHA512/256, respectively. .Pp -.Fn EVP_md5_sha1 -returns an -.Vt EVP_MD -structure that provides concatenated MD5 and SHA1 message digests. -.Pp .Fn EVP_md_null is a "null" message digest that does nothing: i.e. the hash it returns is of zero length. @@ -671,9 +655,6 @@ in preference to the low-level interfaces. This is because the code then becomes transparent to the digest used and much more flexible. .Pp -New applications should use the SHA2 digest algorithms such as SHA256. -The other digest algorithms are still in common use. -.Pp For most applications the .Fa impl parameter to @@ -757,10 +738,7 @@ if is .Dv NULL . .Pp -.Fn EVP_md_null , -.Fn EVP_md5 , -.Fn EVP_md5_sha1 , -.Fn EVP_sha1 , +.Fn EVP_md_null and .Fn EVP_ripemd160 return pointers to the corresponding @@ -830,6 +808,7 @@ main(int argc, char *argv[]) .Xr EVP_MD_meth_new 3 , .Xr EVP_PKEY_CTX_set_signature_md 3 , .Xr EVP_PKEY_meth_set_signctx 3 , +.Xr EVP_sha1 3 , .Xr EVP_sha3_224 3 , .Xr EVP_SignInit 3 , .Xr EVP_sm3 3 , @@ -847,10 +826,8 @@ main(int argc, char *argv[]) .Fn EVP_DigestInit , .Fn EVP_DigestUpdate , .Fn EVP_DigestFinal , -.Dv EVP_MAX_MD_SIZE , -.Fn EVP_md5 , and -.Fn EVP_sha1 +.Dv EVP_MAX_MD_SIZE first appeared in SSLeay 0.5.1. .Fn EVP_MD_size first appeared in SSLeay 0.6.6. @@ -869,8 +846,6 @@ first appeared in SSLeay 0.8.1. .Fn EVP_MD_block_size , .Fn EVP_MD_CTX_size , .Fn EVP_MD_CTX_block_size , -.Fn EVP_rc4_40 , -.Fn EVP_rc2_40_cbc , and .Fn EVP_ripemd160 first appeared in SSLeay 0.9.0. @@ -920,9 +895,8 @@ first appeared in OpenSSL 1.1.0 and has been available since .Pp .Fn EVP_MD_CTX_new , .Fn EVP_MD_CTX_reset , -.Fn EVP_MD_CTX_free , and -.Fn EVP_md5_sha1 +.Fn EVP_MD_CTX_free first appeared in OpenSSL 1.1.0 and have been available since .Ox 6.3 . .Pp @@ -940,8 +914,3 @@ and .Fn EVP_sha512_256 first appeared in OpenSSL 1.1.1 and have been available since .Ox 7.4 . -.Pp -The link between digests and signing algorithms was fixed in OpenSSL 1.0 -and later, so now -.Fn EVP_sha1 -can be used with RSA and DSA. diff --git a/lib/libcrypto/man/EVP_sha1.3 b/lib/libcrypto/man/EVP_sha1.3 new file mode 100644 index 00000000000..43898a5f6a0 --- /dev/null +++ b/lib/libcrypto/man/EVP_sha1.3 @@ -0,0 +1,121 @@ +.\" $OpenBSD: EVP_sha1.3,v 1.1 2023/08/27 15:33:08 schwarze Exp $ +.\" +.\" 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. +.\" +.Dd $Mdocdate: August 27 2023 $ +.Dt EVP_SHA1 3 +.Os +.Sh NAME +.Nm EVP_sha1 , +.Nm EVP_md5 , +.Nm EVP_md5_sha1 , +.Nm EVP_md4 +.Nd legacy message digest algorithms +.Sh SYNOPSIS +.In openssl/evp.h +.Ft const EVP_MD * +.Fn EVP_sha1 void +.Ft const EVP_MD * +.Fn EVP_md5 void +.Ft const EVP_MD * +.Fn EVP_md5_sha1 void +.Ft const EVP_MD * +.Fn EVP_md4 void +.Sh DESCRIPTION +The following message digest algorithms are cryptographically broken. +None of them should be used in new code unless there is no way around it. +.Pp +.Fn EVP_sha1 +implements the SHA-1 algorithm and produces 160 bits of output +from a given input. +Examples of protocols and software still requiring it +include OCSP, DNS, and the +.Sy git +version control system. +.Pp +.Fn EVP_md5 +implements the MD5 algorithm and produces 128 bits of output +from a given input. +It is still occasionally used when no security is required +but a fast hash algorithm is beneficial. +.Pp +.Fn EVP_md5_sha1 +produces concatenated MD5 and SHA-1 message digests. +Do not use this except where it is required for the historic SSLv3 protocol. +.Pp +.Fn EVP_md4 +implements the MD4 algorithm and produces 128 bits of output +from a given input. +It has been marked as +.Dq historic +by the Internet Engineering Task Force since 2011. +.Sh RETURN VALUES +These functions return pointers to static +.Vt EVP_MD +objects implementing the hash functions. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_MD_meth_new 3 +.Sh STANDARDS +.Rs +.%A T. Polk +.%A L. Chen +.%A S. Turner +.%A P. Hoffman +.%T Security Considerations for the SHA-0 and SHA-1 Message-Digest Algorithms +.%R RFC 6194 +.%D March 2011 +.Re +.Pp +.Rs +.%A S. Turner +.%A L. Chen +.%T Updated Security Considerations for the MD5 Message-Digest\ + and the HMAC-MD5 Algorithms +.%R RFC 6151 +.%D March 2011 +.Re +.Pp +.Rs +.%A S. Turner +.%A L. Chen +.%T MD4 to Historic Status +.%R RFC 6150 +.%D March 2011 +.Re +.Pp +.Rs +.%A P. Kocher +.%A P. Karlton +.%A A. Freier +.%T The Secure Sockets Layer (SSL) Protocol Version 3.0 +.%R RFC 6101 +.%D August 2011 +.Re +.Sh HISTORY +.Fn EVP_sha1 +and +.Fn EVP_md5 +first appeared in SSLeay 0.5.1 and have been available since +.Ox 2.4 . +.Pp +.Fn EVP_md4 +first appeared in OpenSSL 0.9.6 and has been available since +.Ox 2.9 . +.Pp +.Fn EVP_md5_sha1 +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 6.3 . diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 24b53b9eb13..2c243f7fec9 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.263 2023/08/25 18:22:41 schwarze Exp $ +# $OpenBSD: Makefile,v 1.264 2023/08/27 15:33:08 schwarze Exp $ .include @@ -205,6 +205,7 @@ MAN= \ EVP_chacha20.3 \ EVP_des_cbc.3 \ EVP_rc4.3 \ + EVP_sha1.3 \ EVP_sha3_224.3 \ EVP_sm3.3 \ EVP_sm4_cbc.3 \ diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index 92a6c6a416f..d53fa94fe1d 100644 --- a/lib/libcrypto/man/evp.3 +++ b/lib/libcrypto/man/evp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: evp.3,v 1.19 2023/08/25 18:22:41 schwarze Exp $ +.\" $OpenBSD: evp.3,v 1.20 2023/08/27 15:33:08 schwarze Exp $ .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100 .\" .\" This file was written by Ulf Moeller , @@ -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: August 25 2023 $ +.Dd $Mdocdate: August 27 2023 $ .Dt EVP 3 .Os .Sh NAME @@ -234,6 +234,7 @@ operations are more efficient using the high-level interfaces. .Xr EVP_PKEY_verify_recover 3 , .Xr EVP_rc4 3 , .Xr EVP_SealInit 3 , +.Xr EVP_sha1 3 , .Xr EVP_sha3_224 3 , .Xr EVP_SignInit 3 , .Xr EVP_sm3 3 , -- 2.20.1