Update the message callback documentation
authorMatt Caswell <matt@openssl.org>
Fri, 5 May 2017 10:56:45 +0000 (11:56 +0100)
committerMatt Caswell <matt@openssl.org>
Mon, 8 May 2017 10:42:37 +0000 (11:42 +0100)
Update the message callback documentation to cover the new inner content
type capability. Also major update of the documentation which was very out
of date.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3408)

doc/man3/SSL_CTX_set_msg_callback.pod

index f663ab6..b3e8a4f 100644 (file)
@@ -2,7 +2,11 @@
 
 =head1 NAME
 
-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
+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
 
 =head1 SYNOPSIS
 
@@ -19,7 +23,8 @@ SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SS
 SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
 define a message callback function I<cb> for observing all SSL/TLS
 protocol messages (such as handshake messages) that are received or
-sent.  SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
+sent, as well as other events that occur during processing.
+SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
 can be used to set argument I<arg> to the callback function, which is
 available for arbitrary application use.
 
@@ -27,10 +32,10 @@ SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
 default settings that will be copied to new B<SSL> objects by
 L<SSL_new(3)>. SSL_set_msg_callback() and
 SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
-object. Using a B<0> pointer for I<cb> disables the message callback.
+object. Using a B<NULL> pointer for I<cb> disables the message callback.
 
-When I<cb> is called by the SSL/TLS library for a protocol message,
-the function arguments have the following meaning:
+When I<cb> is called by the SSL/TLS library the function arguments have the
+following meaning:
 
 =over 4
 
@@ -42,23 +47,23 @@ when a protocol message has been sent.
 =item I<version>
 
 The protocol version according to which the protocol message is
-interpreted by the library. Currently, this is one of
-B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL
-3.0 and TLS 1.0, respectively).
+interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION> etc.
+This is set to 0 for the SSL3_RT_HEADER pseudo content type (see NOTES below).
 
 =item I<content_type>
 
-In the case of SSL 2.0, this is always B<0>.  In the case of SSL 3.0
-or TLS 1.0, this is one of the B<ContentType> values defined in the
-protocol specification (B<change_cipher_spec(20)>, B<alert(21)>,
-B<handshake(22)>; but never B<application_data(23)> because the
-callback will only be called for protocol messages).
+This is one of the content type values defined in the protocol specification
+(B<SSL3_RT_CHANGE_CIPHER_SPEC>, B<SSL3_RT_ALERT>, B<SSL3_RT_HANDSHAKE>; but never
+B<SSL3_RT_APPLICATION_DATA> 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).
 
 =item I<buf>, I<len>
 
-I<buf> points to a buffer containing the protocol message, which
-consists of I<len> bytes. The buffer is no longer valid after the
-callback function has returned.
+I<buf> points to a buffer containing the protocol message or other data (in the
+case of pseudo content types), which consists of I<len> bytes. The buffer is no
+longer valid after the callback function has returned.
 
 =item I<ssl>
 
@@ -87,13 +92,37 @@ 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,
 I<version> will be B<SSL3_VERSION>.
 
+Pseudo content type values may be sent at various points during the processing
+of data. The following pseudo content types are currently defined:
+
+=over 4
+
+=item B<SSL3_RT_HEADER>
+
+Used when a record is sent or received. The B<buf> contains the record header
+bytes only.
+
+=item B<SSL3_RT_INNER_CONTENT_TYPE>
+
+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. B<buf> contains the encoded "inner" content type byte.
+
+=back
+
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_new(3)>
 
+=head1 HISTORY
+
+The pseudo content type B<SSL3_RT_INNER_CONTENT_TYPE> was added in OpenSSL
+1.1.1.
+
 =head1 COPYRIGHT
 
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy