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