1=pod 2 3=head1 NAME 4 5BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc, 6BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps, 7BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu, 8BIO_dgram_set0_local_addr - datagram pair BIO 9 10=head1 SYNOPSIS 11 12 #include <openssl/bio.h> 13 14 const BIO_METHOD *BIO_s_dgram_pair(void); 15 16 int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1, 17 BIO **bio2, size_t writebuf2); 18 int BIO_dgram_set_no_trunc(BIO *bio, int enable); 19 int BIO_dgram_get_no_trunc(BIO *bio); 20 uint32_t BIO_dgram_get_effective_caps(BIO *bio); 21 uint32_t BIO_dgram_get_caps(BIO *bio); 22 int BIO_dgram_set_caps(BIO *bio, uint32_t caps); 23 int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu); 24 unsigned int BIO_dgram_get_mtu(BIO *bio); 25 int BIO_dgram_set0_local_addr(BIO *bio, BIO_ADDR *addr); 26 27=head1 DESCRIPTION 28 29BIO_s_dgram_pair() returns the method for a BIO datagram pair. A BIO datagram 30pair is similar to a BIO pair (see L<BIO_s_bio(3)>) but has datagram semantics. 31Broadly, this means that the length of the buffer passed to a write call will 32match that retrieved by a read call. If the buffer passed to a read call is too 33short, the datagram is truncated or the read fails, depending on how the BIO is 34configured. 35 36The BIO datagram pair attaches certain metadata to each write, such as source 37and destination addresses. This information may be retrieved on read. 38 39A typical application of a BIO datagram pair is to allow an application to keep 40all datagram network I/O requested by libssl under application control. 41 42The BIO datagram pair is designed to support multithreaded use where certain 43restrictions are observed; see THREADING. 44 45The BIO datagram pair allows each half of a pair to signal to the other half 46whether they support certain capabilities; see CAPABILITY INDICATION. 47 48BIO_new_bio_dgram_pair() combines the calls to L<BIO_new(3)>, 49L<BIO_make_bio_pair(3)> and L<BIO_set_write_buf_size(3)> to create a connected 50pair of BIOs B<bio1>, B<bio2> with write buffer sizes B<writebuf1> and 51B<writebuf2>. If either size is zero then the default size is used. 52 53L<BIO_make_bio_pair(3)> may be used to join two datagram pair BIOs into a pair. 54The two BIOs must both use the method returned by BIO_s_dgram_pair() and neither 55of the BIOs may currently be associated in a pair. 56 57L<BIO_destroy_bio_pair(3)> destroys the association between two connected BIOs. 58Freeing either half of the pair will automatically destroy the association. 59 60L<BIO_reset(3)> clears any data in the write buffer of the given BIO. This means 61that the opposite BIO in the pair will no longer have any data waiting to be 62read. 63 64The BIO maintains a fixed size internal write buffer. When the buffer is full, 65further writes will fail until the buffer is drained via calls to 66L<BIO_read(3)>. The size of the buffer can be changed using 67L<BIO_set_write_buf_size(3)> and queried using L<BIO_get_write_buf_size(3)>. 68 69Note that the write buffer is partially consumed by metadata stored internally 70which is attached to each datagram, such as source and destination addresses. 71The size of this overhead is undefined and may change between releases. 72 73The standard L<BIO_ctrl_pending(3)> call has modified behaviour and returns the 74size of the next datagram waiting to be read in bytes. An application can use 75this function to ensure it provides an adequate buffer to a subsequent read 76call. If no datagram is waiting to be read, zero is returned. 77 78This BIO does not support sending or receiving zero-length datagrams. Passing a 79zero-length buffer to BIO_write is treated as a no-op. 80 81L<BIO_eof(3)> returns 1 only if the given BIO datagram pair BIO is not currently 82connected to a peer BIO. 83 84L<BIO_get_write_guarantee(3)> and L<BIO_ctrl_get_write_guarantee(3)> return how 85large a datagram the next call to L<BIO_write(3)> can accept. If there is not 86enough space in the write buffer to accept another datagram equal in size to the 87configured MTU, zero is returned (see below). This is intended to avoid a 88situation where an application attempts to read a datagram from a network 89intending to write it to a BIO datagram pair, but where the received datagram 90ends up being too large to write to the BIO datagram pair. 91 92BIO_dgram_set_no_trunc() and BIO_ctrl_get_no_trunc() set and retrieve the 93truncation mode for the given half of a BIO datagram pair. When no-truncate mode 94is enabled, BIO_read() will fail if the buffer provided is inadequate to hold 95the next datagram to be read. If no-truncate mode is disabled (the default), the 96datagram will be silently truncated. This default behaviour maintains 97compatibility with the semantics of the Berkeley sockets API. 98 99BIO_dgram_set_mtu() and BIO_dgram_get_mtu() may be used to set an informational 100MTU value on the BIO datagram pair. If BIO_dgram_set_mtu() is used on a BIO 101which is currently part of a BIO datagram pair, the MTU value is set on both 102halves of the pair. The value does not affect the operation of the BIO datagram 103pair (except for BIO_get_write_guarantee(); see above) but may be used by other 104code to determine a requested MTU. When a BIO datagram pair BIO is created, the 105MTU is set to an unspecified but valid value. 106 107BIO_dgram_set0_local_addr() can be used to set the local BIO_ADDR to be used 108when sending a datagram via a BIO datagram pair. This becomes the peer address 109when receiving on the other half of the pair. If the BIO is used in a call to 110L<BIO_sendmmsg(3)> and a local address is explicitly specified, then the 111explicitly specified local address takes precedence. The reference to the 112BIO_ADDR is passed to the BIO by this call and will be freed automatically when 113the BIO is freed. 114 115L<BIO_flush(3)> is a no-op. 116 117=head1 NOTES 118 119The halves of a BIO datagram pair have independent lifetimes and must be 120separately freed. 121 122=head1 THREADING 123 124L<BIO_recvmmsg(3)>, L<BIO_sendmmsg(3)>, L<BIO_read(3)>, L<BIO_write(3)>, 125L<BIO_pending(3)>, L<BIO_get_write_guarantee(3)> and L<BIO_flush(3)> may be used 126by multiple threads simultaneously on the same BIO datagram pair. Specific 127L<BIO_ctrl(3)> operations (namely BIO_CTRL_PENDING, BIO_CTRL_FLUSH and 128BIO_C_GET_WRITE_GUARANTEE) may also be used. Invoking any other BIO call, or any 129other L<BIO_ctrl(3)> operation, on either half of a BIO datagram pair while any 130other BIO call is also in progress to either half of the same BIO datagram pair 131results in undefined behaviour. 132 133=head1 CAPABILITY INDICATION 134 135The BIO datagram pair can be used to enqueue datagrams which have source and 136destination addresses attached. It is important that the component consuming one 137side of a BIO datagram pair understand whether the other side of the pair will 138honour any source and destination addresses it attaches to each datagram. For 139example, if datagrams are queued with destination addresses set but simply read 140by simple calls to L<BIO_read(3)>, the destination addresses will be discarded. 141 142Each half of a BIO datagram pair can have capability flags set on it which 143indicate whether source and destination addresses will be honoured by the reader 144and whether they will be provided by the writer. These capability flags should 145be set via a call to BIO_dgram_set_caps(), and these capabilities will be 146reflected in the value returned by BIO_dgram_get_effective_caps() on the 147opposite BIO. If necessary, the capability value previously set can be retrieved 148using BIO_dgram_get_caps(). Note that BIO_dgram_set_caps() on a given BIO 149controls the capabilities advertised to the peer, and 150BIO_dgram_get_effective_caps() on a given BIO determines the capabilities 151advertised by the peer of that BIO. 152 153The following capabilities are available: 154 155=over 4 156 157=item B<BIO_DGRAM_CAP_HANDLES_SRC_ADDR> 158 159The user of the datagram pair BIO promises to honour source addresses provided 160with datagrams written to the BIO pair. 161 162=item B<BIO_DGRAM_CAP_HANDLES_DST_ADDR> 163 164The user of the datagram pair BIO promises to honour destination addresses provided 165with datagrams written to the BIO pair. 166 167=item B<BIO_DGRAM_CAP_PROVIDES_SRC_ADDR> 168 169The user of the datagram pair BIO advertises the fact that it will provide source 170addressing information with future writes to the BIO pair, where available. 171 172=item B<BIO_DGRAM_CAP_PROVIDES_DST_ADDR> 173 174The user of the datagram pair BIO advertises the fact that it will provide 175destination addressing information with future writes to the BIO pair, where 176available. 177 178=back 179 180If a caller attempts to specify a destination address (for example, using 181L<BIO_sendmmsg(3)>) and the peer has not advertised the 182B<BIO_DGRAM_CAP_HANDLES_DST_ADDR> capability, the operation fails. Thus, 183capability negotiation is mandatory. 184 185If a caller attempts to specify a source address when writing, or requests a 186destination address when receiving, and local address support has not been 187enabled, the operation fails; see L<BIO_dgram_set_local_addr_enable(3)>. 188 189If a caller attempts to enable local address support using 190L<BIO_dgram_set_local_addr_enable(3)> and L<BIO_dgram_get_local_addr_cap(3)> 191does not return 1 (meaning that the peer has not advertised both the 192B<BIO_DGRAM_CAP_HANDLES_SRC_ADDR> and the B<BIO_DGRAM_CAP_PROVIDES_DST_ADDR> 193capability), the operation fails. 194 195B<BIO_DGRAM_CAP_PROVIDES_SRC_ADDR> and B<BIO_DGRAM_CAP_PROVIDES_DST_ADDR> 196indicate that the application using that half of a BIO datagram pair promises to 197provide source and destination addresses respectively when writing datagrams to 198that half of the BIO datagram pair. However, these capability flags do not 199affect the behaviour of the BIO datagram pair. 200 201=head1 RETURN VALUES 202 203BIO_new_bio_dgram_pair() returns 1 on success, with the new BIOs available in 204B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the 205locations for B<bio1> and B<bio2>. Check the error stack for more information. 206 207BIO_dgram_set_no_trunc(), BIO_dgram_set_caps() and BIO_dgram_set_mtu() return 1 208on success and 0 on failure. 209 210BIO_dgram_get_no_trunc() returns 1 if no-truncate mode is enabled on a BIO, or 0 211if no-truncate mode is not enabled or not supported on a given BIO. 212 213BIO_dgram_get_effective_caps() and BIO_dgram_get_caps() return zero if no 214capabilities are supported. 215 216BIO_dgram_get_mtu() returns the MTU value configured on the BIO, or zero if the 217operation is not supported. 218 219BIO_dgram_set0_local_addr() returns 1 on success and <= 0 otherwise. 220 221=head1 SEE ALSO 222 223L<BIO_s_bio(3)>, L<bio(7)> 224 225=head1 HISTORY 226 227BIO_s_dgram_pair(), BIO_new_bio_dgram_pair() were added in OpenSSL 3.2. 228 229=head1 COPYRIGHT 230 231Copyright 2022-2025 The OpenSSL Project Authors. All Rights Reserved. 232 233Licensed under the Apache License 2.0 (the "License"). You may not use 234this file except in compliance with the License. You can obtain a copy 235in the file LICENSE in the source distribution or at 236L<https://www.openssl.org/source/license.html>. 237 238=cut 239