From 2d3b6a5be7f567d44c88f7b55caff7976229b44a Mon Sep 17 00:00:00 2001
From: =?utf8?q?Lutz=20J=C3=A4nicke?= <jaenicke@openssl.org>
Date: Fri, 20 Jul 2001 18:57:15 +0000
Subject: [PATCH] Some more documentation bits.

---
 doc/ssl/SSL_CTX_set_session_cache_mode.pod |  1 +
 doc/ssl/SSL_session_reused.pod             | 45 ++++++++++++++++++++++
 doc/ssl/SSL_set_session.pod                |  4 +-
 doc/ssl/ssl.pod                            | 10 +++--
 4 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 doc/ssl/SSL_session_reused.pod

diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod
index 8bbfc78720..9aa6c6b2e3 100644
--- a/doc/ssl/SSL_CTX_set_session_cache_mode.pod
+++ b/doc/ssl/SSL_CTX_set_session_cache_mode.pod
@@ -97,6 +97,7 @@ SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
 L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
 L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
 L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
diff --git a/doc/ssl/SSL_session_reused.pod b/doc/ssl/SSL_session_reused.pod
new file mode 100644
index 0000000000..da7d06264d
--- /dev/null
+++ b/doc/ssl/SSL_session_reused.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_session_reused - query whether a reused session was negotiated during handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_session_reused(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Query, whether a reused session was negotiated during the handshake.
+
+=head1 NOTES
+
+During the negotiation, a client can propose to reuse a session. The server
+then looks up the session in its cache. If both client and server agree
+on the session, it will be reused and a flag is being set that can be
+queried by the application.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+A new session was negotiated.
+
+=item 1
+
+A session was reused.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
+
+=cut
diff --git a/doc/ssl/SSL_set_session.pod b/doc/ssl/SSL_set_session.pod
index c4f7878579..1de232fbbc 100644
--- a/doc/ssl/SSL_set_session.pod
+++ b/doc/ssl/SSL_set_session.pod
@@ -16,7 +16,8 @@ SSL_set_session() sets B<session> to be used when the TLS/SSL connection
 is to be established. SSL_set_session() is only useful for TLS/SSL clients.
 When the session is set, the reference count of B<session> is incremented
 by 1. If the session is not reused, the reference count is decremented
-again during SSL_connect().
+again during SSL_connect(). Whether the session was reused can be queried
+with the L<SSL_session_reused(3)|SSL_session_reused(3)> call.
 
 If there is already a session set inside B<ssl> (because it was set with
 SSL_set_session() before or because the same B<ssl> was already used for
@@ -41,6 +42,7 @@ The operation succeeded.
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
 L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>
 
 =cut
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index aace43f919..e5bf61a2ae 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -686,12 +686,16 @@ L<SSL_get_version(3)|SSL_get_version(3)>,
 L<SSL_library_init(3)|SSL_library_init(3)>,
 L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>,
 L<SSL_new(3)|SSL_new(3)>,
-L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
+L<SSL_pending(3)|SSL_pending(3)>,
+L<SSL_read(3)|SSL_read(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_set_bio(3)|SSL_set_bio(3)>,
 L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
-L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>,
+L<SSL_set_fd(3)|SSL_set_fd(3)>,
 L<SSL_set_session(3)|SSL_set_session(3)>,
 L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
-L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_write(3)|SSL_write(3)>,
+L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_write(3)|SSL_write(3)>,
 L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
 L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>,
 L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>,
-- 
2.25.1