From da81f1e563c80a1d4ab82e545f3f5ba6e715267e Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 9 Dec 2022 17:00:46 +0000 Subject: Expand some comments in the header file Reviewed-by: Hugo Landau Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20030) --- test/helpers/quictestlib.h | 69 ++++++++++++++++++++++++++++++++++++++-------- test/quicfaultstest.c | 2 +- 2 files changed, 59 insertions(+), 12 deletions(-) diff --git a/test/helpers/quictestlib.h b/test/helpers/quictestlib.h index d5fe58900a..e9514df6f2 100644 --- a/test/helpers/quictestlib.h +++ b/test/helpers/quictestlib.h @@ -10,22 +10,48 @@ #include #include +/* Type to represent the Fault Injector */ typedef struct ossl_quic_fault OSSL_QUIC_FAULT; +/* + * Structure representing a parse EncryptedExtension message. Listeners can + * make changes to the contents of structure objects as required and the fault + * injector will reconstruct the message to be sent on + */ typedef struct ossl_qf_encrypted_extensions { + /* EncryptedExtension messages just have an extensions block */ unsigned char *extensions; size_t extensionslen; } OSSL_QF_ENCRYPTED_EXTENSIONS; +/* + * Given an SSL_CTX for the client and filenames for the server certificate and + * keyfile, create a server and client instances as well as a fault injector + * instance + */ int qtest_create_quic_objects(SSL_CTX *clientctx, char *certfile, char *keyfile, QUIC_TSERVER **qtserv, SSL **cssl, OSSL_QUIC_FAULT **fault); + +/* + * Free up a Fault Injector instance + */ +void ossl_quic_fault_free(OSSL_QUIC_FAULT *fault); + +/* + * Run the TLS handshake to create a QUIC connection between the client and + * server. + */ int qtest_create_quic_connection(QUIC_TSERVER *qtserv, SSL *clientssl); +/* + * Confirm the server has received a protocol error + */ int qtest_check_server_protocol_err(QUIC_TSERVER *qtserv); -void ossl_quic_fault_free(OSSL_QUIC_FAULT *fault); - +/* + * Enable tests to listen for pre-encryption QUIC packets being sent + */ typedef int (*ossl_quic_fault_on_packet_plain_cb)(OSSL_QUIC_FAULT *fault, QUIC_PKT_HDR *hdr, unsigned char *buf, @@ -36,7 +62,10 @@ int ossl_quic_fault_set_packet_plain_listener(OSSL_QUIC_FAULT *fault, ossl_quic_fault_on_packet_plain_cb pplaincb, void *pplaincbarg); -/* To be called from a packet_plain_listener callback */ +/* + * Helper function to be called from a packet_plain_listener callback if it + * wants to resize the packet (either to add new data to it, or to truncate it) + */ int ossl_quic_fault_resize_plain_packet(OSSL_QUIC_FAULT *fault, size_t newlen); /* @@ -53,11 +82,18 @@ int ossl_quic_fault_set_handshake_listener(OSSL_QUIC_FAULT *fault, void *handshakecbarg); /* - * To be called from a handshake_listener callback. newlen must include the - * length of the handshake message header. + * Helper function to be called from a handshake_listener callback if it wants + * to rezie the handshake message (either to add new data to it, or to truncate + * it). newlen must include the length of the handshake message header. */ int ossl_quic_fault_resize_handshake(OSSL_QUIC_FAULT *fault, size_t newlen); +/* + * TODO(QUIC): Add listeners for specifc types of frame here. E.g. we might + * expect to see an "ACK" frame listener which will be passed pre-parsed ack + * data that can be modified as required. + */ + /* * Handshake message specific listeners. Unlike the general handshake message * listener these messages are pre-parsed and supplied with message specific @@ -72,19 +108,30 @@ int ossl_quic_fault_set_hand_enc_ext_listener(OSSL_QUIC_FAULT *fault, ossl_quic_fault_on_enc_ext_cb encextcb, void *encextcbarg); +/* TODO(QUIC): Add listeners for other types of handshake message here */ + /* - * To be called from message specific listener callbacks. newlen is the new - * length of the specific message excluding the handshake message header. + * Helper function to be called from message specific listener callbacks. newlen + * is the new length of the specific message excluding the handshake message + * header. */ int ossl_quic_fault_resize_message(OSSL_QUIC_FAULT *fault, size_t newlen); /* - * Delete an extension from an extension block. |exttype| is the type of the - * extension to be deleted. |ext| points to the extension block. On entry - * |*extlen| contains the length of the extension block. It is updated with the - * new length on exit. + * Helper function to delete an extension from an extension block. |exttype| is + * the type of the extension to be deleted. |ext| points to the extension block. + * On entry |*extlen| contains the length of the extension block. It is updated + * with the new length on exit. */ int ossl_quic_fault_delete_extension(OSSL_QUIC_FAULT *fault, unsigned int exttype, unsigned char *ext, size_t *extlen); + +/* + * TODO(QUIC): Add additional helper functions for querying extensions here (e.g. + * finding or adding them). We could also provide a "listener" API for listening + * for specific extension types + */ + +/* TODO(QUIC): Add a listener for a datagram here */ \ No newline at end of file diff --git a/test/quicfaultstest.c b/test/quicfaultstest.c index 7def61c4d1..a1cedb49ec 100644 --- a/test/quicfaultstest.c +++ b/test/quicfaultstest.c @@ -129,7 +129,7 @@ static int test_unknown_frame(void) goto err; /* - * Write a message from the server to the client and add an uknown frame + * Write a message from the server to the client and add an unknown frame * type */ if (!TEST_true(ossl_quic_fault_set_packet_plain_listener(fault, -- cgit v1.2.3