SSL_GET_VALUE_UINT(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 NAME 💖

okay bestie, this is the OpenSSL page for SSL_GET_VALUE_UINT(3ossl), and it’s basically the control panel for negotiable features and configuration values on an SSL object 🎛️✨

The whole squad on this page is: 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_QUIC_MAX_PENDING_CONNS, 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, SSL_VALUE_STREAM_WRITE_BUF_SIZE, SSL_get_stream_write_buf_size, SSL_VALUE_STREAM_WRITE_BUF_USED, SSL_get_stream_write_buf_used, SSL_VALUE_STREAM_WRITE_BUF_AVAIL, SSL_get_stream_write_buf_avail — all here to manage negotiable features and configuration values for an SSL object 💅

✨ SYNOPSIS ✨

here’s the include and the signatures, kept exactly as-is because we do not mess with code in this house 🫶

        #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_QUIC_MAX_PENDING_CONNS

        #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

        #define SSL_VALUE_STREAM_WRITE_BUF_SIZE
        #define SSL_VALUE_STREAM_WRITE_BUF_USED
        #define SSL_VALUE_STREAM_WRITE_BUF_AVAIL

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);

        int SSL_get_stream_write_buf_size(SSL *ssl, uint64_t *value);
        int SSL_get_stream_write_buf_avail(SSL *ssl, uint64_t *value);
        int SSL_get_stream_write_buf_used(SSL *ssl, uint64_t *value);

🦋 DESCRIPTION 🦋

SSL_get_value_uint() and SSL_set_value_uint() are your access pass to configurable parameters on a given SSL object. Amongst other things, they’re used to give you control over the feature negotiation process during establishment of a connection, and to give you access to statistics about that connection. no cap 🔥

SSL_get_value_uint() and SSL_set_value_uint() get and set configurable values inside a given value class. The value classes are enumerated by SSL_VALUE_CLASS, and here’s the lineup:

🌸 SSL_VALUE_CLASS_GENERIC

Values in this class do not participate in the feature negotiation process. They might represent connection parameters which do not participate in explicit negotiation, or they might 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.

💜 SSL_VALUE_CLASS_FEATURE_REQUEST

Values in this class are read-write, and they represent what the local party is requesting during feature negotiation. Heads up though: such a request will not necessarily be honoured — see 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.

🎀 SSL_VALUE_CLASS_FEATURE_PEER_REQUEST

Values in this value class are read-only, and they represent what was requested by a peer during feature negotiation. Such a request has not necessarily been honoured; see SSL_VALUE_CLASS_FEATURE_NEGOTIATED.

You can access values in this class using the convenience macro SSL_get_feature_peer_request_uint() for brevity.

👑 SSL_VALUE_CLASS_FEATURE_NEGOTIATED

Values in this value class are read-only, and they 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.

🦋 CONFIGURABLE VALUES FOR QUIC OBJECTS 🦋

okay so these are the configurable values that QUIC SSL objects support 💅 whether a value works on a QUIC connection SSL object or on a QUIC stream SSL object is literally spelled out next to each one below. and heads up — values supported for QUIC stream SSL objects also work on QUIC connection SSL objects if they have a default stream attached. slay ✨

