1=pod
2
3=head1 NAME
4
5SSL_CTX_set_msg_callback,
6SSL_CTX_set_msg_callback_arg,
7SSL_set_msg_callback,
8SSL_set_msg_callback_arg
9- install callback for observing protocol messages
10
11=head1 SYNOPSIS
12
13 #include <openssl/ssl.h>
14
15 void SSL_CTX_set_msg_callback(SSL_CTX *ctx,
16                               void (*cb)(int write_p, int version,
17                                          int content_type, const void *buf,
18                                          size_t len, SSL *ssl, void *arg));
19 void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
20
21 void SSL_set_msg_callback(SSL *ssl,
22                           void (*cb)(int write_p, int version,
23                                      int content_type, const void *buf,
24                                      size_t len, SSL *ssl, void *arg));
25 void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
26
27=head1 DESCRIPTION
28
29SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
30define a message callback function I<cb> for observing all SSL/TLS
31protocol messages (such as handshake messages) that are received or
32sent, as well as other events that occur during processing.
33SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
34can be used to set argument I<arg> to the callback function, which is
35available for arbitrary application use.
36
37SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
38default settings that will be copied to new B<SSL> objects by
39L<SSL_new(3)>. SSL_set_msg_callback() and
40SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
41object. Using a B<NULL> pointer for I<cb> disables the message callback.
42
43When I<cb> is called by the SSL/TLS library the function arguments have the
44following meaning:
45
46=over 4
47
48=item I<write_p>
49
50This flag is B<0> when a protocol message has been received and B<1>
51when a protocol message has been sent.
52
53=item I<version>
54
55The protocol version according to which the protocol message is
56interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION> etc.
57This is set to 0 for the SSL3_RT_HEADER pseudo content type (see NOTES below).
58
59=item I<content_type>
60
61This is one of the content type values defined in the protocol specification
62(B<SSL3_RT_CHANGE_CIPHER_SPEC>, B<SSL3_RT_ALERT>, B<SSL3_RT_HANDSHAKE>; but never
63B<SSL3_RT_APPLICATION_DATA> because the callback will only be called for protocol
64messages). Alternatively it may be a "pseudo" content type. These pseudo
65content types are used to signal some other event in the processing of data (see
66NOTES below).
67
68=item I<buf>, I<len>
69
70I<buf> points to a buffer containing the protocol message or other data (in the
71case of pseudo content types), which consists of I<len> bytes. The buffer is no
72longer valid after the callback function has returned.
73
74=item I<ssl>
75
76The B<SSL> object that received or sent the message.
77
78=item I<arg>
79
80The user-defined argument optionally defined by
81SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
82
83=back
84
85=head1 NOTES
86
87Protocol messages are passed to the callback function after decryption
88and fragment collection where applicable. (Thus record boundaries are
89not visible.)
90
91If processing a received protocol message results in an error,
92the callback function may not be called.  For example, the callback
93function will never see messages that are considered too large to be
94processed.
95
96Due to automatic protocol version negotiation, I<version> is not
97necessarily the protocol version used by the sender of the message: If
98a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
99I<version> will be B<SSL3_VERSION>.
100
101Pseudo content type values may be sent at various points during the processing
102of data. The following pseudo content types are currently defined:
103
104=over 4
105
106=item B<SSL3_RT_HEADER>
107
108Used when a record is sent or received. The B<buf> contains the record header
109bytes only.
110
111=item B<SSL3_RT_INNER_CONTENT_TYPE>
112
113Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3
114records the content type in the record header is always
115SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in
116an "inner" content type. B<buf> contains the encoded "inner" content type byte.
117
118=back
119
120=head1 RETURN VALUES
121
122SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), SSL_set_msg_callback()
123and SSL_set_msg_callback_arg() do not return values.
124
125=head1 SEE ALSO
126
127L<ssl(7)>, L<SSL_new(3)>
128
129=head1 HISTORY
130
131The pseudo content type B<SSL3_RT_INNER_CONTENT_TYPE> was added in OpenSSL 1.1.1.
132
133=head1 COPYRIGHT
134
135Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
136
137Licensed under the Apache License 2.0 (the "License").  You may not use
138this file except in compliance with the License.  You can obtain a copy
139in the file LICENSE in the source distribution or at
140L<https://www.openssl.org/source/license.html>.
141
142=cut
143