move manual pages from doc/ to man/ for consistency with other

libraries, in particular considering that there are unrelated
files in doc/; requested by jsing@ and beck@

1 files changed, 204 insertions, 0 deletions

diff --git a/src/lib/libssl/man/SSL_shutdown.3 b/src/lib/libssl/man/SSL_shutdown.3
new file mode 100644
index 0000000000..1dfcb54bfe
--- /dev/null
+++ b/src/lib/libssl/man/SSL_shutdown.3
@@ -0,0 +1,204 @@
+.\"
+.\"     $OpenBSD: SSL_shutdown.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
+.\"
+.Dd $Mdocdate: November 5 2016 $
+.Dt SSL_SHUTDOWN 3
+.Os
+.Sh NAME
+.Nm SSL_shutdown
+.Nd shut down a TLS/SSL connection
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft int
+.Fn SSL_shutdown "SSL *ssl"
+.Sh DESCRIPTION
+.Fn SSL_shutdown
+shuts down an active TLS/SSL connection.
+It sends the
+.Dq close notify
+shutdown alert to the peer.
+.Sh NOTES
+.Fn SSL_shutdown
+tries to send the
+.Dq close notify
+shutdown alert to the peer.
+Whether the operation succeeds or not, the
+.Dv SSL_SENT_SHUTDOWN
+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
+The shutdown procedure consists of 2 steps: the sending of the
+.Dq close notify
+shutdown alert and the reception of the peer's
+.Dq close notify
+shutdown alert.
+According to the TLS standard, 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).
+When the underlying connection shall be used for more communications,
+the complete shutdown procedure (bidirectional
+.Dq close notify
+alerts) must be performed, so that the peers stay synchronized.
+.Pp
+.Fn SSL_shutdown
+supports both uni- and bidirectional shutdown by its 2 step behavior.
+.Pp
+When the application is the first party to send the
+.Dq close notify
+alert,
+.Fn SSL_shutdown
+will only send the alert and then set the
+.Dv SSL_SENT_SHUTDOWN
+flag (so that the session is considered good and will be kept in cache).
+.Fn SSL_shutdown
+will then return 0.
+If a unidirectional shutdown is enough
+(the underlying connection shall be closed anyway), this first call to
+.Fn SSL_shutdown
+is sufficient.
+In order to complete the bidirectional shutdown handshake,
+.Fn SSL_shutdown
+must be called again.
+The second call will make
+.Fn SSL_shutdown
+wait for the peer's
+.Dq close notify
+shutdown alert.
+On success, the second call to
+.Fn SSL_shutdown
+will return 1.
+.Pp
+If the peer already sent the
+.Dq close notify
+alert and it was already processed implicitly inside another function
+.Pq Xr SSL_read 3 ,
+the
+.Dv SSL_RECEIVED_SHUTDOWN
+flag is set.
+.Fn SSL_shutdown
+will send the
+.Dq close notify
+alert, set the
+.Dv SSL_SENT_SHUTDOWN
+flag and will immediately return with 1.
+Whether
+.Dv SSL_RECEIVED_SHUTDOWN
+is already set can be checked using the
+.Fn SSL_get_shutdown
+(see also the
+.Xr SSL_set_shutdown 3
+call).
+.Pp
+It is therefore recommended to check the return value of
+.Fn SSL_shutdown
+and call
+.Fn SSL_shutdown
+again, if the bidirectional shutdown is not yet complete (return value of the
+first call is 0).
+As the shutdown is not specially handled in the SSLv2 protocol,
+.Fn SSL_shutdown
+will succeed on the first call.
+.Pp
+The behaviour of
+.Fn SSL_shutdown
+additionally depends on the underlying
+.Vt BIO .
+.Pp
+If the underlying
+.Vt BIO
+is
+.Em blocking ,
+.Fn SSL_shutdown
+will only return once the
+handshake step has been finished or an error occurred.
+.Pp
+If the underlying
+.Vt BIO
+is
+.Em non-blocking ,
+.Fn SSL_shutdown
+will also return when the underlying
+.Vt BIO
+could not satisfy the needs of
+.Fn SSL_shutdown
+to continue the handshake.
+In this case a call to
+.Xr SSL_get_error 3
+with the
+return value of
+.Fn SSL_shutdown
+will yield
+.Dv SSL_ERROR_WANT_READ
+or
+.Dv SSL_ERROR_WANT_WRITE .
+The calling process then must repeat the call after taking appropriate action
+to satisfy the needs of
+.Fn SSL_shutdown .
+The action depends on the underlying
+.Vt BIO .
+When using a non-blocking socket, nothing is to be done, but
+.Xr select 2
+can be used to check for the required condition.
+When using a buffering
+.Vt BIO ,
+like a
+.Vt BIO
+pair, data must be written into or retrieved out of the
+.Vt BIO
+before being able to continue.
+.Pp
+.Fn SSL_shutdown
+can be modified to only set the connection to
+.Dq shutdown
+state but not actually send the
+.Dq close notify
+alert messages; see
+.Xr SSL_CTX_set_quiet_shutdown 3 .
+When
+.Dq quiet shutdown
+is enabled,
+.Fn SSL_shutdown
+will always succeed and return 1.
+.Sh RETURN VALUES
+The following return values can occur:
+.Bl -tag -width Ds
+.It 0
+The shutdown is not yet finished.
+Call
+.Fn SSL_shutdown
+for a second time, if a bidirectional shutdown shall be performed.
+The output of
+.Xr SSL_get_error 3
+may be misleading, as an erroneous
+.Dv SSL_ERROR_SYSCALL
+may be flagged even though no error occurred.
+.It 1
+The shutdown was successfully completed.
+The
+.Dq close notify
+alert was sent and the peer's
+.Dq close notify
+alert was received.
+.It \(mi1
+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
+.Vt BIO Ns
+s.
+Call
+.Xr SSL_get_error 3
+with the return value
+.Fa ret
+to find out the reason.
+.El
+.Sh SEE ALSO
+.Xr bio 3 ,
+.Xr ssl 3 ,
+.Xr SSL_accept 3 ,
+.Xr SSL_clear 3 ,
+.Xr SSL_connect 3 ,
+.Xr SSL_CTX_set_quiet_shutdown 3 ,
+.Xr SSL_free 3 ,
+.Xr SSL_get_error 3 ,
+.Xr SSL_set_shutdown 3