Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@

1 files changed, 228 insertions, 0 deletions

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