|
| 1 | +=pod |
| 2 | + |
| 3 | +=head1 NAME |
| 4 | + |
| 5 | +SSL_QUIC_METHOD, |
| 6 | +OSSL_ENCRYPTION_LEVEL, |
| 7 | +SSL_CTX_set_quic_method, |
| 8 | +SSL_set_quic_method, |
| 9 | +SSL_set_quic_transport_params, |
| 10 | +SSL_get_peer_quic_transport_params, |
| 11 | +SSL_quic_max_handshake_flight_len, |
| 12 | +SSL_quic_read_level, |
| 13 | +SSL_quic_write_level, |
| 14 | +SSL_provide_quic_data, |
| 15 | +SSL_process_quic_post_handshake, |
| 16 | +SSL_is_quic |
| 17 | +- QUIC support |
| 18 | + |
| 19 | +=head1 SYNOPSIS |
| 20 | + |
| 21 | + #include <openssl/ssl.h> |
| 22 | + |
| 23 | + typedef struct ssl_quic_method_st SSL_QUIC_METHOD; |
| 24 | + typedef enum ssl_encryption_level_t OSSL_ENCRYPTION_LEVEL; |
| 25 | + |
| 26 | + int SSL_CTX_set_quic_method(SSL_CTX *ctx, const SSL_QUIC_METHOD *quic_method); |
| 27 | + int SSL_set_quic_method(SSL *ssl, const SSL_QUIC_METHOD *quic_method); |
| 28 | + int SSL_set_quic_transport_params(SSL *ssl, |
| 29 | + const uint8_t *params, |
| 30 | + size_t params_len); |
| 31 | + void SSL_get_peer_quic_transport_params(const SSL *ssl, |
| 32 | + const uint8_t **out_params, |
| 33 | + size_t *out_params_len); |
| 34 | + size_t SSL_quic_max_handshake_flight_len(const SSL *ssl, OSSL_ENCRYPTION_LEVEL level); |
| 35 | + OSSL_ENCRYPTION_LEVEL SSL_quic_read_level(const SSL *ssl); |
| 36 | + OSSL_ENCRYPTION_LEVEL SSL_quic_write_level(const SSL *ssl); |
| 37 | + int SSL_provide_quic_data(SSL *ssl, OSSL_ENCRYPTION_LEVEL level, |
| 38 | + const uint8_t *data, size_t len); |
| 39 | + int SSL_process_quic_post_handshake(SSL *ssl); |
| 40 | + int SSL_is_quic(SSL *ssl); |
| 41 | + |
| 42 | +=head1 DESCRIPTION |
| 43 | + |
| 44 | +SSL_CTX_set_quic_method() and SSL_set_quic_method() configures the QUIC methods. |
| 45 | +This should only be configured with a minimum version of TLS 1.3. B<quic_method> |
| 46 | +must remain valid for the lifetime of B<ctx> or B<ssl>. Calling this disables |
| 47 | +the SSL_OP_ENABLE_MIDDLEBOX_COMPAT option, which is not required for QUIC. |
| 48 | + |
| 49 | +SSL_set_quic_transport_params() configures B<ssl> to send B<params> (of length |
| 50 | +B<params_len>) in the quic_transport_parameters extension in either the |
| 51 | +ClientHello or EncryptedExtensions handshake message. This extension will |
| 52 | +only be sent if the TLS version is at least 1.3, and for a server, only if |
| 53 | +the client sent the extension. The buffer pointed to by B<params> only need be |
| 54 | +valid for the duration of the call to this function. |
| 55 | + |
| 56 | +SSL_get_peer_quic_transport_params() provides the caller with the value of the |
| 57 | +quic_transport_parameters extension sent by the peer. A pointer to the buffer |
| 58 | +containing the TransportParameters will be put in B<*out_params>, and its |
| 59 | +length in B<*out_params_len>. This buffer will be valid for the lifetime of the |
| 60 | +B<ssl>. If no params were received from the peer, B<*out_params_len> will be 0. |
| 61 | + |
| 62 | +SSL_quic_max_handshake_flight_len() returns the maximum number of bytes |
| 63 | +that may be received at the given encryption level. This function should be |
| 64 | +used to limit buffering in the QUIC implementation. |
| 65 | + |
| 66 | +See https://tools.ietf.org/html/draft-ietf-quic-transport-16#section-4.4. |
| 67 | + |
| 68 | +SSL_quic_read_level() returns the current read encryption level. |
| 69 | + |
| 70 | +SSL_quic_write_level() returns the current write encryption level. |
| 71 | + |
| 72 | +SSL_provide_quic_data() provides data from QUIC at a particular encryption |
| 73 | +level B<level>. It is an error to call this function outside of the handshake |
| 74 | +or with an encryption level other than the current read level. It returns one |
| 75 | +on success and zero on error. |
| 76 | + |
| 77 | +SSL_process_quic_post_handshake() processes any data that QUIC has provided |
| 78 | +after the handshake has completed. This includes NewSessionTicket messages |
| 79 | +sent by the server. |
| 80 | + |
| 81 | +SSL_is_quic() indicates whether a connection uses QUIC. |
| 82 | + |
| 83 | +=head1 NOTES |
| 84 | + |
| 85 | +These APIs are implementations of BoringSSL's QUIC APIs. |
| 86 | + |
| 87 | +QUIC acts as an underlying transport for the TLS 1.3 handshake. The following |
| 88 | +functions allow a QUIC implementation to serve as the underlying transport as |
| 89 | +described in draft-ietf-quic-tls. |
| 90 | + |
| 91 | +When configured for QUIC, SSL_do_handshake() will drive the handshake as |
| 92 | +before, but it will not use the configured B<BIO>. It will call functions on |
| 93 | +B<SSL_QUIC_METHOD> to configure secrets and send data. If data is needed from |
| 94 | +the peer, it will return B<SSL_ERROR_WANT_READ>. When received, the caller |
| 95 | +should call SSL_provide_quic_data() and then SSL_do_handshake() to continue |
| 96 | +the handshake. After the handshake is complete, the caller should call |
| 97 | +SSL_provide_quic_data() for any post-handshake data, followed by |
| 98 | +SSL_process_quic_post_handshake() to process it. It is an error to call |
| 99 | +SSL_read()/SSL_read_ex() and SSL_write()/SSL_write_ex() in QUIC. |
| 100 | + |
| 101 | +Note that secrets for an encryption level may be available to QUIC before the |
| 102 | +level is active in TLS. Callers should use SSL_quic_read_level() to determine |
| 103 | +the active read level for SSL_provide_quic_data(). SSL_do_handshake() will |
| 104 | +pass the active write level to add_handshake_data() when writing data. Callers |
| 105 | +can use SSL_quic_write_level() to query the active write level when |
| 106 | +generating their own errors. |
| 107 | + |
| 108 | +See https://tools.ietf.org/html/draft-ietf-quic-tls-15#section-4.1 for more |
| 109 | +details. |
| 110 | + |
| 111 | +To avoid DoS attacks, the QUIC implementation must limit the amount of data |
| 112 | +being queued up. The implementation can call |
| 113 | +SSL_quic_max_handshake_flight_len() to get the maximum buffer length at each |
| 114 | +encryption level. |
| 115 | + |
| 116 | +draft-ietf-quic-tls defines a new TLS extension quic_transport_parameters |
| 117 | +used by QUIC for each endpoint to unilaterally declare its supported |
| 118 | +transport parameters. draft-ietf-quic-transport (section 7.4) defines the |
| 119 | +contents of that extension (a TransportParameters struct) and describes how |
| 120 | +to handle it and its semantic meaning. |
| 121 | + |
| 122 | +OpenSSL handles this extension as an opaque byte string. The caller is |
| 123 | +responsible for serializing and parsing it. |
| 124 | + |
| 125 | +=head2 OSSL_ENCRYPTION_LEVEL |
| 126 | + |
| 127 | +B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>) represents the |
| 128 | +encryption levels: |
| 129 | + |
| 130 | +=over 4 |
| 131 | + |
| 132 | +=item ssl_encryption_initial |
| 133 | + |
| 134 | +The initial encryption level that is used for client and server hellos. |
| 135 | + |
| 136 | +=item ssl_encryption_early_data |
| 137 | + |
| 138 | +The encryption level for early data. This is a write-level for the client |
| 139 | +and a read-level for the server. |
| 140 | + |
| 141 | +=item ssl_encryption_handshake |
| 142 | + |
| 143 | +The encryption level for the remainder of the handshake. |
| 144 | + |
| 145 | +=item ssl_encryption_application |
| 146 | + |
| 147 | +The encryption level for the application data. |
| 148 | + |
| 149 | +=back |
| 150 | + |
| 151 | +=head2 SSL_QUIC_METHOD |
| 152 | + |
| 153 | +The B<SSL_QUIC_METHOD> (B<struct ssl_quic_method_st>) describes the |
| 154 | +QUIC methods. |
| 155 | + |
| 156 | + struct ssl_quic_method_st { |
| 157 | + int (*set_encryption_secrets)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level, |
| 158 | + const uint8_t *read_secret, |
| 159 | + const uint8_t *write_secret, size_t secret_len); |
| 160 | + int (*add_handshake_data)(SSL *ssl, OSSL_ENCRYPTION_LEVEL level, |
| 161 | + const uint8_t *data, size_t len); |
| 162 | + int (*flush_flight)(SSL *ssl); |
| 163 | + int (*send_alert)(SSL *ssl, enum ssl_encryption_level_t level, uint8_t alert); |
| 164 | + }; |
| 165 | + typedef struct ssl_quic_method_st SSL_QUIC_METHOD; |
| 166 | + |
| 167 | +set_encryption_secrets() configures the read and write secrets for the given |
| 168 | +encryption level. This function will always be called before an encryption |
| 169 | +level other than B<ssl_encryption_initial> is used. Note, however, that |
| 170 | +secrets for a level may be configured before TLS is ready to send or accept |
| 171 | +data at that level. |
| 172 | + |
| 173 | +When reading packets at a given level, the QUIC implementation must send |
| 174 | +ACKs at the same level, so this function provides read and write secrets |
| 175 | +together. The exception is B<ssl_encryption_early_data>, where secrets are |
| 176 | +only available in the client to server direction. The other secret will be |
| 177 | +NULL. The server acknowledges such data at B<ssl_encryption_application>, |
| 178 | +which will be configured in the same SSL_do_handshake() call. |
| 179 | + |
| 180 | +This function should use SSL_get_current_cipher() to determine the TLS |
| 181 | +cipher suite. |
| 182 | + |
| 183 | +add_handshake_data() adds handshake data to the current flight at the given |
| 184 | +encryption level. It returns one on success and zero on error. |
| 185 | + |
| 186 | +OpenSSL will pack data from a single encryption level together, but a |
| 187 | +single handshake flight may include multiple encryption levels. Callers |
| 188 | +should defer writing data to the network until flush_flight() to better |
| 189 | +pack QUIC packets into transport datagrams. |
| 190 | + |
| 191 | +flush_flight() is called when the current flight is complete and should be |
| 192 | +written to the transport. Note a flight may contain data at several |
| 193 | +encryption levels. |
| 194 | + |
| 195 | +send_alert() sends a fatal alert at the specified encryption level. |
| 196 | + |
| 197 | +All QUIC methods return 1 on success and 0 on error. |
| 198 | + |
| 199 | +=head1 RETURN VALUES |
| 200 | + |
| 201 | +SSL_CTX_set_quic_method(), |
| 202 | +SSL_set_quic_method(), |
| 203 | +SSL_set_quic_transport_params(), and |
| 204 | +SSL_process_quic_post_handshake() |
| 205 | +return 1 on success, and 0 on error. |
| 206 | + |
| 207 | +SSL_quic_read_level() and SSL_quic_write_level() return the current |
| 208 | +encryption level as B<OSSL_ENCRYPTION_LEVEL> (B<enum ssl_encryption_level_t>). |
| 209 | + |
| 210 | +SSL_quic_max_handshake_flight_len() returns the maximum length of a flight |
| 211 | +for a given encryption level. |
| 212 | + |
| 213 | +SSL_is_quic() returns 1 if QUIC is being used, 0 if not. |
| 214 | + |
| 215 | +=head1 SEE ALSO |
| 216 | + |
| 217 | +L<ssl(7)>, L<SSL_CIPHER_get_prf_nid(3)>, L<SSL_do_handshake(3)> |
| 218 | + |
| 219 | +=head1 HISTORY |
| 220 | + |
| 221 | +These functions were added in OpenSSL 3.0.0. |
| 222 | + |
| 223 | +=head1 COPYRIGHT |
| 224 | + |
| 225 | +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. |
| 226 | + |
| 227 | +Licensed under the Apache License 2.0 (the "License"). You may not use |
| 228 | +this file except in compliance with the License. You can obtain a copy |
| 229 | +in the file LICENSE in the source distribution or at |
| 230 | +L<https://www.openssl.org/source/license.html>. |
| 231 | + |
| 232 | +=cut |
0 commit comments