From 5af30545c000c195ca6e44f207da004e5780ddb5 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 5 Nov 2016 15:32:20 +0000 Subject: move manual pages from doc/ to man/ for consistency with other libraries, in particular considering that there are unrelated files in doc/; requested by jsing@ and beck@ --- src/lib/libssl/man/SSL_clear.3 | 92 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 src/lib/libssl/man/SSL_clear.3 (limited to 'src/lib/libssl/man/SSL_clear.3') diff --git a/src/lib/libssl/man/SSL_clear.3 b/src/lib/libssl/man/SSL_clear.3 new file mode 100644 index 0000000000..a9e318320f --- /dev/null +++ b/src/lib/libssl/man/SSL_clear.3 @@ -0,0 +1,92 @@ +.\" +.\" $OpenBSD: SSL_clear.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CLEAR 3 +.Os +.Sh NAME +.Nm SSL_clear +.Nd reset SSL object to allow another connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_clear "SSL *ssl" +.Sh DESCRIPTION +Reset +.Fa ssl +to allow another connection. +All settings (method, ciphers, BIOs) are kept. +.Sh NOTES +.Fn SSL_clear +is used to prepare an +.Vt SSL +object for a new connection. +While all settings are kept, +a side effect is the handling of the current SSL session. +If a session is still +.Em open , +it is considered bad and will be removed from the session cache, +as required by RFC2246. +A session is considered open if +.Xr SSL_shutdown 3 +was not called for the connection or at least +.Xr SSL_set_shutdown 3 +was used to +set the +.Dv SSL_SENT_SHUTDOWN +state. +.Pp +If a session was closed cleanly, +the session object will be kept and all settings corresponding. +This explicitly means that for example the special method used during the +session will be kept for the next handshake. +So if the session was a TLSv1 session, a +.Vt SSL +client object will use a TLSv1 client method for the next handshake and a +.Vt SSL +server object will use a TLSv1 server method, even if +.Fn SSLv23_*_method Ns s +were chosen on startup. +This might lead to connection failures (see +.Xr SSL_new 3 ) +for a description of the method's properties. +.Sh WARNINGS +.Fn SSL_clear +resets the +.Vt SSL +object to allow for another connection. +The reset operation however keeps several settings of the last sessions +(some of these settings were made automatically during the last handshake). +It only makes sense for a new connection with the exact same peer that shares +these settings, +and may fail if that peer changes its settings between connections. +Use the sequence +.Xr SSL_get_session 3 ; +.Xr SSL_new 3 ; +.Xr SSL_set_session 3 ; +.Xr SSL_free 3 +instead to avoid such failures (or simply +.Xr SSL_free 3 ; +.Xr SSL_new 3 +if session reuse is not desired). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The +.Fn SSL_clear +operation could not be performed. +Check the error stack to find out the reason. +.It 1 +The +.Fn SSL_clear +operation was successful. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 -- cgit v1.2.3-55-g6feb