1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_msg_callback_arg - install callback for observing protocol messages
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  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));
   12:  void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
   13: 
   14:  void SSL_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));
   15:  void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
   16: 
   17: =head1 DESCRIPTION
   18: 
   19: SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to
   20: define a message callback function I<cb> for observing all SSL/TLS
   21: protocol messages (such as handshake messages) that are received or
   22: sent.  SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg()
   23: can be used to set argument I<arg> to the callback function, which is
   24: available for arbitrary application use.
   25: 
   26: SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify
   27: default settings that will be copied to new B<SSL> objects by
   28: L<SSL_new(3)|SSL_new(3)>. SSL_set_msg_callback() and
   29: SSL_set_msg_callback_arg() modify the actual settings of an B<SSL>
   30: object. Using a B<0> pointer for I<cb> disables the message callback.
   31: 
   32: When I<cb> is called by the SSL/TLS library for a protocol message,
   33: the function arguments have the following meaning:
   34: 
   35: =over 4
   36: 
   37: =item I<write_p>
   38: 
   39: This flag is B<0> when a protocol message has been received and B<1>
   40: when a protocol message has been sent.
   41: 
   42: =item I<version>
   43: 
   44: The protocol version according to which the protocol message is
   45: interpreted by the library. Currently, this is one of
   46: B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL
   47: 3.0 and TLS 1.0, respectively).
   48: 
   49: =item I<content_type>
   50: 
   51: In the case of SSL 2.0, this is always B<0>.  In the case of SSL 3.0
   52: or TLS 1.0, this is one of the B<ContentType> values defined in the
   53: protocol specification (B<change_cipher_spec(20)>, B<alert(21)>,
   54: B<handshake(22)>; but never B<application_data(23)> because the
   55: callback will only be called for protocol messages).
   56: 
   57: =item I<buf>, I<len>
   58: 
   59: I<buf> points to a buffer containing the protocol message, which
   60: consists of I<len> bytes. The buffer is no longer valid after the
   61: callback function has returned.
   62: 
   63: =item I<ssl>
   64: 
   65: The B<SSL> object that received or sent the message.
   66: 
   67: =item I<arg>
   68: 
   69: The user-defined argument optionally defined by
   70: SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg().
   71: 
   72: =back
   73: 
   74: =head1 NOTES
   75: 
   76: Protocol messages are passed to the callback function after decryption
   77: and fragment collection where applicable. (Thus record boundaries are
   78: not visible.)
   79: 
   80: If processing a received protocol message results in an error,
   81: the callback function may not be called.  For example, the callback
   82: function will never see messages that are considered too large to be
   83: processed.
   84: 
   85: Due to automatic protocol version negotiation, I<version> is not
   86: necessarily the protocol version used by the sender of the message: If
   87: a TLS 1.0 ClientHello message is received by an SSL 3.0-only server,
   88: I<version> will be B<SSL3_VERSION>.
   89: 
   90: =head1 SEE ALSO
   91: 
   92: L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>
   93: 
   94: =head1 HISTORY
   95: 
   96: SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(),
   97: SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7.
   98: 
   99: =cut