Lines Matching refs:to
4 We need to evolve the API surface of BIO which is relevant to BIO_dgram (and the
5 eventual BIO_dgram_mem) to support APIs which allow multiple datagrams to be
22 - It ensures portability between OSes and allows the API to be used
25 - It allows us to use structures in keeping with OpenSSL's existing
28 - We do not have to expose functionality which we cannot guarantee
31 - It avoids the need to include OS headers in our own public headers,
36 calls to `sendmsg`. For OSes which do not support `sendmsg`, we emulate it
37 using `sendto` to the extent feasible. This avoids the need for code consuming
38 these new APIs to define a fallback code path.
45 ABI compatibility using a `stride` argument which callers must set to
46 `sizeof(BIO_MSG)`. Implementations can examine the stride field to determine
47 whether a given field is part of a `BIO_MSG`. This allows us to add optional
48 fields to `BIO_MSG` at a later time without breaking ABI. All new fields must
49 be added to the end of the structure.
51 - The BIO methods are designed to support stateless operation in which they
52 are simply calls to the equivalent system calls, where supported, without
56 The motivation for this is that these functions are intended to support
58 need to be synchronised with a lock, undermining performance on what (for
66 them is by copying the data to be sent into a staging buffer. This would
68 zero/single-copy requirements. Moreover, it would lead to extremely
71 - We do not believe iovecs are needed to meet our performance requirements
75 and there is not going to be any issue depositing the ciphertext in a
78 - Even if we did support iovecs, we would have to impose a limit
80 structures (as discussed above) and also intend these functions to be
82 would need to be allocated on the stack.
84 - Sometimes, an application may wish to learn the local interface address
85 associated with a receive operation or specify the local interface address to
87 to be explicitly enabled before use.
91 this on-demand would require state in the BIO to determine whether this
94 on a given BIO. By requiring this functionality to be enabled explicitly
95 before use, this allows this initialization to be done up front without
96 performance cost. It also aids users of the API to understand that this
97 functionality is not always available and to detect when this functionality is
123 - `msg` points to an array of `num_msg` `BIO_MSG` structures.
126 processed in the array. If no messages were sent due to an error, `-1` is
132 - `stride` must be set to `sizeof(BIO_MSG)`.
134 - `data` points to the buffer of data to be sent or to be filled with received
138 to the actual amount of data sent or received at return time.
140 - `flags` in the `BIO_MSG` structure provides per-message flags to
143 time. The `flags` argument to the call itself provides for global flags
145 are defined and all of these fields are set to zero on call and on return.
147 - `peer` and `local` are optional pointers to `BIO_ADDR` structures into
148 which the remote and local addresses are to be filled. If either of these
155 attempts to use it fail.
176 This design was chosen to form the basis of the adopted design, which is
188 structures through to the syscall without copying them.
190 Note that in `BIO_mem_dgram` we will have to process and therefore understand
208 - We would need to include the OS headers which provide these
211 - If we choose to support these functions when OS support is not available
212 (see discussion below), We would need to define our own structures in this
217 - We would need to translate these structures during every call.
219 But we would need to have storage inside the BIO_dgram for *m* `struct
220 msghdr`, *m\*v* iovecs, etc. Since we want to support multithreaded use
221 these allocations probably will need to be on the stack, and therefore
225 of messages sent, so the existing semantics we are trying to match
226 lets us just send or receive fewer messages than we were asked to.
228 However, it does seem like we will need to limit *v*, the number of iovecs
229 per message. So what limit should we give to *v*, the number of iovecs? We
241 If the first message passed to a call to `BIO_writem` has 64 iovecs
242 attached to it, no further messages can be sent and `BIO_writem`
248 So the only important thing we would need to document in this API
251 guarantee is to be made. e.g. if we allocate 64 iovecs internally,
256 iovecs are small, so we can afford to set the limit high enough
259 it later. So we might want to start with something small, like 8.
261 - We also need to decide what to do for OSes which don't support at least
264 - Don't provide these functions and require all users of these functions to
269 complexity to code using BIO_dgram. (Though it does communicate
270 to code more realistic performance expectations since it
275 - However there is a question here as to how we implement
278 implementing these would then have to be done by copying buffers around
280 iovecs and providing a performance profile which is surprising to code
287 BIO_dgram, but it seems the only way to avoid the surprising performance
288 pitfall of buffer copying to emulate iovec support. There is a fair risk
292 BIO_dgram which is 1 by default, which can be increased by a call to a
295 code a clear way to determine if its expectations are met.
303 The problem here is we want to support “single-copy” (where the data is only
304 copied as it is decrypted). Thus BIO_dgram needs to know the final resting place
307 One option would be to allow the user to set a callback on BIO_dgram it can use
308 to request a new buffer, then have an API which returns the buffer:
322 The BIO_dgram calls the specified callback when it needs to generate internal
325 used in rare circumstances, such as when calls to `BIO_read` and
326 `BIO_read_dequeue` are alternated, or when the BIO_dgram is destroyed prior to
328 extra call to allow a buffer to be pushed back into the BIO_dgram's internal
329 queue of unused read buffers, which avoids the need for the application to do
338 call is made when calling `BIO_flush`. (TBD: whether it is reasonable to
352 The status argument to the write done callback will be 1 on success, some
362 This approach allows `BIO_dgram` to support myriad options via composition of
364 call with an excessive number of arguments or pointers to unwieldy ever-growing
373 to separate these as there is no need for a getter for outgoing packet
386 anyway. Otherwise we will need another piece to do basically the same thing
396 - Very different way of doing reads/writes might be strange to existing
412 a. Use `recvmmsg` and add the received datagrams to an RX queue just as for the
414 (`OPENSSL_malloc`) and flag these datagrams as needing to be freed by OpenSSL,
423 The disadvantage of (a) is it yields an extra copy relative to what we have now,
424 whereas with (b) the buffer passed to `BIO_read` gets passed through to the
425 syscall and we do not have to copy anything.
427 Since we will probably need to support platforms without
430 For (2) the new API is used. Since the previous call to BIO_read is essentially
431 “stateless” (it's just a simple call to `recvfrom`, and doesn't require mutation
438 RX queue. In this case we do have to copy - we have no choice. However this only
442 Subsequently for (3) we have to free the buffer using the free callback. This is
445 But since this seems a very strange API usage pattern, we may just want to fail
450 - After the first call to `BIO_read_dequeue` is made on a BIO_dgram, all
451 subsequent calls to ordinary `BIO_read` will fail.
453 Of course, all of the above applies analogously to the TX side.
458 BIO pair which provides identical semantics to the BIO_dgram above, both for the
463 It is a functional assumption of the above design that we would never want to
467 If we did ever want to do this, multiple BIOs on the same FD is one possibility
469 intention to support multithreaded use of a single BIO at this time (unless I am
472 If we wanted to support multithreaded use of the same FD using the same BIO, we
473 would need to revisit the set-call-then-execute-call API approach above
480 BIO_dgram will call the allocation function to get buffers for `recvmmsg` to
481 fill. We might want to have a way to specify how many buffers it should offer to
487 callback is used to free any unreturned read buffers.
