1=pod 2 3=head1 NAME 4 5BIO_s_datagram, BIO_new_dgram, 6BIO_ctrl_dgram_connect, 7BIO_ctrl_set_connected, 8BIO_dgram_recv_timedout, 9BIO_dgram_send_timedout, 10BIO_dgram_get_peer, 11BIO_dgram_set_peer, 12BIO_dgram_detect_peer_addr, 13BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics 14 15=head1 SYNOPSIS 16 17 #include <openssl/bio.h> 18 19 BIO_METHOD *BIO_s_datagram(void); 20 BIO *BIO_new_dgram(int fd, int close_flag); 21 22 int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer); 23 int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer); 24 int BIO_dgram_recv_timedout(BIO *bio); 25 int BIO_dgram_send_timedout(BIO *bio); 26 int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer); 27 int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer); 28 int BIO_dgram_get_mtu_overhead(BIO *bio); 29 int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer); 30 31=head1 DESCRIPTION 32 33BIO_s_datagram() is a BIO implementation designed for use with network sockets 34which provide datagram semantics, such as UDP sockets. It is suitable for use 35with DTLSv1 or QUIC. 36 37Because BIO_s_datagram() has datagram semantics, a single BIO_write() call sends 38a single datagram and a single BIO_read() call receives a single datagram. If 39the size of the buffer passed to BIO_read() is inadequate, the datagram is 40silently truncated. 41 42For a memory-based BIO which provides datagram semantics identical to those of 43BIO_s_datagram(), see L<BIO_s_dgram_pair(3)>. 44 45This BIO supports the L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> functions. 46 47When using BIO_s_datagram(), it is important to note that: 48 49=over 4 50 51=item 52 53This BIO can be used with either a connected or unconnected network socket. A 54connected socket is a network socket which has had L<BIO_connect(3)> or a 55similar OS-specific function called on it. Such a socket can only receive 56datagrams from the specified peer. Any other socket is an unconnected socket and 57can receive datagrams from any host. 58 59=item 60 61Despite their naming, 62neither BIO_ctrl_dgram_connect() nor BIO_ctrl_set_connected() cause a socket 63to become connected. These controls are provided to indicate to the BIO how 64the underlying socket is configured and how it is to be used; see below. 65 66=item 67 68Use of BIO_s_datagram() with an unconnected network socket is hazardous hecause 69any successful call to BIO_read() results in the peer address used for any 70subsequent call to BIO_write() being set to the source address of the datagram 71received by that call to BIO_read(). Thus, unless the caller calls 72BIO_dgram_set_peer() immediately prior to every call to BIO_write(), or never 73calls BIO_read(), any host on the network may cause future datagrams written to 74be redirected to that host. Therefore, it is recommended that users either use 75BIO_s_dgram() only with a connected socket, or, if using BIO_s_dgram() with an 76unconnected socket, to use the L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> methods 77only and forego use of L<BIO_read(3)> and L<BIO_write(3)>. An exception is where 78L<DTLSv1_listen(3)> must be used; see L<DTLSv1_listen(3)> for further 79discussion. 80 81=item 82 83Unlike L<BIO_read(3)> and L<BIO_write(3)>, the L<BIO_sendmmsg(3)> and 84L<BIO_recvmmsg(3)> methods are stateless and do not cause the internal state of 85the BIO_s_datagram() to change. 86 87=back 88 89Various controls are available for configuring the BIO_s_datagram() using 90L<BIO_ctrl(3)>: 91 92=over 4 93 94=item BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT) 95 96This is equivalent to calling L<BIO_dgram_set_peer(3)>. 97 98Despite its name, this function does not cause the underlying socket to become 99connected. 100 101=item BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED) 102 103This informs the BIO_s_datagram() whether the underlying socket has been 104connected, and therefore how the BIO_s_datagram() should attempt to use the 105socket. 106 107If the I<peer> argument is non-NULL, BIO_s_datagram() assumes that the 108underlying socket has been connected and will attempt to use the socket using OS 109APIs which do not specify peer addresses (for example, send(3) and recv(3) or 110similar). The I<peer> argument should specify the peer address to which the socket 111is connected. 112 113If the I<peer> argument is NULL, BIO_s_datagram() assumes that the underlying 114socket is not connected and will attempt to use the socket using an OS APIs 115which specify peer addresses (for example, sendto(3) and recvfrom(3)). 116 117This control does not affect the operation of L<BIO_sendmmsg(3)> or 118L<BIO_recvmmsg(3)>. 119 120=item BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER) 121 122This outputs a B<BIO_ADDR> which specifies one of the following values, 123whichever happened most recently: 124 125=over 4 126 127=item 128 129The peer address last passed to BIO_dgram_set_peer(), BIO_ctrl_dgram_connect() 130or BIO_ctrl_set_connected(). 131 132=item 133 134The peer address of the datagram last received by a call to BIO_read(). 135 136=back 137 138=item BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER) 139 140Sets the peer address to be used for subsequent writes to this BIO. 141 142Warning: When used with an unconnected network socket, the value set may be 143modified by future calls to L<BIO_read(3)>, making use of BIO_s_datagram() 144hazardous when used with unconnected network sockets; see above. 145 146This does not affect the operation of L<BIO_sendmmsg(3)>. 147L<BIO_recvmmsg(3)> does not affect the value set by BIO_dgram_set_peer(). 148 149=item BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR) 150 151This is similar to BIO_dgram_get_peer() except that if the peer address has not 152been set on the BIO object, an OS call such as getpeername(2) will be attempted 153to try and autodetect the peer address to which the underlying socket is 154connected. Other BIOs may also implement this control if they are capable of 155sensing a peer address, without necessarily also implementing 156BIO_dgram_set_peer() and BIO_dgram_get_peer(). 157 158=item BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP) 159 160Returns 1 if the last I/O operation performed on the BIO (for example, via a 161call to L<BIO_read(3)>) may have been caused by a receive timeout. 162 163=item BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP) 164 165Returns 1 if the last I/O operation performed on the BIO (for example, via a 166call to L<BIO_write(3)>) may have been caused by a send timeout. 167 168=item BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD) 169 170Returns a quantity in bytes which is a rough estimate of the number of bytes of 171overhead which should typically be added to a datagram payload size in order to 172estimate the final size of the Layer 3 (e.g. IP) packet which will contain the 173datagram. In most cases, the maximum datagram payload size which can be 174transmitted can be determined by determining the link MTU in bytes and 175subtracting the value returned by this call. 176 177The value returned by this call depends on the network layer protocol being 178used. 179 180The value returned is not fully reliable because datagram overheads can be 181higher in atypical network configurations, for example where IPv6 extension 182headers or IPv4 options are used. 183 184=item BIO_CTRL_DGRAM_SET_DONT_FRAG 185 186If I<num> is nonzero, configures the underlying network socket to enable Don't 187Fragment mode, in which datagrams will be set with the IP Don't Fragment (DF) 188bit set. If I<num> is zero, Don't Fragment mode is disabled. 189 190=item BIO_CTRL_DGRAM_QUERY_MTU 191 192Queries the OS for its assessment of the Path MTU for the destination to which 193the underlying network socket, and returns that Path MTU in bytes. This control 194can only be used with a connected socket. 195 196This is not supported on all platforms and depends on OS support being 197available. Returns 0 on failure. 198 199=item BIO_CTRL_DGRAM_MTU_DISCOVER 200 201This control requests that Path MTU discovery be enabled on the underlying 202network socket. 203 204=item BIO_CTRL_DGRAM_GET_FALLBACK_MTU 205 206Returns the estimated minimum size of datagram payload which should always be 207supported on the BIO. This size is determined by the minimum MTU required to be 208supported by the applicable underlying network layer. Use of datagrams of this 209size may lead to suboptimal performance, but should be routable in all 210circumstances. The value returned is the datagram payload size in bytes and does 211not include the size of layer 3 or layer 4 protocol headers. 212 213=item BIO_CTRL_DGRAM_MTU_EXCEEDED 214 215Returns 1 if the last attempted write to the BIO failed due to the size of the 216attempted write exceeding the applicable MTU. 217 218=item BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT 219 220Accepts a pointer to a B<struct timeval>. If the time specified is zero, 221disables receive timeouts. Otherwise, configures the specified time interval as 222the receive timeout for the socket for the purposes of future L<BIO_read(3)> 223calls. 224 225=item BIO_CTRL_DGRAM_SET_PEEK_MODE 226 227If B<num> is nonzero, enables peek mode; otherwise, disables peek mode. Where 228peek mode is enabled, calls to L<BIO_read(3)> read datagrams from the underlying 229network socket in peek mode, meaning that a future call to L<BIO_read(3)> will 230yield the same datagram until peek mode is disabled. 231 232L<BIO_recvmmsg(3)> is not affected by this control. 233 234=back 235 236BIO_new_dgram() is a helper function which instantiates a BIO_s_datagram() and 237sets the BIO to use the socket given in I<fd> by calling BIO_set_fd(). 238 239=head1 RETURN VALUES 240 241BIO_s_datagram() returns a BIO method. 242 243BIO_new_dgram() returns a BIO on success and NULL on failure. 244 245BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected() and BIO_dgram_set_peer() 246return 1 on success and 0 on failure. 247 248BIO_dgram_get_peer() and BIO_dgram_detect_peer_addr() return 0 on failure and 249the number of bytes for the outputted address representation (a positive value) 250on success. 251 252BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() return 0 or 1 depending 253on the circumstance; see discussion above. 254 255BIO_dgram_get_mtu_overhead() returns a value in bytes. 256 257=head1 SEE ALSO 258 259L<BIO_sendmmsg(3)>, L<BIO_s_dgram_pair(3)>, L<DTLSv1_listen(3)>, L<bio(7)> 260 261=head1 COPYRIGHT 262 263Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved. 264 265Licensed under the Apache License 2.0 (the "License"). You may not use 266this file except in compliance with the License. You can obtain a copy 267in the file LICENSE in the source distribution or at 268L<https://www.openssl.org/source/license.html>. 269 270=cut 271