secure/lib/libssl/man/SSL_CTX_set_msg_callback.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  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 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  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' '
  62 'br\}
  63 .el\{\
  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
  79 'br\}
  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"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_CTX_set_msg_callback 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 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
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 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'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 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'
 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'\*(#]
 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
 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
 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'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 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
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 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
 192 .SH "SYNOPSIS"
 193 .PP
 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"
 206 \fISSL_CTX_set_msg_callback()\fR or \fISSL_set_msg_callback()\fR can be used to
 207 define a message callback function \fIcb\fR for observing all SSL/TLS
 208 protocol messages (such as handshake messages) that are received or
 209 sent.  \fISSL_CTX_set_msg_callback_arg()\fR and \fISSL_set_msg_callback_arg()\fR
 210 can be used to set argument \fIarg\fR to the callback function, which is
 211 available for arbitrary application use.
 212 .PP
 213 \fISSL_CTX_set_msg_callback()\fR and \fISSL_CTX_set_msg_callback_arg()\fR specify
 214 default settings that will be copied to new \fBSSL\fR objects by
 215 SSL_new(3). \fISSL_set_msg_callback()\fR and
 216 \fISSL_set_msg_callback_arg()\fR modify the actual settings of an \fBSSL\fR
 217 object. Using a \fB0\fR pointer for \fIcb\fR disables the message callback.
 218 .PP
 219 When \fIcb\fR is called by the SSL/TLS library for a protocol message,
 220 the function arguments have the following meaning:
 221 .Ip "\fIwrite_p\fR" 4
 222 This flag is \fB0\fR when a protocol message has been received and \fB1\fR
 223 when a protocol message has been sent.
 224 .Ip "\fIversion\fR" 4
 225 The protocol version according to which the protocol message is
 226 interpreted by the library. Currently, this is one of
 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
 228 3.0 and \s-1TLS\s0 1.0, respectively).
 229 .Ip "\fIcontent_type\fR" 4
 230 In the case of \s-1SSL\s0 2.0, this is always \fB0\fR.  In the case of \s-1SSL\s0 3.0
 231 or \s-1TLS\s0 1.0, this is one of the \fBContentType\fR values defined in the
 232 protocol specification (\fBchange_cipher_spec(20)\fR, \fBalert(21)\fR,
 233 \fBhandshake(22)\fR; but never \fBapplication_data(23)\fR because the
 234 callback will only be called for protocol messages).
 235 .Ip "\fIbuf\fR, \fIlen\fR" 4
 236 \fIbuf\fR points to a buffer containing the protocol message, which
 237 consists of \fIlen\fR bytes. The buffer is no longer valid after the
 238 callback function has returned.
 239 .Ip "\fIssl\fR" 4
 240 The \fB\s-1SSL\s0\fR object that received or sent the message.
 241 .Ip "\fIarg\fR" 4
 242 The user-defined argument optionally defined by
 243 \fISSL_CTX_set_msg_callback_arg()\fR or \fISSL_set_msg_callback_arg()\fR.
 244 .SH "NOTES"
 245 Protocol messages are passed to the callback function after decryption
 246 and fragment collection where applicable. (Thus record boundaries are
 247 not visible.)
 248 .PP
 249 If processing a received protocol message results in an error,
 250 the callback function may not be called.  For example, the callback
 251 function will never see messages that are considered too large to be
 252 processed.
 253 .PP
 254 Due to automatic protocol version negotiation, \fIversion\fR is not
 255 necessarily the protocol version used by the sender of the message: If
 256 a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
 257 \fIversion\fR will be \fBSSL3_VERSION\fR.
 258 .SH "SEE ALSO"
 259 ssl(3), SSL_new(3)
 260 .SH "HISTORY"
 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
 290 .IX Header "HISTORY"
 291