Support QUIC with the msg_callback and -trace in s_client

doc/man3/SSL_CTX_set_msg_callback.pod

@@ -5,7 +5,8 @@
 SSL_CTX_set_msg_callback,
 SSL_CTX_set_msg_callback_arg,
 SSL_set_msg_callback,
-SSL_set_msg_callback_arg
+SSL_set_msg_callback_arg,
+SSL_trace
 - install callback for observing protocol messages
 
 =head1 SYNOPSIS
@@ -24,10 +25,13 @@ SSL_set_msg_callback_arg
                                       size_t len, SSL *ssl, void *arg));
  void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
 
+ void SSL_trace(int write_p, int version, int content_type,
+                const void *buf, size_t len, SSL *ssl, void *arg);
+
 =head1 DESCRIPTION
 
 SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
-define a message callback function I<cb> for observing all SSL/TLS
+define a message callback function I<cb> for observing all SSL/TLS/QUIC
 protocol messages (such as handshake messages) that are received or
 sent, as well as other events that occur during processing.
 SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
@@ -40,7 +44,7 @@ L<SSL_new(3)>. SSL_set_msg_callback() and
 SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
 object. Using a B<NULL> pointer for I<cb> disables the message callback.
 
-When I<cb> is called by the SSL/TLS library the function arguments have the
+When I<cb> is called by the SSL/TLS/QUIC library the function arguments have the
 following meaning:
 
 =over 4
@@ -53,8 +57,9 @@ when a protocol message has been sent.
 =item I<version>
 
 The protocol version according to which the protocol message is
-interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION> etc.
-This is set to 0 for the SSL3_RT_HEADER pseudo content type (see NOTES below).
+interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION>,
+B<OSSL_QUIC1_VERSION> etc. This is set to 0 for the SSL3_RT_HEADER pseudo
+content type (see NOTES below).
 
 =item I<content_type>
 
@@ -82,6 +87,13 @@ SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
 
 =back
 
+The SSL_trace() function can be used as a pre-written callback in a call to
+SSL_CTX_set_msg_callback() or SSL_set_msg_callback(). It requires a BIO to be
+set as the callback argument via SSL_CTX_set_msg_callback_arg() or
+SSL_set_msg_callback_arg(). Setting this callback will cause human readable
+diagostic tracing information about an SSL/TLS/QUIC connection to be written to
+the BIO.
+
 =head1 NOTES
 
 Protocol messages are passed to the callback function after decryption
@@ -105,7 +117,7 @@ of data. The following pseudo content types are currently defined:
 
 =item B<SSL3_RT_HEADER>
 
-Used when a record is sent or received. The B<buf> contains the record header
+Used when a TLS record is sent or received. The B<buf> contains the record header
 bytes only.
 
 =item B<SSL3_RT_INNER_CONTENT_TYPE>
@@ -115,6 +127,32 @@ records the content type in the record header is always
 SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in
 an "inner" content type. B<buf> contains the encoded "inner" content type byte.
 
+=item B<SSL3_RT_QUIC_DATAGRAM>
+
+Used when a QUIC datagram is sent or received.
+
+=item B<SSL3_RT_QUIC_PACKET>
+
+Used when a QUIC packet is sent or received.
+
+=item B<SSL3_RT_QUIC_FRAME_FULL>
+
+Used when a QUIC frame is sent or received. This is only used for non-crypto
+and stream data related frames. The full QUIC frame data is supplied.
+
+=item B<SSL3_RT_QUIC_FRAME_HEADER>
+
+Used when a QUIC stream data or crypto frame is sent or received. Only the QUIC
+frame header data is supplied.
+
+=item B<SSL3_RT_QUIC_FRAME_PADDING>
+
+Used when a sequence of one or more QUIC padding frames is sent or received.
+A padding frame consists of a single byte and it is common to have multiple
+such frames in a sequence. Rather than supplying each frame individually the
+callback will supply all the padding frames in one go via this pseudo content
+type.
+
 =back
 
 =head1 RETURN VALUES
@@ -130,6 +168,10 @@ L<ssl(7)>, L<SSL_new(3)>
 
 The pseudo content type B<SSL3_RT_INNER_CONTENT_TYPE> was added in OpenSSL 1.1.1.
 
