Write SSL_copy_session_id(3) manual from scratch. This function is

listed in ssl(3) and <openssl/ssl.h>, so it's clearly a public interface.

We might wish to merge the improved code from OpenSSL 1.1.0,
but that's major bump, so i'm documenting the BUGS for now.

2 files changed, 78 insertions, 1 deletions

diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile
index 5fe28e4dc65..f6e38e2e140 100644
--- a/lib/libssl/man/Makefile
+++ b/lib/libssl/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.48 2016/12/07 17:09:07 schwarze Exp $
+# $OpenBSD: Makefile,v 1.49 2016/12/07 18:09:31 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -54,6 +54,7 @@ MAN =	BIO_f_ssl.3 \
 	SSL_alert_type_string.3 \
 	SSL_clear.3 \
 	SSL_connect.3 \
+	SSL_copy_session_id.3 \
 	SSL_do_handshake.3 \
 	SSL_dup.3 \
 	SSL_dup_CA_list.3 \
diff --git a/lib/libssl/man/SSL_copy_session_id.3 b/lib/libssl/man/SSL_copy_session_id.3
new file mode 100644
index 00000000000..2f96ecffd7c
--- /dev/null
+++ b/lib/libssl/man/SSL_copy_session_id.3
@@ -0,0 +1,76 @@
+.\"	$OpenBSD: SSL_copy_session_id.3,v 1.1 2016/12/07 18:09:31 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 7 2016 $
+.Dt SSL_COPY_SESSION_ID 3
+.Os
+.Sh NAME
+.Nm SSL_copy_session_id
+.Nd copy session details between SSL objects
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft void
+.Fo SSL_copy_session_id
+.Fa "SSL *to"
+.Fa "const SSL *from"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_copy_session_id
+copies the following data from
+.Fa from
+to
+.Fa to :
+.Bl -dash
+.It
+the pointer to the
+.Vt SSL_SESSION
+object, incrementing its reference count by 1
+.It
+the pointer to the
+.Vt SSL_METHOD
+object; if that changes the method, protocol-specific data is
+reinitialized
+.It
+the pointer to the
+.Vt CERT
+object, incrementing its reference count by 1
+.It
+the session ID context
+.El
+.Pp
+This function is used internally by
+.Xr SSL_dup 3
+and by
+.Xr BIO_ssl_copy_session_id 3 .
+.Sh SEE ALSO
+.Xr BIO_ssl_copy_session_id 3 ,
+.Xr SSL_dup 3 ,
+.Xr SSL_get_session 3 ,
+.Xr SSL_set_session 3 ,
+.Xr SSL_set_session_id_context 3
+.Sh HISTORY
+.Fn SSL_copy_session_id
+is available in all versions of OpenSSL.
+.Sh BUGS
+Failures of
+.Xr SSL_set_session 3 ,
+.Xr SSL_set_session_id_context 3 ,
+.Xr CRYPTO_add 3 ,
+and reinitialization of protocol-specific data are silently ignored
+and may leave
+.Fa to
+in an invalid or inconsistent state.
+An improved version reporting failure is available in OpenSSL 1.1.0.