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