1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_shutdown - shut down a TLS/SSL connection
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_shutdown(SSL *ssl);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_shutdown() shuts down an active TLS/SSL connection. It sends the 
   16: "close notify" shutdown alert to the peer.
   17: 
   18: =head1 NOTES
   19: 
   20: SSL_shutdown() tries to send the "close notify" shutdown alert to the peer.
   21: Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
   22: a currently open session is considered closed and good and will be kept in the
   23: session cache for further reuse.
   24: 
   25: The shutdown procedure consists of 2 steps: the sending of the "close notify"
   26: shutdown alert and the reception of the peer's "close notify" shutdown
   27: alert. According to the TLS standard, it is acceptable for an application
   28: to only send its shutdown alert and then close the underlying connection
   29: without waiting for the peer's response (this way resources can be saved,
   30: as the process can already terminate or serve another connection).
   31: When the underlying connection shall be used for more communications, the
   32: complete shutdown procedure (bidirectional "close notify" alerts) must be
   33: performed, so that the peers stay synchronized.
   34: 
   35: SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
   36: behaviour.
   37: 
   38: =over 4
   39: 
   40: =item When the application is the first party to send the "close notify"
   41: alert, SSL_shutdown() will only send the alert and then set the
   42: SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
   43: be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional
   44: shutdown is enough (the underlying connection shall be closed anyway), this
   45: first call to SSL_shutdown() is sufficient. In order to complete the
   46: bidirectional shutdown handshake, SSL_shutdown() must be called again.
   47: The second call will make SSL_shutdown() wait for the peer's "close notify"
   48: shutdown alert. On success, the second call to SSL_shutdown() will return
   49: with 1.
   50: 
   51: =item If the peer already sent the "close notify" alert B<and> it was
   52: already processed implicitly inside another function
   53: (L<SSL_read(3)|SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
   54: SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
   55: flag and will immediately return with 1.
   56: Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
   57: SSL_get_shutdown() (see also L<SSL_set_shutdown(3)|SSL_set_shutdown(3)> call.
   58: 
   59: =back
   60: 
   61: It is therefore recommended, to check the return value of SSL_shutdown()
   62: and call SSL_shutdown() again, if the bidirectional shutdown is not yet
   63: complete (return value of the first call is 0). As the shutdown is not
   64: specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on
   65: the first call.
   66: 
   67: The behaviour of SSL_shutdown() additionally depends on the underlying BIO. 
   68: 
   69: If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
   70: handshake step has been finished or an error occurred.
   71: 
   72: If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
   73: when the underlying BIO could not satisfy the needs of SSL_shutdown()
   74: to continue the handshake. In this case a call to SSL_get_error() with the
   75: return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
   76: B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
   77: taking appropriate action to satisfy the needs of SSL_shutdown().
   78: The action depends on the underlying BIO. When using a non-blocking socket,
   79: nothing is to be done, but select() can be used to check for the required
   80: condition. When using a buffering BIO, like a BIO pair, data must be written
   81: into or retrieved out of the BIO before being able to continue.
   82: 
   83: SSL_shutdown() can be modified to only set the connection to "shutdown"
   84: state but not actually send the "close notify" alert messages,
   85: see L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>.
   86: When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
   87: and return 1.
   88: 
   89: =head1 RETURN VALUES
   90: 
   91: The following return values can occur:
   92: 
   93: =over 4
   94: 
   95: =item 1
   96: 
   97: The shutdown was successfully completed. The "close notify" alert was sent
   98: and the peer's "close notify" alert was received.
   99: 
  100: =item 0
  101: 
  102: The shutdown is not yet finished. Call SSL_shutdown() for a second time,
  103: if a bidirectional shutdown shall be performed.
  104: The output of L<SSL_get_error(3)|SSL_get_error(3)> may be misleading, as an
  105: erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
  106: 
  107: =item -1
  108: 
  109: The shutdown was not successful because a fatal error occurred either
  110: at the protocol level or a connection failure occurred. It can also occur if
  111: action is need to continue the operation for non-blocking BIOs.
  112: Call L<SSL_get_error(3)|SSL_get_error(3)> with the return value B<ret>
  113: to find out the reason.
  114: 
  115: =back
  116: 
  117: =head1 SEE ALSO
  118: 
  119: L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
  120: L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
  121: L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>,
  122: L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>,
  123: L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
  124: 
  125: =cut