From: Hugo Landau Date: Mon, 14 Nov 2022 18:13:35 +0000 (+0000) Subject: QUIC CSM: Documentation for new APIs X-Git-Tag: openssl-3.2.0-alpha1~1508 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c572bed9f56b48937f58e75cf8132696ba19a6ad;p=thirdparty%2Fopenssl.git QUIC CSM: Documentation for new APIs Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/19703) --- diff --git a/doc/build.info b/doc/build.info index c1d6a5f1dcf..2b169f1cf2c 100644 --- a/doc/build.info +++ b/doc/build.info @@ -607,6 +607,10 @@ DEPEND[html/man3/BIO_get_ex_new_index.html]=man3/BIO_get_ex_new_index.pod GENERATE[html/man3/BIO_get_ex_new_index.html]=man3/BIO_get_ex_new_index.pod DEPEND[man/man3/BIO_get_ex_new_index.3]=man3/BIO_get_ex_new_index.pod GENERATE[man/man3/BIO_get_ex_new_index.3]=man3/BIO_get_ex_new_index.pod +DEPEND[html/man3/BIO_get_rpoll_descriptor.html]=man3/BIO_get_rpoll_descriptor.pod +GENERATE[html/man3/BIO_get_rpoll_descriptor.html]=man3/BIO_get_rpoll_descriptor.pod +DEPEND[man/man3/BIO_get_rpoll_descriptor.3]=man3/BIO_get_rpoll_descriptor.pod +GENERATE[man/man3/BIO_get_rpoll_descriptor.3]=man3/BIO_get_rpoll_descriptor.pod DEPEND[html/man3/BIO_meth_new.html]=man3/BIO_meth_new.pod GENERATE[html/man3/BIO_meth_new.html]=man3/BIO_meth_new.pod DEPEND[man/man3/BIO_meth_new.3]=man3/BIO_meth_new.pod @@ -2539,6 +2543,10 @@ DEPEND[html/man3/SSL_get_rbio.html]=man3/SSL_get_rbio.pod GENERATE[html/man3/SSL_get_rbio.html]=man3/SSL_get_rbio.pod DEPEND[man/man3/SSL_get_rbio.3]=man3/SSL_get_rbio.pod GENERATE[man/man3/SSL_get_rbio.3]=man3/SSL_get_rbio.pod +DEPEND[html/man3/SSL_get_rpoll_descriptor.html]=man3/SSL_get_rpoll_descriptor.pod +GENERATE[html/man3/SSL_get_rpoll_descriptor.html]=man3/SSL_get_rpoll_descriptor.pod +DEPEND[man/man3/SSL_get_rpoll_descriptor.3]=man3/SSL_get_rpoll_descriptor.pod +GENERATE[man/man3/SSL_get_rpoll_descriptor.3]=man3/SSL_get_rpoll_descriptor.pod DEPEND[html/man3/SSL_get_session.html]=man3/SSL_get_session.pod GENERATE[html/man3/SSL_get_session.html]=man3/SSL_get_session.pod DEPEND[man/man3/SSL_get_session.3]=man3/SSL_get_session.pod @@ -2547,6 +2555,10 @@ DEPEND[html/man3/SSL_get_shared_sigalgs.html]=man3/SSL_get_shared_sigalgs.pod GENERATE[html/man3/SSL_get_shared_sigalgs.html]=man3/SSL_get_shared_sigalgs.pod DEPEND[man/man3/SSL_get_shared_sigalgs.3]=man3/SSL_get_shared_sigalgs.pod GENERATE[man/man3/SSL_get_shared_sigalgs.3]=man3/SSL_get_shared_sigalgs.pod +DEPEND[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod +GENERATE[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod +DEPEND[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod +GENERATE[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod DEPEND[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod GENERATE[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod DEPEND[man/man3/SSL_get_verify_result.3]=man3/SSL_get_verify_result.pod @@ -2611,6 +2623,10 @@ DEPEND[html/man3/SSL_set_bio.html]=man3/SSL_set_bio.pod GENERATE[html/man3/SSL_set_bio.html]=man3/SSL_set_bio.pod DEPEND[man/man3/SSL_set_bio.3]=man3/SSL_set_bio.pod GENERATE[man/man3/SSL_set_bio.3]=man3/SSL_set_bio.pod +DEPEND[html/man3/SSL_set_blocking_mode.html]=man3/SSL_set_blocking_mode.pod +GENERATE[html/man3/SSL_set_blocking_mode.html]=man3/SSL_set_blocking_mode.pod +DEPEND[man/man3/SSL_set_blocking_mode.3]=man3/SSL_set_blocking_mode.pod +GENERATE[man/man3/SSL_set_blocking_mode.3]=man3/SSL_set_blocking_mode.pod DEPEND[html/man3/SSL_set_connect_state.html]=man3/SSL_set_connect_state.pod GENERATE[html/man3/SSL_set_connect_state.html]=man3/SSL_set_connect_state.pod DEPEND[man/man3/SSL_set_connect_state.3]=man3/SSL_set_connect_state.pod @@ -2619,6 +2635,10 @@ DEPEND[html/man3/SSL_set_fd.html]=man3/SSL_set_fd.pod GENERATE[html/man3/SSL_set_fd.html]=man3/SSL_set_fd.pod DEPEND[man/man3/SSL_set_fd.3]=man3/SSL_set_fd.pod GENERATE[man/man3/SSL_set_fd.3]=man3/SSL_set_fd.pod +DEPEND[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod +GENERATE[html/man3/SSL_set_initial_peer_addr.html]=man3/SSL_set_initial_peer_addr.pod +DEPEND[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod +GENERATE[man/man3/SSL_set_initial_peer_addr.3]=man3/SSL_set_initial_peer_addr.pod DEPEND[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod GENERATE[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod DEPEND[man/man3/SSL_set_retry_verify.3]=man3/SSL_set_retry_verify.pod @@ -2643,6 +2663,10 @@ DEPEND[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod GENERATE[html/man3/SSL_state_string.html]=man3/SSL_state_string.pod DEPEND[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod GENERATE[man/man3/SSL_state_string.3]=man3/SSL_state_string.pod +DEPEND[html/man3/SSL_tick.html]=man3/SSL_tick.pod +GENERATE[html/man3/SSL_tick.html]=man3/SSL_tick.pod +DEPEND[man/man3/SSL_tick.3]=man3/SSL_tick.pod +GENERATE[man/man3/SSL_tick.3]=man3/SSL_tick.pod DEPEND[html/man3/SSL_want.html]=man3/SSL_want.pod GENERATE[html/man3/SSL_want.html]=man3/SSL_want.pod DEPEND[man/man3/SSL_want.3]=man3/SSL_want.pod @@ -2959,6 +2983,7 @@ html/man3/BIO_f_ssl.html \ html/man3/BIO_find_type.html \ html/man3/BIO_get_data.html \ html/man3/BIO_get_ex_new_index.html \ +html/man3/BIO_get_rpoll_descriptor.html \ html/man3/BIO_meth_new.html \ html/man3/BIO_new.html \ html/man3/BIO_new_CMS.html \ @@ -3442,8 +3467,10 @@ html/man3/SSL_get_peer_signature_nid.html \ html/man3/SSL_get_peer_tmp_key.html \ html/man3/SSL_get_psk_identity.html \ html/man3/SSL_get_rbio.html \ +html/man3/SSL_get_rpoll_descriptor.html \ html/man3/SSL_get_session.html \ html/man3/SSL_get_shared_sigalgs.html \ +html/man3/SSL_get_tick_timeout.html \ html/man3/SSL_get_verify_result.html \ html/man3/SSL_get_version.html \ html/man3/SSL_group_to_name.html \ @@ -3460,14 +3487,17 @@ html/man3/SSL_session_reused.html \ html/man3/SSL_set1_host.html \ html/man3/SSL_set_async_callback.html \ html/man3/SSL_set_bio.html \ +html/man3/SSL_set_blocking_mode.html \ html/man3/SSL_set_connect_state.html \ html/man3/SSL_set_fd.html \ +html/man3/SSL_set_initial_peer_addr.html \ html/man3/SSL_set_retry_verify.html \ html/man3/SSL_set_session.html \ html/man3/SSL_set_shutdown.html \ html/man3/SSL_set_verify_result.html \ html/man3/SSL_shutdown.html \ html/man3/SSL_state_string.html \ +html/man3/SSL_tick.html \ html/man3/SSL_want.html \ html/man3/SSL_write.html \ html/man3/TS_RESP_CTX_new.html \ @@ -3573,6 +3603,7 @@ man/man3/BIO_f_ssl.3 \ man/man3/BIO_find_type.3 \ man/man3/BIO_get_data.3 \ man/man3/BIO_get_ex_new_index.3 \ +man/man3/BIO_get_rpoll_descriptor.3 \ man/man3/BIO_meth_new.3 \ man/man3/BIO_new.3 \ man/man3/BIO_new_CMS.3 \ @@ -4056,8 +4087,10 @@ man/man3/SSL_get_peer_signature_nid.3 \ man/man3/SSL_get_peer_tmp_key.3 \ man/man3/SSL_get_psk_identity.3 \ man/man3/SSL_get_rbio.3 \ +man/man3/SSL_get_rpoll_descriptor.3 \ man/man3/SSL_get_session.3 \ man/man3/SSL_get_shared_sigalgs.3 \ +man/man3/SSL_get_tick_timeout.3 \ man/man3/SSL_get_verify_result.3 \ man/man3/SSL_get_version.3 \ man/man3/SSL_group_to_name.3 \ @@ -4074,14 +4107,17 @@ man/man3/SSL_session_reused.3 \ man/man3/SSL_set1_host.3 \ man/man3/SSL_set_async_callback.3 \ man/man3/SSL_set_bio.3 \ +man/man3/SSL_set_blocking_mode.3 \ man/man3/SSL_set_connect_state.3 \ man/man3/SSL_set_fd.3 \ +man/man3/SSL_set_initial_peer_addr.3 \ man/man3/SSL_set_retry_verify.3 \ man/man3/SSL_set_session.3 \ man/man3/SSL_set_shutdown.3 \ man/man3/SSL_set_verify_result.3 \ man/man3/SSL_shutdown.3 \ man/man3/SSL_state_string.3 \ +man/man3/SSL_tick.3 \ man/man3/SSL_want.3 \ man/man3/SSL_write.3 \ man/man3/TS_RESP_CTX_new.3 \ diff --git a/doc/man3/BIO_get_rpoll_descriptor.pod b/doc/man3/BIO_get_rpoll_descriptor.pod new file mode 100644 index 00000000000..652837d924a --- /dev/null +++ b/doc/man3/BIO_get_rpoll_descriptor.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor - obtain a structure which +can be used to determine when a BIO object can next be read or written + +=head1 SYNOPSIS + + #include + + typedef struct bio_poll_descriptor_st { + int type; + union { + int fd; + union { + void *ptr; + uint64_t u64; + } custom[BIO_POLL_DESCRIPTOR_NUM_CUSTOM]; + } value; + } BIO_POLL_DESCRIPTOR; + + __owur int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc); + __owur int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc); + +=head1 DESCRIPTION + +BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), on success, fill +B<*desc> with a poll descriptor. A poll descriptor is a tagged union structure +which represents some kind of OS or non-OS resource which can be used to +synchronise on I/O availability events. + +BIO_get_rpoll_descriptor() outputs a descriptor which can be used to determine +when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor() +outputs a descriptor which can be used to determine when the BIO can +(potentially) next be written. + +It is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() +to output the same descriptor. + +Poll descriptors can represent different kinds of information. A typical kind of +resource which might be represented by a poll descriptor is an OS file +descriptor which can be used with APIs such as select(). + +The kinds of poll descriptor defined by OpenSSL are: + +=over 4 + +=item BIO_POLL_DESCRIPTOR_TYPE_NONE + +Represents the absence of a valid poll descriptor. It may be used by +BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to indicate that the +BIO is not pollable for readability or writeability respectively. + +For this type, no field within the B field of the B +is valid. + +=item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD + +The poll descriptor represents an OS socket resource. The field B +in the B is valid if it is not set to -1. + +The resource is whatever kind of handle is used by a given OS to represent +sockets, which may vary by OS. For example, on Windows, the value is a B +for use with the Winsock API. On POSIX-like platforms, it is a file descriptor. + +Where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it +should be polled for readability to determine when the BIO might next be able to +successfully complete a BIO_read() operation; likewise, where a poll descriptor +of this type is output by BIO_get_wpoll_descriptor(), it should be polled for +writeability to determine when the BIO might next be able to successfully +complete a BIO_write() operation. + +=item BIO_POLL_DESCRIPTOR_CUSTOM_START + +Type values beginning with this value (inclusive) are reserved for application +allocation for custom poll descriptor types. The field B in the +B is an array of length B. +Each entry in this array can store a void pointer or a B and can be +used by the application arbitrarily. + +=back + +Because poll descriptors are a tagged union structure, they can represent +different kinds of information. New types of poll descriptor may be defined, +including by applications, according to their needs. + +=head1 RETURN VALUES + +The functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 +on success and 0 on failure. + +These functions are permitted to succeed and initialise B<*desc> with a poll +descriptor of type B to indicate that the BIO is +not pollable for readability or writeability respectively. + +=head1 SEE ALSO + +L, L, L, +L, L + +=head1 HISTORY + +The SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() functions were +added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index a90b22d9847..efc4e60de2a 100644 --- a/doc/man3/SSL_get_error.pod +++ b/doc/man3/SSL_get_error.pod @@ -60,8 +60,8 @@ is set. See L for more details. The operation did not complete and can be retried later. -B is returned when the last operation was a read -operation from a nonblocking B. +For non-QUIC SSL objects, B is returned when the last +operation was a read operation from a nonblocking B. It means that not enough data was available at this time to complete the operation. If at a later time the underlying B has data available for reading the same @@ -72,9 +72,10 @@ still unprocessed data available at either the B or the B layer, even for a blocking B. See L for more information. -B is returned when the last operation was a write -to a nonblocking B and it was unable to sent all data to the B. -When the B is writable again, the same function can be called again. +For non-QUIC SSL objects, B is returned when the last +operation was a write to a nonblocking B and it was unable to sent all data +to the B. When the B is writable again, the same function can be +called again. Note that the retry may again lead to an B or B condition. @@ -82,6 +83,15 @@ There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level. +For QUIC SSL objects, the meaning of B and +B have different but largely compatible semantics. Since +QUIC implements its own flow control and uses UDP datagrams, backpressure +conditions in terms of the underlying BIO providing network I/O are not directly +relevant to the circumstances in which these errors are produced. In particular, +B indicates that the internal send buffer for a given QUIC +stream has been filled. Likewise, B indicates that the +internal receive buffer for a given QUIC stream is empty. + It is safe to call SSL_read() or SSL_read_ex() when more data is available even when the call that set this error was an SSL_write() or SSL_write_ex(). However, if the call was an SSL_write() or SSL_write_ex(), it should be called diff --git a/doc/man3/SSL_get_rpoll_descriptor.pod b/doc/man3/SSL_get_rpoll_descriptor.pod new file mode 100644 index 00000000000..a23fbfe86e0 --- /dev/null +++ b/doc/man3/SSL_get_rpoll_descriptor.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_want_net_read, +SSL_want_net_write - obtain information which can be used to determine when +network I/O can be performed + +=head1 SYNOPSIS + + #include + + __owur int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc); + __owur int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc); + __owur int SSL_want_net_read(SSL *s); + __owur int SSL_want_net_write(SSL *s); + +=head1 DESCRIPTION + +The functions SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() can be +used to determine when an SSL object which represents a QUIC connection can +perform useful network I/O, so that an application using a QUIC connection SSL +object in nonblocking mode can determine when it should call SSL_tick(). + +On success, these functions output poll descriptors. For more information on +poll descriptors, see L. + +The functions SSL_want_net_read() and SSL_want_net_write() return 1 or 0 +depending on whether the SSL object is currently interested in receiving data +from the network and/or writing data to the network respectively. +If an SSL object is not interested in reading data from the network at the +current time, SSL_want_net_read() will return 0; likewise, if an SSL object is +not interested in writing data to the network at the current time, +SSL_want_net_write() will return 0. + +The intention is that an application using QUIC in nonblocking mode can use +these calls, in conjunction with L to wait for network +I/O conditions which allow the SSL object to perform useful work. When such a +condition arises, L should be called. + +In particular, the expected usage is as follows: + +=over 4 + +=item * + +SSL_tick() should be called whenever the timeout returned by +SSL_get_tick_timeout(3) (if any) expires + +=item * + +If the last call to SSL_want_net_read() returned 1, SSL_tick() should be called +whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes +readable. + +=item * + +If the last call to SSL_want_net_write() returned 1, SSL_tick() should be called +whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes +writable. + +=back + +The return values of the SSL_want_net_read() and SSL_want_net_write() functions +may change in response to any call to the SSL object other than +SSL_want_net_read(), SSL_want_net_write(), SSL_get_rpoll_descriptor(), +SSL_get_wpoll_descriptor() and SSL_get_tick_timeout(). + +These functions are not supported on non-QUIC SSL objects. + +=head1 RETURN VALUES + +These functions return 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +The SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_want_net_read() +and SSL_want_net_write() functions were added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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/doc/man3/SSL_get_tick_timeout.pod b/doc/man3/SSL_get_tick_timeout.pod new file mode 100644 index 00000000000..7fe66c9a952 --- /dev/null +++ b/doc/man3/SSL_get_tick_timeout.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_get_tick_timeout - determine when an SSL object next needs to be ticked + +=head1 SYNOPSIS + + #include + + __owur int SSL_get_tick_timeout(SSL *s, struct timeval *tv); + +=head1 DESCRIPTION + +SSL_get_tick_timeout() determines when the SSL object next needs to perform +internal processing due to the passage of time. It is currently applicable only +to DTLS and QUIC connection SSL objects, and is not supported on other kinds of +SSL object. + +Calling SSL_get_tick_timeout() results in B<*tv> being written with an amount of +time left before the SSL object needs to be ticked. If the SSL object needs to +be ticked immediately, it is set to zero; if the SSL object currently does not +need to be ticked at any point in the future, B is set to -1, +representing infinity. + +Note that the value output by a call to SSL_get_tick_timeout() may change as a +result of other calls to the SSL object. + +Once the timeout expires, SSL_tick() should be called to handle any internal +processing which is due; for more information, see L. + +=head1 RETURN VALUES + +Returns 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_get_tick_timeout() function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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/doc/man3/SSL_set_blocking_mode.pod b/doc/man3/SSL_set_blocking_mode.pod new file mode 100644 index 00000000000..328e2709bf6 --- /dev/null +++ b/doc/man3/SSL_set_blocking_mode.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +SSL_set_blocking_mode, SSL_get_blocking_mode - configure blocking mode for a +QUIC SSL object + +=head1 SYNOPSIS + + #include + + __owur int SSL_set_blocking_mode(SSL *s, int blocking); + __owur int SSL_get_blocking_mode(SSL *s); + +=head1 DESCRIPTION + +SSL_set_blocking_mode() can be used to enable or disable blocking mode on a QUIC +connection SSL object. By default, blocking is enabled, unless the SSL object is +configured to use an underlying read or write BIO which cannot provide a poll +descriptor (see L), as blocking mode cannot be +supported in this case. + +To enable blocking mode, call SSL_set_blocking_mode() with B set to 1; +to disable it, call SSL_set_blocking_mode() with B set to 0. + +To retrieve the current blocking mode, call SSL_get_blocking_mode(). + +Blocking mode means that calls such as SSL_read() and SSL_write() will block +until the requested operation can be performed. In nonblocking mode, these +calls will fail if the requested operation cannot be performed immediately; see +L. + +These functions are only applicable to QUIC connection SSL objects. Other kinds +of SSL object, such as those for TLS, automatically function in blocking or +nonblocking mode based on whether the underlying network read and write BIOs +provided to the SSL object are themselves configured in nonblocking mode. + +Where a QUIC connection SSL object is used in nonblocking mode, an application +is responsible for ensuring that the SSL object is ticked regularly; see +L. + +=head1 RETURN VALUES + +SSL_set_blocking_mode() returns 1 on success and 0 on failure. The function +fails if called on a SSL object which does not represent a QUIC connection, +or if blocking mode cannot be used for the given connection. + +SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns +-1 if called on an unsupported SSL object. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_set_blocking_mode() and SSL_get_blocking_mode() functions were added in +OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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/doc/man3/SSL_set_initial_peer_addr.pod b/doc/man3/SSL_set_initial_peer_addr.pod new file mode 100644 index 00000000000..9190198682f --- /dev/null +++ b/doc/man3/SSL_set_initial_peer_addr.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_set_initial_peer_addr - set the initial peer address for a QUIC connection + +=head1 SYNOPSIS + + #include + + __owur int SSL_set_initial_peer_addr(SSL *s, const BIO_ADDR *addr); + +=head1 DESCRIPTION + +SSL_set_initial_peer_addr() sets the initial destination peer address to be used +for the purposes of establishing a QUIC connection in client mode. This function +can be used only on a QUIC connection SSL object, and can be used only before a +connection attempt is first made. B must point to a B +representing a UDP destination address of the server to connect to. + +In some cases, the initial destination peer address can be detected +automatically when the SSL object is first provided with a suitable BIO. This +behaviour can be overridden by calling SSL_set_initial_peer_addr() explicitly. + +The destination address used by QUIC may change over time in response to +connection events, such as connection migration (where supported). +SSL_set_initial_peer_addr() configures the destination address used for initial +connection establishment, and does not confer any guarantee about the +destination address being used for communication at any later time in the +connection lifecycle. + +=head1 RETURN VALUES + +Returns 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_set_initial_peer_addr() function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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/doc/man3/SSL_tick.pod b/doc/man3/SSL_tick.pod new file mode 100644 index 00000000000..5aab534dd7e --- /dev/null +++ b/doc/man3/SSL_tick.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +SSL_tick - advance asynchronous state machine and perform network I/O + +=head1 SYNOPSIS + + #include + + int SSL_tick(SSL *ssl); + +=head1 DESCRIPTION + +SSL_tick() performs any internal processing which is due on a SSL object. The +exact operations performed by SSL_tick() vary depending on what kind of protocol +is being used with the given SSL object. For example, SSL_tick() may handle +timeout events which have become due, or may attempt, to the extent currently +possible, to perform network I/O operations on one of the BIOs underlying the +SSL object. + +The primary use case for SSL_tick() is to allow an application which uses +OpenSSL in nonblocking mode to give OpenSSL an opportunity to handle timer +events, or to respond to the availability of new data to be read from an +underlying BIO, or to respond to the opportunity to write pending data to an +underlying BIO. + +SSL_tick() can be used only with the following types of SSL object: + +=over 4 + +=item DTLS SSL objects + +Using SSL_tick() on an SSL object being used with a DTLS method allows timeout +events to be handled properly. This is equivalent to a call to +DTLSv1_handle_timeout(). Since SSL_tick() handles a superset of the use cases of +DTLSv1_handle_timeout(), it should be preferred for new applications which do +not require support for OpenSSL 3.1 or older. + +=item QUIC connection SSL objects + +Using SSL_tick() on an SSL object which represents a QUIC connection allows +timeout events to be handled properly, as well as incoming network data to be +processed, and queued outgoing network data to be written, if the underlying BIO +has the capacity to accept it. + +Ordinarily, when an application uses an SSL object in blocking mode, it does not +need to call SSL_tick() because OpenSSL performs ticking internally on an +automatic basis. However, if an application uses a QUIC connection in +nonblocking mode, it must at a minimum ensure that SSL_tick() is called +periodically to allow timeout events to be handled. An application can +find out when it next needs to call SSL_tick() for this purpose (if at all) by +calling SSL_get_tick_timeout(). + +Calling SSL_tick() on a QUIC connection SSL object being used in blocking mode +is not necessary unless no I/O calls (such as SSL_read() or SSL_write()) will be +made to the object for a substantial period of time. So long as at least one +call to the SSL object is blocking, no such call is needed. However, SSL_tick() +may optionally be used on a QUIC connection object if desired. + +=begin comment + +TODO(QUIC): Update the above paragraph once we support thread assisted mode. + +=end comment + +=back + +=head1 RETURN VALUES + +Returns 1 on success and 0 on failure. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +The SSL_tick() function was added in OpenSSL 3.2. + +=head1 COPYRIGHT + +Copyright 2000-2022 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