Split EVP_rc4(3) out of EVP_EncryptInit(3) to reduce clutter.

The algorithm is insecure and yet its description would spread over
three paragraphs in the cipher list, including remarkable advice
like using a 40 bit key length.

4 files changed, 116 insertions, 21 deletions

diff --git a/lib/libcrypto/man/EVP_EncryptInit.3 b/lib/libcrypto/man/EVP_EncryptInit.3
index a730923d968..ead07dbb2b4 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.32 2019/03/21 12:54:37 schwarze Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.33 2019/03/21 13:37:25 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
@@ -110,9 +110,6 @@
 .Nm EVP_CIPHER_param_to_asn1 ,
 .Nm EVP_CIPHER_asn1_to_param ,
 .Nm EVP_enc_null ,
-.Nm EVP_rc4 ,
-.Nm EVP_rc4_40 ,
-.Nm EVP_rc4_hmac_md5 ,
 .Nm EVP_idea_cbc ,
 .Nm EVP_idea_ecb ,
 .Nm EVP_idea_cfb64 ,
@@ -920,16 +917,6 @@ All algorithms have a fixed key length unless otherwise stated.
 .Bl -tag -width Ds
 .It Fn EVP_enc_null
 Null cipher: does nothing.
-.It Fn EVP_rc4
-RC4 stream cipher.
-This is a variable key length cipher with default key length 128 bits.
-.It Fn EVP_rc4_40
-RC4 stream cipher with 40-bit key length.
-This is obsolete and new code should use
-.Fn EVP_rc4
-and the
-.Fn EVP_CIPHER_CTX_set_key_length
-function.
 .It Xo
 .Fn EVP_idea_cbc ,
 .Fn EVP_idea_ecb ,
@@ -1000,6 +987,7 @@ The key length is 256 bits, the IV is 96 bits long.
 See also
 .Xr EVP_aes_128_cbc 3 ,
 .Xr EVP_des_cbc 3 ,
+.Xr EVP_rc4 3 ,
 and
 .Xr EVP_sm4_cbc 3 .
 .Ss GCM mode
@@ -1207,6 +1195,7 @@ do_crypt(FILE *in, FILE *out, int do_encrypt)
 .Xr evp 3 ,
 .Xr EVP_aes_128_cbc 3 ,
 .Xr EVP_des_cbc 3 ,
+.Xr EVP_rc4 3 ,
 .Xr EVP_sm4_cbc 3
 .Sh HISTORY
 .Fn EVP_EncryptInit ,
@@ -1219,7 +1208,6 @@ do_crypt(FILE *in, FILE *out, int do_encrypt)
 .Fn EVP_CipherUpdate ,
 .Fn EVP_CipherFinal ,
 .Fn EVP_get_cipherbyname ,
-.Fn EVP_rc4 ,
 .Fn EVP_idea_cbc ,
 .Fn EVP_idea_ecb ,
 .Fn EVP_idea_cfb ,
@@ -1315,10 +1303,6 @@ first appeared in OpenSSL 0.9.8b.
 These functions have been available since
 .Ox 4.5 .
 .Pp
-.Fn EVP_rc4_hmac_md5
-first appeared in OpenSSL 1.0.1 and has been available since
-.Ox 5.3 .
-.Pp
 .Fn EVP_CIPHER_CTX_reset
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .
diff --git a/lib/libcrypto/man/EVP_rc4.3 b/lib/libcrypto/man/EVP_rc4.3
new file mode 100644
index 00000000000..fda041113c3
--- /dev/null
+++ b/lib/libcrypto/man/EVP_rc4.3
@@ -0,0 +1,109 @@
+.\" $OpenBSD: EVP_rc4.3,v 1.1 2019/03/21 13:37:25 schwarze Exp $
+.\" full merge up to: OpenSSL 8fa4d95e Oct 21 11:59:09 2017 +0900
+.\"
+.\" This file was written by Ronald Tse <ronald.tse@ribose.com>
+.\" Copyright (c) 2017 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: March 21 2019 $
+.Dt EVP_RC4 3
+.Os
+.Sh NAME
+.Nm EVP_rc4 ,
+.Nm EVP_rc4_40 ,
+.Nm EVP_rc4_hmac_md5
+.Nd EVP RC4 stream cipher
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft const EVP_CIPHER *
+.Fn EVP_rc4 void
+.Ft const EVP_CIPHER *
+.Fn EVP_rc4_40 void
+.Ft const EVP_CIPHER *
+.Fn EVP_rc4_hmac_md5 void
+.Sh DESCRIPTION
+These functions provide the RC4 stream cipher in the
+.Xr evp 3
+framework.
+It is a variable key length cipher.
+.Pp
+.Fn EVP_rc4
+uses a default key length of 128 bits.
+.Pp
+.Fn EVP_rc4_40
+uses a key length of 40 bits instead.
+This function is deprecated.
+Use
+.Fn EVP_rc4
+and
+.Xr EVP_CIPHER_CTX_set_key_length 3
+instead.
+.Pp
+.Fn EVP_rc4_hmac_md5
+provides authenticated encryption with the RC4 stream cipher
+with MD5 as HMAC.
+This function is not intended for usage outside of TLS
+and requires calling of some undocumented control functions.
+It does not conform to the EVP AEAD interface.
+.Sh RETURN VALUES
+These functions return an
+.Vt EVP_CIPHER
+structure that provides the implementation of the symmetric cipher.
+.Sh SEE ALSO
+.Xr evp 3 ,
+.Xr EVP_EncryptInit 3
+.Sh HISTORY
+.Fn EVP_rc4
+first appeared in SSLeay 0.5.1
+and
+.Fn EVP_rc4_40
+in OpenSSL 0.9.1.
+These functions have been available since
+.Ox 2.4 .
+.Pp
+.Fn EVP_rc4_hmac_md5
+first appeared in OpenSSL 1.0.1 and has been available since
+.Ox 5.3 .
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 2e885c1bcda..08888f9fefc 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.146 2019/03/21 12:54:37 schwarze Exp $
+# $OpenBSD: Makefile,v 1.147 2019/03/21 13:37:25 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -153,6 +153,7 @@ MAN=	\
 	EVP_VerifyInit.3 \
 	EVP_aes_128_cbc.3 \
 	EVP_des_cbc.3 \
+	EVP_rc4.3 \
 	EVP_sm4_cbc.3 \
 	EXTENDED_KEY_USAGE_new.3 \
 	GENERAL_NAME_new.3 \
diff --git a/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3
index 4b1f5568b6a..27ecaced4ef 100644
--- a/lib/libcrypto/man/evp.3
+++ b/lib/libcrypto/man/evp.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: evp.3,v 1.8 2019/03/21 12:54:37 schwarze Exp $
+.\"	$OpenBSD: evp.3,v 1.9 2019/03/21 13:37:25 schwarze Exp $
 .\"	OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
@@ -199,6 +199,7 @@ operations are more efficient using the high level interfaces.
 .Xr EVP_PKEY_sign 3 ,
 .Xr EVP_PKEY_verify 3 ,
 .Xr EVP_PKEY_verify_recover 3 ,
+.Xr EVP_rc4 3 ,
 .Xr EVP_SealInit 3 ,
 .Xr EVP_SignInit 3 ,
 .Xr EVP_sm4_cbc 3 ,