diff options
author | Matt Caswell <matt@openssl.org> | 2023-05-09 12:00:18 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2023-05-24 12:18:33 +0100 |
commit | bfcf1356f9fdc6ad939f73f2d4e505bd519c33d2 (patch) | |
tree | 87c81957fb71fae6763582af7efc342337ef3d89 | |
parent | cc87010d27f4dc3645ea718144bf387d8833e14c (diff) |
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)
-rw-r--r-- | doc/man3/SSL_CTX_set_msg_callback.pod | 54 | ||||
-rw-r--r-- | util/missingssl.txt | 1 |
2 files changed, 48 insertions, 7 deletions
diff --git a/doc/man3/SSL_CTX_set_msg_callback.pod b/doc/man3/SSL_CTX_set_msg_callback.pod index 9f7a17433d..bb29761e8d 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 48219fd99a..224eb84899 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) |