2024-02-02 20:24:24 +08:00
|
|
|
=pod
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
|
|
|
SSL_poll,
|
|
|
|
SSL_POLL_EVENT_NONE,
|
|
|
|
SSL_POLL_EVENT_F,
|
|
|
|
SSL_POLL_EVENT_EC,
|
|
|
|
SSL_POLL_EVENT_ECD,
|
|
|
|
SSL_POLL_EVENT_ER,
|
|
|
|
SSL_POLL_EVENT_EW,
|
|
|
|
SSL_POLL_EVENT_R,
|
|
|
|
SSL_POLL_EVENT_W,
|
|
|
|
SSL_POLL_EVENT_ISB,
|
|
|
|
SSL_POLL_EVENT_ISU,
|
|
|
|
SSL_POLL_EVENT_OSB,
|
|
|
|
SSL_POLL_EVENT_OSU,
|
|
|
|
SSL_POLL_EVENT_RW,
|
|
|
|
SSL_POLL_EVENT_RE,
|
|
|
|
SSL_POLL_EVENT_WE,
|
|
|
|
SSL_POLL_EVENT_RWE,
|
|
|
|
SSL_POLL_EVENT_E,
|
|
|
|
SSL_POLL_EVENT_IS,
|
|
|
|
SSL_POLL_EVENT_ISE,
|
|
|
|
SSL_POLL_EVENT_I,
|
|
|
|
SSL_POLL_EVENT_OS,
|
|
|
|
SSL_POLL_EVENT_OSE,
|
|
|
|
SSL_POLL_FLAG_NO_HANDLE_EVENTS
|
|
|
|
- determine or await readiness conditions for one or more pollable objects
|
|
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
|
|
|
|
#define SSL_POLL_EVENT_NONE 0
|
|
|
|
|
|
|
|
#define SSL_POLL_EVENT_F /* F (Failure) */
|
|
|
|
#define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */
|
|
|
|
#define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */
|
|
|
|
#define SSL_POLL_EVENT_ER /* ER (Exception on Read) */
|
|
|
|
#define SSL_POLL_EVENT_EW /* EW (Exception on Write) */
|
|
|
|
#define SSL_POLL_EVENT_R /* R (Readable) */
|
|
|
|
#define SSL_POLL_EVENT_W /* W (Writable) */
|
|
|
|
#define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */
|
|
|
|
#define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */
|
|
|
|
#define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */
|
|
|
|
#define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */
|
|
|
|
|
|
|
|
#define SSL_POLL_EVENT_RW /* R | W */
|
|
|
|
#define SSL_POLL_EVENT_RE /* R | ER */
|
|
|
|
#define SSL_POLL_EVENT_WE /* W | EW */
|
|
|
|
#define SSL_POLL_EVENT_RWE /* RE | WE */
|
|
|
|
#define SSL_POLL_EVENT_E /* EC | ER | EW */
|
|
|
|
#define SSL_POLL_EVENT_IS /* ISB | ISU */
|
|
|
|
#define SSL_POLL_EVENT_ISE /* IS | EC */
|
|
|
|
#define SSL_POLL_EVENT_I /* IS */
|
|
|
|
#define SSL_POLL_EVENT_OS /* OSB | OSU */
|
|
|
|
#define SSL_POLL_EVENT_OSE /* OS | EC */
|
|
|
|
|
|
|
|
typedef struct ssl_poll_item_st {
|
|
|
|
BIO_POLL_DESCRIPTOR desc;
|
|
|
|
uint64_t events, revents;
|
|
|
|
} SSL_POLL_ITEM;
|
|
|
|
|
|
|
|
#define SSL_POLL_FLAG_NO_HANDLE_EVENTS
|
|
|
|
|
|
|
|
int SSL_poll(SSL_POLL_ITEM *items,
|
|
|
|
size_t num_items,
|
|
|
|
size_t stride,
|
|
|
|
const struct timeval *timeout,
|
|
|
|
uint64_t flags,
|
|
|
|
size_t *result_count);
|
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
|
|
SSL_poll() allows the readiness conditions of the resources represented by one
|
|
|
|
or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can
|
|
|
|
be used to query for readiness conditions on QUIC connection SSL objects and
|
|
|
|
QUIC stream SSL objects in a single call.
|
|
|
|
|
|
|
|
A call to SSL_poll() specifies an array of B<SSL_POLL_ITEM> structures, each of
|
|
|
|
which designates a resource which is being polled for readiness, and a set of
|
|
|
|
event flags which indicate the specific readiness events which the caller is
|
|
|
|
interested in in relation to the specified resource.
|
|
|
|
|
|
|
|
The fields of B<SSL_POLL_ITEM> are as follows:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item I<desc>
|
|
|
|
|
|
|
|
The resource being polled for readiness, as represented by a
|
|
|
|
B<BIO_POLL_DESCRIPTOR>. Currently, this must be a poll descriptor of type
|
2024-11-08 04:47:32 +08:00
|
|
|
B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, representing an SSL object pointer, and the SSL
|
2024-02-09 18:27:53 +08:00
|
|
|
object must be a QUIC connection SSL object or QUIC stream SSL object.
|
2024-02-02 20:24:24 +08:00
|
|
|
|
|
|
|
If a B<SSL_POLL_ITEM> has a poll descriptor type of
|
|
|
|
B<BIO_POLL_DESCRIPTOR_TYPE_NONE>, or the SSL object pointer is NULL, the
|
|
|
|
B<SSL_POLL_ITEM> array entry is ignored and I<revents> will be set to 0 on
|
|
|
|
return.
|
|
|
|
|
|
|
|
=item I<events>
|
|
|
|
|
|
|
|
This is the set of zero or more events which the caller is interested in
|
|
|
|
learning about in relation to the resource described by I<desc>. It is a
|
|
|
|
collection of zero or more B<SSL_POLL_EVENT> flags. See L</EVENT TYPES> for a
|
|
|
|
description of each of the event types.
|
|
|
|
|
|
|
|
=item I<revents>
|
|
|
|
|
|
|
|
After SSL_poll() returns, this is the set of zero or more events which are
|
|
|
|
actually applicable to the resource described by I<desc>. As for I<events>,
|
|
|
|
it is a collection of zero or more B<SSL_POLL_EVENT> flags.
|
|
|
|
|
|
|
|
I<revents> need not be a subset of the events specified in I<events>, as some
|
|
|
|
event types are defined as always being enabled (non-maskable). See L</EVENT
|
|
|
|
TYPES> for more information.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
To use SSL_poll(), call it with an array of B<SSL_POLL_ITEM> structures. The
|
|
|
|
array need remain allocated only for the duration of the call. I<num_items> must
|
|
|
|
be set to the number of entries in the array, and I<stride> must be set to
|
|
|
|
C<sizeof(SSL_POLL_ITEM)>.
|
|
|
|
|
|
|
|
The present implementation of SSL_poll() is a subset of the functionality which
|
|
|
|
will eventually be available. Only a nonblocking mode of operation is available
|
|
|
|
at this time, where SSL_poll() always returns immediately. As such, I<timeout>
|
|
|
|
must point to a valid B<struct timeval> and that structure must be set to zero.
|
|
|
|
In future, other inputs to the I<timeout> argument will result in a blocking
|
|
|
|
mode of operation, which is not currently supported. For more information, see
|
|
|
|
L</LIMITATIONS>.
|
|
|
|
|
|
|
|
The following flags are currently defined for the I<flags> argument:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item B<SSL_POLL_FLAG_NO_HANDLE_EVENTS>
|
|
|
|
|
|
|
|
This flag indicates that internal state machine processing should not be
|
|
|
|
performed in an attempt to generate new readiness events. Only existing
|
|
|
|
readiness events will be reported.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
The I<result_count> argument is optional. If it is non-NULL, it is used to
|
|
|
|
output the number of entries in the array which have nonzero I<revents> fields
|
|
|
|
when the call to SSL_poll() returns; see L</RETURN VALUES> for details.
|
|
|
|
|
|
|
|
=head1 EVENT TYPES
|
|
|
|
|
|
|
|
The SSL_poll() interface reports zero or more event types on a given resource,
|
|
|
|
represented by a bit mask.
|
|
|
|
|
|
|
|
All of the event types are level triggered and represent a readiness or
|
|
|
|
permanent exception condition; as such, after an event has been reported by
|
|
|
|
SSL_poll() for a resource, it will continue to be reported in future SSL_poll()
|
|
|
|
calls until the condition ceases to be in effect. A caller must mask the given
|
|
|
|
event type bit in future SSL_poll() calls if it does not wish to receive
|
|
|
|
repeated notifications and has not caused the underlying readiness condition
|
|
|
|
(for example, consuming all available data using L<SSL_read_ex(3)> after
|
|
|
|
B<SSL_POLL_EVENT_R> is reported) to be deasserted.
|
|
|
|
|
|
|
|
Some event types do not make sense on a given kind of resource. In this case,
|
|
|
|
specifying that event type in I<events> is a no-op and will be ignored, and the
|
|
|
|
given event will never be reported in I<revents>.
|
|
|
|
|
|
|
|
Failure of the polling mechanism itself is considered distinct from an exception
|
|
|
|
condition on a resource which was successfully polled. See B<SSL_POLL_EVENT_F>
|
|
|
|
and L</RETURN VALUES> for details.
|
|
|
|
|
|
|
|
In general, an application should always listen for the event types
|
|
|
|
corresponding to exception conditions if it is listening to the corresponding
|
|
|
|
non-exception event types (e.g. B<SSL_POLL_EVENT_EC> and B<SSL_POLL_EVENT_ER>
|
|
|
|
for B<SSL_POLL_EVENT_R>), as not doing so is unlikely to be a sound design.
|
|
|
|
|
|
|
|
Some event types are non-maskable and may be reported in I<revents> regardless
|
|
|
|
of whether they were requested in I<events>.
|
|
|
|
|
|
|
|
The following event types are supported:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_F>
|
|
|
|
|
|
|
|
Polling failure. This event is raised when a resource could not be polled. It is
|
|
|
|
distinct from an exception condition reported on a resource which was
|
|
|
|
successfully polled and represents a failure of the polling process itself in
|
|
|
|
relation to a resource. This may mean that SSL_poll() does not support the kind
|
|
|
|
of resource specified.
|
|
|
|
|
|
|
|
Where this event is raised on at least one item in I<items>, SSL_poll() will
|
|
|
|
return 0 and the ERR stack will contain information pertaining to the first item
|
|
|
|
in I<items> with B<SSL_POLL_EVENT_F> set. See L</RETURN VALUES> for more
|
|
|
|
information.
|
|
|
|
|
|
|
|
This event type may be raised even if it was not requested in I<events>;
|
|
|
|
specifying this event type in I<events> does nothing.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_EC>
|
|
|
|
|
|
|
|
Error at connection level. This event is raised when a connection has failed.
|
|
|
|
In particular, it is raised when a connection begins terminating.
|
|
|
|
|
|
|
|
This event is never raised on objects which are not connections.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_DCD>
|
|
|
|
|
|
|
|
Error at connection level (drained). This event is raised when a connection has
|
|
|
|
finished terminating, and has reached the terminated state. This event will
|
|
|
|
generally occur after an interval of time passes after the B<SSL_POLL_EVENT_EC>
|
|
|
|
event is raised on a connection.
|
|
|
|
|
|
|
|
This event is never raised on objects which are not connections.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_ER>
|
|
|
|
|
|
|
|
Error in read direction. For QUIC, this is raised only in the event that a
|
|
|
|
stream has a read part and that read part has been reset by the peer (for
|
|
|
|
example, using a B<RESET_STREAM> frame).
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_EW>
|
|
|
|
|
|
|
|
Error in write direction. For QUIC, this is raised only in the event that a
|
|
|
|
stream has a write part and that write part has been reset by the peer using a
|
|
|
|
B<STOP_SENDING> frame.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_R>
|
|
|
|
|
|
|
|
Readable. This event is raised when a QUIC stream SSL object (or a QUIC
|
|
|
|
connection SSL object with a default stream attached) has application data
|
|
|
|
waiting to be read using L<SSL_read_ex(3)>, or a FIN event as represented by
|
|
|
|
B<SSL_ERROR_ZERO_RETURN> waiting to be read.
|
|
|
|
|
|
|
|
It is not raised in the event of the receiving part of the QUIC stream being
|
|
|
|
reset by the peer; see B<SSL_POLL_EVENT_ER>.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_W>
|
|
|
|
|
|
|
|
Writable. This event is raised when a QUIC stream SSL object (or a QUIC
|
|
|
|
connection SSL object with a default stream attached) could accept more
|
|
|
|
application data using L<SSL_write_ex(3)>.
|
|
|
|
|
|
|
|
This event is never raised by a receive-only stream.
|
|
|
|
|
|
|
|
This event is never raised by a stream which has had its send part concluded
|
|
|
|
normally (as with L<SSL_stream_conclude(3)>) or locally reset (as with
|
|
|
|
L<SSL_stream_reset(3)>).
|
|
|
|
|
|
|
|
This event does not guarantee that a subsequent call to L<SSL_write_ex(3)> will
|
|
|
|
succeed.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_ISB>
|
|
|
|
|
|
|
|
This event, which is only raised by a QUIC connection SSL object, is raised when
|
|
|
|
one or more incoming bidirectional streams are available to be accepted using
|
|
|
|
L<SSL_accept_stream(3)>.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_ISU>
|
|
|
|
|
|
|
|
This event, which is only raised by a QUIC connection SSL object, is raised when
|
|
|
|
one or more incoming unidirectional streams are available to be accepted using
|
|
|
|
L<SSL_accept_stream(3)>.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_OSB>
|
|
|
|
|
|
|
|
This event, which is only raised by a QUIC connection SSL object, is raised when
|
|
|
|
QUIC stream creation flow control currently permits at least one additional
|
|
|
|
bidirectional stream to be locally created.
|
|
|
|
|
|
|
|
=item B<SSL_POLL_EVENT_OSU>
|
|
|
|
|
|
|
|
This event, which is only raised by a QUIC connection SSL object, is raised when
|
|
|
|
QUIC stream creation flow control currently permits at least one additional
|
|
|
|
unidirectional stream to be locally created.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
=head1 LIMITATIONS
|
|
|
|
|
|
|
|
SSL_poll() as presently implemented has the following limitations:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
The implementation of SSL_poll() only supports nonblocking operation and
|
|
|
|
therefore requires the I<timeout> argument be used to specify a zero timeout.
|
|
|
|
Calls to SSL_poll() which specify another value, or which pass I<timeout> as
|
|
|
|
NULL, will fail. This does not allow waiting, but does allow multiple QUIC SSL
|
|
|
|
objects to be queried for their readiness state in a single call.
|
|
|
|
|
|
|
|
Future releases will remove this limitation and support blocking SSL_poll().
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
Only B<BIO_POLL_DESCRIPTOR> structures with type
|
|
|
|
B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, referencing QUIC connection SSL objects or QUIC
|
|
|
|
stream SSL objects, are supported.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
These limitations will be revised in a future release of OpenSSL.
|
|
|
|
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
|
|
|
|
SSL_poll() returns 1 on success and 0 on failure.
|
|
|
|
|
|
|
|
Unless the I<items> pointer itself is invalid, SSL_poll() will always initialise
|
|
|
|
the I<revents> fields of all items in the input array upon returning, even if it
|
|
|
|
returns failure.
|
|
|
|
|
|
|
|
If I<result_count> is non-NULL, it is always written with the number of items in
|
|
|
|
the array with nonzero I<revents> fields, even if the SSL_poll() call returns
|
|
|
|
failure.
|
|
|
|
|
|
|
|
It is possible for I<result_count> to be written as 0 even if the SSL_poll()
|
|
|
|
call returns success, namely if no events were output but the polling process
|
|
|
|
was successful (e.g. in nonblocking usage) or timed out.
|
|
|
|
|
|
|
|
It is possible for I<result_count> to be written as a nonzero value if the
|
|
|
|
SSL_poll() call returns failure, for example due to B<SSL_POLL_EVENT_F> events,
|
|
|
|
or because some events were detected and output before encountering a failure
|
|
|
|
condition while processing a subsequent entry in the I<items> array.
|
|
|
|
|
|
|
|
If at least one B<SSL_POLL_EVENT_F> event is output, SSL_poll() is guaranteed
|
|
|
|
to return 0 and guaranteed to place at least one ERR on the error stack
|
|
|
|
describing the first B<SSL_POLL_EVENT_F> output. Detailed information on any
|
|
|
|
additional B<SSL_POLL_EVENT_F> events is not available. SSL_poll() may or may
|
|
|
|
not return more than one B<SSL_POLL_EVENT_F> event at once.
|
|
|
|
|
|
|
|
"Normal" events representing exceptional I/O conditions which do not
|
|
|
|
constitute a failure of the SSL_poll() mechanism itself are not considered
|
|
|
|
errors by SSL_poll() and are instead represented using their own event type; see
|
|
|
|
L</EVENT TYPES> for details.
|
|
|
|
|
2024-02-07 16:53:41 +08:00
|
|
|
The caller can establish the meaning of the SSL_poll() return and output values
|
2024-02-02 20:24:24 +08:00
|
|
|
as follows:
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
If SSL_poll() returns 1 and I<result_count> is zero, the operation timed out
|
|
|
|
before any resource was ready.
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
If SSL_poll() returns 1 and I<result_count> is nonzero, that many events were
|
|
|
|
output.
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
If SSL_poll() returns 0 and I<result_count> is zero, the caller has made a basic
|
|
|
|
usage error; check the ERR stack for details.
|
|
|
|
|
|
|
|
=item
|
|
|
|
|
|
|
|
If SSL_poll() returns 0 and I<result_count> is nonzero, inspect the I<items>
|
|
|
|
array for B<SSL_POLL_ITEM> structures with the B<SSL_POLL_EVENT_F> event type
|
|
|
|
raised in I<revents>. The entries added to the ERR stack (of which there is
|
|
|
|
guaranteed to be at least one) reflect the cause of the failure of the first
|
|
|
|
item in I<items> with B<SSL_POLL_EVENT_F> raised. Note that there may be events
|
|
|
|
other than I<SSL_POLL_EVENT_F> output for items which come before the first
|
|
|
|
item with B<SSL_POLL_EVENT_F> raised, and additional B<SSL_POLL_EVENT_F>
|
|
|
|
events may or may not have been output, both of which which will be reflected in
|
|
|
|
I<result_count>.
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
|
|
|
|
L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>,
|
|
|
|
L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>
|
|
|
|
|
|
|
|
=head1 HISTORY
|
|
|
|
|
|
|
|
SSL_poll() was added in OpenSSL 3.3.
|
|
|
|
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
|
|
|
|
Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
|
|
this file except in compliance with the License. You can obtain a copy
|
|
|
|
in the file LICENSE in the source distribution or at
|
|
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
|
|
|
|
=cut
|