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