Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_msg_callback.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_set_msg_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg \- install callback for observing protocol messages
192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 2
198\& 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));
199\& void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
200.Ve
201.Vb 2
202\& void SSL_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));
203\& void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
204.Ve
205.SH "DESCRIPTION"
a7d27d5a
JR
206\fISSL_CTX_set_msg_callback()\fR or \fISSL_set_msg_callback()\fR can be used to
207define a message callback function \fIcb\fR for observing all SSL/TLS
984263bc
MD
208protocol messages (such as handshake messages) that are received or
209sent. \fISSL_CTX_set_msg_callback_arg()\fR and \fISSL_set_msg_callback_arg()\fR
210can be used to set argument \fIarg\fR to the callback function, which is
211available for arbitrary application use.
212.PP
a7d27d5a
JR
213\fISSL_CTX_set_msg_callback()\fR and \fISSL_CTX_set_msg_callback_arg()\fR specify
214default settings that will be copied to new \fBSSL\fR objects by
984263bc 215SSL_new(3). \fISSL_set_msg_callback()\fR and
a7d27d5a 216\fISSL_set_msg_callback_arg()\fR modify the actual settings of an \fBSSL\fR
984263bc
MD
217object. Using a \fB0\fR pointer for \fIcb\fR disables the message callback.
218.PP
a7d27d5a 219When \fIcb\fR is called by the SSL/TLS library for a protocol message,
984263bc
MD
220the function arguments have the following meaning:
221.Ip "\fIwrite_p\fR" 4
984263bc
MD
222This flag is \fB0\fR when a protocol message has been received and \fB1\fR
223when a protocol message has been sent.
224.Ip "\fIversion\fR" 4
984263bc
MD
225The protocol version according to which the protocol message is
226interpreted by the library. Currently, this is one of
a7d27d5a 227\fB\s-1SSL2_VERSION\s0\fR, \fB\s-1SSL3_VERSION\s0\fR and \fB\s-1TLS1_VERSION\s0\fR (for \s-1SSL\s0 2.0, \s-1SSL\s0
984263bc
MD
2283.0 and \s-1TLS\s0 1.0, respectively).
229.Ip "\fIcontent_type\fR" 4
984263bc
MD
230In the case of \s-1SSL\s0 2.0, this is always \fB0\fR. In the case of \s-1SSL\s0 3.0
231or \s-1TLS\s0 1.0, this is one of the \fBContentType\fR values defined in the
232protocol specification (\fBchange_cipher_spec(20)\fR, \fBalert(21)\fR,
a7d27d5a 233\fBhandshake(22)\fR; but never \fBapplication_data(23)\fR because the
984263bc
MD
234callback will only be called for protocol messages).
235.Ip "\fIbuf\fR, \fIlen\fR" 4
a7d27d5a 236\fIbuf\fR points to a buffer containing the protocol message, which
984263bc
MD
237consists of \fIlen\fR bytes. The buffer is no longer valid after the
238callback function has returned.
239.Ip "\fIssl\fR" 4
984263bc
MD
240The \fB\s-1SSL\s0\fR object that received or sent the message.
241.Ip "\fIarg\fR" 4
984263bc 242The user-defined argument optionally defined by
a7d27d5a 243\fISSL_CTX_set_msg_callback_arg()\fR or \fISSL_set_msg_callback_arg()\fR.
984263bc 244.SH "NOTES"
984263bc
MD
245Protocol messages are passed to the callback function after decryption
246and fragment collection where applicable. (Thus record boundaries are
247not visible.)
248.PP
249If processing a received protocol message results in an error,
250the callback function may not be called. For example, the callback
251function will never see messages that are considered too large to be
252processed.
253.PP
254Due to automatic protocol version negotiation, \fIversion\fR is not
255necessarily the protocol version used by the sender of the message: If
a7d27d5a
JR
256a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
257\fIversion\fR will be \fBSSL3_VERSION\fR.
984263bc 258.SH "SEE ALSO"
984263bc
MD
259ssl(3), SSL_new(3)
260.SH "HISTORY"
a7d27d5a
JR
261\fISSL_CTX_set_msg_callback()\fR, \fISSL_CTX_set_msg_callback_arg()\fR,
262\fISSL_set_msg_callback()\fR and \fISSL_get_msg_callback_arg()\fR were added in OpenSSL 0.9.7.
263
264.rn }` ''
265.IX Title "SSL_CTX_set_msg_callback 3"
266.IX Name "SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg - install callback for observing protocol messages"
267
268.IX Header "NAME"
269
270.IX Header "SYNOPSIS"
271
272.IX Header "DESCRIPTION"
273
274.IX Item "\fIwrite_p\fR"
275
276.IX Item "\fIversion\fR"
277
278.IX Item "\fIcontent_type\fR"
279
280.IX Item "\fIbuf\fR, \fIlen\fR"
281
282.IX Item "\fIssl\fR"
283
284.IX Item "\fIarg\fR"
285
286.IX Header "NOTES"
287
288.IX Header "SEE ALSO"
289
984263bc 290.IX Header "HISTORY"
a7d27d5a 291