1 files changed, 54 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_state_string.3 b/src/lib/libssl/doc/SSL_state_string.3
new file mode 100644
index 0000000000..828b8f351a
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_state_string.3
@@ -0,0 +1,54 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_STATE_STRING 3
+.Os
+.Sh NAME
+.Nm SSL_state_string ,
+.Nm SSL_state_string_long
+.Nd get textual description of state of an SSL object
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft const char *
+.Fn SSL_state_string "const SSL *ssl"
+.Ft const char *
+.Fn SSL_state_string_long "const SSL *ssl"
+.Sh DESCRIPTION
+.Fn SSL_state_string
+returns a 6 letter string indicating the current state of the
+.Vt SSL
+object
+.Fa ssl .
+.Pp
+.Fn SSL_state_string_long
+returns a string indicating the current state of the
+.Vt SSL
+object
+.Fa ssl .
+.Sh NOTES
+During its use, an
+.Vt SSL
+object passes several states.
+The state is internally maintained.
+Querying the state information is not very informative before or when a
+connection has been established.
+It however can be of significant interest during the handshake.
+.Pp
+When using non-blocking sockets,
+the function call performing the handshake may return with
+.Dv SSL_ERROR_WANT_READ
+or
+.Dv SSL_ERROR_WANT_WRITE
+condition, so that
+.Fn SSL_state_string[_long]
+may be called.
+.Pp
+For both blocking or non-blocking sockets,
+the details state information can be used within the
+.Fn info_callback
+function set with the
+.Xr SSL_set_info_callback 3
+call.
+.Sh RETURN VALUES
+Detailed description of possible states to be included later.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_set_info_callback 3