Add initial man page for new x509_verify chain validator

This may be changed substantially before we enable the public api,
as discussions are still happening over it's final form, however
after one pass by ingo he would rather this was here and it can be
adjusted in tree, but not installed by the makefile until we make
this visible

ok schwarze@

1 files changed, 225 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/x509_verify.3 b/src/lib/libcrypto/man/x509_verify.3
new file mode 100644
index 0000000000..78ec0536d2
--- /dev/null
+++ b/src/lib/libcrypto/man/x509_verify.3
@@ -0,0 +1,225 @@
+.\" $OpenBSD: x509_verify.3,v 1.1 2020/09/14 12:38:38 beck Exp $
+.\"
+.\" Copyright (c) 2020 Bob Beck <beck@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: September 14 2020 $
+.Dt X509_VERIFY 3
+.Os
+.Sh NAME
+.Nm x509_verify ,
+.Nm x509_verify_ctx_new ,
+.Nm x509_verify_ctx_free ,
+.Nm x509_verify_ctx_set_max_depth ,
+.Nm x509_verify_ctx_set_max_signatures ,
+.Nm x509_verify_ctx_set_max_chains ,
+.Nm x509_verify_ctx_set_purpose ,
+.Nm x509_verify_ctx_set_intermediates ,
+.Nm x509_verify_ctx_error_string ,
+.Nm x509_verify_ctx_error_depth ,
+.Nm x509_verify_ctx_chain
+.Nd discover and verify X.509 certificate chains
+.Sh SYNOPSIS
+.In openssl/x509_verify.h
+.Ft size_t
+.Fo x509_verify
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "X509 *leaf"
+.Fa "char *name"
+.Fc
+.Ft X509_VERIFY_CTX *
+.Fo x509_verify_ctx_new
+.Fa "STACK_OF(X509) *roots"
+.Fc
+.Ft void
+.Fo x509_verify_ctx_free
+.Fa "X509_VERIFY_CTX *ctx"
+.Fc
+.Ft int
+.Fo x509_verify_ctx_set_max_depth
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "size_t max"
+.Fc
+.Ft int
+.Fo x509_verify_ctx_set_max_signatures
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "size_t max"
+.Fc
+.Ft int
+.Fo x509_verify_ctx_set_max_chains
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "size_t max"
+.Fc
+.Ft int
+.Fo x509_verify_ctx_set_purpose
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "int purpose_id"
+.Fc
+.Ft int
+.Fo x509_verify_ctx_set_intermediates
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "STACK_OF(X509) *intermediates"
+.Fc
+.Ft const char *
+.Fo x509_verify_ctx_error_string
+.Fa "X509_VERIFY_CTX *ctx"
+.Fc
+.Ft size_t
+.Fo x509_verify_ctx_error_depth
+.Fa "X509_VERIFY_CTX *ctx"
+.Fc
+.Ft STACK_OF(X509) *
+.Fo x509_verify_ctx_chain
+.Fa "X509_VERIFY_CTX *ctx"
+.Fa "size_t index"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn x509_verify
+function attempts to discover and validate all certificate chains
+for the
+.Fa name
+from the
+.Fa leaf
+certificate based on the parameters in
+.Fa ctx .
+Multiple chains may be built and validated.
+Revocation checking is not done by this function, and should be
+performed by the caller on any returned chains if so desired.
+.Pp
+.Fn x509_verify_ctx_new
+allocates a new context using the trusted
+.Fa roots .
+In case of success, it increments the reference count of
+.Fa roots .
+.Pp
+.Fn x509_verify_ctx_free
+frees
+.Fa ctx
+and decrements the reference count of the
+.Fa roots
+and
+.Fa intermediates
+associated with it.
+If
+.Fa ctx
+is
+.Dv NULL ,
+no action occurs.
+.Pp
+.Fn x509_verify_ctx_set_max_depth
+sets the maximum depth of certificate chains that will be constructed to
+.Fa max ,
+which can be in the range from 1 to the default of 32.
+.Pp
+.Fn x509_verify_ctx_set_max_signatures
+sets the maximum number of public key signature operations that will be
+used when verifying certificate chains to
+.Fa max ,
+which can be in the range from 1 to 100000.
+The default is 256.
+.Pp
+.Fn x509_verify_ctx_set_max_chains
+sets the maximum number of chains which may be returned to
+.Fa max ,
+which can be in the range from 1 to the default of 8.
+.Pp
+.Fn x509_verify_ctx_set_purpose
+sets the certificate purpose for validation to
+.Fa purpose_id .
+The
+.Dv X509_PURPOSE_*
+constants listed in
+.Xr X509_check_purpose 3
+can be used.
+.Pp
+.Fn x509_verify_ctx_set_intermediates
+provides some intermediate certificates, typically received from
+the peer, to be used for building chains.
+In case of success, this function increases the reference count of
+.Fa intermediates .
+.Pp
+.Fn x509_verify_ctx_error_string
+extracts a description of the last error encountered by a previous
+call to
+.Fn x509_verify
+from
+.Fa ctx .
+.Pp
+.Fn x509_verify_ctx_error_depth
+extracts the depth of the last error encountered by a previous
+call to
+.Fn x509_verify
+from
+.Fa ctx .
+.Pp
+.Fn x509_verify_ctx_chain
+extracts the validated chain with the given
+.Fa index
+from
+.Fa ctx
+after a previous call to
+.Fn x509_verify .
+The
+.Fa index
+starts at 0, and it is an error to pass a number
+greater than or equal to the return value of
+.Fn x509_verify .
+The returned chain is neither copied,
+nor is its reference count increased.
+.Sh RETURN VALUES
+.Fn x509_verify
+returns the number of chains successfully built and validated,
+or 0 if
+.Fa ctx
+is
+.Dv NULL
+or if an error occurs.
+.Pp
+.Fn x509_verify_ctx_new
+returns a newly allocated context or
+.Dv NULL
+on failure.
+.Pp
+.Fn x509_verify_ctx_set_max_depth ,
+.Fn x509_verify_ctx_set_max_signatures ,
+.Fn x509_verify_ctx_set_max_chains ,
+.Fn x509_verify_ctx_set_purpose ,
+and
+.Fn x509_verify_ctx_set_intermediates
+return 1 on success or 0 on failure.
+.Pp
+.Fn x509_verify_ctx_error_string
+returns a pointer to a human readable error string.
+If no error occurred,
+.Qq ok
+is returned.
+.Pp
+.Fn x509_verify_ctx_chain
+returns an internal pointer to a validated chain or
+.Dv NULL
+if
+.Fa index
+is greater than or equal to the number of chains
+that were successfully built and validated.
+The returned pointer becomes invalid when
+.Fa ctx
+is destroyed.
+.Sh SEE ALSO
+.Xr X509_verify_cert 3
+.Sh HISTORY
+These functions first appeared in
+.Ox 6.8 .
+.Sh AUTHORS
+.An Bob Beck Aq Mt beck@openbsd.org