1 /* 2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"). 5 * You may not use this file except in compliance with the License. 6 * A copy of the License is located at 7 * 8 * http://aws.amazon.com/apache2.0 9 * 10 * or in the "license" file accompanying this file. This file is distributed 11 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 12 * express or implied. See the License for the specific language governing 13 * permissions and limitations under the License. 14 */ 15 16 #pragma once 17 18 #include "api/s2n.h" 19 20 /* 21 * APIs intended to support an external implementation of the QUIC protocol: 22 * https://datatracker.ietf.org/wg/quic/about/ 23 * 24 * QUIC requires access to parts of S2N not usually surfaced to customers. These APIs change 25 * the behavior of S2N in potentially dangerous ways and should only be used by implementations 26 * of the QUIC protocol. 27 * 28 * Additionally, the QUIC RFC is not yet finalized, so all QUIC APIs are considered experimental 29 * and are subject to change without notice. They should only be used for testing purposes. 30 */ 31 32 S2N_API int s2n_config_enable_quic(struct s2n_config *config); 33 S2N_API int s2n_connection_enable_quic(struct s2n_connection *conn); 34 bool s2n_connection_is_quic_enabled(struct s2n_connection *conn); 35 36 /* 37 * Set the data to be sent in the quic_transport_parameters extension. 38 * The data provided will be copied into a buffer owned by S2N. 39 */ 40 S2N_API int s2n_connection_set_quic_transport_parameters(struct s2n_connection *conn, 41 const uint8_t *data_buffer, uint16_t data_len); 42 43 /* 44 * Retrieve the data from the peer's quic_transport_parameters extension. 45 * data_buffer will be set to a buffer owned by S2N which will be freed when the connection is freed. 46 * data_len will be set to the length of the data returned. 47 * 48 * S2N treats the extension data as opaque bytes and performs no validation. 49 */ 50 S2N_API int s2n_connection_get_quic_transport_parameters(struct s2n_connection *conn, 51 const uint8_t **data_buffer, uint16_t *data_len); 52 53 typedef enum { 54 S2N_CLIENT_EARLY_TRAFFIC_SECRET = 0, 55 S2N_CLIENT_HANDSHAKE_TRAFFIC_SECRET, 56 S2N_SERVER_HANDSHAKE_TRAFFIC_SECRET, 57 S2N_CLIENT_APPLICATION_TRAFFIC_SECRET, 58 S2N_SERVER_APPLICATION_TRAFFIC_SECRET, 59 } s2n_secret_type_t; 60 61 /* 62 * Called when S2N begins using a new key. 63 * 64 * The memory pointed to by "secret" will be wiped after this method returns and should be copied by 65 * the application if necessary. The application should also be very careful managing the memory and 66 * lifespan of the secret: if the secret is compromised, TLS is compromised. 67 */ 68 typedef int (*s2n_secret_cb) (void* context, struct s2n_connection *conn, 69 s2n_secret_type_t secret_type, 70 uint8_t *secret, uint8_t secret_size); 71 72 /* 73 * Set the function to be called when S2N begins using a new key. 74 * 75 * The callback function will ONLY be triggered if QUIC is enabled. This API is not intended to be 76 * used outside of a QUIC implementation. 77 */ 78 S2N_API int s2n_connection_set_secret_callback(struct s2n_connection *conn, s2n_secret_cb cb_func, void *ctx); 79