+The pseudo content types B<SSL3_RT_QUIC_DATAGRAM>, B<SSL3_RT_QUIC_PACKET>,
+B<SSL3_RT_QUIC_FRAME_FULL>, B<SSL3_RT_QUIC_FRAME_HEADER> and
+B<SSL3_RT_QUIC_FRAME_PADDING> were added in OpenSSL 3.2.
+
 =head1 COPYRIGHT
 
 Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.

include/internal/quic_channel.h

@@ -323,6 +323,13 @@ void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs);
 int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch,
                                         const QUIC_CONN_ID *conn_id);
 
+/* Setters for the msg_callback and msg_callback_arg */
+void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch,
+                                        ossl_msg_cb msg_callback,
+                                        SSL *msg_callback_ssl);
+void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch,
+                                            void *msg_callback_arg);
+
 # endif
 
 #endif

include/internal/quic_record_rx.h

@@ -60,6 +60,12 @@ OSSL_QRX *ossl_qrx_new(const OSSL_QRX_ARGS *args);
  */
 void ossl_qrx_free(OSSL_QRX *qrx);
 
+/* Setters for the msg_callback and msg_callback_arg */
+void ossl_qrx_set_msg_callback(OSSL_QRX *qrx, ossl_msg_cb msg_callback,
+                               SSL *msg_callback_ssl);
+void ossl_qrx_set_msg_callback_arg(OSSL_QRX *qrx,
+                                   void *msg_callback_arg);
+
 /*
  * DCID Management
  * ===============

include/internal/quic_record_tx.h

@@ -58,6 +58,11 @@ void ossl_qtx_free(OSSL_QTX *qtx);
 void ossl_qtx_set_mutator(OSSL_QTX *qtx, ossl_mutate_packet_cb mutatecb,
                           ossl_finish_mutate_cb finishmutatecb, void *mutatearg);
 
+/* Setters for the msg_callback and the msg_callback_arg */
+void ossl_qtx_set_msg_callback(OSSL_QTX *qtx, ossl_msg_cb msg_callback,
+                               SSL *msg_callback_ssl);
+void ossl_qtx_set_msg_callback_arg(OSSL_QTX *qtx, void *msg_callback_arg);
+
 /*
  * Secret Management
  * -----------------

include/internal/quic_txp.h

@@ -167,6 +167,13 @@ void ossl_quic_tx_packetiser_schedule_ack_eliciting(OSSL_QUIC_TX_PACKETISER *txp
 int ossl_quic_tx_packetiser_schedule_conn_close(OSSL_QUIC_TX_PACKETISER *txp,
                                                 const OSSL_QUIC_FRAME_CONN_CLOSE *f);
 
+/* Setters for the msg_callback and msg_callback_arg */
+void ossl_quic_tx_packetiser_set_msg_callback(OSSL_QUIC_TX_PACKETISER *txp,
+                                              ossl_msg_cb msg_callback,
+                                              SSL *msg_callback_ssl);
+void ossl_quic_tx_packetiser_set_msg_callback_arg(OSSL_QUIC_TX_PACKETISER *txp,
+                                                  void *msg_callback_arg);
+
 # endif
 
 #endif

include/internal/quic_types.h

@@ -11,6 +11,7 @@
 # define OSSL_QUIC_TYPES_H
 
 # include <openssl/ssl.h>
+# include <internal/ssl.h>
 # include <assert.h>
 # include <string.h>
 

include/internal/quic_wire.h

