Index for Section 3

Alphabetical listing for S

Bottom of page

SSL_shutdown(3)
NAME
  SSL_shutdown - Shut down a TLS/SSL connection

SYNOPSIS
  #include <openssl/ssl.h>

  int SSL_shutdown(
	  SSL *ssl );

DESCRIPTION
  The SSL_shutdown() function shuts down an active TLS/SSL connection. It
  sends the  "lose notify" shutdown alert to the peer.

NOTES
  The SSL_shutdown() function tries to send the "close notify" shutdown alert
  to the peer. Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN
  flag is set and a currently open session is considered closed and good and
  will be kept in the session cache for further reuse.

  The shutdown procedure consists of two steps: the sending of the "close
  notify" shutdown alert and the reception of the peer's "close notify"
  shutdown alert.  According to the TLS standard, it is acceptable for an
  application to only send its shutdown alert and then close the underlying
  connection without waiting for the peer's response. (This way resources can
  be saved as the process can already terminate or serve another connection.)
  When the underlying connection is used for more communications, the
  complete shutdown procedure (bidirectional "close notify" alerts) must be
  performed, so that the peers stay synchronized.

  The SSL_shutdown() function supports both unidirectional and bidirectional
  shutdown by its two-step behavior.

  When the  application is the first party to send the "close notify" alert,
  SSL_shutdown will only send the alert and then set the  SSL_SENT_SHUTDOWN
  flag (so that the session is considered good and will be kept in cache).
  The SSL_shutdown() function will then return with 0. If  a unidirectional
  shutdown is enough (the underlying connection shall be closed anyway), this
  first call to SSL_shutdown() is sufficient. In order to complete the
  bidirectional shutdown handshake, SSL_shutdown() must be called again. The
  second call will make SSL_shutdown() wait for the peer's "close notify"
  shutdown alert. On success, the second call to SSL_shutdown() will return
  with 1.

  If the peer already sent the "close notify" alert and it was already
  processed implicitly inside another function (SSL_read()), the
  SSL_RECEIVED_SHUTDOWN flag is set.  The SSL_shutdown() function will send
  the "close notify" alert, set the SSL_SENT_SHUTDOWN flag and immediately
  return with 1. Whether SSL_RECEIVED_SHUTDOWN is already set can be checked
  using the SSL_get_shutdown() function.

  We recommend checking the return value of SSL_shutdown() and call
  SSL_shutdown() again if the bidirectional shutdown is not complete (return
  value of the first call is 0). Since the shutdown is not specially handled
  in the SSLv2 protocol, SSL_shutdown() will succeed on the first call.

  The behavior of the SSL_shutdown() function also depends on the underlying
  BIO.

  If the underlying BIO is blocking, the SSL_shutdown() function will only
  return once the handshake step has been finished or an error occurred.

  If the underlying BIO is non-blocking, the SSL_shutdown() function will
  also return when the underlying BIO could not satisfy the needs of the
  SSL_shutdown() function to continue the handshake.  In this case, a call to
  SSL_get_error() with the return value of SSL_shutdown() will yield
  SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then
  repeat the call after taking appropriate action to satisfy the needs of
  SSL_shutdown().  The action depends on the underlying BIO. When using a
  non-blocking socket, nothing is to be done, but the select() function can
  be used to check for the required condition. When using a buffering BIO,
  like a BIO pair, data must be written into or retrieved out of the BIO
  before being able to continue.

  The SSL_shutdown() function can be modified to only set the connection to
  ``shutdown'' state but not actually send the ``close notify'' alert
  messages. See SSL_CTX_set_quiet_shutdown().  When ``quiet shutdown'' is
  enabled, the SSL_shutdown() function will always succeed and return 1.

RETURN VALUES
  The following return values can occur:

  1	  The shutdown was successfully completed. The ``close notify'' alert
	  was sent and the peer's ``close notify'' alert was received.

  0	  The shutdown is not finished. Call SSL_shutdown() for a second time
	  if a bidirectional shutdown will be performed. The output of
	  SSL_get_error() may be misleading, as an erroneous
	  SSL_ERROR_SYSCALL may be flagged even though no error occurred.

  --1	  The shutdown was not successful because a fatal error occurred
	  either at the protocol level or a connection failure occurred. It
	  can also occur if action is needed to continue the operation for
	  non-blocking BIOs. Call SSL_get_error() with the return value ret
	  to find the reason.

SEE ALSO
  Functions: SSL_get_error(3), SSL_connect(3), SSL_accept(3),
  SSL_set_shutdown(3), SSL_CTX_set_quiet_shutdown(3) SSL_clear(3),
  SSL_free(3) ssl(3), bio(3)

Index for Section 3

Alphabetical listing for S

Top of page