1=pod 2 3=head1 NAME 4 5SSL_get_value_uint, SSL_set_value_uint, SSL_get_generic_value_uint, 6SSL_set_generic_value_uint, SSL_get_feature_request_uint, 7SSL_set_feature_request_uint, SSL_get_feature_peer_request_uint, 8SSL_get_feature_negotiated_uint, SSL_get_quic_stream_bidi_local_avail, 9SSL_get_quic_stream_bidi_remote_avail, SSL_get_quic_stream_uni_local_avail, 10SSL_get_quic_stream_uni_remote_avail, SSL_VALUE_CLASS_GENERIC, 11SSL_VALUE_CLASS_FEATURE_REQUEST, SSL_VALUE_CLASS_FEATURE_PEER_REQUEST, 12SSL_VALUE_CLASS_FEATURE_NEGOTIATED, SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL, 13SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL, SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL, 14SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, SSL_VALUE_QUIC_IDLE_TIMEOUT, 15SSL_VALUE_QUIC_MAX_PENDING_CONNS, 16SSL_VALUE_EVENT_HANDLING_MODE, 17SSL_VALUE_EVENT_HANDLING_MODE_INHERIT, 18SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT, 19SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT, 20SSL_get_event_handling_mode, 21SSL_set_event_handling_mode, 22SSL_VALUE_STREAM_WRITE_BUF_SIZE, 23SSL_get_stream_write_buf_size, 24SSL_VALUE_STREAM_WRITE_BUF_USED, 25SSL_get_stream_write_buf_used, 26SSL_VALUE_STREAM_WRITE_BUF_AVAIL, 27SSL_get_stream_write_buf_avail - 28manage negotiable features and configuration values for an SSL object 29 30=head1 SYNOPSIS 31 32 #include <openssl/ssl.h> 33 34 int SSL_get_value_uint(SSL *ssl, uint32_t class_, uint32_t id, 35 uint64_t *value); 36 int SSL_set_value_uint(SSL *ssl, uint32_t class_, uint32_t id, 37 uint64_t value); 38 39 #define SSL_VALUE_CLASS_GENERIC 40 #define SSL_VALUE_CLASS_FEATURE_REQUEST 41 #define SSL_VALUE_CLASS_FEATURE_PEER_REQUEST 42 #define SSL_VALUE_CLASS_FEATURE_NEGOTIATED 43 44 #define SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL 45 #define SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL 46 #define SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL 47 #define SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL 48 #define SSL_VALUE_QUIC_IDLE_TIMEOUT 49 #define SSL_VALUE_QUIC_MAX_PENDING_CONNS 50 51 #define SSL_VALUE_EVENT_HANDLING_MODE 52 #define SSL_VALUE_EVENT_HANDLING_MODE_INHERIT 53 #define SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT 54 #define SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT 55 56 #define SSL_VALUE_STREAM_WRITE_BUF_SIZE 57 #define SSL_VALUE_STREAM_WRITE_BUF_USED 58 #define SSL_VALUE_STREAM_WRITE_BUF_AVAIL 59 60The following convenience macros can also be used: 61 62 int SSL_get_generic_value_uint(SSL *ssl, uint32_t id, uint64_t *value); 63 int SSL_set_generic_value_uint(SSL *ssl, uint32_t id, uint64_t value); 64 65 int SSL_get_feature_request_uint(SSL *ssl, uint32_t id, uint64_t *value); 66 int SSL_set_feature_request_uint(SSL *ssl, uint32_t id, uint64_t value); 67 68 int SSL_get_feature_peer_request_uint(SSL *ssl, uint32_t id, uint64_t *value); 69 int SSL_get_feature_negotiated_uint(SSL *ssl, uint32_t id, uint64_t *value); 70 71 int SSL_get_quic_stream_bidi_local_avail(SSL *ssl, uint64_t *value); 72 int SSL_get_quic_stream_bidi_remote_avail(SSL *ssl, uint64_t *value); 73 int SSL_get_quic_stream_uni_local_avail(SSL *ssl, uint64_t *value); 74 int SSL_get_quic_stream_uni_remote_avail(SSL *ssl, uint64_t *value); 75 76 int SSL_get_event_handling_mode(SSL *ssl, uint64_t *value); 77 int SSL_set_event_handling_mode(SSL *ssl, uint64_t value); 78 79 int SSL_get_stream_write_buf_size(SSL *ssl, uint64_t *value); 80 int SSL_get_stream_write_buf_avail(SSL *ssl, uint64_t *value); 81 int SSL_get_stream_write_buf_used(SSL *ssl, uint64_t *value); 82 83=head1 DESCRIPTION 84 85SSL_get_value_uint() and SSL_set_value_uint() provide access to configurable 86parameters for a given SSL object. Amongst other things, they are used to 87provide control over the feature negotiation process during establishment of a 88connection, and access to statistics about that connection. 89 90SSL_get_value_uint() and SSL_set_value_uint() get and set configurable values 91within a given value class. The value classes are enumerated by 92B<SSL_VALUE_CLASS> and are as follows: 93 94=over 4 95 96=item B<SSL_VALUE_CLASS_GENERIC> 97 98Values in this class do not participate in the feature negotiation process. They 99may represent connection parameters which do not participate in explicit 100negotiation or provide connection statistics. Values in this class might be 101read-write or read-only. 102 103You can access values in this class using the convenience macros 104SSL_get_generic_value_uint() and SSL_set_generic_value_uint() for brevity. 105 106=item B<SSL_VALUE_CLASS_FEATURE_REQUEST> 107 108Values in this class are read-write, and represent what the local party is 109requesting during feature negotiation. Such a request will not necessarily be 110honoured; see B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED>. 111 112A value in this class may become read-only in certain circumstances; for 113example, after a connection has been established, for a value which cannot be 114renegotiated after connection establishment. Setting a value in this class after 115connection establishment represents a request for online renegotiation of the 116specified feature. 117 118You can access values in this class using the convenience macros 119SSL_get_feature_request_uint() and SSL_set_feature_request_uint() for brevity. 120 121=item B<SSL_VALUE_CLASS_FEATURE_PEER_REQUEST> 122 123Values in this value class are read-only, and represent what was requested by a 124peer during feature negotiation. Such a request has not necessarily been 125honoured; see B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED>. 126 127You can access values in this class using the convenience macro 128SSL_get_feature_peer_request_uint() for brevity. 129 130=item B<SSL_VALUE_CLASS_FEATURE_NEGOTIATED> 131 132Values in this value class are read-only, and represent the value which was 133actually negotiated based on both local and peer input during feature 134negotiation. This is the effective value in actual use. 135 136Attempting to read a value in this class will generally fail if the feature 137negotiation process has not yet completed and the value is therefore currently 138unknown, unless the nature of the feature in question causes a provisional value 139to be used prior to completion of feature negotiation, in which case that value 140may be returned. If an online (post-handshake) renegotiation of a feature is 141in progress, retrieving the negotiated value will continue to retrieve the 142previous negotiated value until that process is completed. See the documentation 143of specific values for full details of its behaviour. 144 145You can access values in this class using the convenience macro 146SSL_get_feature_negotiated_uint() for brevity. 147 148=back 149 150=head1 CONFIGURABLE VALUES FOR QUIC OBJECTS 151 152The following configurable values are supported for QUIC SSL objects. Whether a 153value is supported for a QUIC connection SSL object or a QUIC stream SSL object 154is indicated in the heading for each value. Values supported for QUIC stream SSL 155objects are also supported on QUIC connection SSL objects if they have a default 156stream attached. 157 158SSL_get_value() does not cause internal event processing to occur unless the 159documentation for a specific value specifies otherwise. 160 161=over 4 162 163=item B<SSL_VALUE_QUIC_IDLE_TIMEOUT> (connection object) 164 165Negotiated feature value. This configures the desired QUIC idle timeout in 166milliseconds, where 0 represents a lack of an idle timeout. This feature can 167only be configured prior to connection establishment and cannot be subsequently 168changed. 169 170This release of OpenSSL uses a default value of 30 seconds. This default value 171may change between releases of OpenSSL. 172 173=item B<SSL_VALUE_QUIC_MAX_PENDING_CONNS> (listener object) 174 175Generic value, sets the limit on channels (connection objects) which a QUIC server can 176insert into the list of pending connections. A pending connection is a connection 177which the local application needs to accept (L<SSL_accept_connection(3)>) in order to retrieve 178an SSL connection object. The connection is removed from the pending queue by a call 179to L<SSL_accept_connection(3)>. The default limit for pending connections is 256. An INITIAL 180QUIC packet, which is received by a QUIC server with a full pending connections 181queue, is silently discarded. Setting the value to zero disables the limit. 182 183=item B<SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL> (connection object) 184 185Generic read-only statistical value. The number of bidirectional, 186locally-initiated streams available to be created (but not yet created). For 187example, a value of 100 would mean that L<SSL_new_stream(3)> could be called 100 188times to create 100 bidirectional streams before L<SSL_new_stream(3)> would 189block or fail due to backpressure. 190 191Can be queried using the convenience macro 192SSL_get_quic_stream_bidi_local_avail(). 193 194=item B<SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL> (connection object) 195 196As above, but provides the number of unidirectional, locally-initiated streams 197available to be created (but not yet created). 198 199Can be queried using the convenience macro 200SSL_get_quic_stream_uni_local_avail(). 201 202=item B<SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL> (connection object) 203 204As above, but provides the number of bidirectional, remotely-initiated streams 205available to be created (but not yet created) by the peer. This represents the 206number of streams the local endpoint has authorised the peer to create in terms 207of QUIC stream creation flow control. 208 209Can be queried using the convenience macro 210SSL_get_quic_stream_bidi_remote_avail(). 211 212=item B<SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL> (connection object) 213 214As above, but provides the number of unidirectional, remotely-initiated streams 215available to be created (but not yet created). 216 217Can be queried using the convenience macro 218SSL_get_quic_stream_uni_remote_avail(). 219 220=item B<SSL_VALUE_EVENT_HANDLING_MODE> (connection or stream object) 221 222Generic value. This is an integer value which takes one of the following values, 223and determines the event handling mode in use: 224 225=over 4 226 227=item B<SSL_VALUE_EVENT_HANDLING_MODE_INHERIT> 228 229When set, the event handling mode used is inherited from the value set on the 230parent connection (for a stream), or, for a connection, defaults to the implicit 231event handling model. 232 233When a new connection is created, or a new stream is created or accepted, it 234defaults to this setting. 235 236=item B<SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT> (Implicit event handling) 237 238If set to this value, the implicit event handling model is used. Under this 239model, QUIC objects will automatically perform background event processing 240(equivalent to a call to L<SSL_handle_events(3)>) when calls to I/O functions 241such as L<SSL_read_ex(3)> or L<SSL_write_ex(3)> are made on a QUIC SSL object. 242This helps to maintain the health of the QUIC connection and ensures that 243incoming datagrams and timeout events are processed. 244 245=item B<SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT> (Explicit event handling) 246 247If set to this value, the explicit event handling model is used. Under this 248model, B<nonblocking> calls to I/O functions such as L<SSL_read_ex(3)> or 249L<SSL_write_ex(3)> do not result in the automatic processing of QUIC events. Any 250new incoming network traffic is not handled; no new outgoing network traffic is 251generated, and pending timeout events are not processed. This allows an 252application to obtain greater control over the circumstances in which QUIC event 253processing occurs. If this event handling model is used, it is the application's 254responsibility to call L<SSL_handle_events(3)> as and when called for by the 255QUIC implementation; see the L<SSL_get_rpoll_descriptor(3)> man page for more 256information. 257 258Selecting this model does not affect the operation of blocking I/O calls, which 259will continue to use the implicit event handling model. Therefore, applications 260using this model will generally want to disable blocking operation using 261L<SSL_set_blocking_mode(3)>. 262 263=back 264 265Can be configured using the convenience macros SSL_get_event_handling_mode() and 266SSL_set_event_handling_mode(). 267 268A call to SSL_set_value_uint() which causes this value to switch back to the 269implicit event handling model does not in itself cause implicit event handling 270to occur; such handling will occur on the next I/O API call. Equally, a call to 271SSL_set_value_uint() which causes this value to switch to the explicit event 272handling model will not cause event handling to occur before making that 273transition. 274 275This value controls whether implicit event handling occurs when making an I/O 276API call on the SSL object it is set on. However, event processing is not 277confined to state which relates to only that object. For example, if you 278configure explicit event handling on QUIC stream SSL object "A" and configure 279implicit event handling on QUIC stream SSL object "B", a call to an I/O function 280on "B" may result in state changes to "A". In other words, if event handling 281does happen as a result of an API call to an object related to a connection, 282processing of background events (for example, received QUIC network traffic) may 283also affect the state of any other object related to a connection. 284 285=item B<SSL_VALUE_STREAM_WRITE_BUF_SIZE> (stream object) 286 287Generic read-only statistical value. The size of the write buffer allocated to 288hold data written to a stream with L<SSL_write_ex(3)> until it is transmitted 289and subsequently acknowledged by the peer. This value may change at any time, as 290buffer sizes are optimised in response to network conditions to optimise 291throughput. 292 293Can be queried using the convenience macro SSL_get_stream_write_buf_size(). 294 295=item B<SSL_VALUE_STREAM_WRITE_BUF_USED> (stream object) 296 297Generic read-only statistical value. The number of bytes currently consumed 298in the write buffer which have yet to be acknowledged by the peer. Successful 299calls to L<SSL_write_ex(3)> which accept data cause this number to increase. 300This number will then decrease as data is acknowledged by the peer. 301 302Can be queried using the convenience macro SSL_get_stream_write_buf_used(). 303 304=item B<SSL_VALUE_STREAM_WRITE_BUF_AVAIL> (stream object) 305 306Generic read-only statistical value. The number of bytes available in the write 307buffer which have yet to be consumed by calls to L<SSL_write_ex(3)>. Successful 308calls to L<SSL_write_ex(3)> which accept data cause this number to decrease. 309This number will increase as data is acknowledged by the peer. It may also 310change if the buffer is resized automatically to optimise throughput. 311 312Can be queried using the convenience macro SSL_get_stream_write_buf_avail(). 313 314=back 315 316No configurable values are currently defined for non-QUIC SSL objects. 317 318=head1 RETURN VALUES 319 320Returns 1 on success or 0 on failure. This function can fail for a number of 321reasons: 322 323=over 4 324 325=item 326 327An argument is invalid (e.g. NULL pointer or invalid class). 328 329=item 330 331The given value is not supported by the SSL object on which it was called. 332 333=item 334 335The given operation (get or set) is not supported by the specified 336configurable value. 337 338=item 339 340You are trying to modify the given value and the value is not modifiable at this 341time. 342 343=back 344 345=head1 SEE ALSO 346 347L<SSL_ctrl(3)>, L<SSL_get_accept_stream_queue_len(3)>, 348L<SSL_get_stream_read_state(3)>, L<SSL_get_stream_write_state(3)>, 349L<SSL_get_stream_read_error_code(3)>, L<SSL_get_stream_write_error_code(3)>, 350L<SSL_set_default_stream_mode(3)>, L<SSL_set_incoming_stream_policy(3)>, 351L<SSL_accept_connection(3)> 352 353=head1 HISTORY 354 355The value SSL_VALUE_QUIC_MAX_PENDING_CONNS has been added in OpenSSL 4.1 356and ported to older releases 4.0.2, 3.6.4 and 3.5.8. 357 358The remaining functions and values described here were all added in OpenSSL 3.3. 359 360=head1 COPYRIGHT 361 362Copyright 2002-2026 The OpenSSL Project Authors. All Rights Reserved. 363 364Licensed under the Apache License 2.0 (the "License"). You may not use 365this file except in compliance with the License. You can obtain a copy 366in the file LICENSE in the source distribution or at 367L<https://www.openssl.org/source/license.html>. 368 369=cut 370