1 files changed, 19 insertions, 0 deletions
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index adcec5ffa9..bb3bc94809 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -447,6 +447,25 @@ success or 0 on failure.
 
 =item SSL *B<SSL_dup>(SSL *ssl);
 
+SSL_dup() allows applications to configure an SSL handle for use
+in multiple SSL connections, and then duplicate it prior to initiating
+each connection with the duplicated handle.
+Use of SSL_dup() avoids the need to repeat the configuration of the
+handles for each connection.
+This is used internally by L<BIO_s_accept(3)> to construct
+per-connection SSL handles after L<accept(2)>.
+
+For SSL_dup() to work, the connection MUST be in its initial state
+and MUST NOT have not yet have started the SSL handshake.
+For connections that are not in their initial state SSL_dup() just
+increments an internal reference count and returns the I<same>
+handle.
+It may be possible to use L<SSL_clear(3)> to recycle an SSL handle
+that is not in its initial state for re-use, but this is best
+avoided.
+Instead, save and restore the session, if desired, and construct a
+fresh handle for each connection.
+
 =item STACK *B<SSL_dup_CA_list>(STACK *sk);
 
 =item void B<SSL_free>(SSL *ssl);