From 5af30545c000c195ca6e44f207da004e5780ddb5 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 5 Nov 2016 15:32:20 +0000 Subject: move manual pages from doc/ to man/ for consistency with other libraries, in particular considering that there are unrelated files in doc/; requested by jsing@ and beck@ --- src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 | 231 ---------------------- 1 file changed, 231 deletions(-) delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 (limited to 'src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3') diff --git a/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 deleted file mode 100644 index 253274d122..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 +++ /dev/null @@ -1,231 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.Dt SSL_CTX_SET_TMP_RSA_CALLBACK.POD 3 -.Os -.Sh NAME -.Nm SSL_CTX_set_tmp_rsa_callback , -.Nm SSL_CTX_set_tmp_rsa , -.Nm SSL_CTX_need_tmp_rsa , -.Nm SSL_set_tmp_rsa_callback , -.Nm SSL_set_tmp_rsa , -.Nm SSL_need_tmp_rsa -.Nd handle RSA keys for ephemeral key exchange -.Sh SYNOPSIS -.In openssl/ssl.h -.Ft void -.Fo SSL_CTX_set_tmp_rsa_callback -.Fa "SSL_CTX *ctx" -.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" -.Fc -.Ft long -.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa" -.Ft long -.Fn SSL_CTX_need_tmp_rsa "SSL_CTX *ctx" -.Ft void -.Fo SSL_set_tmp_rsa_callback -.Fa "SSL_CTX *ctx" -.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" -.Fc -.Ft long -.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 EDH (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 -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 -.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 -- cgit v1.2.3-55-g6feb