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