Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_msg_callback.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_MSG_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_MSG_CALLBACK 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_msg_callback,
65 SSL_CTX_set_msg_callback_arg,
66 SSL_set_msg_callback,
67 SSL_set_msg_callback_arg,
68 SSL_trace
69 \&\- install callback for observing protocol messages
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/ssl.h>
74 \&
75 \& void SSL_CTX_set_msg_callback(SSL_CTX *ctx,
76 \& void (*cb)(int write_p, int version,
77 \& int content_type, const void *buf,
78 \& size_t len, SSL *ssl, void *arg));
79 \& void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
80 \&
81 \& void SSL_set_msg_callback(SSL *ssl,
82 \& void (*cb)(int write_p, int version,
83 \& int content_type, const void *buf,
84 \& size_t len, SSL *ssl, void *arg));
85 \& void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
86 \&
87 \& void SSL_trace(int write_p, int version, int content_type,
88 \& const void *buf, size_t len, SSL *ssl, void *arg);
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 \&\fBSSL_CTX_set_msg_callback()\fR or \fBSSL_set_msg_callback()\fR can be used to
93 define a message callback function \fIcb\fR for observing all SSL/TLS/QUIC
94 protocol messages (such as handshake messages) that are received or
95 sent, as well as other events that occur during processing.
96 \&\fBSSL_CTX_set_msg_callback_arg()\fR and \fBSSL_set_msg_callback_arg()\fR
97 can be used to set argument \fIarg\fR to the callback function, which is
98 available for arbitrary application use.
99 .PP
100 \&\fBSSL_CTX_set_msg_callback()\fR and \fBSSL_CTX_set_msg_callback_arg()\fR specify
101 default settings that will be copied to new \fBSSL\fR objects by
102 \&\fBSSL_new\fR\|(3). \fBSSL_set_msg_callback()\fR and
103 \&\fBSSL_set_msg_callback_arg()\fR modify the actual settings of an \fBSSL\fR
104 object. Using a \fBNULL\fR pointer for \fIcb\fR disables the message callback.
105 .PP
106 When \fIcb\fR is called by the SSL/TLS/QUIC library the function arguments have the
107 following meaning:
108 .IP \fIwrite_p\fR 4
109 .IX Item "write_p"
110 This flag is \fB0\fR when a protocol message has been received and \fB1\fR
111 when a protocol message has been sent.
112 .IP \fIversion\fR 4
113 .IX Item "version"
114 The protocol version according to which the protocol message is
115 interpreted by the library such as \fBTLS1_3_VERSION\fR, \fBTLS1_2_VERSION\fR,
116 \&\fBOSSL_QUIC1_VERSION\fR etc. For the SSL3_RT_HEADER pseudo
117 content type (see NOTES below) this value will be the decoded
118 version/legacy_version field of the record header.
119 .IP \fIcontent_type\fR 4
120 .IX Item "content_type"
121 This is one of the content type values defined in the protocol specification
122 (\fBSSL3_RT_CHANGE_CIPHER_SPEC\fR, \fBSSL3_RT_ALERT\fR, \fBSSL3_RT_HANDSHAKE\fR; but never
123 \&\fBSSL3_RT_APPLICATION_DATA\fR because the callback will only be called for protocol
124 messages). Alternatively it may be a "pseudo" content type. These pseudo
125 content types are used to signal some other event in the processing of data (see
126 NOTES below).
127 .IP "\fIbuf\fR, \fIlen\fR" 4
128 .IX Item "buf, len"
129 \&\fIbuf\fR points to a buffer containing the protocol message or other data (in the
130 case of pseudo content types), which consists of \fIlen\fR bytes. The buffer is no
131 longer valid after the callback function has returned.
132 .IP \fIssl\fR 4
133 .IX Item "ssl"
134 The \fBSSL\fR object that received or sent the message.
135 .IP \fIarg\fR 4
136 .IX Item "arg"
137 The user-defined argument optionally defined by
138 \&\fBSSL_CTX_set_msg_callback_arg()\fR or \fBSSL_set_msg_callback_arg()\fR.
139 .PP
140 The \fBSSL_trace()\fR function can be used as a pre-written callback in a call to
141 \&\fBSSL_CTX_set_msg_callback()\fR or \fBSSL_set_msg_callback()\fR. It requires a BIO to be
142 set as the callback argument via \fBSSL_CTX_set_msg_callback_arg()\fR or
143 \&\fBSSL_set_msg_callback_arg()\fR. Setting this callback will cause human readable
144 diagostic tracing information about an SSL/TLS/QUIC connection to be written to
145 the BIO.
146 .SH NOTES
147 .IX Header "NOTES"
148 Protocol messages are passed to the callback function after decryption
149 and fragment collection where applicable. (Thus record boundaries are
150 not visible.)
151 .PP
152 If processing a received protocol message results in an error,
153 the callback function may not be called. For example, the callback
154 function will never see messages that are considered too large to be
155 processed.
156 .PP
157 Due to automatic protocol version negotiation, \fIversion\fR is not
158 necessarily the protocol version used by the sender of the message: If
159 a TLS 1.0 ClientHello message is received by an SSL 3.0\-only server,
160 \&\fIversion\fR will be \fBSSL3_VERSION\fR.
161 .PP
162 Pseudo content type values may be sent at various points during the processing
163 of data. The following pseudo content types are currently defined:
164 .IP \fBSSL3_RT_HEADER\fR 4
165 .IX Item "SSL3_RT_HEADER"
166 Used when a TLS record is sent or received. The \fBbuf\fR contains the record header
167 bytes only.
168 .IP \fBSSL3_RT_INNER_CONTENT_TYPE\fR 4
169 .IX Item "SSL3_RT_INNER_CONTENT_TYPE"
170 Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3
171 records the content type in the record header is always
172 SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in
173 an "inner" content type. \fBbuf\fR contains the encoded "inner" content type byte.
174 .IP \fBSSL3_RT_QUIC_DATAGRAM\fR 4
175 .IX Item "SSL3_RT_QUIC_DATAGRAM"
176 Used when a QUIC datagram is sent or received.
177 .IP \fBSSL3_RT_QUIC_PACKET\fR 4
178 .IX Item "SSL3_RT_QUIC_PACKET"
179 Used when a QUIC packet is sent or received.
180 .IP \fBSSL3_RT_QUIC_FRAME_FULL\fR 4
181 .IX Item "SSL3_RT_QUIC_FRAME_FULL"
182 Used when a QUIC frame is sent or received. This is only used for non-crypto
183 and stream data related frames. The full QUIC frame data is supplied.
184 .IP \fBSSL3_RT_QUIC_FRAME_HEADER\fR 4
185 .IX Item "SSL3_RT_QUIC_FRAME_HEADER"
186 Used when a QUIC stream data or crypto frame is sent or received. Only the QUIC
187 frame header data is supplied.
188 .IP \fBSSL3_RT_QUIC_FRAME_PADDING\fR 4
189 .IX Item "SSL3_RT_QUIC_FRAME_PADDING"
190 Used when a sequence of one or more QUIC padding frames is sent or received.
191 A padding frame consists of a single byte and it is common to have multiple
192 such frames in a sequence. Rather than supplying each frame individually the
193 callback will supply all the padding frames in one go via this pseudo content
194 type.
195 .SH "RETURN VALUES"
196 .IX Header "RETURN VALUES"
197 \&\fBSSL_CTX_set_msg_callback()\fR, \fBSSL_CTX_set_msg_callback_arg()\fR, \fBSSL_set_msg_callback()\fR
198 and \fBSSL_set_msg_callback_arg()\fR do not return values.
199 .SH "SEE ALSO"
200 .IX Header "SEE ALSO"
201 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3)
202 .SH HISTORY
203 .IX Header "HISTORY"
204 The pseudo content type \fBSSL3_RT_INNER_CONTENT_TYPE\fR was added in OpenSSL 1.1.1.
205 .PP
206 The pseudo content types \fBSSL3_RT_QUIC_DATAGRAM\fR, \fBSSL3_RT_QUIC_PACKET\fR,
207 \&\fBSSL3_RT_QUIC_FRAME_FULL\fR, \fBSSL3_RT_QUIC_FRAME_HEADER\fR and
208 \&\fBSSL3_RT_QUIC_FRAME_PADDING\fR were added in OpenSSL 3.2.
209 .PP
210 In versions previous to OpenSSL 3.0 \fIcb\fR was called with 0 as \fIversion\fR for
211 the pseudo content type \fBSSL3_RT_HEADER\fR for TLS records.
212 .PP
213 In versions previous to OpenSSL 3.2 \fIcb\fR was called with 0 as \fIversion\fR for
214 the pseudo content type \fBSSL3_RT_HEADER\fR for DTLS records.
215 .SH COPYRIGHT
216 .IX Header "COPYRIGHT"
217 Copyright 2001\-2023 The OpenSSL Project Authors. All Rights Reserved.
218 .PP
219 Licensed under the Apache License 2.0 (the "License"). You may not use
220 this file except in compliance with the License. You can obtain a copy
221 in the file LICENSE in the source distribution or at
222 <https://www.openssl.org/source/license.html>.