Documentation updates for TLSv1.3 sessions

L<SSL_CTX_set_session_cache_mode(3)>).

The new_session_cb() is passed the B<ssl> connection and the ssl session

B<sess>. If the callback returns B<0>, the session will be immediately

removed again.

removed again. Note that in TLSv1.3 sessions are established after the main

handshake has completed. The server decides when to send the client the session

information and this may occur some time after the end of the handshake (or not

at all). This means that applications should expect the new_session_cb()

function to be invoked during the handshake (for <= TLSv1.2) or after the

handshake (for TLSv1.3). It is also possible in TLSv1.3 for multiple sessions to

be established with a single connection. In these case the new_session_cb()

function will be invoked multiple times.

In TLSv1.3 it is recommended that each SSL_SESSION object is only used for

resumption once.

The remove_session_cb() is called, whenever the SSL engine removes a session

from the internal cache. This happens when the session is removed because

=pod

=head1 NAME

SSL_SESSION_is_resumable

- determine whether an SSL_SESSION object can be used for resumption

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 const SSL_CIPHER *SSL_SESSION_is_resumable(const SSL_SESSSION *s);

=head1 DESCRIPTION

SSL_SESSION_is_resumable() determines whether an SSL_SESSION object can be used

to resume a session or not. Returns 1 if it can or 0 if not. Note that

attempting to resume with a non-resumable session will result in OpenSSL

performing a full handshake.

=head1 SEE ALSO

L<ssl(7)>,

L<SSL_get_session(3)>,

L<SSL_CTX_sess_set_new_cb(3)>

=head1 HISTORY

SSL_SESSION_is_resumable() was first added to OpenSSL 1.1.1

=head1 COPYRIGHT

Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

=head1 NOTES

The ssl session contains all information required to re-establish the

connection without a new handshake.

connection without a full handshake for SSL versions <= TLSv1.2. In TLSv1.3 the

same is true, but sessions are established after the main handshake has occurred.

The server will send the session information to the client at a time of its

choosing which may be some while after the initial connection is established (or

not at all). Calling these functions on the client side in TLSv1.3 before the

session has been established will still return an SSL_SESSION object but it

cannot be used for resuming the session. See L<SSL_SESSION_is_resumable(3)> for

information on how to determine whether an SSL_SESSION object can be used for

resumption or not.

Additionally, in TLSv1.3, a server can send multiple session messages for a

single connection. In that case the above functions will only return information

on the last session that was received.

The preferred way for applications to obtain a resumable SSL_SESSION object is

to use a new session callback as described in L<SSL_CTX_sess_set_new_cb(3)>.

The new session callback is only invoked when a session is actually established,

so this avoids the problem described above where an application obtains an

SSL_SESSION object that cannot be used for resumption in TLSv1.3. It also

enables applications to obtain information about all sessions sent by the

server.

In TLSv1.3 it is recommended that each SSL_SESSION object is only used for

resumption once.

SSL_get0_session() returns a pointer to the actual session. As the

reference counter is not incremented, the pointer is only valid while