1 files changed, 109 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3
new file mode 100644
index 0000000000..b34d3a6003
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3
@@ -0,0 +1,109 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt SSL_CTX_SET_CERT_VERIFY_CALLBACK 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_set_cert_verify_callback
+.Nd set peer certificate verification procedure
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft void
+.Fo SSL_CTX_set_cert_verify_callback
+.Fa "SSL_CTX *ctx"
+.Fa "int (*callback)(X509_STORE_CTX *, void *)"
+.Fa "void *arg"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_CTX_set_cert_verify_callback
+sets the verification callback function for
+.Fa ctx .
+.Vt SSL
+objects that are created from
+.Fa ctx
+inherit the setting valid at the time when
+.Xr SSL_new 3
+is called.
+.Sh NOTES
+Whenever a certificate is verified during a SSL/TLS handshake,
+a verification function is called.
+If the application does not explicitly specify a verification callback
+function, the built-in verification function is used.
+If a verification callback
+.Fa callback
+is specified via
+.Fn SSL_CTX_set_cert_verify_callback ,
+the supplied callback function is called instead.
+By setting
+.Fa callback
+to
+.Dv NULL ,
+the default behaviour is restored.
+.Pp
+When the verification must be performed,
+.Fa callback
+will be called with the arguments
+.Fn callback "X509_STORE_CTX *x509_store_ctx" "void *arg" .
+The argument
+.Fa arg
+is specified by the application when setting
+.Fa callback .
+.Pp
+.Fa callback
+should return 1 to indicate verification success and 0 to indicate verification
+failure.
+If
+.Dv SSL_VERIFY_PEER
+is set and
+.Fa callback
+returns 0, the handshake will fail.
+As the verification procedure may allow the connection to continue in case of
+failure (by always returning 1) the verification result must be set in any case
+using the
+.Fa error
+member of
+.Fa x509_store_ctx
+so that the calling application will be informed about the detailed result of
+the verification procedure!
+.Pp
+Within
+.Fa x509_store_ctx ,
+.Fa callback
+has access to the
+.Fa verify_callback
+function set using
+.Xr SSL_CTX_set_verify 3 .
+.Sh WARNINGS
+Do not mix the verification callback described in this function with the
+.Fa verify_callback
+function called during the verification process.
+The latter is set using the
+.Xr SSL_CTX_set_verify 3
+family of functions.
+.Pp
+Providing a complete verification procedure including certificate purpose
+settings, etc., is a complex task.
+The built-in procedure is quite powerful and in most cases it should be
+sufficient to modify its behaviour using the
+.Fa verify_callback
+function.
+.Sh RETURN VALUES
+.Fn SSL_CTX_set_cert_verify_callback
+does not provide diagnostic information.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_load_verify_locations 3 ,
+.Xr SSL_CTX_set_verify 3 ,
+.Xr SSL_get_verify_result 3
+.Sh HISTORY
+Previous to OpenSSL 0.9.7, the
+.Fa arg
+argument to
+.Fn SSL_CTX_set_cert_verify_callback
+was ignored, and
+.Fa callback
+was called
+simply as
+.Ft int
+.Fn (*callback) "X509_STORE_CTX *" .
+To compile software written for previous versions of OpenSSL,
+a dummy argument will have to be added to
+.Fa callback .