Debian Codegraph @

upstream/debian-unstable/man3/BIO_s_datagram.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_S_DATAGRAM 3SSL"
58 .TH BIO_S_DATAGRAM 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_s_datagram, BIO_new_dgram,
65 BIO_ctrl_dgram_connect,
66 BIO_ctrl_set_connected,
67 BIO_dgram_recv_timedout,
68 BIO_dgram_send_timedout,
69 BIO_dgram_get_peer,
70 BIO_dgram_set_peer,
71 BIO_dgram_detect_peer_addr,
72 BIO_dgram_get_mtu_overhead \- Network BIO with datagram semantics
73 .SH SYNOPSIS
74 .IX Header "SYNOPSIS"
75 .Vb 1
76 \& #include <openssl/bio.h>
77 \&
78 \& BIO_METHOD *BIO_s_datagram(void);
79 \& BIO *BIO_new_dgram(int fd, int close_flag);
80 \&
81 \& int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);
82 \& int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);
83 \& int BIO_dgram_recv_timedout(BIO *bio);
84 \& int BIO_dgram_send_timedout(BIO *bio);
85 \& int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);
86 \& int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);
87 \& int BIO_dgram_get_mtu_overhead(BIO *bio);
88 \& int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 \&\fBBIO_s_datagram()\fR is a BIO implementation designed for use with network sockets
93 which provide datagram semantics, such as UDP sockets. It is suitable for use
94 with DTLSv1 or QUIC.
95 .PP
96 Because \fBBIO_s_datagram()\fR has datagram semantics, a single \fBBIO_write()\fR call sends
97 a single datagram and a single \fBBIO_read()\fR call receives a single datagram. If
98 the size of the buffer passed to \fBBIO_read()\fR is inadequate, the datagram is
99 silently truncated.
100 .PP
101 For a memory-based BIO which provides datagram semantics identical to those of
102 \&\fBBIO_s_datagram()\fR, see \fBBIO_s_dgram_pair\fR\|(3).
103 .PP
104 This BIO supports the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) functions.
105 .PP
106 When using \fBBIO_s_datagram()\fR, it is important to note that:
107 .IP \(bu 4
108 This BIO can be used with either a connected or unconnected network socket. A
109 connected socket is a network socket which has had \fBBIO_connect\fR\|(3) or a
110 similar OS-specific function called on it. Such a socket can only receive
111 datagrams from the specified peer. Any other socket is an unconnected socket and
112 can receive datagrams from any host.
113 .IP \(bu 4
114 Despite their naming,
115 neither \fBBIO_ctrl_dgram_connect()\fR nor \fBBIO_ctrl_set_connected()\fR cause a socket
116 to become connected. These controls are provided to indicate to the BIO how
117 the underlying socket is configured and how it is to be used; see below.
118 .IP \(bu 4
119 Use of \fBBIO_s_datagram()\fR with an unconnected network socket is hazardous hecause
120 any successful call to \fBBIO_read()\fR results in the peer address used for any
121 subsequent call to \fBBIO_write()\fR being set to the source address of the datagram
122 received by that call to \fBBIO_read()\fR. Thus, unless the caller calls
123 \&\fBBIO_dgram_set_peer()\fR immediately prior to every call to \fBBIO_write()\fR, or never
124 calls \fBBIO_read()\fR, any host on the network may cause future datagrams written to
125 be redirected to that host. Therefore, it is recommended that users either use
126 \&\fBBIO_s_dgram()\fR only with a connected socket, or, if using \fBBIO_s_dgram()\fR with an
127 unconnected socket, to use the \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) methods
128 only and forego use of \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3). An exception is where
129 \&\fBDTLSv1_listen\fR\|(3) must be used; see \fBDTLSv1_listen\fR\|(3) for further
130 discussion.
131 .IP \(bu 4
132 Unlike \fBBIO_read\fR\|(3) and \fBBIO_write\fR\|(3), the \fBBIO_sendmmsg\fR\|(3) and
133 \&\fBBIO_recvmmsg\fR\|(3) methods are stateless and do not cause the internal state of
134 the \fBBIO_s_datagram()\fR to change.
135 .PP
136 Various controls are available for configuring the \fBBIO_s_datagram()\fR using
137 \&\fBBIO_ctrl\fR\|(3):
138 .IP "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)" 4
139 .IX Item "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)"
140 This is equivalent to calling \fBBIO_dgram_set_peer\fR\|(3).
141 .Sp
142 Despite its name, this function does not cause the underlying socket to become
143 connected.
144 .IP "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)" 4
145 .IX Item "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)"
146 This informs the \fBBIO_s_datagram()\fR whether the underlying socket has been
147 connected, and therefore how the \fBBIO_s_datagram()\fR should attempt to use the
148 socket.
149 .Sp
150 If the \fIpeer\fR argument is non-NULL, \fBBIO_s_datagram()\fR assumes that the
151 underlying socket has been connected and will attempt to use the socket using OS
152 APIs which do not specify peer addresses (for example, \fBsend\fR\|(3) and \fBrecv\fR\|(3) or
153 similar). The \fIpeer\fR argument should specify the peer address to which the socket
154 is connected.
155 .Sp
156 If the \fIpeer\fR argument is NULL, \fBBIO_s_datagram()\fR assumes that the underlying
157 socket is not connected and will attempt to use the socket using an OS APIs
158 which specify peer addresses (for example, \fBsendto\fR\|(3) and \fBrecvfrom\fR\|(3)).
159 .Sp
160 This control does not affect the operation of \fBBIO_sendmmsg\fR\|(3) or
161 \&\fBBIO_recvmmsg\fR\|(3).
162 .IP "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)" 4
163 .IX Item "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)"
164 This outputs a \fBBIO_ADDR\fR which specifies one of the following values,
165 whichever happened most recently:
166 .RS 4
167 .IP \(bu 4
168 The peer address last passed to \fBBIO_dgram_set_peer()\fR, \fBBIO_ctrl_dgram_connect()\fR
169 or \fBBIO_ctrl_set_connected()\fR.
170 .IP \(bu 4
171 The peer address of the datagram last received by a call to \fBBIO_read()\fR.
172 .RE
173 .RS 4
174 .RE
175 .IP "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)" 4
176 .IX Item "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)"
177 Sets the peer address to be used for subsequent writes to this BIO.
178 .Sp
179 Warning: When used with an unconnected network socket, the value set may be
180 modified by future calls to \fBBIO_read\fR\|(3), making use of \fBBIO_s_datagram()\fR
181 hazardous when used with unconnected network sockets; see above.
182 .Sp
183 This does not affect the operation of \fBBIO_sendmmsg\fR\|(3).
184 \&\fBBIO_recvmmsg\fR\|(3) does not affect the value set by \fBBIO_dgram_set_peer()\fR.
185 .IP "BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)" 4
186 .IX Item "BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)"
187 This is similar to \fBBIO_dgram_get_peer()\fR except that if the peer address has not
188 been set on the BIO object, an OS call such as \fBgetpeername\fR\|(2) will be attempted
189 to try and autodetect the peer address to which the underlying socket is
190 connected. Other BIOs may also implement this control if they are capable of
191 sensing a peer address, without necessarily also implementing
192 \&\fBBIO_dgram_set_peer()\fR and \fBBIO_dgram_get_peer()\fR.
193 .IP "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)" 4
194 .IX Item "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)"
195 Returns 1 if the last I/O operation performed on the BIO (for example, via a
196 call to \fBBIO_read\fR\|(3)) may have been caused by a receive timeout.
197 .IP "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)" 4
198 .IX Item "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)"
199 Returns 1 if the last I/O operation performed on the BIO (for example, via a
200 call to \fBBIO_write\fR\|(3)) may have been caused by a send timeout.
201 .IP "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)" 4
202 .IX Item "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)"
203 Returns a quantity in bytes which is a rough estimate of the number of bytes of
204 overhead which should typically be added to a datagram payload size in order to
205 estimate the final size of the Layer 3 (e.g. IP) packet which will contain the
206 datagram. In most cases, the maximum datagram payload size which can be
207 transmitted can be determined by determining the link MTU in bytes and
208 subtracting the value returned by this call.
209 .Sp
210 The value returned by this call depends on the network layer protocol being
211 used.
212 .Sp
213 The value returned is not fully reliable because datagram overheads can be
214 higher in atypical network configurations, for example where IPv6 extension
215 headers or IPv4 options are used.
216 .IP BIO_CTRL_DGRAM_SET_DONT_FRAG 4
217 .IX Item "BIO_CTRL_DGRAM_SET_DONT_FRAG"
218 If \fInum\fR is nonzero, configures the underlying network socket to enable Don't
219 Fragment mode, in which datagrams will be set with the IP Don't Fragment (DF)
220 bit set. If \fInum\fR is zero, Don't Fragment mode is disabled.
221 .IP BIO_CTRL_DGRAM_QUERY_MTU 4
222 .IX Item "BIO_CTRL_DGRAM_QUERY_MTU"
223 Queries the OS for its assessment of the Path MTU for the destination to which
224 the underlying network socket, and returns that Path MTU in bytes. This control
225 can only be used with a connected socket.
226 .Sp
227 This is not supported on all platforms and depends on OS support being
228 available. Returns 0 on failure.
229 .IP BIO_CTRL_DGRAM_MTU_DISCOVER 4
230 .IX Item "BIO_CTRL_DGRAM_MTU_DISCOVER"
231 This control requests that Path MTU discovery be enabled on the underlying
232 network socket.
233 .IP BIO_CTRL_DGRAM_GET_FALLBACK_MTU 4
234 .IX Item "BIO_CTRL_DGRAM_GET_FALLBACK_MTU"
235 Returns the estimated minimum size of datagram payload which should always be
236 supported on the BIO. This size is determined by the minimum MTU required to be
237 supported by the applicable underlying network layer. Use of datagrams of this
238 size may lead to suboptimal performance, but should be routable in all
239 circumstances. The value returned is the datagram payload size in bytes and does
240 not include the size of layer 3 or layer 4 protocol headers.
241 .IP BIO_CTRL_DGRAM_MTU_EXCEEDED 4
242 .IX Item "BIO_CTRL_DGRAM_MTU_EXCEEDED"
243 Returns 1 if the last attempted write to the BIO failed due to the size of the
244 attempted write exceeding the applicable MTU.
245 .IP BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT 4
246 .IX Item "BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT"
247 Accepts a pointer to a \fBstruct timeval\fR. If the time specified is zero,
248 disables receive timeouts. Otherwise, configures the specified time interval as
249 the receive timeout for the socket for the purposes of future \fBBIO_read\fR\|(3)
250 calls.
251 .IP BIO_CTRL_DGRAM_SET_PEEK_MODE 4
252 .IX Item "BIO_CTRL_DGRAM_SET_PEEK_MODE"
253 If \fBnum\fR is nonzero, enables peek mode; otherwise, disables peek mode. Where
254 peek mode is enabled, calls to \fBBIO_read\fR\|(3) read datagrams from the underlying
255 network socket in peek mode, meaning that a future call to \fBBIO_read\fR\|(3) will
256 yield the same datagram until peek mode is disabled.
257 .Sp
258 \&\fBBIO_recvmmsg\fR\|(3) is not affected by this control.
259 .PP
260 \&\fBBIO_new_dgram()\fR is a helper function which instantiates a \fBBIO_s_datagram()\fR and
261 sets the BIO to use the socket given in \fIfd\fR by calling \fBBIO_set_fd()\fR.
262 .SH "RETURN VALUES"
263 .IX Header "RETURN VALUES"
264 \&\fBBIO_s_datagram()\fR returns a BIO method.
265 .PP
266 \&\fBBIO_new_dgram()\fR returns a BIO on success and NULL on failure.
267 .PP
268 \&\fBBIO_ctrl_dgram_connect()\fR, \fBBIO_ctrl_set_connected()\fR and \fBBIO_dgram_set_peer()\fR
269 return 1 on success and 0 on failure.
270 .PP
271 \&\fBBIO_dgram_get_peer()\fR and \fBBIO_dgram_detect_peer_addr()\fR return 0 on failure and
272 the number of bytes for the outputted address representation (a positive value)
273 on success.
274 .PP
275 \&\fBBIO_dgram_recv_timedout()\fR and \fBBIO_dgram_send_timedout()\fR return 0 or 1 depending
276 on the circumstance; see discussion above.
277 .PP
278 \&\fBBIO_dgram_get_mtu_overhead()\fR returns a value in bytes.
279 .SH "SEE ALSO"
280 .IX Header "SEE ALSO"
281 \&\fBBIO_sendmmsg\fR\|(3), \fBBIO_s_dgram_pair\fR\|(3), \fBDTLSv1_listen\fR\|(3), \fBbio\fR\|(7)
282 .SH HISTORY
283 .IX Header "HISTORY"
284 \&\fBBIO_dgram_detect_peer_addr()\fR was added in OpenSSL 3.2.
285 .SH COPYRIGHT
286 .IX Header "COPYRIGHT"
287 Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved.
288 .PP
289 Licensed under the Apache License 2.0 (the "License"). You may not use
290 this file except in compliance with the License. You can obtain a copy
291 in the file LICENSE in the source distribution or at
292 <https://www.openssl.org/source/license.html>.