Update the message callback documentation

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)

diff --git a/doc/man3/SSL_CTX_set_msg_callback.pod b/doc/man3/SSL_CTX_set_msg_callback.pod
index f663ab67c2ab58ecc0086e33ab4c4381ddd773b6..b3e8a4fd4cf232cc4a803da1e36bf9b0cb769b38 100644 (file)
--- a/doc/man3/SSL_CTX_set_msg_callback.pod
+++ b/doc/man3/SSL_CTX_set_msg_callback.pod
@@ -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