From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001 From: bentley <> Date: Sun, 12 Oct 2014 09:33:04 +0000 Subject: Convert libssl manpages from pod to mdoc(7). libcrypto has not been started yet. ok schwarze@ miod@ --- src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 | 228 ++++++++++++++++++++++ 1 file changed, 228 insertions(+) create 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 new file mode 100644 index 0000000000..55b3aaafed --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,228 @@ +.Dd $Mdocdate: October 12 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 ciphers 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