1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_clear - reset SSL object to allow another connection
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_clear(SSL *ssl);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: Reset B<ssl> to allow another connection. All settings (method, ciphers,
   16: BIOs) are kept.
   17: 
   18: =head1 NOTES
   19: 
   20: SSL_clear is used to prepare an SSL object for a new connection. While all
   21: settings are kept, a side effect is the handling of the current SSL session.
   22: If a session is still B<open>, it is considered bad and will be removed
   23: from the session cache, as required by RFC2246. A session is considered open,
   24: if L<SSL_shutdown(3)|SSL_shutdown(3)> was not called for the connection
   25: or at least L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> was used to
   26: set the SSL_SENT_SHUTDOWN state.
   27: 
   28: If a session was closed cleanly, the session object will be kept and all
   29: settings corresponding. This explicitly means, that e.g. the special method
   30: used during the session will be kept for the next handshake. So if the
   31: session was a TLSv1 session, a SSL client object will use a TLSv1 client
   32: method for the next handshake and a SSL server object will use a TLSv1
   33: server method, even if SSLv23_*_methods were chosen on startup. This
   34: will might lead to connection failures (see L<SSL_new(3)|SSL_new(3)>)
   35: for a description of the method's properties.
   36: 
   37: =head1 WARNINGS
   38: 
   39: SSL_clear() resets the SSL object to allow for another connection. The
   40: reset operation however keeps several settings of the last sessions
   41: (some of these settings were made automatically during the last
   42: handshake). It only makes sense when opening a new session (or reusing
   43: an old one) with the same peer that shares these settings.
   44: SSL_clear() is not a short form for the sequence
   45: L<SSL_free(3)|SSL_free(3)>; L<SSL_new(3)|SSL_new(3)>; .
   46: 
   47: =head1 RETURN VALUES
   48: 
   49: The following return values can occur:
   50: 
   51: =over 4
   52: 
   53: =item 0
   54: 
   55: The SSL_clear() operation could not be performed. Check the error stack to
   56: find out the reason.
   57: 
   58: =item 1
   59: 
   60: The SSL_clear() operation was successful.
   61: 
   62: =back
   63: 
   64: L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>,
   65: L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
   66: L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>,
   67: L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>
   68: 
   69: =cut