1=pod 2 3=head1 NAME 4 5SSL_CTX_set_msg_callback, 6SSL_CTX_set_msg_callback_arg, 7SSL_set_msg_callback, 8SSL_set_msg_callback_arg 9- install callback for observing protocol messages 10 11=head1 SYNOPSIS 12 13 #include <openssl/ssl.h> 14 15 void SSL_CTX_set_msg_callback(SSL_CTX *ctx, 16 void (*cb)(int write_p, int version, 17 int content_type, const void *buf, 18 size_t len, SSL *ssl, void *arg)); 19 void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); 20 21 void SSL_set_msg_callback(SSL *ssl, 22 void (*cb)(int write_p, int version, 23 int content_type, const void *buf, 24 size_t len, SSL *ssl, void *arg)); 25 void SSL_set_msg_callback_arg(SSL *ssl, void *arg); 26 27=head1 DESCRIPTION 28 29SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to 30define a message callback function I<cb> for observing all SSL/TLS 31protocol messages (such as handshake messages) that are received or 32sent, as well as other events that occur during processing. 33SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() 34can be used to set argument I<arg> to the callback function, which is 35available for arbitrary application use. 36 37SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify 38default settings that will be copied to new B<SSL> objects by 39L<SSL_new(3)>. SSL_set_msg_callback() and 40SSL_set_msg_callback_arg() modify the actual settings of an B<SSL> 41object. Using a B<NULL> pointer for I<cb> disables the message callback. 42 43When I<cb> is called by the SSL/TLS library the function arguments have the 44following meaning: 45 46=over 4 47 48=item I<write_p> 49 50This flag is B<0> when a protocol message has been received and B<1> 51when a protocol message has been sent. 52 53=item I<version> 54 55The protocol version according to which the protocol message is 56interpreted by the library such as B<TLS1_3_VERSION>, B<TLS1_2_VERSION> etc. 57This is set to 0 for the SSL3_RT_HEADER pseudo content type (see NOTES below). 58 59=item I<content_type> 60 61This is one of the content type values defined in the protocol specification 62(B<SSL3_RT_CHANGE_CIPHER_SPEC>, B<SSL3_RT_ALERT>, B<SSL3_RT_HANDSHAKE>; but never 63B<SSL3_RT_APPLICATION_DATA> because the callback will only be called for protocol 64messages). Alternatively it may be a "pseudo" content type. These pseudo 65content types are used to signal some other event in the processing of data (see 66NOTES below). 67 68=item I<buf>, I<len> 69 70I<buf> points to a buffer containing the protocol message or other data (in the 71case of pseudo content types), which consists of I<len> bytes. The buffer is no 72longer valid after the callback function has returned. 73 74=item I<ssl> 75 76The B<SSL> object that received or sent the message. 77 78=item I<arg> 79 80The user-defined argument optionally defined by 81SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). 82 83=back 84 85=head1 NOTES 86 87Protocol messages are passed to the callback function after decryption 88and fragment collection where applicable. (Thus record boundaries are 89not visible.) 90 91If processing a received protocol message results in an error, 92the callback function may not be called. For example, the callback 93function will never see messages that are considered too large to be 94processed. 95 96Due to automatic protocol version negotiation, I<version> is not 97necessarily the protocol version used by the sender of the message: If 98a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, 99I<version> will be B<SSL3_VERSION>. 100 101Pseudo content type values may be sent at various points during the processing 102of data. The following pseudo content types are currently defined: 103 104=over 4 105 106=item B<SSL3_RT_HEADER> 107 108Used when a record is sent or received. The B<buf> contains the record header 109bytes only. 110 111=item B<SSL3_RT_INNER_CONTENT_TYPE> 112 113Used when an encrypted TLSv1.3 record is sent or received. In encrypted TLSv1.3 114records the content type in the record header is always 115SSL3_RT_APPLICATION_DATA. The real content type for the record is contained in 116an "inner" content type. B<buf> contains the encoded "inner" content type byte. 117 118=back 119 120=head1 RETURN VALUES 121 122SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), SSL_set_msg_callback() 123and SSL_set_msg_callback_arg() do not return values. 124 125=head1 SEE ALSO 126 127L<ssl(7)>, L<SSL_new(3)> 128 129=head1 HISTORY 130 131The pseudo content type B<SSL3_RT_INNER_CONTENT_TYPE> was added in OpenSSL 1.1.1. 132 133=head1 COPYRIGHT 134 135Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. 136 137Licensed under the OpenSSL license (the "License"). You may not use 138this file except in compliance with the License. You can obtain a copy 139in the file LICENSE in the source distribution or at 140L<https://www.openssl.org/source/license.html>. 141 142=cut 143