Remove lots of outdated information found by jsing@.

OK jsing.

1 files changed, 14 insertions, 192 deletions

diff --git a/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 b/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3
index e24a04992ec..8a3c5fa4137 100644
--- a/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3
+++ b/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.3 2016/12/06 22:55:35 schwarze Exp $
+.\"	$OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.4 2017/08/12 12:21:55 schwarze Exp $
 .\"	OpenSSL 0b30fc90 Dec 19 15:23:05 2013 -0500
 .\"
 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
@@ -48,8 +48,8 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 6 2016 $
-.Dt SSL_CTX_SET_TMP_RSA_CALLBACK.POD 3
+.Dd $Mdocdate: August 12 2017 $
+.Dt SSL_CTX_SET_TMP_RSA_CALLBACK 3
 .Os
 .Sh NAME
 .Nm SSL_CTX_set_tmp_rsa_callback ,
@@ -79,200 +79,22 @@
 .Fn SSL_set_tmp_rsa "SSL *ssl" "RSA *rsa"
 .Ft long
 .Fn SSL_need_tmp_rsa "SSL *ssl"
-.Ft RSA *
-.Fn "(*tmp_rsa_callback)" "SSL *ssl" "int is_export" "int keylength"
 .Sh DESCRIPTION
-.Fn SSL_CTX_set_tmp_rsa_callback
-sets the callback function for
-.Fa ctx
-to be used when a temporary/ephemeral RSA key is required to
-.Fa tmp_rsa_callback .
-The callback is inherited by all
-.Vt SSL
-objects newly created from
-.Fa ctx
-with
-.Xr SSL_new 3 .
-Already created SSL objects are not affected.
-.Pp
-.Fn SSL_CTX_set_tmp_rsa
-sets the temporary/ephemeral RSA key to be used to be
-.Fa rsa .
-The key is inherited by all
-.Vt SSL
-objects newly created from
-.Fa ctx
-with
-.Xr SSL_new 3 .
-Already created SSL objects are not affected.
-.Pp
-.Fn SSL_CTX_need_tmp_RSA
-returns 1,
-if a temporary/ephemeral RSA key is needed for RSA-based strength-limited
-.Sq exportable
-ciphersuites because a RSA key with a keysize larger than 512 bits is installed.
-.Pp
-.Fn SSL_set_tmp_rsa_callback
-sets the callback only for
-.Fa ssl .
-.Pp
-.Fn SSL_set_tmp_rsa
-sets the key only for
-.Fa ssl .
-.Pp
-.Fn SSL_need_tmp_rsa
-returns 1,
-if a temporary/ephemeral RSA key is needed for RSA-based strength-limited
-.Sq exportable
-ciphersuites because a RSA key with a keysize larger than 512 bits is installed.
-.Pp
-These functions apply to SSL/TLS servers only.
-.Sh NOTES
-When using a cipher with RSA authentication,
-an ephemeral RSA key exchange can take place.
-In this case the session data are negotiated using the ephemeral/temporary RSA
-key and the RSA key supplied and certified by the certificate chain is only
-used for signing.
-.Pp
-Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
-than the usual key length of 1024 bits were created.
-To use these ciphers with RSA keys of usual length, an ephemeral key exchange
-must be performed, as the normal (certified) key cannot be directly used.
-.Pp
-Using ephemeral RSA key exchange yields forward secrecy,
-as the connection can only be decrypted when the RSA key is known.
-By generating a temporary RSA key inside the server application that is lost
-when the application is left, it becomes impossible for an attacker to decrypt
-past sessions, even if he gets hold of the normal (certified) RSA key,
-as this key was used for signing only.
-The downside is that creating a RSA key is computationally expensive.
-.Pp
-Additionally, the use of ephemeral RSA key exchange is only allowed in the TLS
-standard when the RSA key can be used for signing only, that is,
-for export ciphers.
-Using ephemeral RSA key exchange for other purposes violates the standard and
-can break interoperability with clients.
-It is therefore strongly recommended to not use ephemeral RSA key exchange and
-use DHE (Ephemeral Diffie-Hellman) key exchange instead in order to achieve
-forward secrecy (see
-.Xr SSL_CTX_set_tmp_dh_callback 3 ) .
-.Pp
-On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default
-and must be explicitly enabled using the
-.Dv SSL_OP_EPHEMERAL_RSA
-option of
-.Xr SSL_CTX_set_options 3 ,
-violating the TLS/SSL
-standard.
-When ephemeral RSA key exchange is required for export ciphers,
-it will automatically be used without this option!
-.Pp
-An application may either directly specify the key or can supply the key via
-a callback function.
-The callback approach has the advantage that the callback may generate the key
-only in case it is actually needed.
-However, as the generation of a RSA key is costly,
-it will lead to a significant delay in the handshake procedure.
-Another advantage of the callback function is that it can supply keys of
-different size (e.g., for
-.Dv SSL_OP_EPHEMERAL_RSA
-usage) while the explicit setting of the key is only useful for key size of
-512 bits to satisfy the export restricted ciphers and does give away key length
-if a longer key would be allowed.
-.Pp
-The
-.Fa tmp_rsa_callback
-is called with the
-.Fa keylength
-needed and the
-.Fa is_export
-information.
-The
-.Fa is_export
-flag is set when the ephemeral RSA key exchange is performed with an export
-cipher.
-.Sh RETURN VALUES
-.Fn SSL_CTX_set_tmp_rsa_callback
-and
-.Fn SSL_set_tmp_rsa_callback
-do not return diagnostic output.
-.Pp
-.Fn SSL_CTX_set_tmp_rsa
+Since they mattered only for deliberately insecure RSA authentication
+mandated by historical U.S. export restrictions, these functions
+are all deprecated and have no effect except that
+.Fn SSL_CTX_set_tmp_rsa_callback ,
+.Fn SSL_CTX_set_tmp_rsa ,
+.Fn SSL_set_tmp_rsa_callback ,
 and
 .Fn SSL_set_tmp_rsa
