forked from cory/tildefriends
288 lines
11 KiB
Groff
288 lines
11 KiB
Groff
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
. ds C`
|
||
|
|
. ds C'
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.\"
|
||
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
||
|
|
.de IX
|
||
|
|
..
|
||
|
|
.nr rF 0
|
||
|
|
.if \n(.g .if rF .nr rF 1
|
||
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
||
|
|
. if \nF \{\
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. if !\nF==2 \{\
|
||
|
|
. nr % 0
|
||
|
|
. nr F 2
|
||
|
|
. \}
|
||
|
|
. \}
|
||
|
|
.\}
|
||
|
|
.rr rF
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "SSL_SHUTDOWN 3"
|
||
|
|
.TH SSL_SHUTDOWN 3 "2020-04-21" "1.1.1g" "OpenSSL"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "NAME"
|
||
|
|
SSL_shutdown \- shut down a TLS/SSL connection
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 1
|
||
|
|
\& #include <openssl/ssl.h>
|
||
|
|
\&
|
||
|
|
\& int SSL_shutdown(SSL *ssl);
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
\&\fBSSL_shutdown()\fR shuts down an active \s-1TLS/SSL\s0 connection. It sends the
|
||
|
|
close_notify shutdown alert to the peer.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "NOTES"
|
||
|
|
\&\fBSSL_shutdown()\fR tries to send the close_notify shutdown alert to the peer.
|
||
|
|
Whether the operation succeeds or not, the \s-1SSL_SENT_SHUTDOWN\s0 flag is set and
|
||
|
|
a currently open session is considered closed and good and will be kept in the
|
||
|
|
session cache for further reuse.
|
||
|
|
.PP
|
||
|
|
Note that \fBSSL_shutdown()\fR must not be called if a previous fatal error has
|
||
|
|
occurred on a connection i.e. if \fBSSL_get_error()\fR has returned \s-1SSL_ERROR_SYSCALL\s0
|
||
|
|
or \s-1SSL_ERROR_SSL.\s0
|
||
|
|
.PP
|
||
|
|
The shutdown procedure consists of two steps: sending of the close_notify
|
||
|
|
shutdown alert, and reception of the peer's close_notify shutdown alert.
|
||
|
|
The order of those two steps depends on the application.
|
||
|
|
.PP
|
||
|
|
It is acceptable for an application to only send its shutdown alert and
|
||
|
|
then close the underlying connection without waiting for the peer's response.
|
||
|
|
This way resources can be saved, as the process can already terminate or
|
||
|
|
serve another connection.
|
||
|
|
This should only be done when it is known that the other side will not send more
|
||
|
|
data, otherwise there is a risk of a truncation attack.
|
||
|
|
.PP
|
||
|
|
When a client only writes and never reads from the connection, and the server
|
||
|
|
has sent a session ticket to establish a session, the client might not be able
|
||
|
|
to resume the session because it did not received and process the session ticket
|
||
|
|
from the server.
|
||
|
|
In case the application wants to be able to resume the session, it is recommended to
|
||
|
|
do a complete shutdown procedure (bidirectional close_notify alerts).
|
||
|
|
.PP
|
||
|
|
When the underlying connection shall be used for more communications, the
|
||
|
|
complete shutdown procedure must be performed, so that the peers stay
|
||
|
|
synchronized.
|
||
|
|
.PP
|
||
|
|
\&\fBSSL_shutdown()\fR only closes the write direction.
|
||
|
|
It is not possible to call \fBSSL_write()\fR after calling \fBSSL_shutdown()\fR.
|
||
|
|
The read direction is closed by the peer.
|
||
|
|
.SS "First to close the connection"
|
||
|
|
.IX Subsection "First to close the connection"
|
||
|
|
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 the cache).
|
||
|
|
If successful, \fBSSL_shutdown()\fR will return 0.
|
||
|
|
.PP
|
||
|
|
If a unidirectional shutdown is enough (the underlying connection shall be
|
||
|
|
closed anyway), this first successful call to \fBSSL_shutdown()\fR is sufficient.
|
||
|
|
.PP
|
||
|
|
In order to complete the bidirectional shutdown handshake, the peer needs
|
||
|
|
to send back a close_notify alert.
|
||
|
|
The \s-1SSL_RECEIVED_SHUTDOWN\s0 flag will be set after receiving and processing
|
||
|
|
it.
|
||
|
|
.PP
|
||
|
|
The peer is still allowed to send data after receiving the close_notify
|
||
|
|
event.
|
||
|
|
When it is done sending data, it will send the close_notify alert.
|
||
|
|
\&\fBSSL_read()\fR should be called until all data is received.
|
||
|
|
\&\fBSSL_read()\fR will indicate the end of the peer data by returning <= 0
|
||
|
|
and \fBSSL_get_error()\fR returning \s-1SSL_ERROR_ZERO_RETURN.\s0
|
||
|
|
.SS "Peer closes the connection"
|
||
|
|
.IX Subsection "Peer closes the connection"
|
||
|
|
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_read()\fR will return <= 0 in that case, and \fBSSL_get_error()\fR will return
|
||
|
|
\&\s-1SSL_ERROR_ZERO_RETURN.\s0
|
||
|
|
\&\fBSSL_shutdown()\fR will send the close_notify alert, set the \s-1SSL_SENT_SHUTDOWN\s0
|
||
|
|
flag.
|
||
|
|
If successful, \fBSSL_shutdown()\fR will return 1.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "NOTES"
|
||
|
|
The behaviour of \fBSSL_shutdown()\fR additionally depends on the underlying \s-1BIO.\s0
|
||
|
|
If the underlying \s-1BIO\s0 is \fBblocking\fR, \fBSSL_shutdown()\fR will only return once the
|
||
|
|
handshake step has been finished or an error occurred.
|
||
|
|
.PP
|
||
|
|
If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fBSSL_shutdown()\fR will also return
|
||
|
|
when the underlying \s-1BIO\s0 could not satisfy the needs of \fBSSL_shutdown()\fR
|
||
|
|
to continue the handshake. In this case a call to \fBSSL_get_error()\fR with the
|
||
|
|
return value of \fBSSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
|
||
|
|
\&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after
|
||
|
|
taking appropriate action to satisfy the needs of \fBSSL_shutdown()\fR.
|
||
|
|
The action depends on the underlying \s-1BIO.\s0 When using a non-blocking socket,
|
||
|
|
nothing is to be done, but \fBselect()\fR can be used to check for the required
|
||
|
|
condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written
|
||
|
|
into or retrieved out of the \s-1BIO\s0 before being able to continue.
|
||
|
|
.PP
|
||
|
|
After \fBSSL_shutdown()\fR returned 0, it is possible to call \fBSSL_shutdown()\fR again
|
||
|
|
to wait for the peer's close_notify alert.
|
||
|
|
\&\fBSSL_shutdown()\fR will return 1 in that case.
|
||
|
|
However, it is recommended to wait for it using \fBSSL_read()\fR instead.
|
||
|
|
.PP
|
||
|
|
\&\fBSSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R"
|
||
|
|
state but not actually send the close_notify alert messages,
|
||
|
|
see \fBSSL_CTX_set_quiet_shutdown\fR\|(3).
|
||
|
|
When \*(L"quiet shutdown\*(R" is enabled, \fBSSL_shutdown()\fR will always succeed
|
||
|
|
and return 1.
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
.IX Header "RETURN VALUES"
|
||
|
|
The following return values can occur:
|
||
|
|
.IP "0" 4
|
||
|
|
The shutdown is not yet finished: the close_notify was sent but the peer
|
||
|
|
did not send it back yet.
|
||
|
|
Call \fBSSL_read()\fR to do a bidirectional shutdown.
|
||
|
|
The output of \fBSSL_get_error\fR\|(3) may be misleading, as an
|
||
|
|
erroneous \s-1SSL_ERROR_SYSCALL\s0 may be flagged even though no error occurred.
|
||
|
|
.IP "1" 4
|
||
|
|
.IX Item "1"
|
||
|
|
The shutdown was successfully completed. The close_notify alert was sent
|
||
|
|
and the peer's close_notify alert was received.
|
||
|
|
.IP "<0" 4
|
||
|
|
.IX Item "<0"
|
||
|
|
The shutdown was not successful.
|
||
|
|
Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
|
||
|
|
It can occur if an action is needed to continue the operation for non-blocking
|
||
|
|
BIOs.
|
||
|
|
.Sp
|
||
|
|
It can also occur when not all data was read using \fBSSL_read()\fR.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3),
|
||
|
|
\&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
|
||
|
|
\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3),
|
||
|
|
\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3),
|
||
|
|
\&\fBssl\fR\|(7), \fBbio\fR\|(7)
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
||
|
|
<https://www.openssl.org/source/license.html>.
|