mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-21 01:15:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

QUIC CSM: Documentation for new APIs

Browse Source 
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19703)
This commit is contained in:
Hugo Landau 2022-11-14 18:13:35 +00:00
parent a64d82485d
commit c572bed9f5
8 changed files with 525 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/build.info
View File

@ -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 \

116
doc/man3/BIO_get_rpoll_descriptor.pod Normal file
View File

@ -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 <openssl/bio.h>
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<value> field of the B<BIO_POLL_DESCRIPTOR>
is valid.
=item BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD
The poll descriptor represents an OS socket resource. The field B<value.fd>
in the B<BIO_POLL_DESCRIPTOR> 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<SOCKET>
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<value.custom> in the
B<BIO_POLL_DESCRIPTOR> is an array of length B<BIO_POLL_DESCRIPTOR_NUM_CUSTOM>.
Each entry in this array can store a void pointer or a B<uint64_t> 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<BIO_POLL_DESCRIPTOR_TYPE_NONE> to indicate that the BIO is
not pollable for readability or writeability respectively.
=head1 SEE ALSO
L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_get_wpoll_descriptor(3)>, L<bio(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

20
doc/man3/SSL_get_error.pod
View File

@ -60,8 +60,8 @@ is set. See L<SSL_CTX_set_options(3)> for more details.
The operation did not complete and can be retried later.
B<SSL_ERROR_WANT_READ> is returned when the last operation was a read
operation from a nonblocking B<BIO>.
For non-QUIC SSL objects, B<SSL_ERROR_WANT_READ> is returned when the last
operation was a read operation from a nonblocking B<BIO>.
It means that not enough data was available at this time to complete the
operation.
If at a later time the underlying B<BIO> has data available for reading the same
@ -72,9 +72,10 @@ still unprocessed data available at either the B<SSL> or the B<BIO> layer, even
for a blocking B<BIO>.
See L<SSL_read(3)> for more information.
B<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write
to a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>.
When the B<BIO> is writable again, the same function can be called again.
For non-QUIC SSL objects, B<SSL_ERROR_WANT_WRITE> is returned when the last
operation was a write to a nonblocking B<BIO> and it was unable to sent all data
to the B<BIO>. When the B<BIO> is writable again, the same function can be
called again.
Note that the retry may again lead to an B<SSL_ERROR_WANT_READ> or
B<SSL_ERROR_WANT_WRITE> 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<SSL_ERROR_WANT_READ> and
B<SSL_ERROR_WANT_WRITE> 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<SSL_ERROR_WANT_WRITE> indicates that the internal send buffer for a given QUIC
stream has been filled. Likewise, B<SSL_ERROR_WANT_READ> 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

93
doc/man3/SSL_get_rpoll_descriptor.pod Normal file
View File

@ -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 <openssl/ssl.h>
__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<BIO_get_rpoll_descriptor(3)>.
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<SSL_get_tick_timeout(3)> to wait for network
I/O conditions which allow the SSL object to perform useful work. When such a
condition arises, L<SSL_tick(3)> 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<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<ssl(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

53
doc/man3/SSL_get_tick_timeout.pod Normal file
View File

@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_get_tick_timeout - determine when an SSL object next needs to be ticked
=head1 SYNOPSIS
#include <openssl/ssl.h>
__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<tv_sec> 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<SSL_tick(3)>.
=head1 RETURN VALUES
Returns 1 on success and 0 on failure.
=head1 SEE ALSO
L<SSL_tick(3)>, L<ssl(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

69
doc/man3/SSL_set_blocking_mode.pod Normal file
View File

@ -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 <openssl/ssl.h>
__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<BIO_get_rpoll_descriptor(3)>), as blocking mode cannot be
supported in this case.
To enable blocking mode, call SSL_set_blocking_mode() with B<blocking> set to 1;
to disable it, call SSL_set_blocking_mode() with B<blocking> 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<SSL_get_error(3)>.
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<SSL_tick(3)>.
=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<SSL_tick(3)>, L<ssl(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

53
doc/man3/SSL_set_initial_peer_addr.pod Normal file
View File

@ -0,0 +1,53 @@
=pod
=head1 NAME
SSL_set_initial_peer_addr - set the initial peer address for a QUIC connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
__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<addr> must point to a B<BIO_ADDR>
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<BIO_ADDR(3)>, L<ssl(7)>
=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<https://www.openssl.org/source/license.html>.
=cut

90
doc/man3/SSL_tick.pod Normal file
View File

@ -0,0 +1,90 @@
=pod
=head1 NAME
SSL_tick - advance asynchronous state machine and perform network I/O
=head1 SYNOPSIS
#include <openssl/ssl.h>
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<SSL_get_tick_timeout(3)>, L<ssl(7)>
=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<https://www.openssl.org/source/license.html>.
=cut