Mini Shell
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_CTX_SET_QUIC_METHOD 3ossl"
.TH SSL_CTX_SET_QUIC_METHOD 3ossl "2024-09-03" "3.1.7+quic" "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_QUIC_METHOD,
OSSL_ENCRYPTION_LEVEL,
SSL_CTX_set_quic_method,
SSL_set_quic_method,
SSL_set_quic_transport_params,
SSL_get_peer_quic_transport_params,
SSL_quic_max_handshake_flight_len,
SSL_quic_read_level,
SSL_quic_write_level,
SSL_provide_quic_data,
SSL_process_quic_post_handshake,
SSL_is_quic,
SSL_get_peer_quic_transport_version,
SSL_get_quic_transport_version,
SSL_set_quic_transport_version,
SSL_set_quic_use_legacy_codepoint,
SSL_set_quic_early_data_enabled
\&\- QUIC support
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& typedef struct ssl_quic_method_st SSL_QUIC_METHOD;
\& typedef enum ssl_encryption_level_t OSSL_ENCRYPTION_LEVEL;
\&
\& int SSL_CTX_set_quic_method(SSL_CTX *ctx, const SSL_QUIC_METHOD *quic_method);
\& int SSL_set_quic_method(SSL *ssl, const SSL_QUIC_METHOD *quic_method);
\& int SSL_set_quic_transport_params(SSL *ssl,
\& const uint8_t *params,
\& size_t params_len);
\& void SSL_get_peer_quic_transport_params(const SSL *ssl,
\& const uint8_t **out_params,
\& size_t *out_params_len);
\& size_t SSL_quic_max_handshake_flight_len(const SSL *ssl, OSSL_ENCRYPTION_LEVEL level);
\& OSSL_ENCRYPTION_LEVEL SSL_quic_read_level(const SSL *ssl);
\& OSSL_ENCRYPTION_LEVEL SSL_quic_write_level(const SSL *ssl);
\& int SSL_provide_quic_data(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
\& const uint8_t *data, size_t len);
\& int SSL_process_quic_post_handshake(SSL *ssl);
\& int SSL_is_quic(SSL *ssl);
\&
\& void SSL_set_quic_use_legacy_codepoint(SSL *ssl, int use_legacy);
\& void SSL_set_quic_transport_version(SSL *ssl, int version);
\& int SSL_get_quic_transport_version(const SSL *ssl);
\& int SSL_get_peer_quic_transport_version(const SSL *ssl);
\& void SSL_set_quic_early_data_enabled(SSL *ssl, int enabled);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBSSL_CTX_set_quic_method()\fR and \fBSSL_set_quic_method()\fR configures the \s-1QUIC\s0 methods.
This should only be configured with a minimum version of \s-1TLS 1.3.\s0 \fBquic_method\fR
must remain valid for the lifetime of \fBctx\fR or \fBssl\fR. Calling this disables
the \s-1SSL_OP_ENABLE_MIDDLEBOX_COMPAT\s0 option, which is not required for \s-1QUIC.\s0
.PP
\&\fBSSL_set_quic_transport_params()\fR configures \fBssl\fR to send \fBparams\fR (of length
\&\fBparams_len\fR) in the quic_transport_parameters extension in either the
ClientHello or EncryptedExtensions handshake message. This extension will
only be sent if the \s-1TLS\s0 version is at least 1.3, and for a server, only if
the client sent the extension. The buffer pointed to by \fBparams\fR only need be
valid for the duration of the call to this function.
.PP
\&\fBSSL_get_peer_quic_transport_params()\fR provides the caller with the value of the
quic_transport_parameters extension sent by the peer. A pointer to the buffer
containing the TransportParameters will be put in \fB*out_params\fR, and its
length in \fB*out_params_len\fR. This buffer will be valid for the lifetime of the
\&\fBssl\fR. If no params were received from the peer, \fB*out_params_len\fR will be 0.
.PP
\&\fBSSL_quic_max_handshake_flight_len()\fR returns the maximum number of bytes
that may be received at the given encryption level. This function should be
used to limit buffering in the \s-1QUIC\s0 implementation.
.PP
See <https://tools.ietf.org/html/RFC9000#section\-4>.
.PP
\&\fBSSL_quic_read_level()\fR returns the current read encryption level.
.PP
\&\fBSSL_quic_write_level()\fR returns the current write encryption level.
.PP
\&\fBSSL_provide_quic_data()\fR is used to provide data from \s-1QUIC CRYPTO\s0 frames to the
state machine, at a particular encryption level \fBlevel\fR. It is an error to
call this function with an encryption level less than the current read level.
It returns one on success and zero on error.
.PP
\&\fBSSL_process_quic_post_handshake()\fR processes any data that \s-1QUIC\s0 has provided
after the handshake has completed. This includes NewSessionTicket messages
sent by the server.
.PP
\&\fBSSL_is_quic()\fR indicates whether a connection uses \s-1QUIC.\s0 A given \fB\s-1SSL\s0\fR
or \fB\s-1SSL_CTX\s0\fR can only be used with \s-1QUIC\s0 or \s-1TLS,\s0 but not both.
.PP
\&\fBSSL_set_quic_use_legacy_codepoint()\fR specifies the legacy extension codepoint
in manner compatible with some versions of BoringSSL.
.PP
\&\fBSSL_set_quic_transport_version()\fR specifies the quic transport version that
allows for backwards and forwards compatibility. If set to 0 (default) the
server will use the highest version the client sent. If set to 0 (default)
the client will send both extensions.
.PP
\&\fBSSL_get_quic_transport_version()\fR returns the value set by
\&\fBSSL_set_quic_transport_version()\fR.
.PP
\&\fBSSL_get_peer_quic_transport_version()\fR returns the version the that was
negotiated.
.PP
\&\fBSSL_set_quic_early_data_enabled()\fR enables \s-1QUIC\s0 early data if a nonzero
value is passed. Clients must set a resumed session before calling this
function. Servers must additionally call \fBSSL_CTX_set_max_early_data()\fR or
\&\fBSSL_set_max_early_data()\fR with 0xffffffffu as the argument, so that any
issued session tickets indicate that server is able to accept early data.
.SH "NOTES"
.IX Header "NOTES"
These APIs are implementations of BoringSSL's \s-1QUIC\s0 APIs.
.PP
\&\s-1QUIC\s0 acts as an underlying transport for the \s-1TLS 1.3\s0 handshake. The following
functions allow a \s-1QUIC\s0 implementation to serve as the underlying transport as
described in \s-1RFC9001.\s0
.PP
When configured for \s-1QUIC,\s0 \fBSSL_do_handshake()\fR will drive the handshake as
before, but it will not use the configured \fB\s-1BIO\s0\fR. It will call functions from
the configured \fB\s-1SSL_QUIC_METHOD\s0\fR to configure secrets and send data. If data
is needed from the peer, it will return \fB\s-1SSL_ERROR_WANT_READ\s0\fR. When received,
the caller should call \fBSSL_provide_quic_data()\fR and then \fBSSL_do_handshake()\fR to
continue the handshake. After the handshake is complete, the caller should call
\&\fBSSL_provide_quic_data()\fR for any post-handshake data, followed by
\&\fBSSL_process_quic_post_handshake()\fR to process it. It is an error to call
\&\fBSSL_read()\fR/\fBSSL_read_ex()\fR and \fBSSL_write()\fR/\fBSSL_write_ex()\fR in \s-1QUIC.\s0
.PP
Note that secrets for an encryption level may be available to \s-1QUIC\s0 before the
level is active in \s-1TLS.\s0 Callers should use \fBSSL_quic_read_level()\fR to determine
the active read level for \fBSSL_provide_quic_data()\fR. \fBSSL_do_handshake()\fR will
pass the active write level to \fBadd_handshake_data()\fR when writing data. Callers
can use \fBSSL_quic_write_level()\fR to query the active write level when
generating their own errors.
.PP
See <https://tools.ietf.org/html/RFC9001#section\-4.1> for more details.
.PP
To avoid amplifying DoS attacks, the \s-1QUIC\s0 implementation must limit the amount
of data being queued up. The implementation can call
\&\fBSSL_quic_max_handshake_flight_len()\fR to get the maximum buffer length at each
encryption level.
.PP
\&\s-1RFC9001\s0 defines a new \s-1TLS\s0 extension \*(L"quic_transport_parameters\*(R"
used by \s-1QUIC\s0 for each endpoint to unilaterally declare its supported
transport parameters. The contents of the extension are specified in
<https://tools.ietf.org/html/RFC9000#section\-18> (as
a sequence of tag/length/value parameters) along with the interpretation of the
various parameters and the rules for their processing.
.PP
OpenSSL handles this extension as an opaque byte string. The caller is
responsible for serializing and parsing it.
.SS "\s-1OSSL_ENCRYPTION_LEVEL\s0"
.IX Subsection "OSSL_ENCRYPTION_LEVEL"
\&\fB\s-1OSSL_ENCRYPTION_LEVEL\s0\fR (\fBenum ssl_encryption_level_t\fR) represents the
encryption levels:
.IP "ssl_encryption_initial" 4
.IX Item "ssl_encryption_initial"
The initial encryption level that is used for client and server hellos.
.IP "ssl_encryption_early_data" 4
.IX Item "ssl_encryption_early_data"
The encryption level for early data. This is a write-level for the client
and a read-level for the server.
.IP "ssl_encryption_handshake" 4
.IX Item "ssl_encryption_handshake"
The encryption level for the remainder of the handshake.
.IP "ssl_encryption_application" 4
.IX Item "ssl_encryption_application"
The encryption level for the application data.
.SS "\s-1SSL_QUIC_METHOD\s0"
.IX Subsection "SSL_QUIC_METHOD"
The \fB\s-1SSL_QUIC_METHOD\s0\fR (\fBstruct ssl_quic_method_st\fR) describes the
\&\s-1QUIC\s0 methods.
.PP
.Vb 10
\& struct ssl_quic_method_st {
\& int (*set_encryption_secrets)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
\& const uint8_t *read_secret,
\& const uint8_t *write_secret, size_t secret_len);
\& int (*add_handshake_data)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level,
\& const uint8_t *data, size_t len);
\& int (*flush_flight)(SSL *ssl);
\& int (*send_alert)(SSL *ssl, enum ssl_encryption_level_t level, uint8_t alert);
\& };
\& typedef struct ssl_quic_method_st SSL_QUIC_METHOD;
.Ve
.PP
\&\fBset_encryption_secrets()\fR configures the read and write secrets for the given
encryption level. This function will always be called before an encryption
level other than \fBssl_encryption_initial\fR is used. Note, however, that
secrets for a level may be configured before \s-1TLS\s0 is ready to send or accept
data at that level.
.PP
When reading packets at a given level, the \s-1QUIC\s0 implementation must send
ACKs at the same level, so this function provides read and write secrets
together. The exception is \fBssl_encryption_early_data\fR, where secrets are
only available in the client to server direction. The other secret will be
\&\s-1NULL.\s0 The server acknowledges such data at \fBssl_encryption_application\fR,
which will be configured in the same \fBSSL_do_handshake()\fR call.
.PP
\&\fBadd_handshake_data()\fR adds handshake data to the current flight at the given
encryption level. It returns one on success and zero on error.
.PP
OpenSSL will pack data from a single encryption level together, but a
single handshake flight may include multiple encryption levels. Callers
should defer writing data to the network until \fBflush_flight()\fR to better
pack \s-1QUIC\s0 packets into transport datagrams.
.PP
\&\fBflush_flight()\fR is called when the current flight is complete and should be
written to the transport. Note a flight may contain data at several
encryption levels.
.PP
\&\fBsend_alert()\fR sends a fatal alert at the specified encryption level.
.PP
All \s-1QUIC\s0 methods return 1 on success and 0 on error.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_CTX_set_quic_method()\fR,
\&\fBSSL_set_quic_method()\fR,
\&\fBSSL_set_quic_transport_params()\fR, and
\&\fBSSL_process_quic_post_handshake()\fR
return 1 on success, and 0 on error.
.PP
\&\fBSSL_quic_read_level()\fR and \fBSSL_quic_write_level()\fR return the current
encryption level as an \fB\s-1OSSL_ENCRYPTION_LEVEL\s0\fR
(\fBenum ssl_encryption_level_t\fR).
.PP
\&\fBSSL_quic_max_handshake_flight_len()\fR returns the maximum length in bytes of a
flight for a given encryption level.
.PP
\&\fBSSL_is_quic()\fR returns 1 if \s-1QUIC\s0 is being used, 0 if not.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBssl\fR\|(7), \fBSSL_CIPHER_get_prf_nid\fR\|(3), \fBSSL_do_handshake\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
These functions were added in OpenSSL 3.0.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
Zerion Mini Shell 1.0