secure/lib/libcrypto/man/SSL_shutdown.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_SHUTDOWN 3"
 132 .TH SSL_SHUTDOWN 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_shutdown \- shut down a TLS/SSL connection
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_shutdown(SSL *ssl);
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 \&\fISSL_shutdown()\fR shuts down an active \s-1TLS/SSL\s0 connection. It sends the
 149 close_notify shutdown alert to the peer.
 150 .SH "NOTES"
 151 .IX Header "NOTES"
 152 \&\fISSL_shutdown()\fR tries to send the close_notify shutdown alert to the peer.
 153 Whether the operation succeeds or not, the \s-1SSL_SENT_SHUTDOWN\s0 flag is set and
 154 a currently open session is considered closed and good and will be kept in the
 155 session cache for further reuse.
 156 .PP
 157 The shutdown procedure consists of two steps: sending of the close_notify
 158 shutdown alert, and reception of the peer's close_notify shutdown alert.
 159 The order of those two steps depends on the application.
 160 .PP
 161 It is acceptable for an application to only send its shutdown alert and
 162 then close the underlying connection without waiting for the peer's response.
 163 This way resources can be saved, as the process can already terminate or
 164 serve another connection.
 165 This should only be done when it is known that the other side will not send more
 166 data, otherwise there is a risk of a truncation attack.
 167 .PP
 168 When a client only writes and never reads from the connection, and the server
 169 has sent a session ticket to establish a session, the client might not be able
 170 to resume the session because it did not received and process the session ticket
 171 from the server.
 172 In case the application wants to be able to resume the session, it is recommended to
 173 do a complete shutdown procedure (bidirectional close_notify alerts).
 174 .PP
 175 When the underlying connection shall be used for more communications, the
 176 complete shutdown procedure must be performed, so that the peers stay
 177 synchronized.
 178 .PP
 179 \&\fISSL_shutdown()\fR only closes the write direction.
 180 It is not possible to call \fISSL_write()\fR after calling \fISSL_shutdown()\fR.
 181 The read direction is closed by the peer.
 182 .SS "First to close the connection"
 183 .IX Subsection "First to close the connection"
 184 When the application is the first party to send the close_notify
 185 alert, \fISSL_shutdown()\fR will only send the alert and then set the
 186 \&\s-1SSL_SENT_SHUTDOWN\s0 flag (so that the session is considered good and will
 187 be kept in the cache).
 188 If successful, \fISSL_shutdown()\fR will return 0.
 189 .PP
 190 If a unidirectional shutdown is enough (the underlying connection shall be
 191 closed anyway), this first successful call to \fISSL_shutdown()\fR is sufficient.
 192 .PP
 193 In order to complete the bidirectional shutdown handshake, the peer needs
 194 to send back a close_notify alert.
 195 The \s-1SSL_RECEIVED_SHUTDOWN\s0 flag will be set after receiving and processing
 196 it.
 197 .PP
 198 The peer is still allowed to send data after receiving the close_notify
 199 event.
 200 When it is done sending data, it will send the close_notify alert.
 201 \&\fISSL_read()\fR should be called until all data is received.
 202 \&\fISSL_read()\fR will indicate the end of the peer data by returning <= 0
 203 and \fISSL_get_error()\fR returning \s-1SSL_ERROR_ZERO_RETURN.\s0
 204 .SS "Peer closes the connection"
 205 .IX Subsection "Peer closes the connection"
 206 If the peer already sent the close_notify alert \fBand\fR it was
 207 already processed implicitly inside another function
 208 (\fISSL_read\fR\|(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set.
 209 \&\fISSL_read()\fR will return <= 0 in that case, and \fISSL_get_error()\fR will return
 210 \&\s-1SSL_ERROR_ZERO_RETURN.\s0
 211 \&\fISSL_shutdown()\fR will send the close_notify alert, set the \s-1SSL_SENT_SHUTDOWN\s0
 212 flag.
 213 If successful, \fISSL_shutdown()\fR will return 1.
 214 .PP
 215 Whether \s-1SSL_RECEIVED_SHUTDOWN\s0 is already set can be checked using the
 216 \&\fISSL_get_shutdown()\fR (see also \fISSL_set_shutdown\fR\|(3) call.
 217 .SH "NOTES"
 218 .IX Header "NOTES"
 219 The behaviour of \fISSL_shutdown()\fR additionally depends on the underlying \s-1BIO.\s0
 220 If the underlying \s-1BIO\s0 is \fBblocking\fR, \fISSL_shutdown()\fR will only return once the
 221 handshake step has been finished or an error occurred.
 222 .PP
 223 If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fISSL_shutdown()\fR will also return
 224 when the underlying \s-1BIO\s0 could not satisfy the needs of \fISSL_shutdown()\fR
 225 to continue the handshake. In this case a call to \fISSL_get_error()\fR with the
 226 return value of \fISSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 227 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after
 228 taking appropriate action to satisfy the needs of \fISSL_shutdown()\fR.
 229 The action depends on the underlying \s-1BIO.\s0 When using a non-blocking socket,
 230 nothing is to be done, but \fIselect()\fR can be used to check for the required
 231 condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written
 232 into or retrieved out of the \s-1BIO\s0 before being able to continue.
 233 .PP
 234 After \fISSL_shutdown()\fR returned 0, it is possible to call \fISSL_shutdown()\fR again
 235 to wait for the peer's close_notify alert.
 236 \&\fISSL_shutdown()\fR will return 1 in that case.
 237 However, it is recommended to wait for it using \fISSL_read()\fR instead.
 238 .PP
 239 \&\fISSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R"
 240 state but not actually send the close_notify alert messages,
 241 see \fISSL_CTX_set_quiet_shutdown\fR\|(3).
 242 When \*(L"quiet shutdown\*(R" is enabled, \fISSL_shutdown()\fR will always succeed
 243 and return 1.
 244 .SH "RETURN VALUES"
 245 .IX Header "RETURN VALUES"
 246 The following return values can occur:
 247 .IP "0" 4
 248 The shutdown is not yet finished: the close_notify was sent but the peer
 249 did not send it back yet.
 250 Call \fISSL_read()\fR to do a bidirectional shutdown.
 251 The output of \fISSL_get_error\fR\|(3) may be misleading, as an
 252 erroneous \s-1SSL_ERROR_SYSCALL\s0 may be flagged even though no error occurred.
 253 .IP "1" 4
 254 .IX Item "1"
 255 The shutdown was successfully completed. The close_notify alert was sent
 256 and the peer's close_notify alert was received.
 257 .IP "<0" 4
 258 .IX Item "<0"
 259 The shutdown was not successful.
 260 Call \fISSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
 261 It can occur if an action is needed to continue the operation for non-blocking
 262 BIOs.
 263 .Sp
 264 It can also occur when not all data was read using \fISSL_read()\fR.
 265 .SH "SEE ALSO"
 266 .IX Header "SEE ALSO"
 267 \&\fISSL_get_error\fR\|(3), \fISSL_connect\fR\|(3),
 268 \&\fISSL_accept\fR\|(3), \fISSL_set_shutdown\fR\|(3),
 269 \&\fISSL_CTX_set_quiet_shutdown\fR\|(3),
 270 \&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3),
 271 \&\fIssl\fR\|(7), \fIbio\fR\|(7)
 272 .SH "COPYRIGHT"
 273 .IX Header "COPYRIGHT"
 274 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 275 .PP
 276 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 277 this file except in compliance with the License.  You can obtain a copy
 278 in the file \s-1LICENSE\s0 in the source distribution or at
 279 <https://www.openssl.org/source/license.html>.