183 lines
7.2 KiB
HTML
183 lines
7.2 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>SSL_CTX_set_msg_callback</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<li><a href="#notes">NOTES</a></li>
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>SSL_CTX_set_msg_callback,
|
||
|
SSL_CTX_set_msg_callback_arg,
|
||
|
SSL_set_msg_callback,
|
||
|
SSL_set_msg_callback_arg
|
||
|
- install callback for observing protocol messages</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/ssl.h></pre>
|
||
|
<pre>
|
||
|
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));
|
||
|
void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);</pre>
|
||
|
<pre>
|
||
|
void SSL_set_msg_callback(SSL *ssl,
|
||
|
void (*cb)(int write_p, int version,
|
||
|
int content_type, const void *buf,
|
||
|
size_t len, SSL *ssl, void *arg));
|
||
|
void SSL_set_msg_callback_arg(SSL *ssl, void *arg);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p><code>SSL_CTX_set_msg_callback()</code> or <code>SSL_set_msg_callback()</code> can be used to
|
||
|
define a message callback function <em>cb</em> for observing all SSL/TLS
|
||
|
protocol messages (such as handshake messages) that are received or
|
||
|
sent, as well as other events that occur during processing.
|
||
|
<code>SSL_CTX_set_msg_callback_arg()</code> and <code>SSL_set_msg_callback_arg()</code>
|
||
|
can be used to set argument <em>arg</em> to the callback function, which is
|
||
|
available for arbitrary application use.</p>
|
||
|
<p><code>SSL_CTX_set_msg_callback()</code> and <code>SSL_CTX_set_msg_callback_arg()</code> specify
|
||
|
default settings that will be copied to new <strong>SSL</strong> objects by
|
||
|
<em>SSL_new(3)</em>. <code>SSL_set_msg_callback()</code> and
|
||
|
<code>SSL_set_msg_callback_arg()</code> modify the actual settings of an <strong>SSL</strong>
|
||
|
object. Using a <strong>NULL</strong> pointer for <em>cb</em> disables the message callback.</p>
|
||
|
<p>When <em>cb</em> is called by the SSL/TLS library the function arguments have the
|
||
|
following meaning:</p>
|
||
|
<dl>
|
||
|
<dt><strong><a name="write_p" class="item"><em>write_p</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This flag is <strong>0</strong> when a protocol message has been received and <strong>1</strong>
|
||
|
when a protocol message has been sent.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="version" class="item"><em>version</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The protocol version according to which the protocol message is
|
||
|
interpreted by the library such as <strong>TLS1_3_VERSION</strong>, <strong>TLS1_2_VERSION</strong> etc.
|
||
|
This is set to 0 for the SSL3_RT_HEADER pseudo content type (see NOTES below).</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="content_type" class="item"><em>content_type</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This is one of the content type values defined in the protocol specification
|
||
|
(<strong>SSL3_RT_CHANGE_CIPHER_SPEC</strong>, <strong>SSL3_RT_ALERT</strong>, <strong>SSL3_RT_HANDSHAKE</strong>; but never
|
||
|
<strong>SSL3_RT_APPLICATION_DATA</strong> because the callback will only be called for protocol
|
||
|
messages). Alternatively it may be a "pseudo" content type. These pseudo
|
||
|
content types are used to signal some other event in the processing of data (see
|
||
|
NOTES below).</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="buf_len" class="item"><em>buf</em>, <em>len</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p><em>buf</em> points to a buffer containing the protocol message or other data (in the
|
||
|
case of pseudo content types), which consists of <em>len</em> bytes. The buffer is no
|
||
|
longer valid after the callback function has returned.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="ssl" class="item"><em>ssl</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The <strong>SSL</strong> object that received or sent the message.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="arg" class="item"><em>arg</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The user-defined argument optionally defined by
|
||
|
<code>SSL_CTX_set_msg_callback_arg()</code> or <code>SSL_set_msg_callback_arg()</code>.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p>Protocol messages are passed to the callback function after decryption
|
||
|
and fragment collection where applicable. (Thus record boundaries are
|
||
|
not visible.)</p>
|
||
|
<p>If processing a received protocol message results in an error,
|
||
|
the callback function may not be called. For example, the callback
|
||
|
function will never see messages that are considered too large to be
|
||
|
processed.</p>
|
||
|
<p>Due to automatic protocol version negotiation, <em>version</em> is not
|
||
|
necessarily the protocol version used by the sender of the message: If
|
||
|
a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
|
||
|
<em>version</em> will be <strong>SSL3_VERSION</strong>.</p>
|
||
|
<p>Pseudo content type values may be sent at various points during the processing
|
||
|
of data. The following pseudo content types are currently defined:</p>
|
||
|
<dl>
|
||
|
<dt><strong><a name="ssl3_rt_header" class="item"><strong>SSL3_RT_HEADER</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Used when a record is sent or received. The <strong>buf</strong> contains the record header
|
||
|
bytes only.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="ssl3_rt_inner_content_type" class="item"><strong>SSL3_RT_INNER_CONTENT_TYPE</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3
|
||
|
records the content type in the record header is always
|
||
|
SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in
|
||
|
an "inner" content type. <strong>buf</strong> contains the encoded "inner" content type byte.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>SSL_CTX_set_msg_callback()</code>, <code>SSL_CTX_set_msg_callback_arg()</code>, <code>SSL_set_msg_callback()</code>
|
||
|
and <code>SSL_set_msg_callback_arg()</code> do not return values.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><a href="#ssl">ssl(7)</a>, <em>SSL_new(3)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>The pseudo content type <strong>SSL3_RT_INNER_CONTENT_TYPE</strong> was added in OpenSSL 1.1.1.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
this file except in compliance with the License. You can obtain a copy
|
||
|
in the file LICENSE in the source distribution or at
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|