diff options
-rw-r--r-- | doc/apps/s_client.pod | 5 | ||||
-rw-r--r-- | doc/apps/s_server.pod | 5 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_msg_callback.pod | 97 |
3 files changed, 107 insertions, 0 deletions
diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index 275e886966..7fca9cbdbd 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -18,6 +18,7 @@ B<openssl> B<s_client> [B<-pause>] [B<-showcerts>] [B<-debug>] +[B<-msg>] [B<-nbio_test>] [B<-state>] [B<-nbio>] @@ -112,6 +113,10 @@ prints out the SSL session states. print extensive debugging information including a hex dump of all traffic. +=item B<-msg> + +show all protocol messages with hex dump. + =item B<-nbio_test> tests non-blocking I/O diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod index f94d48e0e8..4b1e4260ef 100644 --- a/doc/apps/s_server.pod +++ b/doc/apps/s_server.pod @@ -21,6 +21,7 @@ B<openssl> B<s_server> [B<-nbio_test>] [B<-crlf>] [B<-debug>] +[B<-msg>] [B<-state>] [B<-CApath directory>] [B<-CAfile filename>] @@ -136,6 +137,10 @@ prints out the SSL session states. print extensive debugging information including a hex dump of all traffic. +=item B<-msg> + +show all protocol messages with hex dump. + =item B<-nbio_test> tests non blocking I/O diff --git a/doc/ssl/SSL_CTX_set_msg_callback.pod b/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 0000000000..a423932d0a --- /dev/null +++ b/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +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 + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + 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)); + void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + + 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)); + void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + +=head1 DESCRIPTION + +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() +can be used to set argument I<arg> to the callback function, which is +available for arbitrary application use. + +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_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. + +When I<cb> is called by the SSL/TLS library for a protocol message, +the function arguments have the following meaning: + +=over 4 + +=item I<write_p> + +This flag is B<0> when a protocol message has been received and B<1> +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). + +=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). + +=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. + +=item I<ssl> + +The B<SSL> object that received or sent the message. + +=item I<arg> + +The user-defined argument optionally defined by +SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). + +=head1 NOTES + +Protocol messages are passed to the callback function after decryption +and fragment collection where applicable. (Thus record boundaries are +not visible.) + +If processing a received protocol message results in an error, +the callback function may not be called. For example, the callback +function will never see messages that are considered too large to be +processed. + +Due to automatic protocol version negotiation, I<version> is not +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>. + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)> + +=head1 HISTORY + +SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), +SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7. + +=cut |