SSL_shutdown man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=SSL_shutdown&af=0&tf=2&of=DigitalUNIX

SSL_shutdown(3)						       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  consid‐
       ered  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 underly‐
       ing 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  bidirec‐
       tional 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	suffi‐
       cient.  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 imme‐
       diately 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 spe‐
       cially handled in the SSLv2 protocol, SSL_shutdown()  will  succeed  on
       the first call.

       The  behavior of the SSL_shutdown() function also depends on the under‐
       lying 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: 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 erro‐
       neous 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  rea‐
       son.

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)

							       SSL_shutdown(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net