Expand some comments in the header file

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20030)

1 files changed, 58 insertions, 11 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 <openssl/ssl.h>
 #include <internal/quic_tserver.h>
 
+/* 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,12 +82,19 @@ 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
  * data and exclude the handshake header
@@ -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