docs: Added All OpenBSD Manuals

1 files changed, 254 insertions, 0 deletions

diff --git a/static/openbsd/man3/SSL_shutdown.3 b/static/openbsd/man3/SSL_shutdown.3
new file mode 100644
index 00000000..ad49a47d
--- /dev/null
+++ b/static/openbsd/man3/SSL_shutdown.3
@@ -0,0 +1,254 @@
+.\"	$OpenBSD: SSL_shutdown.3,v 1.6 2025/06/08 22:52:00 schwarze Exp $
+.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
+.\"
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
+.\" Copyright (c) 2000, 2001, 2004, 2014 The OpenSSL Project.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: June 8 2025 $
+.Dt SSL_SHUTDOWN 3
+.Os
+.Sh NAME
+.Nm SSL_shutdown
+.Nd shut down a TLS/SSL connection
+.Sh SYNOPSIS
+.Lb libssl libcrypto
+.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.
+.Pp
+.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).
+.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_new 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
+.Sh HISTORY
+.Fn SSL_shutdown
+first appeared in SSLeay 0.8.0 and has been available since
+.Ox 2.4 .