From: Hugo Landau Date: Fri, 2 Feb 2024 12:24:24 +0000 (+0000) Subject: QUIC: Add manpage for SSL_poll X-Git-Tag: openssl-3.3.0-alpha1~111 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c9b0df2250e2;p=thirdparty%2Fopenssl.git QUIC: Add manpage for SSL_poll Reviewed-by: Neil Horman Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/23495) --- diff --git a/doc/man3/SSL_poll.pod b/doc/man3/SSL_poll.pod new file mode 100644 index 00000000000..a5d56541f89 --- /dev/null +++ b/doc/man3/SSL_poll.pod @@ -0,0 +1,389 @@ +=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 + + #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 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 are as follows: + +=over 4 + +=item I + +The resource being polled for readiness, as represented by a +B. Currently, this must be a poll descriptor of type +B, representing a SSL object pointer, and the SSL +object must be to a QUIC connection SSL object or QUIC stream SSL object. + +If a B has a poll descriptor type of +B, or the SSL object pointer is NULL, the +B array entry is ignored and I will be set to 0 on +return. + +=item I + +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. It is a +collection of zero or more B flags. See L for a +description of each of the event types. + +=item I + +After SSL_poll() returns, this is the set of zero or more events which are +actually applicable to the resource described by I. As for I, +it is a collection of zero or more B flags. + +I need not be a subset of the events specified in I, as some +event types are defined as always being enabled (non-maskable). See L for more information. + +=back + +To use SSL_poll(), call it with an array of B structures. The +array need remain allocated only for the duration of the call. I must +be set to the number of entries in the array, and I must be set to +C. + +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 +must point to a valid B and that structure must be set to zero. +In future, other inputs to the I argument will result in a blocking +mode of operation, which is not currently supported. For more information, see +L. + +The following flags are currently defined for the I argument: + +=over 4 + +=item B + +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 argument is optional. If it is non-NULL, it is used to +output the number of entries in the array which have nonzero I fields +when the call to SSL_poll() returns; see L 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 after +B 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 is a no-op and will be ignored, and the +given event will never be reported in I. + +Failure of the polling mechanism itself is considered distinct from an exception +condition on a resource which was successfully polled. See B +and L 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 and B +for B), as not doing so is unlikely to be a sound design. + +Some event types are non-maskable and may be reported in I regardless +of whether they were requested in I. + +The following event types are supported: + +=over 4 + +=item B + +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, SSL_poll() will +return 0 and the ERR stack will contain information pertaining to the first item +in I with B set. See L for more +information. + +This event type may be raised even if it was not requested in I; +specifying this event type in I does nothing. + +=item B + +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 + +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 +event is raised on a connection. + +This event is never raised on objects which are not connections. + +=item B + +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 frame). + +=item B + +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 frame. + +=item B + +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, or a FIN event as represented by +B 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. + +=item B + +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. + +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) or locally reset (as with +L). + +This event does not guarantee that a subsequent call to L will +succeed. + +=item B + +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. + +=item B + +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. + +=item B + +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 + +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 argument be used to specify a zero timeout. +Calls to SSL_poll() which specify another value, or which pass I 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 structures with type +B, 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 pointer itself is invalid, SSL_poll() will always initialise +the I fields of all items in the input array upon returning, even if it +returns failure. + +If I is non-NULL, it is always written with the number of items in +the array with nonzero I fields, even if the SSL_poll() call returns +failure. + +It is possible for I 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 to be written as a nonzero value if the +SSL_poll() call returns failure, for example due to B events, +or because some events were detected and output before encountering a failure +condition while processing a subsequent entry in the I array. + +If at least one B 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 output. Detailed information on any +additional B events is not available. SSL_poll() may or may +not return more than one B 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 for details. + +The caller can esablish the meaning of the SSL_poll() return and output values +as follows: + +=over 4 + +=item + +If SSL_poll() returns 1 and I is zero, the operation timed out +before any resource was ready. + +=item + +If SSL_poll() returns 1 and I is nonzero, that many events were +output. + +=item + +If SSL_poll() returns 0 and I is zero, the caller has made a basic +usage error; check the ERR stack for details. + +=item + +If SSL_poll() returns 0 and I is nonzero, inspect the I +array for B structures with the B event type +raised in I. 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 with B raised. Note that there may be events +other than I output for items which come before the first +item with B raised, and additional B +events may or may not have been output, both of which which will be reflected in +I. + +=back + +=head1 SEE ALSO + +L, L, +L, L + +=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. + +=cut diff --git a/util/other.syms b/util/other.syms index 048223b424e..3148866fb12 100644 --- a/util/other.syms +++ b/util/other.syms @@ -150,6 +150,10 @@ PKCS12_create_cb datatype ASN1_BIT_STRING_digest define BIO_IS_ERRNO define BIO_UNPACK_ERRNO define +BIO_POLL_DESCRIPTOR_TYPE_NONE define +BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD define +BIO_POLL_DESCRIPTOR_TYPE_SSL define +BIO_POLL_DESCRIPTOR_TYPE_CUSTOM_START define BIO_append_filename define BIO_destroy_bio_pair define BIO_dgram_get_local_addr_cap define @@ -665,6 +669,31 @@ SSL_CONN_CLOSE_FLAG_TRANSPORT define SSLv23_client_method define SSLv23_method define SSLv23_server_method define +SSL_POLL_EVENT_NONE define +SSL_POLL_EVENT_EC define +SSL_POLL_EVENT_ECD define +SSL_POLL_EVENT_EL define +SSL_POLL_EVENT_F define +SSL_POLL_EVENT_R define +SSL_POLL_EVENT_ER define +SSL_POLL_EVENT_W define +SSL_POLL_EVENT_EW define +SSL_POLL_EVENT_ISB define +SSL_POLL_EVENT_ISU define +SSL_POLL_EVENT_IS define +SSL_POLL_EVENT_ISE define +SSL_POLL_EVENT_IC define +SSL_POLL_EVENT_I define +SSL_POLL_EVENT_OSB define +SSL_POLL_EVENT_OSU define +SSL_POLL_EVENT_OS define +SSL_POLL_EVENT_OSE define +SSL_POLL_EVENT_RW define +SSL_POLL_EVENT_RWE define +SSL_POLL_EVENT_RE define +SSL_POLL_EVENT_WE define +SSL_POLL_EVENT_E define +SSL_POLL_FLAG_NO_HANDLE_EVENTS define SSL_STREAM_FLAG_UNI define SSL_STREAM_FLAG_NO_BLOCK define SSL_STREAM_FLAG_ADVANCE define