NAME

SYNOPSIS

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

DESCRIPTION

SSL_set_quic_transport_params() configures ssl to send params (of length params_len) in the quic_transport_parameters extension in either the ClientHello or EncryptedExtensions handshake message. This extension will only be sent if the TLS version is at least 1.3, and for a server, only if the client sent the extension. The buffer pointed to by params only need be valid for the duration of the call to this function.

SSL_get_peer_quic_transport_params() 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 *out_params, and its length in *out_params_len. This buffer will be valid for the lifetime of the ssl. If no params were received from the peer, *out_params_len will be 0.

SSL_quic_max_handshake_flight_len() 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 QUIC implementation.

See <https://tools.ietf.org/html/RFC9000#section-4>.

SSL_quic_read_level() returns the current read encryption level.

SSL_quic_write_level() returns the current write encryption level.

SSL_provide_quic_data() is used to provide data from QUIC CRYPTO frames to the state machine, at a particular encryption level level. 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.

SSL_process_quic_post_handshake() processes any data that QUIC has provided after the handshake has completed. This includes NewSessionTicket messages sent by the server.

SSL_is_quic() indicates whether a connection uses QUIC. A given SSL or SSL_CTX can only be used with QUIC or TLS, but not both.

SSL_set_quic_use_legacy_codepoint() specifies the legacy extension codepoint in manner compatible with some versions of BoringSSL.

SSL_set_quic_transport_version() 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.

SSL_get_quic_transport_version() returns the value set by SSL_set_quic_transport_version().

SSL_get_peer_quic_transport_version() returns the version the that was negotiated.

SSL_set_quic_early_data_enabled() enables QUIC early data if a nonzero value is passed. Clients must set a resumed session before calling this function. Servers must additionally call SSL_CTX_set_max_early_data() or SSL_set_max_early_data() with 0xffffffffu as the argument, so that any issued session tickets indicate that server is able to accept early data.

NOTES

QUIC acts as an underlying transport for the TLS 1.3 handshake. The following functions allow a QUIC implementation to serve as the underlying transport as described in RFC9001.

When configured for QUIC, SSL_do_handshake() will drive the handshake as before, but it will not use the configured BIO. It will call functions from the configured SSL_QUIC_METHOD to configure secrets and send data. If data is needed from the peer, it will return SSL_ERROR_WANT_READ. When received, the caller should call SSL_provide_quic_data() and then SSL_do_handshake() to continue the handshake. After the handshake is complete, the caller should call SSL_provide_quic_data() for any post-handshake data, followed by SSL_process_quic_post_handshake() to process it. It is an error to call SSL_read()/SSL_read_ex() and SSL_write()/SSL_write_ex() in QUIC.

Note that secrets for an encryption level may be available to QUIC before the level is active in TLS. Callers should use SSL_quic_read_level() to determine the active read level for SSL_provide_quic_data(). SSL_do_handshake() will pass the active write level to add_handshake_data() when writing data. Callers can use SSL_quic_write_level() to query the active write level when generating their own errors.

See <https://tools.ietf.org/html/RFC9001#section-4.1> for more details.

To avoid amplifying DoS attacks, the QUIC implementation must limit the amount of data being queued up. The implementation can call SSL_quic_max_handshake_flight_len() to get the maximum buffer length at each encryption level.

RFC9001 defines a new TLS extension "quic_transport_parameters" used by QUIC 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.

OpenSSL handles this extension as an opaque byte string. The caller is responsible for serializing and parsing it.

 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;

RETURN VALUES

SSL_quic_read_level() and SSL_quic_write_level() return the current encryption level as an OSSL_ENCRYPTION_LEVEL (enum ssl_encryption_level_t).

SSL_quic_max_handshake_flight_len() returns the maximum length in bytes of a flight for a given encryption level.

SSL_is_quic() returns 1 if QUIC is being used, 0 if not.

SEE ALSO

HISTORY

COPYRIGHT

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>.