From 018ef6efe1e20b420eaa3afdaa37b0abeba93a1a Mon Sep 17 00:00:00 2001 From: simon Date: Sat, 29 Jul 2006 19:41:41 +0000 Subject: Upgrade to OpenSSL 0.9.8b. --- secure/lib/libssl/man/SSL_shutdown.3 | 75 ++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 42 deletions(-) (limited to 'secure/lib/libssl/man/SSL_shutdown.3') diff --git a/secure/lib/libssl/man/SSL_shutdown.3 b/secure/lib/libssl/man/SSL_shutdown.3 index 291aa32..a6259db 100644 --- a/secure/lib/libssl/man/SSL_shutdown.3 +++ b/secure/lib/libssl/man/SSL_shutdown.3 @@ -1,8 +1,7 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Feb 19 16:47:49 2003 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: -.\" ====================================================================== +.\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp @@ -15,12 +14,6 @@ .if t .sp .5v .if n .sp .. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. .de Vb \" Begin verbatim text .ft CW .nf @@ -28,15 +21,14 @@ .. .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. | will give a -.\" real vertical bar. \*(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<> +.\" real vertical bar. \*(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-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ @@ -56,10 +48,10 @@ . ds R" '' 'br\} .\" -.\" If the F register is turned on, we'll generate index entries on stderr -.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and -.\" index entries marked with X<> in POD. Of course, you'll have to process -.\" the output yourself in some meaningful fashion. +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" @@ -68,14 +60,13 @@ . rr F .\} .\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. -.bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 @@ -135,18 +126,18 @@ . ds Ae AE .\} .rm #[ #] #H #V #F C -.\" ====================================================================== +.\" ======================================================================== .\" .IX Title "SSL_shutdown 3" -.TH SSL_shutdown 3 "0.9.7a" "2003-02-19" "OpenSSL" -.UC +.TH SSL_shutdown 3 "2006-07-29" "0.9.8b" "OpenSSL" .SH "NAME" -SSL_shutdown \- shut down a \s-1TLS/SSL\s0 connection +SSL_shutdown \- shut down a TLS/SSL connection .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include .Ve +.PP .Vb 1 \& int SSL_shutdown(SSL *ssl); .Ve @@ -171,15 +162,15 @@ When the underlying connection shall be used for more communications, the complete shutdown procedure (bidirectional \*(L"close notify\*(R" alerts) must be performed, so that the peers stay synchronized. .PP -\&\fISSL_shutdown()\fR supports both uni- and bidirectional shutdown by its 2 step +\&\fISSL_shutdown()\fR supports both uni\- and bidirectional shutdown by its 2 step behaviour. -.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 -.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 -.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." +.ie n .IP "When the application is the first party to send the ""close notify"" alert, \fISSL_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 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 +.el .IP "When the application is the first party to send the ``close notify'' alert, \fISSL_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 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 +.IX Item "When the application is the first party to send the close notify alert, SSL_shutdown() will only send the alert and then 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." .PD 0 -.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 -.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 -.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." +.ie n .IP "If the peer already sent the ""close notify"" alert \fBand\fR it was already processed implicitly inside another function (\fISSL_read\fR\|(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 \fISSL_set_shutdown\fR\|(3) call." 4 +.el .IP "If the peer already sent the ``close notify'' alert \fBand\fR it was already processed implicitly inside another function (\fISSL_read\fR\|(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 \fISSL_set_shutdown\fR\|(3) call." 4 +.IX Item "If the peer already sent the close notify alert and it was already processed implicitly inside another function (SSL_read), 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 call." .PD .PP It is therefore recommended, to check the return value of \fISSL_shutdown()\fR @@ -206,32 +197,32 @@ into or retrieved out of the \s-1BIO\s0 before being able to continue. .PP \&\fISSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R" state but not actually send the \*(L"close notify\*(R" alert messages, -see SSL_CTX_set_quiet_shutdown(3). +see \fISSL_CTX_set_quiet_shutdown\fR\|(3). When \*(L"quiet shutdown\*(R" is enabled, \fISSL_shutdown()\fR will always succeed and return 1. .SH "RETURN VALUES" .IX Header "RETURN VALUES" The following return values can occur: -.Ip "1" 4 +.IP "1" 4 .IX Item "1" The shutdown was successfully completed. The \*(L"close notify\*(R" alert was sent and the peer's \*(L"close notify\*(R" alert was received. -.Ip "0" 4 +.IP "0" 4 The shutdown is not yet finished. Call \fISSL_shutdown()\fR for a second time, if a bidirectional shutdown shall be performed. -The output of SSL_get_error(3) may be misleading, as an +The output of \fISSL_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 +.IP "\-1" 4 .IX Item "-1" The shutdown was not successful because a fatal error occurred either at the protocol level or a connection failure occurred. It can also occur if action is need to continue the operation for non-blocking BIOs. -Call SSL_get_error(3) with the return value \fBret\fR +Call \fISSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason. .SH "SEE ALSO" .IX Header "SEE ALSO" -SSL_get_error(3), SSL_connect(3), -SSL_accept(3), SSL_set_shutdown(3), -SSL_CTX_set_quiet_shutdown(3), -SSL_clear(3), SSL_free(3), -ssl(3), bio(3) +\&\fISSL_get_error\fR\|(3), \fISSL_connect\fR\|(3), +\&\fISSL_accept\fR\|(3), \fISSL_set_shutdown\fR\|(3), +\&\fISSL_CTX_set_quiet_shutdown\fR\|(3), +\&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3), +\&\fIssl\fR\|(3), \fIbio\fR\|(3) -- cgit v1.1