Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_msg_callback.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
e056f0e0
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
e056f0e0
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
e056f0e0
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
e056f0e0 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
e056f0e0
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
e056f0e0
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
e056f0e0 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
e056f0e0
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
e056f0e0
JR
124.\" ========================================================================
125.\"
126.IX Title "SSL_CTX_set_msg_callback 3"
e3261593 127.TH SSL_CTX_set_msg_callback 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133SSL_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
134.SH "SYNOPSIS"
e056f0e0 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/ssl.h>
e257b235 138\&
984263bc
MD
139\& 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));
140\& void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
e257b235 141\&
984263bc
MD
142\& 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));
143\& void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
144.Ve
145.SH "DESCRIPTION"
e056f0e0
JR
146.IX Header "DESCRIPTION"
147\&\fISSL_CTX_set_msg_callback()\fR or \fISSL_set_msg_callback()\fR can be used to
148define a message callback function \fIcb\fR for observing all \s-1SSL/TLS\s0
984263bc
MD
149protocol messages (such as handshake messages) that are received or
150sent. \fISSL_CTX_set_msg_callback_arg()\fR and \fISSL_set_msg_callback_arg()\fR
151can be used to set argument \fIarg\fR to the callback function, which is
152available for arbitrary application use.
153.PP
e056f0e0
JR
154\&\fISSL_CTX_set_msg_callback()\fR and \fISSL_CTX_set_msg_callback_arg()\fR specify
155default settings that will be copied to new \fB\s-1SSL\s0\fR objects by
156\&\fISSL_new\fR\|(3). \fISSL_set_msg_callback()\fR and
157\&\fISSL_set_msg_callback_arg()\fR modify the actual settings of an \fB\s-1SSL\s0\fR
984263bc
MD
158object. Using a \fB0\fR pointer for \fIcb\fR disables the message callback.
159.PP
e056f0e0 160When \fIcb\fR is called by the \s-1SSL/TLS\s0 library for a protocol message,
984263bc 161the function arguments have the following meaning:
e056f0e0
JR
162.IP "\fIwrite_p\fR" 4
163.IX Item "write_p"
984263bc
MD
164This flag is \fB0\fR when a protocol message has been received and \fB1\fR
165when a protocol message has been sent.
e056f0e0
JR
166.IP "\fIversion\fR" 4
167.IX Item "version"
984263bc
MD
168The protocol version according to which the protocol message is
169interpreted by the library. Currently, this is one of
e056f0e0 170\&\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 1713.0 and \s-1TLS\s0 1.0, respectively).
e056f0e0
JR
172.IP "\fIcontent_type\fR" 4
173.IX Item "content_type"
984263bc
MD
174In the case of \s-1SSL\s0 2.0, this is always \fB0\fR. In the case of \s-1SSL\s0 3.0
175or \s-1TLS\s0 1.0, this is one of the \fBContentType\fR values defined in the
176protocol specification (\fBchange_cipher_spec(20)\fR, \fBalert(21)\fR,
e056f0e0 177\&\fBhandshake(22)\fR; but never \fBapplication_data(23)\fR because the
984263bc 178callback will only be called for protocol messages).
e056f0e0
JR
179.IP "\fIbuf\fR, \fIlen\fR" 4
180.IX Item "buf, len"
181\&\fIbuf\fR points to a buffer containing the protocol message, which
984263bc
MD
182consists of \fIlen\fR bytes. The buffer is no longer valid after the
183callback function has returned.
e056f0e0
JR
184.IP "\fIssl\fR" 4
185.IX Item "ssl"
984263bc 186The \fB\s-1SSL\s0\fR object that received or sent the message.
e056f0e0
JR
187.IP "\fIarg\fR" 4
188.IX Item "arg"
984263bc 189The user-defined argument optionally defined by
e056f0e0 190\&\fISSL_CTX_set_msg_callback_arg()\fR or \fISSL_set_msg_callback_arg()\fR.
984263bc 191.SH "NOTES"
e056f0e0 192.IX Header "NOTES"
984263bc
MD
193Protocol messages are passed to the callback function after decryption
194and fragment collection where applicable. (Thus record boundaries are
195not visible.)
196.PP
197If processing a received protocol message results in an error,
198the callback function may not be called. For example, the callback
199function will never see messages that are considered too large to be
200processed.
201.PP
202Due to automatic protocol version negotiation, \fIversion\fR is not
203necessarily the protocol version used by the sender of the message: If
e056f0e0
JR
204a \s-1TLS\s0 1.0 ClientHello message is received by an \s-1SSL\s0 3.0\-only server,
205\&\fIversion\fR will be \fB\s-1SSL3_VERSION\s0\fR.
984263bc 206.SH "SEE ALSO"
a7d27d5a 207.IX Header "SEE ALSO"
e056f0e0
JR
208\&\fIssl\fR\|(3), \fISSL_new\fR\|(3)
209.SH "HISTORY"
984263bc 210.IX Header "HISTORY"
e056f0e0
JR
211\&\fISSL_CTX_set_msg_callback()\fR, \fISSL_CTX_set_msg_callback_arg()\fR,
212\&\fISSL_set_msg_callback()\fR and \fISSL_get_msg_callback_arg()\fR were added in OpenSSL 0.9.7.