From d51398b9984d31eab275250a650c2621f3ebdf0d Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Mon, 22 Jan 2024 11:42:41 +0000 Subject: [PATCH] QUIC: Add documentation for tuning API Reviewed-by: Neil Horman Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/23360) --- doc/build.info | 6 + doc/man3/SSL_get_value_uint.pod | 222 ++++++++++++++++++++++++++++++++ include/openssl/ssl.h.in | 41 ++++++ util/libssl.num | 2 + util/other.syms | 19 +++ 5 files changed, 290 insertions(+) create mode 100644 doc/man3/SSL_get_value_uint.pod diff --git a/doc/build.info b/doc/build.info index 76fe803f41..a5f004107a 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2615,6 +2615,10 @@ DEPEND[html/man3/SSL_get_stream_read_state.html]=man3/SSL_get_stream_read_state. GENERATE[html/man3/SSL_get_stream_read_state.html]=man3/SSL_get_stream_read_state.pod DEPEND[man/man3/SSL_get_stream_read_state.3]=man3/SSL_get_stream_read_state.pod GENERATE[man/man3/SSL_get_stream_read_state.3]=man3/SSL_get_stream_read_state.pod +DEPEND[html/man3/SSL_get_value_uint.html]=man3/SSL_get_value_uint.pod +GENERATE[html/man3/SSL_get_value_uint.html]=man3/SSL_get_value_uint.pod +DEPEND[man/man3/SSL_get_value_uint.3]=man3/SSL_get_value_uint.pod +GENERATE[man/man3/SSL_get_value_uint.3]=man3/SSL_get_value_uint.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 @@ -3577,6 +3581,7 @@ html/man3/SSL_get_session.html \ html/man3/SSL_get_shared_sigalgs.html \ html/man3/SSL_get_stream_id.html \ html/man3/SSL_get_stream_read_state.html \ +html/man3/SSL_get_value_uint.html \ html/man3/SSL_get_verify_result.html \ html/man3/SSL_get_version.html \ html/man3/SSL_group_to_name.html \ @@ -4220,6 +4225,7 @@ man/man3/SSL_get_session.3 \ man/man3/SSL_get_shared_sigalgs.3 \ man/man3/SSL_get_stream_id.3 \ man/man3/SSL_get_stream_read_state.3 \ +man/man3/SSL_get_value_uint.3 \ man/man3/SSL_get_verify_result.3 \ man/man3/SSL_get_version.3 \ man/man3/SSL_group_to_name.3 \ diff --git a/doc/man3/SSL_get_value_uint.pod b/doc/man3/SSL_get_value_uint.pod new file mode 100644 index 0000000000..9b2a30aea4 --- /dev/null +++ b/doc/man3/SSL_get_value_uint.pod @@ -0,0 +1,222 @@ +=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 - manage +negotiable features and configuration values for a SSL object + +=head1 SYNOPSIS + + #include + + 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 + +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); + +=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 and are as follows: + +=over 4 + +=item B + +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 + +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. + +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 + +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. + +You can access values in this class using the convenience macro +SSL_get_feature_peer_request_uint() for brevity. + +=item B + +Values in this value class are read-only, and represent the value which was +actually negotated 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_neogtiated_uint() for brevity. + +=back + +=head1 CONFIGURABLE VALUES FOR QUIC CONNECTIONS + +The following configurable values are supported for QUIC connection SSL objects: + +=over 4 + +=item B + +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. + +=item B + +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 could be called 100 +times to create 100 bidirectional streams before L would +block or fail due to backpressure. + +Can be queried using the convenience macro +SSL_get_quic_stream_bidi_local_avail(). + +=item B + +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 + +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 + +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(). + +=back + +No configurable values are currently defined for QUIC stream SSL objects or for +other kinds of SSL object. + +=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, L, +L, L, +L, L, +L, L + +=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. + +=cut diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in index 8f1aff9fc0..9855a3836c 100644 --- a/include/openssl/ssl.h.in +++ b/include/openssl/ssl.h.in @@ -2366,6 +2366,47 @@ __owur int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info, size_t info_len); +# define SSL_VALUE_CLASS_GENERIC 0 +# define SSL_VALUE_CLASS_FEATURE_REQUEST 1 +# define SSL_VALUE_CLASS_FEATURE_PEER_REQUEST 2 +# define SSL_VALUE_CLASS_FEATURE_NEGOTIATED 3 + +# define SSL_VALUE_NONE 0 +# define SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL 1 +# define SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL 2 +# define SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL 3 +# define SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL 4 +# define SSL_VALUE_QUIC_IDLE_TIMEOUT 0x8000 + +int SSL_get_value_uint(SSL *s, uint32_t class_, uint32_t id, uint64_t *v); +int SSL_set_value_uint(SSL *s, uint32_t class_, uint32_t id, uint64_t v); + +# define SSL_get_generic_value_uint(ssl, id, v) \ + SSL_get_value_uint((ssl), SSL_VALUE_CLASS_GENERIC, (id), (v)) +# define SSL_set_generic_value_uint(ssl, id, v) \ + SSL_set_value_uint((ssl), SSL_VALUE_CLASS_GENERIC, (id), (v)) +# define SSL_get_feature_request_uint(ssl, id, v) \ + SSL_get_value_uint((ssl), SSL_VALUE_CLASS_FEATURE_REQUEST, (id), (v)) +# define SSL_set_feature_request_uint(ssl, id, v) \ + SSL_set_value_uint((ssl), SSL_VALUE_CLASS_FEATURE_REQUEST, (id), (v)) +# define SSL_get_feature_peer_request_uint(ssl, id, v) \ + SSL_get_value_uint((ssl), SSL_VALUE_CLASS_FEATURE_PEER_REQUEST, (id), (v)) +# define SSL_get_feature_negotiated_uint(ssl, id, v) \ + SSL_get_value_uint((ssl), SSL_VALUE_CLASS_FEATURE_NEGOTIATED, (id), (v)) + +# define SSL_get_quic_stream_bidi_local_avail(ssl, value) \ + SSL_get_generic_value_uint((ssl), SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL, \ + (value)) +# define SSL_get_quic_stream_bidi_remote_avail(ssl, value) \ + SSL_get_generic_value_uint((ssl), SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL, \ + (value)) +# define SSL_get_quic_stream_uni_local_avail(ssl, value) \ + SSL_get_generic_value_uint((ssl), SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL, \ + (value)) +# define SSL_get_quic_stream_uni_remote_avail(ssl, value) \ + SSL_get_generic_value_uint((ssl), SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, \ + (value)) + # ifndef OPENSSL_NO_DEPRECATED_1_1_0 # define SSL_cache_hit(s) SSL_session_reused(s) # endif diff --git a/util/libssl.num b/util/libssl.num index c58d3330fb..7010f32daa 100644 --- a/util/libssl.num +++ b/util/libssl.num @@ -578,3 +578,5 @@ SSL_get_event_timeout 578 3_2_0 EXIST::FUNCTION: SSL_get0_group_name 579 3_2_0 EXIST::FUNCTION: SSL_is_stream_local 580 3_2_0 EXIST::FUNCTION: SSL_write_ex2 ? 3_3_0 EXIST::FUNCTION: +SSL_get_value_uint ? 3_3_0 EXIST::FUNCTION: +SSL_set_value_uint ? 3_3_0 EXIST::FUNCTION: diff --git a/util/other.syms b/util/other.syms index 9dfd3cba1d..048223b424 100644 --- a/util/other.syms +++ b/util/other.syms @@ -650,6 +650,16 @@ SSL_want_read define SSL_want_retry_verify define SSL_want_write define SSL_want_x509_lookup define +SSL_get_feature_request_uint define +SSL_set_feature_request_uint define +SSL_get_feature_peer_request_uint define +SSL_get_feature_negotiated_uint define +SSL_get_generic_value_uint define +SSL_set_generic_value_uint define +SSL_get_quic_stream_bidi_local_avail define +SSL_get_quic_stream_bidi_remote_avail define +SSL_get_quic_stream_uni_local_avail define +SSL_get_quic_stream_uni_remote_avail define SSL_CONN_CLOSE_FLAG_LOCAL define SSL_CONN_CLOSE_FLAG_TRANSPORT define SSLv23_client_method define @@ -677,6 +687,15 @@ SSL_INCOMING_STREAM_POLICY_ACCEPT define SSL_INCOMING_STREAM_POLICY_AUTO define SSL_INCOMING_STREAM_POLICY_REJECT define SSL_WRITE_FLAG_CONCLUDE 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_IDLE_TIMEOUT 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 TLS_DEFAULT_CIPHERSUITES define deprecated 3.0.0 X509_CRL_http_nbio define deprecated 3.0.0 X509_http_nbio define deprecated 3.0.0 -- 2.34.1