1BIO_S_DATAGRAM(3ossl)               OpenSSL              BIO_S_DATAGRAM(3ossl)
2
3
4

NAME

6       BIO_s_datagram, BIO_new_dgram, BIO_ctrl_dgram_connect,
7       BIO_ctrl_set_connected, BIO_dgram_recv_timedout,
8       BIO_dgram_send_timedout, BIO_dgram_get_peer, BIO_dgram_set_peer,
9       BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics
10

SYNOPSIS

12        #include <openssl/bio.h>
13
14        BIO_METHOD *BIO_s_datagram(void);
15        BIO *BIO_new_dgram(int fd, int close_flag);
16
17        int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);
18        int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);
19        int BIO_dgram_recv_timedout(BIO *bio);
20        int BIO_dgram_send_timedout(BIO *bio);
21        int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);
22        int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);
23        int BIO_dgram_get_mtu_overhead(BIO *bio);
24

DESCRIPTION

26       BIO_s_datagram() is a BIO implementation designed for use with network
27       sockets which provide datagram semantics, such as UDP sockets. It is
28       suitable for use with DTLSv1.
29
30       Because BIO_s_datagram() has datagram semantics, a single BIO_write()
31       call sends a single datagram and a single BIO_read() call receives a
32       single datagram. If the size of the buffer passed to BIO_read() is
33       inadequate, the datagram is silently truncated.
34
35       When using BIO_s_datagram(), it is important to note that:
36
37       •   This BIO can be used with either a connected or unconnected network
38           socket. A connected socket is a network socket which has had
39           BIO_connect(3) or a similar OS-specific function called on it. Such
40           a socket can only receive datagrams from the specified peer. Any
41           other socket is an unconnected socket and can receive datagrams
42           from any host.
43
44       •   Despite their naming, neither BIO_ctrl_dgram_connect() nor
45           BIO_ctrl_set_connected() cause a socket to become connected. These
46           controls are provided to indicate to the BIO how the underlying
47           socket is configured and how it is to be used; see below.
48
49       •   Use of BIO_s_datagram() with an unconnected network socket is
50           hazardous hecause any successful call to BIO_read() results in the
51           peer address used for any subsequent call to BIO_write() being set
52           to the source address of the datagram received by that call to
53           BIO_read(). Thus, unless the caller calls BIO_dgram_set_peer()
54           immediately prior to every call to BIO_write(), or never calls
55           BIO_read(), any host on the network may cause future datagrams
56           written to be redirected to that host. Therefore, it is recommended
57           that users use BIO_s_dgram() only with a connected socket. An
58           exception is where DTLSv1_listen(3) must be used; see
59           DTLSv1_listen(3) for further discussion.
60
61       Various controls are available for configuring the BIO_s_datagram()
62       using BIO_ctrl(3):
63
64       BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)
65           This is equivalent to calling BIO_dgram_set_peer(3).
66
67           Despite its name, this function does not cause the underlying
68           socket to become connected.
69
70       BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)
71           This informs the BIO_s_datagram() whether the underlying socket has
72           been connected, and therefore how the BIO_s_datagram() should
73           attempt to use the socket.
74
75           If the peer argument is non-NULL, BIO_s_datagram() assumes that the
76           underlying socket has been connected and will attempt to use the
77           socket using OS APIs which do not specify peer addresses (for
78           example, send(3) and recv(3) or similar). The peer argument should
79           specify the peer address to which the socket is connected.
80
81           If the peer argument is NULL, BIO_s_datagram() assumes that the
82           underlying socket is not connected and will attempt to use the
83           socket using an OS APIs which specify peer addresses (for example,
84           sendto(3) and recvfrom(3)).
85
86       BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)
87           This outputs a BIO_ADDR which specifies one of the following
88           values, whichever happened most recently:
89
90           •   The peer address last passed to BIO_dgram_set_peer(),
91               BIO_ctrl_dgram_connect() or BIO_ctrl_set_connected().
92
93           •   The peer address of the datagram last received by a call to
94               BIO_read().
95
96       BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)
97           Sets the peer address to be used for subsequent writes to this BIO.
98
99           Warning: When used with an unconnected network socket, the value
100           set may be modified by future calls to BIO_read(3), making use of
101           BIO_s_datagram() hazardous when used with unconnected network
102           sockets; see above.
103
104       BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)
105           Returns 1 if the last I/O operation performed on the BIO (for
106           example, via a call to BIO_read(3)) may have been caused by a
107           receive timeout.
108
109       BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)
110           Returns 1 if the last I/O operation performed on the BIO (for
111           example, via a call to BIO_write(3)) may have been caused by a send
112           timeout.
113
114       BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)
115           Returns a quantity in bytes which is a rough estimate of the number
116           of bytes of overhead which should typically be added to a datagram
117           payload size in order to estimate the final size of the Layer 3
118           (e.g. IP) packet which will contain the datagram. In most cases,
119           the maximum datagram payload size which can be transmitted can be
120           determined by determining the link MTU in bytes and subtracting the
121           value returned by this call.
122
123           The value returned by this call depends on the network layer
124           protocol being used.
125
126           The value returned is not fully reliable because datagram overheads
127           can be higher in atypical network configurations, for example where
128           IPv6 extension headers or IPv4 options are used.
129
130       BIO_CTRL_DGRAM_SET_DONT_FRAG
131           If num is nonzero, configures the underlying network socket to
132           enable Don't Fragment mode, in which datagrams will be set with the
133           IP Don't Fragment (DF) bit set. If num is zero, Don't Fragment mode
134           is disabled.
135
136       BIO_CTRL_DGRAM_QUERY_MTU
137           Queries the OS for its assessment of the Path MTU for the
138           destination to which the underlying network socket, and returns
139           that Path MTU in bytes. This control can only be used with a
140           connected socket.
141
142           This is not supported on all platforms and depends on OS support
143           being available. Returns 0 on failure.
144
145       BIO_CTRL_DGRAM_MTU_DISCOVER
146           This control requests that Path MTU discovery be enabled on the
147           underlying network socket.
148
149       BIO_CTRL_DGRAM_GET_FALLBACK_MTU
150           Returns the estimated minimum size of datagram payload which should
151           always be supported on the BIO. This size is determined by the
152           minimum MTU required to be supported by the applicable underlying
153           network layer. Use of datagrams of this size may lead to suboptimal
154           performance, but should be routable in all circumstances. The value
155           returned is the datagram payload size in bytes and does not include
156           the size of layer 3 or layer 4 protocol headers.
157
158       BIO_CTRL_DGRAM_MTU_EXCEEDED
159           Returns 1 if the last attempted write to the BIO failed due to the
160           size of the attempted write exceeding the applicable MTU.
161
162       BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT
163           Accepts a pointer to a struct timeval. If the time specified is
164           zero, disables receive timeouts. Otherwise, configures the
165           specified time interval as the receive timeout for the socket for
166           the purposes of future BIO_read(3) calls.
167
168       BIO_CTRL_DGRAM_SET_PEEK_MODE
169           If num is nonzero, enables peek mode; otherwise, disables peek
170           mode. Where peek mode is enabled, calls to BIO_read(3) read
171           datagrams from the underlying network socket in peek mode, meaning
172           that a future call to BIO_read(3) will yield the same datagram
173           until peek mode is disabled.
174
175       BIO_new_dgram() is a helper function which instantiates a
176       BIO_s_datagram() and sets the BIO to use the socket given in fd by
177       calling BIO_set_fd().
178

RETURN VALUES

180       BIO_s_datagram() returns a BIO method.
181
182       BIO_new_dgram() returns a BIO on success and NULL on failure.
183
184       BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected(),
185       BIO_dgram_get_peer(), BIO_dgram_set_peer() return 1 on success and 0 on
186       failure.
187
188       BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() return 0 or 1
189       depending on the circumstance; see discussion above.
190
191       BIO_dgram_get_mtu_overhead() returns a value in bytes.
192

SEE ALSO

194       DTLSv1_listen(3), bio(7)
195
197       Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
198
199       Licensed under the Apache License 2.0 (the "License").  You may not use
200       this file except in compliance with the License.  You can obtain a copy
201       in the file LICENSE in the source distribution or at
202       <https://www.openssl.org/source/license.html>.
203
204
205
2063.1.1                             2023-08-31             BIO_S_DATAGRAM(3ossl)
Impressum