doc/man3/BIO_s_dgram_pair.pod

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