secure/lib/libssl/man/SSL_shutdown.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_shutdown 3"
 136 .TH SSL_shutdown 3 "2019-02-26" "1.0.2r" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_shutdown \- shut down a TLS/SSL connection
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_shutdown(SSL *ssl);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\fBSSL_shutdown()\fR shuts down an active \s-1TLS/SSL\s0 connection. It sends the
 153 \&\*(L"close notify\*(R" shutdown alert to the peer.
 154 .SH "NOTES"
 155 .IX Header "NOTES"
 156 \&\fBSSL_shutdown()\fR tries to send the \*(L"close notify\*(R" shutdown alert to the peer.
 157 Whether the operation succeeds or not, the \s-1SSL_SENT_SHUTDOWN\s0 flag is set and
 158 a currently open session is considered closed and good and will be kept in the
 159 session cache for further reuse.
 160 .PP
 161 Note that \fBSSL_shutdown()\fR must not be called if a previous fatal error has
 162 occurred on a connection i.e. if \fBSSL_get_error()\fR has returned \s-1SSL_ERROR_SYSCALL\s0
 163 or \s-1SSL_ERROR_SSL.\s0
 164 .PP
 165 The shutdown procedure consists of 2 steps: the sending of the \*(L"close notify\*(R"
 166 shutdown alert and the reception of the peer's \*(L"close notify\*(R" shutdown
 167 alert. According to the \s-1TLS\s0 standard, it is acceptable for an application
 168 to only send its shutdown alert and then close the underlying connection
 169 without waiting for the peer's response (this way resources can be saved,
 170 as the process can already terminate or serve another connection).
 171 When the underlying connection shall be used for more communications, the
 172 complete shutdown procedure (bidirectional \*(L"close notify\*(R" alerts) must be
 173 performed, so that the peers stay synchronized.
 174 .PP
 175 \&\fBSSL_shutdown()\fR supports both uni\- and bidirectional shutdown by its 2 step
 176 behaviour.
 177 .ie n .IP "When the application is the first party to send the ""close notify"" alert, \fBSSL_shutdown()\fR will only send the alert and then set the \s-1SSL_SENT_SHUTDOWN\s0 flag (so that the session is considered good and will be kept in cache). \fBSSL_shutdown()\fR will then return with 0. If a unidirectional shutdown is enough (the underlying connection shall be closed anyway), this first call to \fBSSL_shutdown()\fR is sufficient. In order to complete the bidirectional shutdown handshake, \fBSSL_shutdown()\fR must be called again. The second call will make \fBSSL_shutdown()\fR wait for the peer's ""close notify"" shutdown alert. On success, the second call to \fBSSL_shutdown()\fR will return with 1." 4
 178 .el .IP "When the application is the first party to send the ``close notify'' alert, \fBSSL_shutdown()\fR will only send the alert and then set the \s-1SSL_SENT_SHUTDOWN\s0 flag (so that the session is considered good and will be kept in cache). \fBSSL_shutdown()\fR will then return with 0. If a unidirectional shutdown is enough (the underlying connection shall be closed anyway), this first call to \fBSSL_shutdown()\fR is sufficient. In order to complete the bidirectional shutdown handshake, \fBSSL_shutdown()\fR must be called again. The second call will make \fBSSL_shutdown()\fR wait for the peer's ``close notify'' shutdown alert. On success, the second call to \fBSSL_shutdown()\fR will return with 1." 4
 179 .IX Item "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). SSL_shutdown() 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."
 180 .PD 0
 181 .ie n .IP "If the peer already sent the ""close notify"" alert \fBand\fR it was already processed implicitly inside another function (\fBSSL_read\fR\|(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set. \fBSSL_shutdown()\fR will send the ""close notify"" alert, set the \s-1SSL_SENT_SHUTDOWN\s0 flag and will immediately return with 1. Whether \s-1SSL_RECEIVED_SHUTDOWN\s0 is already set can be checked using the \fBSSL_get_shutdown()\fR (see also \fBSSL_set_shutdown\fR\|(3) call." 4
 182 .el .IP "If the peer already sent the ``close notify'' alert \fBand\fR it was already processed implicitly inside another function (\fBSSL_read\fR\|(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set. \fBSSL_shutdown()\fR will send the ``close notify'' alert, set the \s-1SSL_SENT_SHUTDOWN\s0 flag and will immediately return with 1. Whether \s-1SSL_RECEIVED_SHUTDOWN\s0 is already set can be checked using the \fBSSL_get_shutdown()\fR (see also \fBSSL_set_shutdown\fR\|(3) call." 4
 183 .IX Item "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. SSL_shutdown() will send the close notify alert, set the SSL_SENT_SHUTDOWN flag and will immediately return with 1. Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the SSL_get_shutdown() (see also SSL_set_shutdown call."
 184 .PD
 185 .PP
 186 It is therefore recommended, to check the return value of \fBSSL_shutdown()\fR
 187 and call \fBSSL_shutdown()\fR again, if the bidirectional shutdown is not yet
 188 complete (return value of the first call is 0). As the shutdown is not
 189 specially handled in the SSLv2 protocol, \fBSSL_shutdown()\fR will succeed on
 190 the first call.
 191 .PP
 192 The behaviour of \fBSSL_shutdown()\fR additionally depends on the underlying \s-1BIO.\s0
 193 .PP
 194 If the underlying \s-1BIO\s0 is \fBblocking\fR, \fBSSL_shutdown()\fR will only return once the
 195 handshake step has been finished or an error occurred.
 196 .PP
 197 If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fBSSL_shutdown()\fR will also return
 198 when the underlying \s-1BIO\s0 could not satisfy the needs of \fBSSL_shutdown()\fR
 199 to continue the handshake. In this case a call to \fBSSL_get_error()\fR with the
 200 return value of \fBSSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 201 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after
 202 taking appropriate action to satisfy the needs of \fBSSL_shutdown()\fR.
 203 The action depends on the underlying \s-1BIO.\s0 When using a non-blocking socket,
 204 nothing is to be done, but \fBselect()\fR can be used to check for the required
 205 condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written
 206 into or retrieved out of the \s-1BIO\s0 before being able to continue.
 207 .PP
 208 \&\fBSSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R"
 209 state but not actually send the \*(L"close notify\*(R" alert messages,
 210 see \fBSSL_CTX_set_quiet_shutdown\fR\|(3).
 211 When \*(L"quiet shutdown\*(R" is enabled, \fBSSL_shutdown()\fR will always succeed
 212 and return 1.
 213 .SH "RETURN VALUES"
 214 .IX Header "RETURN VALUES"
 215 The following return values can occur:
 216 .IP "0" 4
 217 The shutdown is not yet finished. Call \fBSSL_shutdown()\fR for a second time,
 218 if a bidirectional shutdown shall be performed.
 219 The output of \fBSSL_get_error\fR\|(3) may be misleading, as an
 220 erroneous \s-1SSL_ERROR_SYSCALL\s0 may be flagged even though no error occurred.
 221 .IP "1" 4
 222 .IX Item "1"
 223 The shutdown was successfully completed. The \*(L"close notify\*(R" alert was sent
 224 and the peer's \*(L"close notify\*(R" alert was received.
 225 .IP "<0" 4
 226 .IX Item "<0"
 227 The shutdown was not successful because a fatal error occurred either
 228 at the protocol level or a connection failure occurred. It can also occur if
 229 action is need to continue the operation for non-blocking BIOs.
 230 Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR
 231 to find out the reason.
 232 .SH "SEE ALSO"
 233 .IX Header "SEE ALSO"
 234 \&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3),
 235 \&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
 236 \&\fBSSL_CTX_set_quiet_shutdown\fR\|(3),
 237 \&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3),
 238 \&\fBssl\fR\|(3), \fBbio\fR\|(3)