[thirdparty/openssl.git] / doc / man3 / SSL_set_session.pod

=pod

=head1 NAME

SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_set_session(SSL *ssl, SSL_SESSION *session);

=head1 DESCRIPTION

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(). Whether the session was reused can be queried
with the L<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
a connection), SSL_SESSION_free() will be called for that session. If that old
session is still B<open>, it is considered bad and will be removed from the
session cache (if used). A session is considered open, if L<SSL_shutdown(3)> was
not called for the connection (or at least L<SSL_set_shutdown(3)> was used to
set the SSL_SENT_SHUTDOWN state).

=head1 NOTES

SSL_SESSION objects keep internal link information about the session cache
list, when being inserted into one SSL_CTX object's session cache.
One SSL_SESSION object, regardless of its reference count, must therefore
only be used with one SSL_CTX object (and the SSL objects created
from this SSL_CTX object).

=head1 RETURN VALUES

The following return values can occur:

=over 4

=item Z<>0

The operation failed; check the error stack to find out the reason.

=item Z<>1

The operation succeeded.

=back

=head1 SEE ALSO

L<ssl(7)>, L<SSL_SESSION_free(3)>,
L<SSL_get_session(3)>,
L<SSL_session_reused(3)>,
L<SSL_CTX_set_session_cache_mode(3)>

=head1 COPYRIGHT

Copyright 2000-2016 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
Commit	Line	Data
cc99526d RL	1	=pod
	2
	3	=head1 NAME
	4
1e4e5492	5	SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect
cc99526d RL	6
	7	=head1 SYNOPSIS
	8
	9	#include <openssl/ssl.h>
	10
c6def253	11	int SSL_set_session(SSL ssl, SSL_SESSION session);
cc99526d RL	12
	13	=head1 DESCRIPTION
	14
1e4e5492 UM	15	SSL_set_session() sets B<session> to be used when the TLS/SSL connection
1e4e5492 UM	16	is to be established. SSL_set_session() is only useful for TLS/SSL clients.
cc99526d RL	17	When the session is set, the reference count of B<session> is incremented
cc99526d RL	18	by 1. If the session is not reused, the reference count is decremented
2d3b6a5b	19	again during SSL_connect(). Whether the session was reused can be queried
9b86974e	20	with the L<SSL_session_reused(3)> call.
cc99526d RL	21
	22	If there is already a session set inside B<ssl> (because it was set with
	23	SSL_set_session() before or because the same B<ssl> was already used for
ec02df83 MC	24	a connection), SSL_SESSION_free() will be called for that session. If that old
	25	session is still B<open>, it is considered bad and will be removed from the
	26	session cache (if used). A session is considered open, if L<SSL_shutdown(3)> was
	27	not called for the connection (or at least L<SSL_set_shutdown(3)> was used to
	28	set the SSL_SENT_SHUTDOWN state).
cc99526d	29
56fa8e69 LJ	30	=head1 NOTES
	31
	32	SSL_SESSION objects keep internal link information about the session cache
	33	list, when being inserted into one SSL_CTX object's session cache.
	34	One SSL_SESSION object, regardless of its reference count, must therefore
	35	only be used with one SSL_CTX object (and the SSL objects created
	36	from this SSL_CTX object).
	37
cc99526d RL	38	=head1 RETURN VALUES
	39
	40	The following return values can occur:
	41
	42	=over 4
	43
c8919dde	44	=item Z<>0
cc99526d	45
1e4e5492	46	The operation failed; check the error stack to find out the reason.
cc99526d	47
c8919dde	48	=item Z<>1
cc99526d RL	49
	50	The operation succeeded.
	51
	52	=back
	53
	54	=head1 SEE ALSO
	55
b97fdb57	56	L<ssl(7)>, L<SSL_SESSION_free(3)>,
9b86974e RS	57	L<SSL_get_session(3)>,
	58	L<SSL_session_reused(3)>,
	59	L<SSL_CTX_set_session_cache_mode(3)>
cc99526d	60
e2f92610 RS	61	=head1 COPYRIGHT
	62
	63	Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
	64
	65	Licensed under the OpenSSL license (the "License"). You may not use
	66	this file except in compliance with the License. You can obtain a copy
	67	in the file LICENSE in the source distribution or at
	68	L<https://www.openssl.org/source/license.html>.
	69
	70	=cut