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