*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> SSL_shutdown (3)              



NAME    [Toc]    [Back]

       SSL_shutdown - Shut down a TLS/SSL connection

SYNOPSIS    [Toc]    [Back]

       #include <openssl/ssl.h>

       int SSL_shutdown(
               SSL *ssl );

DESCRIPTION    [Toc]    [Back]

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

NOTES    [Toc]    [Back]

       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

       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()
       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    [Toc]    [Back]

       The following return values can occur:  The  shutdown  was
       successfully  completed.  The  ``close  notify'' alert was
       sent and the peer's ``close notify'' alert  was  received.
       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.  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

SEE ALSO    [Toc]    [Back]

       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)

[ Back ]
 Similar pages
Name OS Title
shutdown IRIX shut down part of a full-duplex connection
shutdown Linux shut down part of a full-duplex connection
shutdown OpenBSD shut down part of a full-duplex connection
shutdown NetBSD shut down part of a full-duplex connection
shutdown IRIX shut down part of a full-duplex connection
shutdown FreeBSD shut down part of a full-duplex connection
shutdown HP-UX shut down a socket
xlv_shutdown IRIX shut down XLV volumes
shutdown Tru64 Shut down socket send and receive operations
ftpshut HP-UX create shutdown message file to shut down the ftp servers at a given time
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service