@@ -557,9 +557,11 @@ int ossl_quic_wire_decode_frame_stop_sending(PACKET *pkt,
  * Decodes a QUIC CRYPTO frame.
  *
  * f->data is set to point inside the packet buffer inside the PACKET, therefore
- * it is safe to access for as long as the packet buffer exists.
+ * it is safe to access for as long as the packet buffer exists. If nodata is
+ * set to 1 then reading the PACKET stops after the frame header and f->data is
+ * set to NULL.
  */
-int ossl_quic_wire_decode_frame_crypto(PACKET *pkt,
+int ossl_quic_wire_decode_frame_crypto(PACKET *pkt, int nodata,
                                        OSSL_QUIC_FRAME_CRYPTO *f);
 
 /*
@@ -573,6 +575,10 @@ int ossl_quic_wire_decode_frame_new_token(PACKET               *pkt,
 /*
  * Decodes a QUIC STREAM frame.
  *
+ * If nodata is set to 1 then reading the PACKET stops after the frame header
+ * and f->data is set to NULL. In this case f->len will also be 0 in the event
+ * that "has_explicit_len" is 0.
+ *
  * If the frame did not contain an offset field, f->offset is set to 0, as the
  * absence of an offset field is equivalent to an offset of 0.
  *
@@ -595,7 +601,7 @@ int ossl_quic_wire_decode_frame_new_token(PACKET               *pkt,
  * f->is_fin is set according to whether the frame was marked as ending the
  * stream.
  */
-int ossl_quic_wire_decode_frame_stream(PACKET *pkt,
+int ossl_quic_wire_decode_frame_stream(PACKET *pkt, int nodata,
                                        OSSL_QUIC_FRAME_STREAM *f);
 
 /*

include/internal/quic_wire_pkt.h

@@ -425,6 +425,9 @@ struct quic_pkt_hdr_ptrs_st {
  * If partial is 0, the input is assumed to have already had header protection
  * removed, and all header fields are decoded.
  *
+ * If nodata is 1, the input is assumed to have no payload data in it. Otherwise
+ * payload data must be present.
+ *
  * On success, the logical decode of the packet header is written to *hdr.
  * hdr->partial is set or cleared according to whether a partial decode was
  * performed. *ptrs is filled with pointers to various parts of the packet
@@ -441,6 +444,7 @@ struct quic_pkt_hdr_ptrs_st {
 int ossl_quic_wire_decode_pkt_hdr(PACKET *pkt,
                                   size_t short_conn_id_len,
                                   int partial,
+                                  int nodata,
                                   QUIC_PKT_HDR *hdr,
                                   QUIC_PKT_HDR_PTRS *ptrs);
 

include/internal/ssl.h

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License 2.0 (the "License").  You may not use
+ * this file except in compliance with the License.  You can obtain a copy
+ * in the file LICENSE in the source distribution or at
+ * https://www.openssl.org/source/license.html
+ */
+
+#include <openssl/ssl.h>
+
+#ifndef OSSL_INTERNAL_SSL_H
+# define OSSL_INTERNAL_SSL_H
+# pragma once
+
+typedef void (*ossl_msg_cb)(int write_p, int version, int content_type,
+                            const void *buf, size_t len, SSL *ssl, void *arg);
+
+#endif

include/openssl/ssl3.h

@@ -239,6 +239,13 @@ extern "C" {
 # define SSL3_RT_HEADER                  0x100
 # define SSL3_RT_INNER_CONTENT_TYPE      0x101
 
+/* Pseudo content types for QUIC */
+# define SSL3_RT_QUIC_DATAGRAM            0x200
+# define SSL3_RT_QUIC_PACKET              0x201
+# define SSL3_RT_QUIC_FRAME_FULL          0x202
+# define SSL3_RT_QUIC_FRAME_HEADER        0x203
+# define SSL3_RT_QUIC_FRAME_PADDING       0x204
+
 # define SSL3_AL_WARNING                 1
 # define SSL3_AL_FATAL                   2
 

ssl/quic/build.info

@@ -13,3 +13,4 @@ SOURCE[$LIBSSL]=quic_channel.c
 SOURCE[$LIBSSL]=quic_tserver.c
 SOURCE[$LIBSSL]=quic_tls.c
 SOURCE[$LIBSSL]=quic_thread_assist.c
+SOURCE[$LIBSSL]=quic_trace.c

ssl/quic/quic_channel.c

@@ -207,6 +207,7 @@ static int ch_init(QUIC_CHANNEL *ch)
     txp_args.cc_data                = ch->cc_data;
     txp_args.now                    = get_time;
     txp_args.now_arg                = ch;
+
     for (pn_space = QUIC_PN_SPACE_INITIAL; pn_space < QUIC_PN_SPACE_NUM; ++pn_space) {
         ch->crypto_send[pn_space] = ossl_quic_sstream_new(INIT_CRYPTO_BUF_LEN);
         if (ch->crypto_send[pn_space] == NULL)
@@ -1589,7 +1590,7 @@ static void ch_default_packet_handler(QUIC_URXE *e, void *arg)
      * operation to fail if we get a 1-RTT packet. This is fine since we only
      * care about Initial packets.
      */
-    if (!ossl_quic_wire_decode_pkt_hdr(&pkt, SIZE_MAX, 1, &hdr, NULL))
+    if (!ossl_quic_wire_decode_pkt_hdr(&pkt, SIZE_MAX, 1, 0, &hdr, NULL))
         goto undesirable;
 
     switch (hdr.version) {
@@ -2508,3 +2509,24 @@ int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch,
         return 0;
     return 1;
 }
+
+void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch,
+                                        ossl_msg_cb msg_callback,
+                                        SSL *msg_callback_ssl)
+{
+    ch->msg_callback = msg_callback;
+    ch->msg_callback_ssl = msg_callback_ssl;
+    ossl_qtx_set_msg_callback(ch->qtx, msg_callback, msg_callback_ssl);
+    ossl_quic_tx_packetiser_set_msg_callback(ch->txp, msg_callback,
+                                             msg_callback_ssl);
+    ossl_qrx_set_msg_callback(ch->qrx, msg_callback, msg_callback_ssl);
+}
+
+void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch,
+                                            void *msg_callback_arg)
+{
+    ch->msg_callback_arg = msg_callback_arg;
+    ossl_qtx_set_msg_callback_arg(ch->qtx, msg_callback_arg);
+    ossl_quic_tx_packetiser_set_msg_callback_arg(ch->txp, msg_callback_arg);
+    ossl_qrx_set_msg_callback_arg(ch->qrx, msg_callback_arg);
+}

ssl/quic/quic_channel_local.h

@@ -93,6 +93,11 @@ struct quic_channel_st {
     OSSL_QTX                        *qtx;
     OSSL_QRX                        *qrx;
 
+    /* Message callback related arguments */
+    ossl_msg_cb                     msg_callback;
+    void                            *msg_callback_arg;
+    SSL                             *msg_callback_ssl;
+
     /*
      * Send and receive parts of the crypto streams.
      * crypto_send[QUIC_PN_SPACE_APP] is the 1-RTT crypto stream. There is no

ssl/quic/quic_impl.c

@@ -309,6 +309,9 @@ SSL *ossl_quic_new(SSL_CTX *ctx)
     if (!create_channel(qc))
         goto err;
 
+    ossl_quic_channel_set_msg_callback(qc->ch, ctx->msg_callback, ssl_base);
+    ossl_quic_channel_set_msg_callback_arg(qc->ch, ctx->msg_callback_arg);
+
     qc_update_reject_policy(qc);
 
     /*
@@ -1009,6 +1012,12 @@ long ossl_quic_ctrl(SSL *s, int cmd, long larg, void *parg)
         }
 
         return ctx.qc->default_ssl_mode;
+
+    case SSL_CTRL_SET_MSG_CALLBACK_ARG:
+        ossl_quic_channel_set_msg_callback_arg(ctx.qc->ch, parg);
+        /* This ctrl also needs to be passed to the internal SSL object */
+        return SSL_ctrl(ctx.qc->tls, cmd, larg, parg);
+
     default:
         /* Probably a TLS related ctrl. Defer to our internal SSL object */
         return SSL_ctrl(ctx.qc->tls, cmd, larg, parg);
@@ -2608,7 +2617,22 @@ long ossl_quic_ctx_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg)
 
 long ossl_quic_callback_ctrl(SSL *s, int cmd, void (*fp) (void))
 {
-    return ssl3_callback_ctrl(s, cmd, fp);
+    QCTX ctx;
+
+    if (!expect_quic_conn_only(s, &ctx))
+        return 0;
+
+    switch (cmd) {
+    case SSL_CTRL_SET_MSG_CALLBACK:
+        ossl_quic_channel_set_msg_callback(ctx.qc->ch, (ossl_msg_cb)fp,
+                                           &ctx.qc->ssl);
+        /* This callback also needs to be set on the internal SSL object */
+        return ssl3_callback_ctrl(ctx.qc->tls, cmd, fp);;
+
+    default:
+        /* Probably a TLS related ctrl. Defer to our internal SSL object */
+        return ssl3_callback_ctrl(ctx.qc->tls, cmd, fp);
+    }
 }
 
 long ossl_quic_ctx_callback_ctrl(SSL_CTX *ctx, int cmd, void (*fp) (void))

ssl/quic/quic_local.h

@@ -206,6 +206,9 @@ void ossl_quic_conn_raise_protocol_error(QUIC_CONNECTION *qc,
 void ossl_quic_conn_on_remote_conn_close(QUIC_CONNECTION *qc,
                                          OSSL_QUIC_FRAME_CONN_CLOSE *f);
 
+int ossl_quic_trace(int write_p, int version, int content_type,
+                    const void *buf, size_t msglen, SSL *ssl, void *arg);
+
 #  define OSSL_QUIC_ANY_VERSION 0xFFFFF
 
 #  define QUIC_CONNECTION_FROM_SSL_int(ssl, c)   \