-return 1 on success and 0 on failure.
-Check the error queue to find out the reason of failure.
-.Pp
-.Fn SSL_CTX_need_tmp_RSA
-and
-.Fn SSL_need_tmp_rsa
-return 1 if a temporary RSA key is needed and 0 otherwise.
-.Sh EXAMPLES
-Generate temporary RSA keys to prepare ephemeral RSA key exchange.
-As the generation of a RSA key costs a lot of computer time,
-they are saved for later reuse.
-For demonstration purposes, two keys for 512 bits and 1024 bits
-respectively are generated.
-.Bd -literal
-\&...
-
-/* Set up ephemeral RSA stuff */
-RSA *rsa_512 = NULL;
-RSA *rsa_1024 = NULL;
-
-rsa_512 = RSA_generate_key(512, RSA_F4, NULL, NULL);
-if (rsa_512 == NULL)
-	evaluate_error_queue();
-
-rsa_1024 = RSA_generate_key(1024, RSA_F4, NULL, NULL);
-if (rsa_1024 == NULL)
-	evaluate_error_queue();
-
-\&...
-
-RSA *
-tmp_rsa_callback(SSL *s, int is_export, int keylength)
-{
-	RSA *rsa_tmp = NULL;
-
-	switch (keylength) {
-	case 512:
-		if (rsa_512)
-			rsa_tmp = rsa_512;
-		else {
-			/*
-			 * generate on the fly,
-			 * should not happen in this example
-			 */
-			rsa_tmp = RSA_generate_key(keylength, RSA_F4, NULL,
-			    NULL);
-			rsa_512 = rsa_tmp; /* Remember for later reuse */
-		}
-		break;
-	case 1024:
-		if (rsa_1024)
-			rsa_tmp = rsa_1024;
-		else
-			should_not_happen_in_this_example();
-		break;
-	default:
-		/*
-		 * Generating a key on the fly is very costly,
-		 * so use what is there
-		 */
-		if (rsa_1024)
-			rsa_tmp = rsa_1024;
-		else
-			/* Use at least a shorter key */
-			rsa_tmp = rsa_512;
-	}
-	return rsa_tmp;
-}
-.Ed
+issue error messages when called.
+.Sh RETURN VALUES
+These functions always return 0, indicating failure.
 .Sh SEE ALSO
-.Xr openssl 1 ,
 .Xr ssl 3 ,
 .Xr SSL_CTX_set_cipher_list 3 ,
 .Xr SSL_CTX_set_options 3 ,
 .Xr SSL_CTX_set_tmp_dh_callback 3 ,
-.Xr SSL_new 3
+.Xr SSL_new 3 ,
+.Xr SSL_set_tmp_ecdh 3