doc/ssl/SSL_CTX_set_msg_callback.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 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
   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 *ssl, 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 *ssl, 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_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)>, L<SSL_new(3)>
  93
  94 =cut