mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
74f8d9ce08
Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/22241)
192 lines
6.6 KiB
Plaintext
192 lines
6.6 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_CTX_set_msg_callback,
|
|
SSL_CTX_set_msg_callback_arg,
|
|
SSL_set_msg_callback,
|
|
SSL_set_msg_callback_arg,
|
|
SSL_trace
|
|
- install callback for observing protocol messages
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
void SSL_CTX_set_msg_callback(SSL_CTX *ctx,
|
|
void (*cb)(int write_p, int version,
|
|
int content_type, const void *buf,
|
|
size_t len, SSL *ssl, void *arg));
|
|
void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
|
|
|
|
void SSL_set_msg_callback(SSL *ssl,
|
|
void (*cb)(int write_p, int version,
|
|
int content_type, const void *buf,
|
|
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/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()
|
|
can be used to set argument I<arg> to the callback function, which is
|
|
available for arbitrary application use.
|
|
|
|
SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
|
|
default settings that will be copied to new B<SSL> objects by
|
|
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/QUIC library the function arguments have the
|
|
following meaning:
|
|
|
|
=over 4
|
|
|
|
=item I<write_p>
|
|
|
|
This flag is B<0> when a protocol message has been received and B<1>
|
|
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>,
|
|
B<OSSL_QUIC1_VERSION> etc. For the SSL3_RT_HEADER pseudo
|
|
content type (see NOTES below) this value will be the decoded
|
|
version/legacy_version field of the record header.
|
|
|
|
=item I<content_type>
|
|
|
|
This is one of the content type values defined in the protocol specification
|
|
(B<SSL3_RT_CHANGE_CIPHER_SPEC>, B<SSL3_RT_ALERT>, B<SSL3_RT_HANDSHAKE>; but never
|
|
B<SSL3_RT_APPLICATION_DATA> because the callback will only be called for protocol
|
|
messages). Alternatively it may be a "pseudo" content type. These pseudo
|
|
content types are used to signal some other event in the processing of data (see
|
|
NOTES below).
|
|
|
|
=item I<buf>, I<len>
|
|
|
|
I<buf> points to a buffer containing the protocol message or other data (in the
|
|
case of pseudo content types), which consists of I<len> bytes. The buffer is no
|
|
longer valid after the callback function has returned.
|
|
|
|
=item I<ssl>
|
|
|
|
The B<SSL> object that received or sent the message.
|
|
|
|
=item I<arg>
|
|
|
|
The user-defined argument optionally defined by
|
|
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
|
|
and fragment collection where applicable. (Thus record boundaries are
|
|
not visible.)
|
|
|
|
If processing a received protocol message results in an error,
|
|
the callback function may not be called. For example, the callback
|
|
function will never see messages that are considered too large to be
|
|
processed.
|
|
|
|
Due to automatic protocol version negotiation, I<version> is not
|
|
necessarily the protocol version used by the sender of the message: If
|
|
a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
|
|
I<version> will be B<SSL3_VERSION>.
|
|
|
|
Pseudo content type values may be sent at various points during the processing
|
|
of data. The following pseudo content types are currently defined:
|
|
|
|
=over 4
|
|
|
|
=item B<SSL3_RT_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>
|
|
|
|
Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3
|
|
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
|
|
|
|
SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), SSL_set_msg_callback()
|
|
and SSL_set_msg_callback_arg() do not return values.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(7)>, L<SSL_new(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
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.
|
|
|
|
In versions previous to OpenSSL 3.0 I<cb> was called with 0 as I<version> for
|
|
the pseudo content type B<SSL3_RT_HEADER> for TLS records.
|
|
|
|
In versions previous to OpenSSL 3.2 I<cb> was called with 0 as I<version> for
|
|
the pseudo content type B<SSL3_RT_HEADER> for DTLS records.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2001-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
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|