secure/lib/libcrypto/man/man3/SSL_shutdown.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   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 "2020-09-22" "1.1.1h" "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 close_notify shutdown alert to the peer.
 154 .SH "NOTES"
 155 .IX Header "NOTES"
 156 \&\fBSSL_shutdown()\fR tries to send the close_notify 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 two steps: sending of the close_notify
 166 shutdown alert, and reception of the peer's close_notify shutdown alert.
 167 The order of those two steps depends on the application.
 168 .PP
 169 It is acceptable for an application to only send its shutdown alert and
 170 then close the underlying connection without waiting for the peer's response.
 171 This way resources can be saved, as the process can already terminate or
 172 serve another connection.
 173 This should only be done when it is known that the other side will not send more
 174 data, otherwise there is a risk of a truncation attack.
 175 .PP
 176 When a client only writes and never reads from the connection, and the server
 177 has sent a session ticket to establish a session, the client might not be able
 178 to resume the session because it did not received and process the session ticket
 179 from the server.
 180 In case the application wants to be able to resume the session, it is recommended to
 181 do a complete shutdown procedure (bidirectional close_notify alerts).
 182 .PP
 183 When the underlying connection shall be used for more communications, the
 184 complete shutdown procedure must be performed, so that the peers stay
 185 synchronized.
 186 .PP
 187 \&\fBSSL_shutdown()\fR only closes the write direction.
 188 It is not possible to call \fBSSL_write()\fR after calling \fBSSL_shutdown()\fR.
 189 The read direction is closed by the peer.
 190 .SS "First to close the connection"
 191 .IX Subsection "First to close the connection"
 192 When the application is the first party to send the close_notify
 193 alert, \fBSSL_shutdown()\fR will only send the alert and then set the
 194 \&\s-1SSL_SENT_SHUTDOWN\s0 flag (so that the session is considered good and will
 195 be kept in the cache).
 196 If successful, \fBSSL_shutdown()\fR will return 0.
 197 .PP
 198 If a unidirectional shutdown is enough (the underlying connection shall be
 199 closed anyway), this first successful call to \fBSSL_shutdown()\fR is sufficient.
 200 .PP
 201 In order to complete the bidirectional shutdown handshake, the peer needs
 202 to send back a close_notify alert.
 203 The \s-1SSL_RECEIVED_SHUTDOWN\s0 flag will be set after receiving and processing
 204 it.
 205 .PP
 206 The peer is still allowed to send data after receiving the close_notify
 207 event.
 208 When it is done sending data, it will send the close_notify alert.
 209 \&\fBSSL_read()\fR should be called until all data is received.
 210 \&\fBSSL_read()\fR will indicate the end of the peer data by returning <= 0
 211 and \fBSSL_get_error()\fR returning \s-1SSL_ERROR_ZERO_RETURN.\s0
 212 .SS "Peer closes the connection"
 213 .IX Subsection "Peer closes the connection"
 214 If the peer already sent the close_notify alert \fBand\fR it was
 215 already processed implicitly inside another function
 216 (\fBSSL_read\fR\|(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set.
 217 \&\fBSSL_read()\fR will return <= 0 in that case, and \fBSSL_get_error()\fR will return
 218 \&\s-1SSL_ERROR_ZERO_RETURN.\s0
 219 \&\fBSSL_shutdown()\fR will send the close_notify alert, set the \s-1SSL_SENT_SHUTDOWN\s0
 220 flag.
 221 If successful, \fBSSL_shutdown()\fR will return 1.
 222 .PP
 223 Whether \s-1SSL_RECEIVED_SHUTDOWN\s0 is already set can be checked using the
 224 \&\fBSSL_get_shutdown()\fR (see also \fBSSL_set_shutdown\fR\|(3) call.
 225 .SH "NOTES"
 226 .IX Header "NOTES"
 227 The behaviour of \fBSSL_shutdown()\fR additionally depends on the underlying \s-1BIO.\s0
 228 If the underlying \s-1BIO\s0 is \fBblocking\fR, \fBSSL_shutdown()\fR will only return once the
 229 handshake step has been finished or an error occurred.
 230 .PP
 231 If the underlying \s-1BIO\s0 is \fBnonblocking\fR, \fBSSL_shutdown()\fR will also return
 232 when the underlying \s-1BIO\s0 could not satisfy the needs of \fBSSL_shutdown()\fR
 233 to continue the handshake. In this case a call to \fBSSL_get_error()\fR with the
 234 return value of \fBSSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 235 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after
 236 taking appropriate action to satisfy the needs of \fBSSL_shutdown()\fR.
 237 The action depends on the underlying \s-1BIO.\s0 When using a nonblocking socket,
 238 nothing is to be done, but \fBselect()\fR can be used to check for the required
 239 condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written
 240 into or retrieved out of the \s-1BIO\s0 before being able to continue.
 241 .PP
 242 After \fBSSL_shutdown()\fR returned 0, it is possible to call \fBSSL_shutdown()\fR again
 243 to wait for the peer's close_notify alert.
 244 \&\fBSSL_shutdown()\fR will return 1 in that case.
 245 However, it is recommended to wait for it using \fBSSL_read()\fR instead.
 246 .PP
 247 \&\fBSSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R"
 248 state but not actually send the close_notify alert messages,
 249 see \fBSSL_CTX_set_quiet_shutdown\fR\|(3).
 250 When \*(L"quiet shutdown\*(R" is enabled, \fBSSL_shutdown()\fR will always succeed
 251 and return 1.
 252 Note that this is not standard compliant behaviour.
 253 It should only be done when the peer has a way to make sure all
 254 data has been received and doesn't wait for the close_notify alert
 255 message, otherwise an unexpected \s-1EOF\s0 will be reported.
 256 .PP
 257 There are implementations that do not send the required close_notify alert.
 258 If there is a need to communicate with such an implementation, and it's clear
 259 that all data has been received, do not wait for the peer's close_notify alert.
 260 Waiting for the close_notify alert when the peer just closes the connection will
 261 result in an error being generated.
 262 .SH "RETURN VALUES"
 263 .IX Header "RETURN VALUES"
 264 The following return values can occur:
 265 .IP "0" 4
 266 The shutdown is not yet finished: the close_notify was sent but the peer
 267 did not send it back yet.
 268 Call \fBSSL_read()\fR to do a bidirectional shutdown.
 269 .Sp
 270 Unlike most other function, returning 0 does not indicate an error.
 271 \&\fBSSL_get_error\fR\|(3) should not get called, it may misleadingly
 272 indicate an error even though no error occurred.
 273 .IP "1" 4
 274 .IX Item "1"
 275 The shutdown was successfully completed. The close_notify alert was sent
 276 and the peer's close_notify alert was received.
 277 .IP "<0" 4
 278 .IX Item "<0"
 279 The shutdown was not successful.
 280 Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
 281 It can occur if an action is needed to continue the operation for nonblocking
 282 BIOs.
 283 .Sp
 284 It can also occur when not all data was read using \fBSSL_read()\fR.
 285 .SH "SEE ALSO"
 286 .IX Header "SEE ALSO"
 287 \&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3),
 288 \&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
 289 \&\fBSSL_CTX_set_quiet_shutdown\fR\|(3),
 290 \&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3),
 291 \&\fBssl\fR\|(7), \fBbio\fR\|(7)
 292 .SH "COPYRIGHT"
 293 .IX Header "COPYRIGHT"
 294 Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved.
 295 .PP
 296 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 297 this file except in compliance with the License.  You can obtain a copy
 298 in the file \s-1LICENSE\s0 in the source distribution or at
 299 <https://www.openssl.org/source/license.html>.