1.\" $OpenBSD: SSL_CTX_set_msg_callback.3,v 1.5 2021/04/15 16:43:27 tb Exp $ 2.\" OpenSSL SSL_CTX_set_msg_callback.pod e9b77246 Jan 20 19:58:49 2017 +0100 3.\" OpenSSL SSL_CTX_set_msg_callback.pod b97fdb57 Nov 11 09:33:09 2016 +0100 4.\" 5.\" This file was written by Bodo Moeller <bodo@openssl.org>. 6.\" Copyright (c) 2001, 2014, 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: April 15 2021 $ 53.Dt SSL_CTX_SET_MSG_CALLBACK 3 54.Os 55.Sh NAME 56.Nm SSL_CTX_set_msg_callback , 57.Nm SSL_CTX_set_msg_callback_arg , 58.Nm SSL_set_msg_callback , 59.Nm SSL_set_msg_callback_arg 60.Nd install callback for observing protocol messages 61.Sh SYNOPSIS 62.In openssl/ssl.h 63.Ft void 64.Fo SSL_CTX_set_msg_callback 65.Fa "SSL_CTX *ctx" 66.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" 67.Fc 68.Ft void 69.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg" 70.Ft void 71.Fo SSL_set_msg_callback 72.Fa "SSL *ssl" 73.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" 74.Fc 75.Ft void 76.Fn SSL_set_msg_callback_arg "SSL *ssl" "void *arg" 77.Sh DESCRIPTION 78.Fn SSL_CTX_set_msg_callback 79or 80.Fn SSL_set_msg_callback 81can be used to define a message callback function 82.Fa cb 83for observing all SSL/TLS protocol messages (such as handshake messages) 84that are received or sent. 85.Fn SSL_CTX_set_msg_callback_arg 86and 87.Fn SSL_set_msg_callback_arg 88can be used to set argument 89.Fa arg 90to the callback function, which is available for arbitrary application use. 91.Pp 92.Fn SSL_CTX_set_msg_callback 93and 94.Fn SSL_CTX_set_msg_callback_arg 95specify default settings that will be copied to new 96.Vt SSL 97objects by 98.Xr SSL_new 3 . 99.Fn SSL_set_msg_callback 100and 101.Fn SSL_set_msg_callback_arg 102modify the actual settings of an 103.Vt SSL 104object. 105Using a 106.Dv NULL 107pointer for 108.Fa cb 109disables the message callback. 110.Pp 111When 112.Fa cb 113is called by the SSL/TLS library for a protocol message, 114the function arguments have the following meaning: 115.Bl -tag -width Ds 116.It Fa write_p 117This flag is 0 when a protocol message has been received and 1 when a protocol 118message has been sent. 119.It Fa version 120The protocol version according to which the protocol message is 121interpreted by the library, such as 122.Dv TLS1_VERSION , 123.Dv TLS1_1_VERSION , 124.Dv TLS1_2_VERSION , 125.Dv DTLS1_VERSION , 126or 127.Dv DTLS1_2_VERSION . 128.It Fa content_type 129This is one of the 130.Em ContentType 131values defined in the protocol specification 132.Po 133.Dv SSL3_RT_CHANGE_CIPHER_SPEC , 134.Dv SSL3_RT_ALERT , 135.Dv SSL3_RT_HANDSHAKE , 136but never 137.Dv SSL3_RT_APPLICATION_DATA 138because the callback will only be called for protocol messages. 139.Pc 140.It Fa buf , Fa len 141.Fa buf 142points to a buffer containing the protocol message, which consists of 143.Fa len 144bytes. 145The buffer is no longer valid after the callback function has returned. 146.It Fa ssl 147The 148.Vt SSL 149object that received or sent the message. 150.It Fa arg 151The user-defined argument optionally defined by 152.Fn SSL_CTX_set_msg_callback_arg 153or 154.Fn SSL_set_msg_callback_arg . 155.El 156.Pp 157Protocol messages are passed to the callback function after decryption 158and fragment collection where applicable. 159(Thus record boundaries are not visible.) 160.Pp 161If processing a received protocol message results in an error, 162the callback function may not be called. 163For example, the callback function will never see messages that are considered 164too large to be processed. 165.Pp 166Due to automatic protocol version negotiation, 167.Fa version 168is not necessarily the protocol version used by the sender of the message: 169If a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, 170.Fa version 171will be 172.Dv SSL3_VERSION . 173.Sh SEE ALSO 174.Xr ssl 3 , 175.Xr SSL_new 3 176.Sh HISTORY 177.Fn SSL_CTX_set_msg_callback , 178.Fn SSL_CTX_set_msg_callback_arg , 179.Fn SSL_set_msg_callback 180and 181.Fn SSL_set_msg_callback_arg 182first appeared in OpenSSL 0.9.7 and have been available since 183.Ox 3.2 . 184