Latest update (add quic)
This commit is contained in:
@@ -0,0 +1,232 @@
|
||||
=pod
|
||||
|
||||
=head1 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
|
||||
- QUIC support
|
||||
|
||||
=head1 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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SSL_CTX_set_quic_method() and SSL_set_quic_method() configures the QUIC methods.
|
||||
This should only be configured with a minimum version of TLS 1.3. B<quic_method>
|
||||
must remain valid for the lifetime of B<ctx> or B<ssl>. Calling this disables
|
||||
the SSL_OP_ENABLE_MIDDLEBOX_COMPAT option, which is not required for QUIC.
|
||||
|
||||
SSL_set_quic_transport_params() configures B<ssl> to send B<params> (of length
|
||||
B<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 B<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 B<*out_params>, and its
|
||||
length in B<*out_params_len>. This buffer will be valid for the lifetime of the
|
||||
B<ssl>. If no params were received from the peer, B<*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/draft-ietf-quic-transport-16#section-4.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() provides data from QUIC at a particular encryption
|
||||
level B<level>. It is an error to call this function outside of the handshake
|
||||
or with an encryption level other 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.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
These APIs are implementations of BoringSSL's QUIC APIs.
|
||||
|
||||
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 draft-ietf-quic-tls.
|
||||
|
||||
When configured for QUIC, SSL_do_handshake() will drive the handshake as
|
||||
before, but it will not use the configured B<BIO>. It will call functions on
|
||||
B<SSL_QUIC_METHOD> to configure secrets and send data. If data is needed from
|
||||
the peer, it will return B<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/draft-ietf-quic-tls-15#section-4.1 for more
|
||||
details.
|
||||
|
||||
To avoid 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.
|
||||
|
||||
draft-ietf-quic-tls defines a new TLS extension quic_transport_parameters
|
||||
used by QUIC for each endpoint to unilaterally declare its supported
|
||||
transport parameters. draft-ietf-quic-transport (section 7.4) defines the
|
||||
contents of that extension (a TransportParameters struct) and describes how
|
||||
to handle it and its semantic meaning.
|
||||
|
||||
OpenSSL handles this extension as an opaque byte string. The caller is
|
||||
responsible for serializing and parsing it.
|
||||
|
||||
=head2 OSSL_ENCRYPTION_LEVEL
|
||||
|
||||
B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>) represents the
|
||||
encryption levels:
|
||||
|
||||
=over 4
|
||||
|
||||
=item ssl_encryption_initial
|
||||
|
||||
The initial encryption level that is used for client and server hellos.
|
||||
|
||||
=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.
|
||||
|
||||
=item ssl_encryption_handshake
|
||||
|
||||
The encryption level for the remainder of the handshake.
|
||||
|
||||
=item ssl_encryption_application
|
||||
|
||||
The encryption level for the application data.
|
||||
|
||||
=back
|
||||
|
||||
=head2 SSL_QUIC_METHOD
|
||||
|
||||
The B<SSL_QUIC_METHOD> (B<struct ssl_quic_method_st>) describes the
|
||||
QUIC methods.
|
||||
|
||||
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;
|
||||
|
||||
set_encryption_secrets() configures the read and write secrets for the given
|
||||
encryption level. This function will always be called before an encryption
|
||||
level other than B<ssl_encryption_initial> is used. Note, however, that
|
||||
secrets for a level may be configured before TLS is ready to send or accept
|
||||
data at that level.
|
||||
|
||||
When reading packets at a given level, the QUIC implementation must send
|
||||
ACKs at the same level, so this function provides read and write secrets
|
||||
together. The exception is B<ssl_encryption_early_data>, where secrets are
|
||||
only available in the client to server direction. The other secret will be
|
||||
NULL. The server acknowledges such data at B<ssl_encryption_application>,
|
||||
which will be configured in the same SSL_do_handshake() call.
|
||||
|
||||
This function should use SSL_get_current_cipher() to determine the TLS
|
||||
cipher suite.
|
||||
|
||||
add_handshake_data() adds handshake data to the current flight at the given
|
||||
encryption level. It returns one on success and zero on error.
|
||||
|
||||
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 flush_flight() to better
|
||||
pack QUIC packets into transport datagrams.
|
||||
|
||||
flush_flight() 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.
|
||||
|
||||
send_alert() sends a fatal alert at the specified encryption level.
|
||||
|
||||
All QUIC methods return 1 on success and 0 on error.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
SSL_CTX_set_quic_method(),
|
||||
SSL_set_quic_method(),
|
||||
SSL_set_quic_transport_params(), and
|
||||
SSL_process_quic_post_handshake()
|
||||
return 1 on success, and 0 on error.
|
||||
|
||||
SSL_quic_read_level() and SSL_quic_write_level() return the current
|
||||
encryption level as B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>).
|
||||
|
||||
SSL_quic_max_handshake_flight_len() returns the maximum length of a flight
|
||||
for a given encryption level.
|
||||
|
||||
SSL_is_quic() returns 1 if QUIC is being used, 0 if not.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ssl(7)>, L<SSL_CIPHER_get_prf_nid(3)>, L<SSL_do_handshake(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These functions were added in OpenSSL 3.0.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019 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
|
||||
L<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
Reference in New Issue
Block a user