forked from openssl/openssl
-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This is a cherry-pick of 2a4b03a306439307e0b822b17eda3bdabddfbb68 on the master-quic-support2 branch (2019-10-07) Which was a rebase/squash of master-quic-support: * 5aa62ce Add support for more secrets - Todd Short/Todd Short (master-quic-support) * 58e0643 Tweeks to quic_change_cipher_state() - Todd Short/Todd Short * 8169702 Move QUIC code out of tls13_change_cipher_state() - Todd Short/Todd Short * a08cfe6 Correctly disable middlebox compat - Todd Short/Todd Short * 3a9eabf Add OPENSSL_NO_QUIC wrapper - Todd Short/Todd Short * f550eca Add client early traffic secret storage - Todd Short/Todd Short * 1b787ae Quick fix: s2c to c2s for early secret - Todd Short/Todd Short * f97e6a9 Don't process an incomplete message - Todd Short/Todd Short * 81f0ce2 Reset init state in SSL_process_quic_post_handshake() - Todd Short/Todd Short * 5d59cf9 Fix quic_transport constructors/parsers - Todd Short/Todd Short * 5e5f91c Fix INSTALL nit. - Todd Short/Todd Short * bd290ab Fix duplicate word in docs - Todd Short/Todd Short * 699590b fixup! Handle partial handshake messages - Todd Short/Todd Short * a472a8d Handle partial handshake messages - Todd Short/Todd Short * 363cf3d fixup! Use proper secrets for handshake - Todd Short/Todd Short * b03fee6 Use proper secrets for handshake - Todd Short/Todd Short * 2ab1aa0 Move QUIC transport params to encrypted extensions - Todd Short/Todd Short * 0d16af9 Make temp secret names less confusing - Todd Short/Todd Short * abb6f39 New method to get QUIC secret length - Todd Short/Todd Short * 05fdae9 Add support for BoringSSL QUIC APIs - Todd Short/Todd Short This adds a compatible API for BoringSSL's QUIC support, based on the current |draft-ietf-quic-tls|. Based on BoringSSL commit 3c034b2cf386b3131f75520705491871a2e0cafe Based on BoringSSL commit c8e0f90f83b9ec38ea833deb86b5a41360b62b6a Based on BoringSSL commit 3cbb0299a28a8bd0136257251a78b91a96c5eec8 Based on BoringSSL commit cc9d935256539af2d3b7f831abf57c0d685ffd81 Based on BoringSSL commit e6eef1ca16a022e476bbaedffef044597cfc8f4b Based on BoringSSL commit 6f733791148cf8a076bf0e95498235aadbe5926d Based on BoringSSL commit 384d0eaf1930af1ebc47eda751f0c78dfcba1c03 Based on BoringSSL commit a0373182eb5cc7b81d49f434596b473c7801c942 Based on BoringSSL commit b1b76aee3cb43ce11889403c5334283d951ebd37 New method to get QUIC secret length Make temp secret names less confusing Move QUIC transport params to encrypted extensions Use proper secrets for handshake fixup! Use proper secrets for handshake Handle partial handshake messages fixup! Handle partial handshake messages Fix duplicate word in docs Fix INSTALL nit. Fix quic_transport constructors/parsers Reset init state in SSL_process_quic_post_handshake() Don't process an incomplete message Quick fix: s2c to c2s for early secret Add client early traffic secret storage Add OPENSSL_NO_QUIC wrapper Correctly disable middlebox compat Move QUIC code out of tls13_change_cipher_state() Create quic_change_cipher_state() that does the minimal required to generate the QUIC secrets. (e.g. encryption contexts are not initialized). Tweeks to quic_change_cipher_state() Add support for more secrets
- Loading branch information
Showing
31 changed files
with
1,338 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.