mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
a768a796f2
Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Neil Horman <nhorman@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/23535)
306 lines
12 KiB
Plaintext
306 lines
12 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_get_value_uint, SSL_set_value_uint, SSL_get_generic_value_uint,
|
|
SSL_set_generic_value_uint, SSL_get_feature_request_uint,
|
|
SSL_set_feature_request_uint, SSL_get_feature_peer_request_uint,
|
|
SSL_get_feature_negotiated_uint, SSL_get_quic_stream_bidi_local_avail,
|
|
SSL_get_quic_stream_bidi_remote_avail, SSL_get_quic_stream_uni_local_avail,
|
|
SSL_get_quic_stream_uni_remote_avail, SSL_VALUE_CLASS_GENERIC,
|
|
SSL_VALUE_CLASS_FEATURE_REQUEST, SSL_VALUE_CLASS_FEATURE_PEER_REQUEST,
|
|
SSL_VALUE_CLASS_FEATURE_NEGOTIATED, SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL,
|
|
SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL, SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL,
|
|
SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, SSL_VALUE_QUIC_IDLE_TIMEOUT,
|
|
SSL_VALUE_EVENT_HANDLING_MODE,
|
|
SSL_VALUE_EVENT_HANDLING_MODE_INHERIT,
|
|
SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT,
|
|
SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT,
|
|
SSL_get_event_handling_mode,
|
|
SSL_set_event_handling_mode -
|
|
manage negotiable features and configuration values for a SSL object
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
int SSL_get_value_uint(SSL *ssl, uint32_t class_, uint32_t id,
|
|
uint64_t *value);
|
|
int SSL_set_value_uint(SSL *ssl, uint32_t class_, uint32_t id,
|
|
uint64_t value);
|
|
|
|
#define SSL_VALUE_CLASS_GENERIC
|
|
#define SSL_VALUE_CLASS_FEATURE_REQUEST
|
|
#define SSL_VALUE_CLASS_FEATURE_PEER_REQUEST
|
|
#define SSL_VALUE_CLASS_FEATURE_NEGOTIATED
|
|
|
|
#define SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL
|
|
#define SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL
|
|
#define SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL
|
|
#define SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL
|
|
#define SSL_VALUE_QUIC_IDLE_TIMEOUT
|
|
|
|
#define SSL_VALUE_EVENT_HANDLING_MODE
|
|
#define SSL_VALUE_EVENT_HANDLING_MODE_INHERIT
|
|
#define SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT
|
|
#define SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT
|
|
|
|
The following convenience macros can also be used:
|
|
|
|
int SSL_get_generic_value_uint(SSL *ssl, uint32_t id, uint64_t *value);
|
|
int SSL_set_generic_value_uint(SSL *ssl, uint32_t id, uint64_t value);
|
|
|
|
int SSL_get_feature_request_uint(SSL *ssl, uint32_t id, uint64_t *value);
|
|
int SSL_set_feature_request_uint(SSL *ssl, uint32_t id, uint64_t value);
|
|
|
|
int SSL_get_feature_peer_request_uint(SSL *ssl, uint32_t id, uint64_t *value);
|
|
int SSL_get_feature_negotiated_uint(SSL *ssl, uint32_t id, uint64_t *value);
|
|
|
|
int SSL_get_quic_stream_bidi_local_avail(SSL *ssl, uint64_t *value);
|
|
int SSL_get_quic_stream_bidi_remote_avail(SSL *ssl, uint64_t *value);
|
|
int SSL_get_quic_stream_uni_local_avail(SSL *ssl, uint64_t *value);
|
|
int SSL_get_quic_stream_uni_remote_avail(SSL *ssl, uint64_t *value);
|
|
|
|
int SSL_get_event_handling_mode(SSL *ssl, uint64_t *value);
|
|
int SSL_set_event_handling_mode(SSL *ssl, uint64_t value);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SSL_get_value_uint() and SSL_set_value_uint() provide access to configurable
|
|
parameters for a given SSL object. Amongst other things, they are used to
|
|
provide control over the feature negotiation process during establishment of a
|
|
connection, and access to statistics about that connection.
|
|
|
|
SSL_get_value_uint() and SSL_set_value_uint() get and set configurable values
|
|
within a given value class. The value classes are enumerated by
|
|
B<SSL_VALUE_CLASS> and are as follows:
|
|
|
|
=over 4
|
|
|
|
=item B<SSL_VALUE_CLASS_GENERIC>
|
|
|
|
Values in this class do not participate in the feature negotiation process. They
|
|
may represent connection parameters which do not participate in explicit
|
|
negotiation or provide connection statistics. Values in this class might be
|
|
read-write or read-only.
|
|
|
|
You can access values in this class using the convenience macros
|
|
SSL_get_generic_value_uint() and SSL_set_generic_value_uint() for brevity.
|
|
|
|
=item B<SSL_VALUE_CLASS_FEATURE_REQUEST>
|
|
|
|
Values in this class are read-write, and represent what the local party is
|
|
requesting during feature negotiation. Such a request will not necessarily be
|
|
honoured; see B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED>.
|
|
|
|
A value in this class may become read-only in certain circumstances; for
|
|
example, after a connection has been established, for a value which cannot be
|
|
renegotiated after connection establishment. Setting a value in this class after
|
|
connection establishment represents a request for online renegotiation of the
|
|
specified feature.
|
|
|
|
You can access values in this class using the convenience macros
|
|
SSL_get_feature_request_uint() and SSL_set_feature_request_uint() for brevity.
|
|
|
|
=item B<SSL_VALUE_CLASS_FEATURE_PEER_REQUEST>
|
|
|
|
Values in this value class are read-only, and represent what was requested by a
|
|
peer during feature negotiation. Such a request has not necessarily been
|
|
honoured; see B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED>.
|
|
|
|
You can access values in this class using the convenience macro
|
|
SSL_get_feature_peer_request_uint() for brevity.
|
|
|
|
=item B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED>
|
|
|
|
Values in this value class are read-only, and represent the value which was
|
|
actually negotiated based on both local and peer input during feature
|
|
negotiation. This is the effective value in actual use.
|
|
|
|
Attempting to read a value in this class will generally fail if the feature
|
|
negotiation process has not yet completed and the value is therefore currently
|
|
unknown, unless the nature of the feature in question causes a provisional value
|
|
to be used prior to completion of feature negotiation, in which case that value
|
|
may be returned. If an online (post-handshake) renegotiation of a feature is
|
|
in progress, retrieving the negotiated value will continue to retrieve the
|
|
previous negotiated value until that process is completed. See the documentation
|
|
of specific values for full details of its behaviour.
|
|
|
|
You can access values in this class using the convenience macro
|
|
SSL_get_feature_negotiated_uint() for brevity.
|
|
|
|
=back
|
|
|
|
=head1 CONFIGURABLE VALUES FOR QUIC CONNECTIONS
|
|
|
|
The following configurable values are supported for QUIC SSL objects. Whether a
|
|
value is supported for a QUIC connection SSL object or a QUIC stream SSL object
|
|
is indicated in the heading for each value:
|
|
|
|
=over 4
|
|
|
|
=item B<SSL_VALUE_QUIC_IDLE_TIMEOUT> (connection object)
|
|
|
|
Negotiated feature value. This configures the desired QUIC idle timeout in
|
|
milliseconds, where 0 represents a lack of an idle timeout. This feature can
|
|
only be configured prior to connection establishment and cannot be subsequently
|
|
changed.
|
|
|
|
This release of OpenSSL uses a default value of 30 seconds. This default value
|
|
may change between releases of OpenSSL.
|
|
|
|
=item B<SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL> (connection object)
|
|
|
|
Generic read-only statistical value. The number of bidirectional,
|
|
locally-initiated streams available to be created (but not yet created). For
|
|
example, a value of 100 would mean that L<SSL_new_stream(3)> could be called 100
|
|
times to create 100 bidirectional streams before L<SSL_new_stream(3)> would
|
|
block or fail due to backpressure.
|
|
|
|
Can be queried using the convenience macro
|
|
SSL_get_quic_stream_bidi_local_avail().
|
|
|
|
=item B<SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL> (connection object)
|
|
|
|
As above, but provides the number of unidirectional, locally-initiated streams
|
|
available to be created (but not yet created).
|
|
|
|
Can be queried using the convenience macro
|
|
SSL_get_quic_stream_uni_local_avail().
|
|
|
|
=item B<SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL> (connection object)
|
|
|
|
As above, but provides the number of bidirectional, remotely-initiated streams
|
|
available to be created (but not yet created) by the peer. This represents the
|
|
number of streams the local endpoint has authorised the peer to create in terms
|
|
of QUIC stream creation flow control.
|
|
|
|
Can be queried using the convenience macro
|
|
SSL_get_quic_stream_bidi_remote_avail().
|
|
|
|
=item B<SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL> (connection object)
|
|
|
|
As above, but provides the number of unidirectional, remotely-initiated streams
|
|
available to be created (but not yet created).
|
|
|
|
Can be queried using the convenience macro
|
|
SSL_get_quic_stream_uni_remote_avail().
|
|
|
|
=item B<SSL_VALUE_EVENT_HANDLING_MODE> (connection or stream object)
|
|
|
|
Generic value. This is an integer value which takes one of the following values,
|
|
and determines the event handling mode in use:
|
|
|
|
=over 4
|
|
|
|
=item B<SSL_VALUE_EVENT_HANDLING_MODE_INHERIT>
|
|
|
|
When set, the event handling mode used is inherited from the value set on the
|
|
parent connection (for a stream), or, for a connection, defaults to the implicit
|
|
event handling model.
|
|
|
|
When a new connection is created, or a new stream is created or accepted, it
|
|
defaults to this setting.
|
|
|
|
=item B<SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT> (Implicit event handling)
|
|
|
|
If set to this value, the implicit event handling model is used. Under this
|
|
model, QUIC objects will automatically perform background event processing
|
|
(equivalent to a call to L<SSL_handle_events(3)>) when calls to I/O functions
|
|
such as L<SSL_read_ex(3)> or L<SSL_write_ex(3)> are made on a QUIC SSL object.
|
|
This helps to maintain the health of the QUIC connection and ensures that
|
|
incoming datagrams and timeout events are processed.
|
|
|
|
=item B<SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT> (Explicit event handling)
|
|
|
|
If set to this value, the explicit event handling model is used. Under this
|
|
model, B<nonblocking> calls to I/O functions such as L<SSL_read_ex(3)> or
|
|
L<SSL_write_ex(3)> do not result in the automatic processing of QUIC events. Any
|
|
new incoming network traffic is not handled; no new outgoing network traffic is
|
|
generated, and pending timeout events are not processed. This allows an
|
|
application to obtain greater control over the circumstances in which QUIC event
|
|
processing occurs. If this event handling model is used, it is the application's
|
|
responsibility to call L<SSL_handle_events(3)> as and when called for by the
|
|
QUIC implementation; see the L<SSL_get_rpoll_descriptor(3)> man page for more
|
|
information.
|
|
|
|
Selecting this model does not affect the operation of blocking I/O calls, which
|
|
will continue to use the implicit event handling model. Therefore, applications
|
|
using this model will generally want to disable blocking operation using
|
|
L<SSL_set_blocking_mode(3)>.
|
|
|
|
=back
|
|
|
|
Can be configured using the convenience macros SSL_get_event_handling_mode() and
|
|
SSL_set_event_handling_mode().
|
|
|
|
A call to SSL_set_value_uint() which causes this value to switch back to the
|
|
implicit event handling model does not in itself cause implicit event handling
|
|
to occur; such handling will occur on the next I/O API call. Equally, a call to
|
|
SSL_set_value_uint() which causes this value to switch to the explicit event
|
|
handling model will not cause event handling to occur before making that
|
|
transition.
|
|
|
|
This value controls whether implicit event handling occurs when making an I/O
|
|
API call on the SSL object it is set on. However, event processing is not
|
|
confined to state which relates to only that object. For example, if you
|
|
configure explicit event handling on QUIC stream SSL object "A" and configure
|
|
implicit event handling on QUIC stream SSL object "B", a call to an I/O function
|
|
on "B" may result in state changes to "A". In other words, if event handling
|
|
does happen as a result of an API call to an object related to a connection,
|
|
processing of background events (for example, received QUIC network traffic) may
|
|
also affect the state of any other object related to a connection.
|
|
|
|
=back
|
|
|
|
No configurable values are currently defined for non-QUIC SSL objects.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
Returns 1 on success or 0 on failure. This function can fail for a number of
|
|
reasons:
|
|
|
|
=over 4
|
|
|
|
=item
|
|
|
|
An argument is invalid (e.g. NULL pointer or invalid class).
|
|
|
|
=item
|
|
|
|
The given value is not supported by the SSL object on which it was called.
|
|
|
|
=item
|
|
|
|
The given operation (get or set) is not supported by the specified
|
|
configurable value.
|
|
|
|
=item
|
|
|
|
You are trying to modify the given value and the value is not modifiable at this
|
|
time.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<SSL_ctrl(3)>, L<SSL_get_accept_stream_queue_len(3)>,
|
|
L<SSL_get_stream_read_state(3)>, L<SSL_get_stream_write_state(3)>,
|
|
L<SSL_get_stream_read_error_code(3)>, L<SSL_get_stream_write_error_code(3)>,
|
|
L<SSL_set_default_stream_mode(3)>, L<SSL_set_incoming_stream_policy(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
These functions were added in OpenSSL 3.3.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2002-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
|