also, super important: SSL_get_value() does not make internal event processing happen unless the docs for that specific value say otherwise. no surprise background work, ngl 🫶

  • SSL_VALUE_QUIC_IDLE_TIMEOUT (connection object) — this one's a negotiated feature value. it configures the QUIC idle timeout you want, in milliseconds, where 0 means "no idle timeout at all, we live forever 💀". you can only configure it before the connection is established — after that it's locked in, no takebacks. this release of OpenSSL uses a default of 30 seconds, and that default might change between releases, so don't get too attached 👑
  • SSL_VALUE_QUIC_MAX_PENDING_CONNS (listener object) — generic value. sets the limit on channels (connection objects) that a QUIC server can insert into the list of pending connections. a pending connection is one that the local application still needs to SSL_accept_connection(3) before it can get an SSL connection object out of it, and calling SSL_accept_connection(3) is what removes it from the pending queue. the default limit for pending connections is 256. if a QUIC server receives an INITIAL QUIC packet while the pending connections queue is full, that packet is silently discarded 🙈 (yes, silently, it's giving ghosted). setting the value to zero disables the limit entirely.
  • SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL (connection object) — generic read-only statistical value: how many bidirectional, locally-initiated streams are available to be created (but not yet created). like, a value of 100 means you could call SSL_new_stream(3) 100 times and actually create 100 bidirectional streams before SSL_new_stream(3) would block or fail from backpressure. the way that number just tells you your budget 🎀

can be queried using the convenience macro SSL_get_quic_stream_bidi_local_avail().

  • SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL (connection object) — same vibe as above, but it's 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().

  • SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL (connection object) — again, same as above, but this is the number of bidirectional, remotely-initiated streams available to be created (but not yet created) by the peer. so basically how many streams the local endpoint has authorised the peer to create, in terms of QUIC stream creation flow control. you're the one handing out the permits 💅

can be queried using the convenience macro SSL_get_quic_stream_bidi_remote_avail().

  • SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL (connection object) — as above, but for 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().

  • SSL_VALUE_EVENT_HANDLING_MODE (connection or stream object) — generic value, an integer, and it picks which event handling mode is in play. it takes one of these:
    • SSL_VALUE_EVENT_HANDLING_MODE_INHERIT — when set, the event handling mode used is inherited from whatever was set on the parent connection (for a stream); for a connection, it defaults to the implicit event handling model. and when a new connection is created, or a new stream is created or accepted, it defaults to this setting. it's the "ask your parent" option, lowkey iconic 🌸
    • SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT (Implicit event handling) — set it to this and you get the implicit event handling model. under this model, QUIC objects automatically do background event processing (equivalent to a call to SSL_handle_events(3)) whenever I/O functions like SSL_read_ex(3) or SSL_write_ex(3) get called on a QUIC SSL object. it helps keep the QUIC connection healthy and makes sure incoming datagrams and timeout events actually get processed. main character energy, it just handles itself 🔥
    • SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT (Explicit event handling) — set it to this and you get the explicit event handling model. under this model, nonblocking calls to I/O functions like SSL_read_ex(3) or SSL_write_ex(3) do not cause 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 gives your app way more control over exactly when QUIC event processing happens. if you pick this model, it is the application's responsibility to call SSL_handle_events(3) as and when the QUIC implementation needs it — check out the SSL_get_rpoll_descriptor(3) man page for more info 👑
picking this model does not change how blocking I/O calls behave — those keep using the implicit event handling model. so if you're running explicit mode, you'll generally want to turn off blocking operation with SSL_set_blocking_mode(3). fr fr, don't skip this step 😭

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() that switches this value back to the implicit event handling model doesn't itself cause implicit event handling to happen — that'll happen on the next I/O API call. same energy the other way: a call to SSL_set_value_uint() that switches this value over to the explicit event handling model will not cause event handling to occur before that transition is made. 🎀

this value controls whether implicit event handling happens when you make an I/O API call on the SSL object it's set on. but — and this is the plot twist — event processing isn't confined to state relating to just that one object. example time: if you set explicit event handling on QUIC stream SSL object "A" and implicit event handling on QUIC stream SSL object "B", a call to an I/O function on "B" could still change state on "A". in other words, if event handling does happen because of an API call on an object related to a connection, background event processing (like received QUIC network traffic, bestie) may affect the state of any other object related to that connection. they're all in the group chat 💀

  • SSL_VALUE_STREAM_WRITE_BUF_SIZE (stream object) — generic read-only statistical value: the size of the write buffer allocated to hold data written to a stream with SSL_write_ex(3), held there until it's transmitted and then acknowledged by the peer. this value can change at any time, because buffer sizes get optimised in response to network conditions to optimise throughput. it's giving adaptive 🦋

can be queried using the convenience macro SSL_get_stream_write_buf_size().

  • SSL_VALUE_STREAM_WRITE_BUF_USED (stream object) — generic read-only statistical value: the number of bytes currently consumed in the write buffer that have yet to be acknowledged by the peer. successful calls to SSL_write_ex(3) that accept data make this number go up 📈, and then it goes down as the peer acknowledges data.

can be queried using the convenience macro SSL_get_stream_write_buf_used().

  • SSL_VALUE_STREAM_WRITE_BUF_AVAIL (stream object) — generic read-only statistical value: the number of bytes available in the write buffer that have yet to be consumed by calls to SSL_write_ex(3). successful calls to SSL_write_ex(3) that accept data make this number go down 📉, and it goes back up as data is acknowledged by the peer. it may also change if the buffer gets resized automatically to optimise throughput.

can be queried using the convenience macro SSL_get_stream_write_buf_avail().

and ngl, there are currently no configurable values defined for non-QUIC SSL objects. sorry to the non-QUIC girlies 💅

✨ RETURN VALUES ✨

returns 1 on success or 0 on failure 😭 and yeah, this function can fail for a whole bunch of reasons:

  • an argument is invalid (e.g. NULL pointer or invalid class).
  • the given value isn't supported by the SSL object it was called on.
  • the given operation (get or set) isn't supported by the specified configurable value.
  • you're trying to modify the given value and that value simply isn't modifiable at this time. not right now bestie 🫶

🌈 SEE ALSO 🌈

SSL_ctrl(3), SSL_get_accept_stream_queue_len(3), SSL_get_stream_read_state(3), SSL_get_stream_write_state(3), SSL_get_stream_read_error_code(3), SSL_get_stream_write_error_code(3), SSL_set_default_stream_mode(3), SSL_set_incoming_stream_policy(3), SSL_accept_connection(3)

💜 HISTORY 💜

the value SSL_VALUE_QUIC_MAX_PENDING_CONNS was added in OpenSSL 4.1 and then ported back to older releases 4.0.2, 3.6.4 and 3.5.8. iconic of them to backport it 🎀

and the remaining functions and values described here were all added in OpenSSL 3.3. periodt ✨

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 <https://www.openssl.org/source/license.html>.

okay that's the whole page, bestie — you ate that 💅 this was OpenSSL 3.5.0, dated 2026-09-25, and it's the SSL_GET_VALUE_UINT(3ossl) man page. go forth and configure your values 🦋🌸💖

📦 where this page comes from