diff options
Diffstat (limited to 'upstream/archlinux/man3/SSL_get_value_uint.3ssl')
| -rw-r--r-- | upstream/archlinux/man3/SSL_get_value_uint.3ssl | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/SSL_get_value_uint.3ssl b/upstream/archlinux/man3/SSL_get_value_uint.3ssl new file mode 100644 index 00000000..87b90ada --- /dev/null +++ b/upstream/archlinux/man3/SSL_get_value_uint.3ssl @@ -0,0 +1,371 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "SSL_GET_VALUE_UINT 3ssl" +.TH SSL_GET_VALUE_UINT 3ssl 2024-04-28 3.3.0 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH 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, +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 \- +manage negotiable features and configuration values for a SSL object +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #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 +\& +\& #define SSL_VALUE_STREAM_WRITE_BUF_SIZE +\& #define SSL_VALUE_STREAM_WRITE_BUF_USED +\& #define SSL_VALUE_STREAM_WRITE_BUF_AVAIL +.Ve +.PP +The following convenience macros can also be used: +.PP +.Vb 2 +\& 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); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_get_value_uint()\fR and \fBSSL_set_value_uint()\fR 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. +.PP +\&\fBSSL_get_value_uint()\fR and \fBSSL_set_value_uint()\fR get and set configurable values +within a given value class. The value classes are enumerated by +\&\fBSSL_VALUE_CLASS\fR and are as follows: +.IP \fBSSL_VALUE_CLASS_GENERIC\fR 4 +.IX Item "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. +.Sp +You can access values in this class using the convenience macros +\&\fBSSL_get_generic_value_uint()\fR and \fBSSL_set_generic_value_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_REQUEST\fR 4 +.IX Item "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 \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR. +.Sp +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. +.Sp +You can access values in this class using the convenience macros +\&\fBSSL_get_feature_request_uint()\fR and \fBSSL_set_feature_request_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_PEER_REQUEST\fR 4 +.IX Item "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 \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR. +.Sp +You can access values in this class using the convenience macro +\&\fBSSL_get_feature_peer_request_uint()\fR for brevity. +.IP \fBSSL_VALUE_CLASS_FEATURE_NEGOTIATED\fR 4 +.IX Item "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. +.Sp +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. +.Sp +You can access values in this class using the convenience macro +\&\fBSSL_get_feature_negotiated_uint()\fR for brevity. +.SH "CONFIGURABLE VALUES FOR QUIC OBJECTS" +.IX Header "CONFIGURABLE VALUES FOR QUIC OBJECTS" +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. Values supported for QUIC stream SSL +objects are also supported on QUIC connection SSL objects if they have a default +stream attached. +.PP +\&\fBSSL_get_value()\fR does not cause internal event processing to occur unless the +documentation for a specific value specifies otherwise. +.IP "\fBSSL_VALUE_QUIC_IDLE_TIMEOUT\fR (connection object)" 4 +.IX Item "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. +.Sp +This release of OpenSSL uses a default value of 30 seconds. This default value +may change between releases of OpenSSL. +.IP "\fBSSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL\fR (connection object)" 4 +.IX Item "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 \fBSSL_new_stream\fR\|(3) could be called 100 +times to create 100 bidirectional streams before \fBSSL_new_stream\fR\|(3) would +block or fail due to backpressure. +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_bidi_local_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL\fR (connection object)" 4 +.IX Item "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). +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_uni_local_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL\fR (connection object)" 4 +.IX Item "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. +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_bidi_remote_avail()\fR. +.IP "\fBSSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL\fR (connection object)" 4 +.IX Item "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). +.Sp +Can be queried using the convenience macro +\&\fBSSL_get_quic_stream_uni_remote_avail()\fR. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE\fR (connection or stream object)" 4 +.IX Item "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: +.RS 4 +.IP \fBSSL_VALUE_EVENT_HANDLING_MODE_INHERIT\fR 4 +.IX Item "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. +.Sp +When a new connection is created, or a new stream is created or accepted, it +defaults to this setting. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT\fR (Implicit event handling)" 4 +.IX Item "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 \fBSSL_handle_events\fR\|(3)) when calls to I/O functions +such as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(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. +.IP "\fBSSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT\fR (Explicit event handling)" 4 +.IX Item "SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT (Explicit event handling)" +If set to this value, the explicit event handling model is used. Under this +model, \fBnonblocking\fR calls to I/O functions such as \fBSSL_read_ex\fR\|(3) or +\&\fBSSL_write_ex\fR\|(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 \fBSSL_handle_events\fR\|(3) as and when called for by the +QUIC implementation; see the \fBSSL_get_rpoll_descriptor\fR\|(3) man page for more +information. +.Sp +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 +\&\fBSSL_set_blocking_mode\fR\|(3). +.RE +.RS 4 +.Sp +Can be configured using the convenience macros \fBSSL_get_event_handling_mode()\fR and +\&\fBSSL_set_event_handling_mode()\fR. +.Sp +A call to \fBSSL_set_value_uint()\fR 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 +\&\fBSSL_set_value_uint()\fR which causes this value to switch to the explicit event +handling model will not cause event handling to occur before making that +transition. +.Sp +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. +.RE +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_SIZE\fR (stream object)" 4 +.IX Item "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 \fBSSL_write_ex\fR\|(3) until it is transmitted +and subsequently acknowledged by the peer. This value may change at any time, as +buffer sizes are optimised in response to network conditions to optimise +throughput. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_size()\fR. +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_USED\fR (stream object)" 4 +.IX Item "SSL_VALUE_STREAM_WRITE_BUF_USED (stream object)" +Generic read-only statistical value. The number of bytes currently consumed +in the write buffer which have yet to be acknowledged by the peer. Successful +calls to \fBSSL_write_ex\fR\|(3) which accept data cause this number to increase. +This number will then decrease as data is acknowledged by the peer. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_used()\fR. +.IP "\fBSSL_VALUE_STREAM_WRITE_BUF_AVAIL\fR (stream object)" 4 +.IX Item "SSL_VALUE_STREAM_WRITE_BUF_AVAIL (stream object)" +Generic read-only statistical value. The number of bytes available in the write +buffer which have yet to be consumed by calls to \fBSSL_write_ex\fR\|(3). Successful +calls to \fBSSL_write_ex\fR\|(3) which accept data cause this number to decrease. +This number will increase as data is acknowledged by the peer. It may also +change if the buffer is resized automatically to optimise throughput. +.Sp +Can be queried using the convenience macro \fBSSL_get_stream_write_buf_avail()\fR. +.PP +No configurable values are currently defined for non-QUIC SSL objects. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Returns 1 on success or 0 on failure. This function can fail for a number of +reasons: +.IP \(bu 4 +An argument is invalid (e.g. NULL pointer or invalid class). +.IP \(bu 4 +The given value is not supported by the SSL object on which it was called. +.IP \(bu 4 +The given operation (get or set) is not supported by the specified +configurable value. +.IP \(bu 4 +You are trying to modify the given value and the value is not modifiable at this +time. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_ctrl\fR\|(3), \fBSSL_get_accept_stream_queue_len\fR\|(3), +\&\fBSSL_get_stream_read_state\fR\|(3), \fBSSL_get_stream_write_state\fR\|(3), +\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_stream_write_error_code\fR\|(3), +\&\fBSSL_set_default_stream_mode\fR\|(3), \fBSSL_set_incoming_stream_policy\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +These functions were added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2002\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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>. |