Merging upstream version 4.23.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 265 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/BIO_s_dgram_pair.3ssl b/upstream/debian-unstable/man3/BIO_s_dgram_pair.3ssl
new file mode 100644
index 00000000..b33402f3
--- /dev/null
+++ b/upstream/debian-unstable/man3/BIO_s_dgram_pair.3ssl
@@ -0,0 +1,265 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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
+.\" ========================================================================
+.\"
+.IX Title "BIO_S_DGRAM_PAIR 3SSL"
+.TH BIO_S_DGRAM_PAIR 3SSL 2024-04-04 3.2.2-dev 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
+BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc,
+BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps,
+BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu \- datagram pair BIO
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/bio.h>
+\&
+\& const BIO_METHOD *BIO_s_dgram_pair(void);
+\&
+\& int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,
+\&                            BIO **bio2, size_t writebuf2);
+\& int BIO_dgram_set_no_trunc(BIO *bio, int enable);
+\& int BIO_dgram_get_no_trunc(BIO *bio);
+\& uint32_t BIO_dgram_get_effective_caps(BIO *bio);
+\& uint32_t BIO_dgram_get_caps(BIO *bio);
+\& int BIO_dgram_set_caps(BIO *bio, uint32_t caps);
+\& int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);
+\& unsigned int BIO_dgram_get_mtu(BIO *bio);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBBIO_s_dgram_pair()\fR returns the method for a BIO datagram pair. A BIO datagram
+pair is similar to a BIO pair (see \fBBIO_s_bio\fR\|(3)) but has datagram semantics.
+Broadly, this means that the length of the buffer passed to a write call will
+match that retrieved by a read call. If the buffer passed to a read call is too
+short, the datagram is truncated or the read fails, depending on how the BIO is
+configured.
+.PP
+The BIO datagram pair attaches certain metadata to each write, such as source
+and destination addresses. This information may be retrieved on read.
+.PP
+A typical application of a BIO datagram pair is to allow an application to keep
+all datagram network I/O requested by libssl under application control.
+.PP
+The BIO datagram pair is designed to support multithreaded use where certain
+restrictions are observed; see THREADING.
+.PP
+The BIO datagram pair allows each half of a pair to signal to the other half
+whether they support certain capabilities; see CAPABILITY INDICATION.
+.PP
+\&\fBBIO_new_bio_dgram_pair()\fR combines the calls to \fBBIO_new\fR\|(3),
+\&\fBBIO_make_bio_pair\fR\|(3) and \fBBIO_set_write_buf_size\fR\|(3) to create a connected
+pair of BIOs \fBbio1\fR, \fBbio2\fR with write buffer sizes \fBwritebuf1\fR and
+\&\fBwritebuf2\fR. If either size is zero then the default size is used.
+.PP
+\&\fBBIO_make_bio_pair\fR\|(3) may be used to join two datagram pair BIOs into a pair.
+The two BIOs must both use the method returned by \fBBIO_s_dgram_pair()\fR and neither
+of the BIOs may currently be associated in a pair.
+.PP
+\&\fBBIO_destroy_bio_pair\fR\|(3) destroys the association between two connected BIOs.
+Freeing either half of the pair will automatically destroy the association.
+.PP
+\&\fBBIO_reset\fR\|(3) clears any data in the write buffer of the given BIO. This means
+that the opposite BIO in the pair will no longer have any data waiting to be
+read.
+.PP
+The BIO maintains a fixed size internal write buffer. When the buffer is full,
+further writes will fail until the buffer is drained via calls to
+\&\fBBIO_read\fR\|(3). The size of the buffer can be changed using
+\&\fBBIO_set_write_buf_size\fR\|(3) and queried using \fBBIO_get_write_buf_size\fR\|(3).
+.PP
+Note that the write buffer is partially consumed by metadata stored internally
+which is attached to each datagram, such as source and destination addresses.
+The size of this overhead is undefined and may change between releases.
+.PP
+The standard \fBBIO_ctrl_pending\fR\|(3) call has modified behaviour and returns the
+size of the next datagram waiting to be read in bytes. An application can use
+this function to ensure it provides an adequate buffer to a subsequent read
+call. If no datagram is waiting to be read, zero is returned.
+.PP
+This BIO does not support sending or receiving zero-length datagrams. Passing a
+zero-length buffer to BIO_write is treated as a no-op.
+.PP
+\&\fBBIO_eof\fR\|(3) returns 1 only if the given BIO datagram pair BIO is not currently
+connected to a peer BIO.
+.PP
+\&\fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_ctrl_get_write_guarantee\fR\|(3) return how
+large a datagram the next call to \fBBIO_write\fR\|(3) can accept. If there is not
+enough space in the write buffer to accept another datagram equal in size to the
+configured MTU, zero is returned (see below). This is intended to avoid a
+situation where an application attempts to read a datagram from a network
+intending to write it to a BIO datagram pair, but where the received datagram
+ends up being too large to write to the BIO datagram pair.
+.PP
+\&\fBBIO_dgram_set_no_trunc()\fR and \fBBIO_ctrl_get_no_trunc()\fR set and retrieve the
+truncation mode for the given half of a BIO datagram pair. When no-truncate mode
+is enabled, \fBBIO_read()\fR will fail if the buffer provided is inadequate to hold
+the next datagram to be read. If no-truncate mode is disabled (the default), the
+datagram will be silently truncated. This default behaviour maintains
+compatibility with the semantics of the Berkeley sockets API.
+.PP
+\&\fBBIO_dgram_set_mtu()\fR and \fBBIO_dgram_get_mtu()\fR may be used to set an informational
+MTU value on the BIO datagram pair. If \fBBIO_dgram_set_mtu()\fR is used on a BIO
+which is currently part of a BIO datagram pair, the MTU value is set on both
+halves of the pair. The value does not affect the operation of the BIO datagram
+pair (except for \fBBIO_get_write_guarantee()\fR; see above) but may be used by other
+code to determine a requested MTU. When a BIO datagram pair BIO is created, the
+MTU is set to an unspecified but valid value.
+.PP
+\&\fBBIO_flush\fR\|(3) is a no-op.
+.SH NOTES
+.IX Header "NOTES"
+The halves of a BIO datagram pair have independent lifetimes and must be
+separately freed.
+.SH THREADING
+.IX Header "THREADING"
+\&\fBBIO_recvmmsg\fR\|(3), \fBBIO_sendmmsg\fR\|(3), \fBBIO_read\fR\|(3), \fBBIO_write\fR\|(3),
+\&\fBBIO_pending\fR\|(3), \fBBIO_get_write_guarantee\fR\|(3) and \fBBIO_flush\fR\|(3) may be used
+by multiple threads simultaneously on the same BIO datagram pair. Specific
+\&\fBBIO_ctrl\fR\|(3) operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and
+BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any
+other \fBBIO_ctrl\fR\|(3) operation, on either half of a BIO datagram pair while any
+other BIO call is also in progress to either half of the same BIO datagram pair
+results in undefined behaviour.
+.SH "CAPABILITY INDICATION"
+.IX Header "CAPABILITY INDICATION"
+The BIO datagram pair can be used to enqueue datagrams which have source and
+destination addresses attached. It is important that the component consuming one
+side of a BIO datagram pair understand whether the other side of the pair will
+honour any source and destination addresses it attaches to each datagram. For
+example, if datagrams are queued with destination addresses set but simply read
+by simple calls to \fBBIO_read\fR\|(3), the destination addresses will be discarded.
+.PP
+Each half of a BIO datagram pair can have capability flags set on it which
+indicate whether source and destination addresses will be honoured by the reader
+and whether they will be provided by the writer. These capability flags should
+be set via a call to \fBBIO_dgram_set_caps()\fR, and these capabilities will be
+reflected in the value returned by \fBBIO_dgram_get_effective_caps()\fR on the
+opposite BIO. If necessary, the capability value previously set can be retrieved
+using \fBBIO_dgram_get_caps()\fR. Note that \fBBIO_dgram_set_caps()\fR on a given BIO
+controls the capabilities advertised to the peer, and
+\&\fBBIO_dgram_get_effective_caps()\fR on a given BIO determines the capabilities
+advertised by the peer of that BIO.
+.PP
+The following capabilities are available:
+.IP \fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR 4
+.IX Item "BIO_DGRAM_CAP_HANDLES_SRC_ADDR"
+The user of the datagram pair BIO promises to honour source addresses provided
+with datagrams written to the BIO pair.
+.IP \fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR 4
+.IX Item "BIO_DGRAM_CAP_HANDLES_DST_ADDR"
+The user of the datagram pair BIO promises to honour destination addresses provided
+with datagrams written to the BIO pair.
+.IP \fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR 4
+.IX Item "BIO_DGRAM_CAP_PROVIDES_SRC_ADDR"
+The user of the datagram pair BIO advertises the fact that it will provide source
+addressing information with future writes to the BIO pair, where available.
+.IP \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR 4
+.IX Item "BIO_DGRAM_CAP_PROVIDES_DST_ADDR"
+The user of the datagram pair BIO advertises the fact that it will provide
+destination addressing information with future writes to the BIO pair, where
+available.
+.PP
+If a caller attempts to specify a destination address (for example, using
+\&\fBBIO_sendmmsg\fR\|(3)) and the peer has not advertised the
+\&\fBBIO_DGRAM_CAP_HANDLES_DST_ADDR\fR capability, the operation fails. Thus,
+capability negotiation is mandatory.
+.PP
+If a caller attempts to specify a source address when writing, or requests a
+destination address when receiving, and local address support has not been
+enabled, the operation fails; see \fBBIO_dgram_set_local_addr_enable\fR\|(3).
+.PP
+If a caller attempts to enable local address support using
+\&\fBBIO_dgram_set_local_addr_enable\fR\|(3) and \fBBIO_dgram_get_local_addr_cap\fR\|(3)
+does not return 1 (meaning that the peer has not advertised both the
+\&\fBBIO_DGRAM_CAP_HANDLES_SRC_ADDR\fR and the \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR
+capability), the operation fails.
+.PP
+\&\fBBIO_DGRAM_CAP_PROVIDES_SRC_ADDR\fR and \fBBIO_DGRAM_CAP_PROVIDES_DST_ADDR\fR
+indicate that the application using that half of a BIO datagram pair promises to
+provide source and destination addresses respectively when writing datagrams to
+that half of the BIO datagram pair. However, these capability flags do not
+affect the behaviour of the BIO datagram pair.
+.SH "RETURN VALUES"
+.IX Header "RETURN VALUES"
+\&\fBBIO_new_bio_dgram_pair()\fR returns 1 on success, with the new BIOs available in
+\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with NULL pointers stored into the
+locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information.
+.PP
+\&\fBBIO_dgram_set_no_trunc()\fR, \fBBIO_dgram_set_caps()\fR and \fBBIO_dgram_set_mtu()\fR return 1
+on success and 0 on failure.
+.PP
+\&\fBBIO_dgram_get_no_trunc()\fR returns 1 if no-truncate mode is enabled on a BIO, or 0
+if no-truncate mode is not enabled or not supported on a given BIO.
+.PP
+\&\fBBIO_dgram_get_effective_caps()\fR and \fBBIO_dgram_get_caps()\fR return zero if no
+capabilities are supported.
+.PP
+\&\fBBIO_dgram_get_mtu()\fR returns the MTU value configured on the BIO, or zero if the
+operation is not supported.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBBIO_s_bio\fR\|(3), \fBbio\fR\|(7)
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+<https://www.openssl.org/source/license.html>.