test/helpers/quictestlib.h

   1 /*
   2  * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #include <openssl/ssl.h>
  11 #include <internal/quic_tserver.h>
  12
  13 /* Type to represent the Fault Injector */
  14 typedef struct qtest_fault QTEST_FAULT;
  15
  16 /*
  17  * Structure representing a parsed EncryptedExtension message. Listeners can
  18  * make changes to the contents of structure objects as required and the fault
  19  * injector will reconstruct the message to be sent on
  20  */
  21 typedef struct qtest_fault_encrypted_extensions {
  22     /* EncryptedExtension messages just have an extensions block */
  23     unsigned char *extensions;
  24     size_t extensionslen;
  25 } QTEST_ENCRYPTED_EXTENSIONS;
  26
  27 /*
  28  * Given an SSL_CTX for the client and filenames for the server certificate and
  29  * keyfile, create a server and client instances as well as a fault injector
  30  * instance
  31  */
  32 int qtest_create_quic_objects(SSL_CTX *clientctx, char *certfile, char *keyfile,
  33                               QUIC_TSERVER **qtserv, SSL **cssl,
  34                               QTEST_FAULT **fault);
  35
  36 /*
  37  * Free up a Fault Injector instance
  38  */
  39 void qtest_fault_free(QTEST_FAULT *fault);
  40
  41 /*
  42  * Run the TLS handshake to create a QUIC connection between the client and
  43  * server.
  44  */
  45 int qtest_create_quic_connection(QUIC_TSERVER *qtserv, SSL *clientssl);
  46
  47 /*
  48  * Confirm that the server has received the given transport error code.
  49  */
  50 int qtest_check_server_transport_err(QUIC_TSERVER *qtserv, uint64_t code);
  51
  52 /*
  53  * Confirm the server has received a protocol error. Equivalent to calling
  54  * qtest_check_server_transport_err with a code of QUIC_ERR_PROTOCOL_VIOLATION
  55  */
  56 int qtest_check_server_protocol_err(QUIC_TSERVER *qtserv);
  57
  58 /*
  59  * Enable tests to listen for pre-encryption QUIC packets being sent
  60  */
  61 typedef int (*qtest_fault_on_packet_plain_cb)(QTEST_FAULT *fault,
  62                                               QUIC_PKT_HDR *hdr,
  63                                               unsigned char *buf,
  64                                               size_t len,
  65                                               void *cbarg);
  66
  67 int qtest_fault_set_packet_plain_listener(QTEST_FAULT *fault,
  68                                           qtest_fault_on_packet_plain_cb pplaincb,
  69                                           void *pplaincbarg);
  70
  71
  72 /*
  73  * Helper function to be called from a packet_plain_listener callback if it
  74  * wants to resize the packet (either to add new data to it, or to truncate it).
  75  * The buf provided to packet_plain_listener is over allocated, so this just
  76  * changes the logical size and never changes the actual address of the buf.
  77  * This will fail if a large resize is attempted that exceeds the over
  78  * allocation.
  79  */
  80 int qtest_fault_resize_plain_packet(QTEST_FAULT *fault, size_t newlen);
  81
  82 /*
  83  * Prepend frame data into a packet. To be called from a packet_plain_listener
  84  * callback
  85  */
  86 int qtest_fault_prepend_frame(QTEST_FAULT *fault, unsigned char *frame,
  87                               size_t frame_len);
  88
  89 /*
  90  * The general handshake message listener is sent the entire handshake message
  91  * data block, including the handshake header itself
  92  */
  93 typedef int (*qtest_fault_on_handshake_cb)(QTEST_FAULT *fault,
  94                                            unsigned char *msg,
  95                                            size_t msglen,
  96                                            void *handshakecbarg);
  97
  98 int qtest_fault_set_handshake_listener(QTEST_FAULT *fault,
  99                                        qtest_fault_on_handshake_cb handshakecb,
 100                                        void *handshakecbarg);
 101
 102 /*
 103  * Helper function to be called from a handshake_listener callback if it wants
 104  * to resize the handshake message (either to add new data to it, or to truncate
 105  * it). newlen must include the length of the handshake message header. The
 106  * handshake message buffer is over allocated, so this just changes the logical
 107  * size and never changes the actual address of the buf.
 108  * This will fail if a large resize is attempted that exceeds the over
 109  * allocation.
 110  */
 111 int qtest_fault_resize_handshake(QTEST_FAULT *fault, size_t newlen);
 112
 113 /*
 114  * TODO(QUIC): Add listeners for specifc types of frame here. E.g. we might
 115  * expect to see an "ACK" frame listener which will be passed pre-parsed ack
 116  * data that can be modified as required.
 117  */
 118
 119 /*
 120  * Handshake message specific listeners. Unlike the general handshake message
 121  * listener these messages are pre-parsed and supplied with message specific
 122  * data and exclude the handshake header
 123  */
 124 typedef int (*qtest_fault_on_enc_ext_cb)(QTEST_FAULT *fault,
 125                                          QTEST_ENCRYPTED_EXTENSIONS *ee,
 126                                          size_t eelen,
 127                                          void *encextcbarg);
 128
 129 int qtest_fault_set_hand_enc_ext_listener(QTEST_FAULT *fault,
 130                                           qtest_fault_on_enc_ext_cb encextcb,
 131                                           void *encextcbarg);
 132
 133 /* TODO(QUIC): Add listeners for other types of handshake message here */
 134
 135
 136 /*
 137  * Helper function to be called from message specific listener callbacks. newlen
 138  * is the new length of the specific message excluding the handshake message
 139  * header.  The buffers provided to the message specific listeners are over
 140  * allocated, so this just changes the logical size and never changes the actual
 141  * address of the buffer. This will fail if a large resize is attempted that
 142  * exceeds the over allocation.
 143  */
 144 int qtest_fault_resize_message(QTEST_FAULT *fault, size_t newlen);
 145
 146 /*
 147  * Helper function to delete an extension from an extension block. |exttype| is
 148  * the type of the extension to be deleted. |ext| points to the extension block.
 149  * On entry |*extlen| contains the length of the extension block. It is updated
 150  * with the new length on exit.
 151  */
 152 int qtest_fault_delete_extension(QTEST_FAULT *fault,
 153                                  unsigned int exttype, unsigned char *ext,
 154                                  size_t *extlen);
 155
 156 /*
 157  * TODO(QUIC): Add additional helper functions for querying extensions here (e.g.
 158  * finding or adding them). We could also provide a "listener" API for listening
 159  * for specific extension types
 160  */
 161
 162 /*
 163  * Enable tests to listen for post-encryption QUIC packets being sent
 164  */
 165 typedef int (*qtest_fault_on_packet_cipher_cb)(QTEST_FAULT *fault,
 166                                                /* The parsed packet header */
 167                                                QUIC_PKT_HDR *hdr,
 168                                                /* The packet payload data */
 169                                                unsigned char *buf,
 170                                                /* Length of the payload */
 171                                                size_t len,
 172                                                void *cbarg);
 173
 174 int qtest_fault_set_packet_cipher_listener(QTEST_FAULT *fault,
 175                                            qtest_fault_on_packet_cipher_cb pciphercb,
 176                                            void *picphercbarg);
 177
 178 /*
 179  * Enable tests to listen for datagrams being sent
 180  */
 181 typedef int (*qtest_fault_on_datagram_cb)(QTEST_FAULT *fault,
 182                                           BIO_MSG *m,
 183                                           size_t stride,
 184                                           void *cbarg);
 185
 186 int qtest_fault_set_datagram_listener(QTEST_FAULT *fault,
 187                                       qtest_fault_on_datagram_cb datagramcb,
 188                                       void *datagramcbarg);
 189
 190 /*
 191  * To be called from a datagram_listener callback. The datagram buffer is over
 192  * allocated, so this just changes the logical size and never changes the actual
 193  * address of the buffer. This will fail if a large resize is attempted that
 194  * exceeds the over allocation.
 195  */
 196 int qtest_fault_resize_datagram(QTEST_FAULT *fault, size_t newlen);