From: Matt Caswell <matt@openssl.org>
Date: Tue, 9 May 2023 11:00:18 +0000 (+0100)
Subject: Update the msg_callback documentation
X-Git-Tag: openssl-3.2.0-alpha1~760
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bfcf1356f9fdc6ad939f73f2d4e505bd519c33d2;p=thirdparty%2Fopenssl.git

Update the msg_callback documentation

We provide information about the new QUIC support related to the
msg_callback. We also document SSL_trace() which was previously missing
from the man pages.

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

diff --git a/doc/man3/SSL_CTX_set_msg_callback.pod b/doc/man3/SSL_CTX_set_msg_callback.pod
index 9f7a17433d2..bb29761e8d2 100644
--- a/doc/man3/SSL_CTX_set_msg_callback.pod
+++ b/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.
diff --git a/util/missingssl.txt b/util/missingssl.txt
index 48219fd99a9..224eb84899f 100644
--- a/util/missingssl.txt
+++ b/util/missingssl.txt
@@ -31,4 +31,3 @@ SSL_set_session_ticket_ext(3)
 SSL_set_session_ticket_ext_cb(3)
 SSL_srp_server_param_with_username(3)
 SSL_test_functions(3)
-SSL_trace(3)