secure/lib/libssl/man/SSL_shutdown.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_shutdown 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 SSL_shutdown \- shut down a TLS/SSL connection
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 1
 198 \& int SSL_shutdown(SSL *ssl);
 199 .Ve
 200 .SH "DESCRIPTION"
 201 \fISSL_shutdown()\fR shuts down an active TLS/SSL connection. It sends the
 202 \*(L"close notify\*(R" shutdown alert to the peer.
 203 .SH "NOTES"
 204 \fISSL_shutdown()\fR tries to send the \*(L"close notify\*(R" shutdown alert to the peer.
 205 Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
 206 a currently open session is considered closed and good and will be kept in the
 207 session cache for further reuse.
 208 .PP
 209 The shutdown procedure consists of 2 steps: the sending of the \*(L"close notify\*(R"
 210 shutdown alert and the reception of the peer's \*(L"close notify\*(R" shutdown
 211 alert. According to the TLS standard, it is acceptable for an application
 212 to only send its shutdown alert and then close the underlying connection
 213 without waiting for the peer's response (this way resources can be saved,
 214 as the process can already terminate or serve another connection).
 215 When the underlying connection shall be used for more communications, the
 216 complete shutdown procedure (bidirectional \*(L"close notify\*(R" alerts) must be
 217 performed, so that the peers stay synchronized.
 218 .PP
 219 \fISSL_shutdown()\fR supports both uni- and bidirectional shutdown by its 2 step
 220 behaviour.
 221 .Ip "When the application is the first party to send the \*(N"close notify\*(T" alert, SSL_shutdown() will only send the alert and the set the \s-1SSL_SENT_SHUTDOWN\s0 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 \*(N"close notify\*(T" shutdown alert. On success, the second call to SSL_shutdown() will return with 1." 4
 222 .Ip "If the peer already sent the \*(N"close notify\*(T" alert \fBand\fR it was already processed implicitly inside another function (SSL_read(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set. SSL_shutdown() will send the \*(N"close notify\*(T" 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 SSL_get_shutdown() (see also SSL_set_shutdown(3) call." 4
 223 .PP
 224 It is therefore recommended, to check the return value of \fISSL_shutdown()\fR
 225 and call \fISSL_shutdown()\fR again, if the bidirectional shutdown is not yet
 226 complete (return value of the first call is 0). As the shutdown is not
 227 specially handled in the SSLv2 protocol, \fISSL_shutdown()\fR will succeed on
 228 the first call.
 229 .PP
 230 The behaviour of \fISSL_shutdown()\fR additionally depends on the underlying \s-1BIO\s0.
 231 .PP
 232 If the underlying \s-1BIO\s0 is \fBblocking\fR, \fISSL_shutdown()\fR will only return once the
 233 handshake step has been finished or an error occurred.
 234 .PP
 235 If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fISSL_shutdown()\fR will also return
 236 when the underlying \s-1BIO\s0 could not satisfy the needs of \fISSL_shutdown()\fR
 237 to continue the handshake. In this case a call to \fISSL_get_error()\fR with the
 238 return value of \fISSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
 239 \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after
 240 taking appropriate action to satisfy the needs of \fISSL_shutdown()\fR.
 241 The action depends on the underlying \s-1BIO\s0. When using a non-blocking socket,
 242 nothing is to be done, but \fIselect()\fR can be used to check for the required
 243 condition. When using a buffering \s-1BIO\s0, like a \s-1BIO\s0 pair, data must be written
 244 into or retrieved out of the \s-1BIO\s0 before being able to continue.
 245 .PP
 246 \fISSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R"
 247 state but not actually send the \*(L"close notify\*(R" alert messages,
 248 see SSL_CTX_set_quiet_shutdown(3).
 249 When \*(L"quiet shutdown\*(R" is enabled, \fISSL_shutdown()\fR will always succeed
 250 and return 1.
 251 .SH "RETURN VALUES"
 252 The following return values can occur:
 253 .Ip "1" 4
 254 The shutdown was successfully completed. The \*(L"close notify\*(R" alert was sent
 255 and the peer's \*(L"close notify\*(R" alert was received.
 256 .Ip "0" 4
 257 The shutdown is not yet finished. Call \fISSL_shutdown()\fR for a second time,
 258 if a bidirectional shutdown shall be performed.
 259 The output of SSL_get_error(3) may be misleading, as an
 260 erroneous \s-1SSL_ERROR_SYSCALL\s0 may be flagged even though no error occurred.
 261 .Ip "-1" 4
 262 The shutdown was not successful because a fatal error occurred either
 263 at the protocol level or a connection failure occurred. It can also occur if
 264 action is need to continue the operation for non-blocking BIOs.
 265 Call SSL_get_error(3) with the return value \fBret\fR
 266 to find out the reason.
 267 .SH "SEE ALSO"
 268 SSL_get_error(3), SSL_connect(3),
 269 SSL_accept(3), SSL_set_shutdown(3),
 270 SSL_CTX_set_quiet_shutdown(3),
 271 SSL_clear(3), SSL_free(3),
 272 ssl(3), bio(3)
 273
 274 .rn }` ''
 275 .IX Title "SSL_shutdown 3"
 276 .IX Name "SSL_shutdown - shut down a TLS/SSL connection"
 277
 278 .IX Header "NAME"
 279
 280 .IX Header "SYNOPSIS"
 281
 282 .IX Header "DESCRIPTION"
 283
 284 .IX Header "NOTES"
 285
 286 .IX Item "When the application is the first party to send the \*(N"close notify\*(T" alert, SSL_shutdown() will only send the alert and the set the \s-1SSL_SENT_SHUTDOWN\s0 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 \*(N"close notify\*(T" shutdown alert. On success, the second call to SSL_shutdown() will return with 1."
 287
 288 .IX Item "If the peer already sent the \*(N"close notify\*(T" alert \fBand\fR it was already processed implicitly inside another function (SSL_read(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set. SSL_shutdown() will send the \*(N"close notify\*(T" 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 SSL_get_shutdown() (see also SSL_set_shutdown(3) call."
 289
 290 .IX Header "RETURN VALUES"
 291
 292 .IX Item "1"
 293
 294 .IX Item "0"
 295
 296 .IX Item "-1"
 297
 298 .IX Header "SEE ALSO"
 299