1=pod 2 3=head1 NAME 4 5SSL_poll, 6SSL_POLL_EVENT_NONE, 7SSL_POLL_EVENT_F, 8SSL_POLL_EVENT_EC, 9SSL_POLL_EVENT_ECD, 10SSL_POLL_EVENT_ER, 11SSL_POLL_EVENT_EW, 12SSL_POLL_EVENT_R, 13SSL_POLL_EVENT_W, 14SSL_POLL_EVENT_ISB, 15SSL_POLL_EVENT_ISU, 16SSL_POLL_EVENT_OSB, 17SSL_POLL_EVENT_OSU, 18SSL_POLL_EVENT_RW, 19SSL_POLL_EVENT_RE, 20SSL_POLL_EVENT_WE, 21SSL_POLL_EVENT_RWE, 22SSL_POLL_EVENT_E, 23SSL_POLL_EVENT_IS, 24SSL_POLL_EVENT_ISE, 25SSL_POLL_EVENT_I, 26SSL_POLL_EVENT_OS, 27SSL_POLL_EVENT_OSE, 28SSL_POLL_FLAG_NO_HANDLE_EVENTS 29- determine or await readiness conditions for one or more pollable objects 30 31=head1 SYNOPSIS 32 33 #include <openssl/ssl.h> 34 35 #define SSL_POLL_EVENT_NONE 0 36 37 #define SSL_POLL_EVENT_F /* F (Failure) */ 38 #define SSL_POLL_EVENT_EC /* EC (Exception on Conn) */ 39 #define SSL_POLL_EVENT_ECD /* ECD (Exception on Conn Drained) */ 40 #define SSL_POLL_EVENT_ER /* ER (Exception on Read) */ 41 #define SSL_POLL_EVENT_EW /* EW (Exception on Write) */ 42 #define SSL_POLL_EVENT_R /* R (Readable) */ 43 #define SSL_POLL_EVENT_W /* W (Writable) */ 44 #define SSL_POLL_EVENT_ISB /* ISB (Incoming Stream: Bidi) */ 45 #define SSL_POLL_EVENT_ISU /* ISU (Incoming Stream: Uni) */ 46 #define SSL_POLL_EVENT_OSB /* OSB (Outgoing Stream: Bidi) */ 47 #define SSL_POLL_EVENT_OSU /* OSU (Outgoing Stream: Uni) */ 48 49 #define SSL_POLL_EVENT_RW /* R | W */ 50 #define SSL_POLL_EVENT_RE /* R | ER */ 51 #define SSL_POLL_EVENT_WE /* W | EW */ 52 #define SSL_POLL_EVENT_RWE /* RE | WE */ 53 #define SSL_POLL_EVENT_E /* EC | ER | EW */ 54 #define SSL_POLL_EVENT_IS /* ISB | ISU */ 55 #define SSL_POLL_EVENT_ISE /* IS | EC */ 56 #define SSL_POLL_EVENT_I /* IS */ 57 #define SSL_POLL_EVENT_OS /* OSB | OSU */ 58 #define SSL_POLL_EVENT_OSE /* OS | EC */ 59 60 typedef struct ssl_poll_item_st { 61 BIO_POLL_DESCRIPTOR desc; 62 uint64_t events, revents; 63 } SSL_POLL_ITEM; 64 65 #define SSL_POLL_FLAG_NO_HANDLE_EVENTS 66 67 int SSL_poll(SSL_POLL_ITEM *items, 68 size_t num_items, 69 size_t stride, 70 const struct timeval *timeout, 71 uint64_t flags, 72 size_t *result_count); 73 74=head1 DESCRIPTION 75 76SSL_poll() allows the readiness conditions of the resources represented by one 77or more BIO_POLL_DESCRIPTOR structures to be determined. In particular, it can 78be used to query for readiness conditions on QUIC connection SSL objects and 79QUIC stream SSL objects in a single call. 80 81A call to SSL_poll() specifies an array of B<SSL_POLL_ITEM> structures, each of 82which designates a resource which is being polled for readiness, and a set of 83event flags which indicate the specific readiness events which the caller is 84interested in in relation to the specified resource. 85 86The fields of B<SSL_POLL_ITEM> are as follows: 87 88=over 4 89 90=item I<desc> 91 92The resource being polled for readiness, as represented by a 93B<BIO_POLL_DESCRIPTOR>. Currently, this must be a poll descriptor of type 94B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, representing an SSL object pointer, and the SSL 95object must be a QUIC connection SSL object or QUIC stream SSL object. 96 97If a B<SSL_POLL_ITEM> has a poll descriptor type of 98B<BIO_POLL_DESCRIPTOR_TYPE_NONE>, or the SSL object pointer is NULL, the 99B<SSL_POLL_ITEM> array entry is ignored and I<revents> will be set to 0 on 100return. 101 102=item I<events> 103 104This is the set of zero or more events which the caller is interested in 105learning about in relation to the resource described by I<desc>. It is a 106collection of zero or more B<SSL_POLL_EVENT> flags. See L</EVENT TYPES> for a 107description of each of the event types. 108 109=item I<revents> 110 111After SSL_poll() returns, this is the set of zero or more events which are 112actually applicable to the resource described by I<desc>. As for I<events>, 113it is a collection of zero or more B<SSL_POLL_EVENT> flags. 114 115I<revents> need not be a subset of the events specified in I<events>, as some 116event types are defined as always being enabled (non-maskable). See L</EVENT 117TYPES> for more information. 118 119=back 120 121To use SSL_poll(), call it with an array of B<SSL_POLL_ITEM> structures. The 122array need remain allocated only for the duration of the call. I<num_items> must 123be set to the number of entries in the array, and I<stride> must be set to 124C<sizeof(SSL_POLL_ITEM)>. 125 126The present implementation of SSL_poll() is a subset of the functionality which 127will eventually be available. Only a nonblocking mode of operation is available 128at this time, where SSL_poll() always returns immediately. As such, I<timeout> 129must point to a valid B<struct timeval> and that structure must be set to zero. 130In future, other inputs to the I<timeout> argument will result in a blocking 131mode of operation, which is not currently supported. For more information, see 132L</LIMITATIONS>. 133 134The following flags are currently defined for the I<flags> argument: 135 136=over 4 137 138=item B<SSL_POLL_FLAG_NO_HANDLE_EVENTS> 139 140This flag indicates that internal state machine processing should not be 141performed in an attempt to generate new readiness events. Only existing 142readiness events will be reported. 143 144=back 145 146The I<result_count> argument is optional. If it is non-NULL, it is used to 147output the number of entries in the array which have nonzero I<revents> fields 148when the call to SSL_poll() returns; see L</RETURN VALUES> for details. 149 150=head1 EVENT TYPES 151 152The SSL_poll() interface reports zero or more event types on a given resource, 153represented by a bit mask. 154 155All of the event types are level triggered and represent a readiness or 156permanent exception condition; as such, after an event has been reported by 157SSL_poll() for a resource, it will continue to be reported in future SSL_poll() 158calls until the condition ceases to be in effect. A caller must mask the given 159event type bit in future SSL_poll() calls if it does not wish to receive 160repeated notifications and has not caused the underlying readiness condition 161(for example, consuming all available data using L<SSL_read_ex(3)> after 162B<SSL_POLL_EVENT_R> is reported) to be deasserted. 163 164Some event types do not make sense on a given kind of resource. In this case, 165specifying that event type in I<events> is a no-op and will be ignored, and the 166given event will never be reported in I<revents>. 167 168Failure of the polling mechanism itself is considered distinct from an exception 169condition on a resource which was successfully polled. See B<SSL_POLL_EVENT_F> 170and L</RETURN VALUES> for details. 171 172In general, an application should always listen for the event types 173corresponding to exception conditions if it is listening to the corresponding 174non-exception event types (e.g. B<SSL_POLL_EVENT_EC> and B<SSL_POLL_EVENT_ER> 175for B<SSL_POLL_EVENT_R>), as not doing so is unlikely to be a sound design. 176 177Some event types are non-maskable and may be reported in I<revents> regardless 178of whether they were requested in I<events>. 179 180The following event types are supported: 181 182=over 4 183 184=item B<SSL_POLL_EVENT_F> 185 186Polling failure. This event is raised when a resource could not be polled. It is 187distinct from an exception condition reported on a resource which was 188successfully polled and represents a failure of the polling process itself in 189relation to a resource. This may mean that SSL_poll() does not support the kind 190of resource specified. 191 192Where this event is raised on at least one item in I<items>, SSL_poll() will 193return 0 and the ERR stack will contain information pertaining to the first item 194in I<items> with B<SSL_POLL_EVENT_F> set. See L</RETURN VALUES> for more 195information. 196 197This event type may be raised even if it was not requested in I<events>; 198specifying this event type in I<events> does nothing. 199 200=item B<SSL_POLL_EVENT_EC> 201 202Error at connection level. This event is raised when a connection has failed. 203In particular, it is raised when a connection begins terminating. 204 205This event is never raised on objects which are not connections. 206 207=item B<SSL_POLL_EVENT_DCD> 208 209Error at connection level (drained). This event is raised when a connection has 210finished terminating, and has reached the terminated state. This event will 211generally occur after an interval of time passes after the B<SSL_POLL_EVENT_EC> 212event is raised on a connection. 213 214This event is never raised on objects which are not connections. 215 216=item B<SSL_POLL_EVENT_ER> 217 218Error in read direction. For QUIC, this is raised only in the event that a 219stream has a read part and that read part has been reset by the peer (for 220example, using a B<RESET_STREAM> frame). 221 222=item B<SSL_POLL_EVENT_EW> 223 224Error in write direction. For QUIC, this is raised only in the event that a 225stream has a write part and that write part has been reset by the peer using a 226B<STOP_SENDING> frame. 227 228=item B<SSL_POLL_EVENT_R> 229 230Readable. This event is raised when a QUIC stream SSL object (or a QUIC 231connection SSL object with a default stream attached) has application data 232waiting to be read using L<SSL_read_ex(3)>, or a FIN event as represented by 233B<SSL_ERROR_ZERO_RETURN> waiting to be read. 234 235It is not raised in the event of the receiving part of the QUIC stream being 236reset by the peer; see B<SSL_POLL_EVENT_ER>. 237 238=item B<SSL_POLL_EVENT_W> 239 240Writable. This event is raised when a QUIC stream SSL object (or a QUIC 241connection SSL object with a default stream attached) could accept more 242application data using L<SSL_write_ex(3)>. 243 244This event is never raised by a receive-only stream. 245 246This event is never raised by a stream which has had its send part concluded 247normally (as with L<SSL_stream_conclude(3)>) or locally reset (as with 248L<SSL_stream_reset(3)>). 249 250This event does not guarantee that a subsequent call to L<SSL_write_ex(3)> will 251succeed. 252 253=item B<SSL_POLL_EVENT_ISB> 254 255This event, which is only raised by a QUIC connection SSL object, is raised when 256one or more incoming bidirectional streams are available to be accepted using 257L<SSL_accept_stream(3)>. 258 259=item B<SSL_POLL_EVENT_ISU> 260 261This event, which is only raised by a QUIC connection SSL object, is raised when 262one or more incoming unidirectional streams are available to be accepted using 263L<SSL_accept_stream(3)>. 264 265=item B<SSL_POLL_EVENT_OSB> 266 267This event, which is only raised by a QUIC connection SSL object, is raised when 268QUIC stream creation flow control currently permits at least one additional 269bidirectional stream to be locally created. 270 271=item B<SSL_POLL_EVENT_OSU> 272 273This event, which is only raised by a QUIC connection SSL object, is raised when 274QUIC stream creation flow control currently permits at least one additional 275unidirectional stream to be locally created. 276 277=back 278 279=head1 LIMITATIONS 280 281SSL_poll() as presently implemented has the following limitations: 282 283=over 4 284 285=item 286 287The implementation of SSL_poll() only supports nonblocking operation and 288therefore requires the I<timeout> argument be used to specify a zero timeout. 289Calls to SSL_poll() which specify another value, or which pass I<timeout> as 290NULL, will fail. This does not allow waiting, but does allow multiple QUIC SSL 291objects to be queried for their readiness state in a single call. 292 293Future releases will remove this limitation and support blocking SSL_poll(). 294 295=item 296 297Only B<BIO_POLL_DESCRIPTOR> structures with type 298B<BIO_POLL_DESCRIPTOR_TYPE_SSL>, referencing QUIC connection SSL objects or QUIC 299stream SSL objects, are supported. 300 301=back 302 303These limitations will be revised in a future release of OpenSSL. 304 305=head1 RETURN VALUES 306 307SSL_poll() returns 1 on success and 0 on failure. 308 309Unless the I<items> pointer itself is invalid, SSL_poll() will always initialise 310the I<revents> fields of all items in the input array upon returning, even if it 311returns failure. 312 313If I<result_count> is non-NULL, it is always written with the number of items in 314the array with nonzero I<revents> fields, even if the SSL_poll() call returns 315failure. 316 317It is possible for I<result_count> to be written as 0 even if the SSL_poll() 318call returns success, namely if no events were output but the polling process 319was successful (e.g. in nonblocking usage) or timed out. 320 321It is possible for I<result_count> to be written as a nonzero value if the 322SSL_poll() call returns failure, for example due to B<SSL_POLL_EVENT_F> events, 323or because some events were detected and output before encountering a failure 324condition while processing a subsequent entry in the I<items> array. 325 326If at least one B<SSL_POLL_EVENT_F> event is output, SSL_poll() is guaranteed 327to return 0 and guaranteed to place at least one ERR on the error stack 328describing the first B<SSL_POLL_EVENT_F> output. Detailed information on any 329additional B<SSL_POLL_EVENT_F> events is not available. SSL_poll() may or may 330not return more than one B<SSL_POLL_EVENT_F> event at once. 331 332"Normal" events representing exceptional I/O conditions which do not 333constitute a failure of the SSL_poll() mechanism itself are not considered 334errors by SSL_poll() and are instead represented using their own event type; see 335L</EVENT TYPES> for details. 336 337The caller can establish the meaning of the SSL_poll() return and output values 338as follows: 339 340=over 4 341 342=item 343 344If SSL_poll() returns 1 and I<result_count> is zero, the operation timed out 345before any resource was ready. 346 347=item 348 349If SSL_poll() returns 1 and I<result_count> is nonzero, that many events were 350output. 351 352=item 353 354If SSL_poll() returns 0 and I<result_count> is zero, the caller has made a basic 355usage error; check the ERR stack for details. 356 357=item 358 359If SSL_poll() returns 0 and I<result_count> is nonzero, inspect the I<items> 360array for B<SSL_POLL_ITEM> structures with the B<SSL_POLL_EVENT_F> event type 361raised in I<revents>. The entries added to the ERR stack (of which there is 362guaranteed to be at least one) reflect the cause of the failure of the first 363item in I<items> with B<SSL_POLL_EVENT_F> raised. Note that there may be events 364other than I<SSL_POLL_EVENT_F> output for items which come before the first 365item with B<SSL_POLL_EVENT_F> raised, and additional B<SSL_POLL_EVENT_F> 366events may or may not have been output, both of which which will be reflected in 367I<result_count>. 368 369=back 370 371=head1 SEE ALSO 372 373L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>, 374L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> 375 376=head1 HISTORY 377 378SSL_poll() was added in OpenSSL 3.3. 379 380=head1 COPYRIGHT 381 382Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. 383 384Licensed under the Apache License 2.0 (the "License"). You may not use 385this file except in compliance with the License. You can obtain a copy 386in the file LICENSE in the source distribution or at 387L<https://www.openssl.org/source/license.html>. 388 389=cut 390
