]>
Commit | Line | Data |
---|---|---|
1d8634b1 BM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
e091367d MC |
5 | SSL_CTX_set_msg_callback, |
6 | SSL_CTX_set_msg_callback_arg, | |
7 | SSL_set_msg_callback, | |
bfcf1356 MC |
8 | SSL_set_msg_callback_arg, |
9 | SSL_trace | |
e091367d | 10 | - install callback for observing protocol messages |
1d8634b1 BM |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/ssl.h> | |
15 | ||
e9b77246 BB |
16 | void SSL_CTX_set_msg_callback(SSL_CTX *ctx, |
17 | void (*cb)(int write_p, int version, | |
18 | int content_type, const void *buf, | |
19 | size_t len, SSL *ssl, void *arg)); | |
1d8634b1 BM |
20 | void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); |
21 | ||
e9b77246 BB |
22 | void SSL_set_msg_callback(SSL *ssl, |
23 | void (*cb)(int write_p, int version, | |
24 | int content_type, const void *buf, | |
25 | size_t len, SSL *ssl, void *arg)); | |
15658d0c | 26 | void SSL_set_msg_callback_arg(SSL *ssl, void *arg); |
1d8634b1 | 27 | |
bfcf1356 MC |
28 | void SSL_trace(int write_p, int version, int content_type, |
29 | const void *buf, size_t len, SSL *ssl, void *arg); | |
30 | ||
1d8634b1 BM |
31 | =head1 DESCRIPTION |
32 | ||
33 | SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to | |
bfcf1356 | 34 | define a message callback function I<cb> for observing all SSL/TLS/QUIC |
1d8634b1 | 35 | protocol messages (such as handshake messages) that are received or |
e091367d MC |
36 | sent, as well as other events that occur during processing. |
37 | SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() | |
1d8634b1 BM |
38 | can be used to set argument I<arg> to the callback function, which is |
39 | available for arbitrary application use. | |
40 | ||
41 | SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify | |
42 | default settings that will be copied to new B<SSL> objects by | |
9b86974e | 43 | L<SSL_new(3)>. SSL_set_msg_callback() and |
1d8634b1 | 44 | SSL_set_msg_callback_arg() modify the actual settings of an B<SSL> |
e091367d | 45 | object. Using a B<NULL> pointer for I<cb> disables the message callback. |
1d8634b1 | 46 | |
bfcf1356 | 47 | When I<cb> is called by the SSL/TLS/QUIC library the function arguments have the |
e091367d | 48 | following meaning: |
1d8634b1 BM |
49 | |
50 | =over 4 | |
51 | ||
52 | =item I<write_p> | |
53 | ||
54 | This flag is B<0> when a protocol message has been received and B<1> | |
55 | when a protocol message has been sent. | |
56 | ||
57 | =item I<version> | |
58 | ||
59 | The protocol version according to which the protocol message is | |
bfcf1356 MC |
60 | interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION>, |
61 | B<OSSL_QUIC1_VERSION> etc. This is set to 0 for the SSL3_RT_HEADER pseudo | |
62 | content type (see NOTES below). | |
1d8634b1 BM |
63 | |
64 | =item I<content_type> | |
65 | ||
e091367d MC |
66 | This is one of the content type values defined in the protocol specification |
67 | (B<SSL3_RT_CHANGE_CIPHER_SPEC>, B<SSL3_RT_ALERT>, B<SSL3_RT_HANDSHAKE>; but never | |
68 | B<SSL3_RT_APPLICATION_DATA> because the callback will only be called for protocol | |
69 | messages). Alternatively it may be a "pseudo" content type. These pseudo | |
70 | content types are used to signal some other event in the processing of data (see | |
71 | NOTES below). | |
1d8634b1 BM |
72 | |
73 | =item I<buf>, I<len> | |
74 | ||
e091367d MC |
75 | I<buf> points to a buffer containing the protocol message or other data (in the |
76 | case of pseudo content types), which consists of I<len> bytes. The buffer is no | |
77 | longer valid after the callback function has returned. | |
1d8634b1 BM |
78 | |
79 | =item I<ssl> | |
80 | ||
81 | The B<SSL> object that received or sent the message. | |
82 | ||
83 | =item I<arg> | |
84 | ||
85 | The user-defined argument optionally defined by | |
86 | SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). | |
87 | ||
37f5fcf8 RL |
88 | =back |
89 | ||
bfcf1356 MC |
90 | The SSL_trace() function can be used as a pre-written callback in a call to |
91 | SSL_CTX_set_msg_callback() or SSL_set_msg_callback(). It requires a BIO to be | |
92 | set as the callback argument via SSL_CTX_set_msg_callback_arg() or | |
93 | SSL_set_msg_callback_arg(). Setting this callback will cause human readable | |
94 | diagostic tracing information about an SSL/TLS/QUIC connection to be written to | |
95 | the BIO. | |
96 | ||
1d8634b1 BM |
97 | =head1 NOTES |
98 | ||
99 | Protocol messages are passed to the callback function after decryption | |
100 | and fragment collection where applicable. (Thus record boundaries are | |
101 | not visible.) | |
102 | ||
103 | If processing a received protocol message results in an error, | |
104 | the callback function may not be called. For example, the callback | |
105 | function will never see messages that are considered too large to be | |
106 | processed. | |
107 | ||
108 | Due to automatic protocol version negotiation, I<version> is not | |
109 | necessarily the protocol version used by the sender of the message: If | |
110 | a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, | |
111 | I<version> will be B<SSL3_VERSION>. | |
112 | ||
e091367d MC |
113 | Pseudo content type values may be sent at various points during the processing |
114 | of data. The following pseudo content types are currently defined: | |
115 | ||
116 | =over 4 | |
117 | ||
118 | =item B<SSL3_RT_HEADER> | |
119 | ||
bfcf1356 | 120 | Used when a TLS record is sent or received. The B<buf> contains the record header |
e091367d MC |
121 | bytes only. |
122 | ||
123 | =item B<SSL3_RT_INNER_CONTENT_TYPE> | |
124 | ||
125 | Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3 | |
126 | records the content type in the record header is always | |
127 | SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in | |
128 | an "inner" content type. B<buf> contains the encoded "inner" content type byte. | |
129 | ||
bfcf1356 MC |
130 | =item B<SSL3_RT_QUIC_DATAGRAM> |
131 | ||
132 | Used when a QUIC datagram is sent or received. | |
133 | ||
134 | =item B<SSL3_RT_QUIC_PACKET> | |
135 | ||
136 | Used when a QUIC packet is sent or received. | |
137 | ||
138 | =item B<SSL3_RT_QUIC_FRAME_FULL> | |
139 | ||
140 | Used when a QUIC frame is sent or received. This is only used for non-crypto | |
141 | and stream data related frames. The full QUIC frame data is supplied. | |
142 | ||
143 | =item B<SSL3_RT_QUIC_FRAME_HEADER> | |
144 | ||
145 | Used when a QUIC stream data or crypto frame is sent or received. Only the QUIC | |
146 | frame header data is supplied. | |
147 | ||
148 | =item B<SSL3_RT_QUIC_FRAME_PADDING> | |
149 | ||
150 | Used when a sequence of one or more QUIC padding frames is sent or received. | |
151 | A padding frame consists of a single byte and it is common to have multiple | |
152 | such frames in a sequence. Rather than supplying each frame individually the | |
153 | callback will supply all the padding frames in one go via this pseudo content | |
154 | type. | |
155 | ||
e091367d MC |
156 | =back |
157 | ||
1f13ad31 PY |
158 | =head1 RETURN VALUES |
159 | ||
160 | SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), SSL_set_msg_callback() | |
161 | and SSL_set_msg_callback_arg() do not return values. | |
162 | ||
1d8634b1 BM |
163 | =head1 SEE ALSO |
164 | ||
b97fdb57 | 165 | L<ssl(7)>, L<SSL_new(3)> |
1d8634b1 | 166 | |
e091367d MC |
167 | =head1 HISTORY |
168 | ||
fc5ecadd | 169 | The pseudo content type B<SSL3_RT_INNER_CONTENT_TYPE> was added in OpenSSL 1.1.1. |
e091367d | 170 | |
bfcf1356 MC |
171 | The pseudo content types B<SSL3_RT_QUIC_DATAGRAM>, B<SSL3_RT_QUIC_PACKET>, |
172 | B<SSL3_RT_QUIC_FRAME_FULL>, B<SSL3_RT_QUIC_FRAME_HEADER> and | |
173 | B<SSL3_RT_QUIC_FRAME_PADDING> were added in OpenSSL 3.2. | |
174 | ||
e2f92610 RS |
175 | =head1 COPYRIGHT |
176 | ||
da1c088f | 177 | Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 178 | |
4746f25a | 179 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
180 | this file except in compliance with the License. You can obtain a copy |
181 | in the file LICENSE in the source distribution or at | |
182 | L<https://www.openssl.org/source/license.html>. | |
183 | ||
184 | =cut |