mmo-ref/dep-openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update the msg_callback documentation

Browse source 
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)
This commit is contained in:
Matt Caswell 2023-05-09 12:00:18 +01:00
parent cc87010d27
commit bfcf1356f9
2 changed files with 48 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

54
doc/man3/SSL_CTX_set_msg_callback.pod
View file

@ -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.

1
util/missingssl.txt
View file

@ -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)