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