new manual page X509_policy_check(3)

6 files changed, 198 insertions, 10 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index a1ea6af33a..f605de5dbc 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.187 2021/07/26 14:03:43 schwarze Exp $
+# $OpenBSD: Makefile,v 1.188 2021/07/27 13:27:46 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -327,6 +327,7 @@ MAN=	\
         X509_get1_email.3 \
         X509_keyid_set1.3 \
         X509_new.3 \
+        X509_policy_check.3 \
         X509_policy_tree_level_count.3 \
         X509_print_ex.3 \
         X509_sign.3 \
diff --git a/src/lib/libcrypto/man/X509_check_purpose.3 b/src/lib/libcrypto/man/X509_check_purpose.3
index 56f6109541..fdb58d5b21 100644
--- a/src/lib/libcrypto/man/X509_check_purpose.3
+++ b/src/lib/libcrypto/man/X509_check_purpose.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_check_purpose.3,v 1.5 2021/07/24 14:33:14 schwarze Exp $
+.\" $OpenBSD: X509_check_purpose.3,v 1.6 2021/07/27 13:27:46 schwarze Exp $
 .\"
 .\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 24 2021 $
+.Dd $Mdocdate: July 27 2021 $
 .Dt X509_CHECK_PURPOSE 3
 .Os
 .Sh NAME
@@ -382,6 +382,7 @@ can be used as a CA for the
 .Xr EXTENDED_KEY_USAGE_new 3 ,
 .Xr X509_check_trust 3 ,
 .Xr X509_new 3 ,
+.Xr X509_policy_check 3 ,
 .Xr X509_PURPOSE_set 3 ,
 .Xr X509V3_get_d2i 3 ,
 .Xr x509v3.cnf 5
diff --git a/src/lib/libcrypto/man/X509_check_trust.3 b/src/lib/libcrypto/man/X509_check_trust.3
index 4b625fdfd4..98bfecb3d4 100644
--- a/src/lib/libcrypto/man/X509_check_trust.3
+++ b/src/lib/libcrypto/man/X509_check_trust.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_check_trust.3,v 1.1 2021/07/24 14:33:14 schwarze Exp $
+.\" $OpenBSD: X509_check_trust.3,v 1.2 2021/07/27 13:27:46 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 24 2021 $
+.Dd $Mdocdate: July 27 2021 $
 .Dt X509_CHECK_TRUST 3
 .Os
 .Sh NAME
@@ -200,6 +200,7 @@ which implies that it is not trusted.
 .Xr X509_CERT_AUX_new 3 ,
 .Xr X509_check_purpose 3 ,
 .Xr X509_new 3 ,
+.Xr X509_policy_check 3 ,
 .Xr X509_TRUST_set 3 ,
 .Xr X509_VERIFY_PARAM_set_trust 3
 .Sh HISTORY
diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3
index 304045f657..8a1da448c4 100644
--- a/src/lib/libcrypto/man/X509_new.3
+++ b/src/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.27 2021/07/26 14:03:43 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.28 2021/07/27 13:27:46 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 26 2021 $
+.Dd $Mdocdate: July 27 2021 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -193,6 +193,7 @@ if an error occurs.
 .Xr X509_get_version 3 ,
 .Xr X509_INFO_new 3 ,
 .Xr X509_NAME_new 3 ,
+.Xr X509_policy_check 3 ,
 .Xr X509_policy_tree_level_count 3 ,
 .Xr X509_print_ex 3 ,
 .Xr X509_PUBKEY_new 3 ,
diff --git a/src/lib/libcrypto/man/X509_policy_check.3 b/src/lib/libcrypto/man/X509_policy_check.3
new file mode 100644
index 0000000000..f245099228
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_policy_check.3
@@ -0,0 +1,183 @@
+.\" $OpenBSD: X509_policy_check.3,v 1.1 2021/07/27 13:27:46 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@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: July 27 2021 $
+.Dt X509_POLICY_CHECK 3
+.Os
+.Sh NAME
+.Nm X509_policy_check
+.Nd construct X.509 valid policy tree
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft int
+.Fo X509_policy_check
+.Fa "X509_POLICY_TREE **ptree"
+.Fa "int *pexplicit_policy"
+.Fa "STACK_OF(X509) *certs"
+.Fa "STACK_OF(ASN1_OBJECT) *policy_oids"
+.Fa "unsigned int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_policy_check
+performs those parts of Basic Certification Path Validation
+described in RFC 5280 section 6.1 that are related to the
+construction of the valid policy tree.
+.Pp
+The
+.Fa certs
+input argument contains the prospective certification path
+according to RFC 5280 paragraph 6.1.1(a), starting with the
+target certificate and ending with the trust anchor.
+If a policy tree is returned, the reference count of each of the
+.Fa certs
+is incremented by 1.
+.Pp
+The
+.Fa policy_oids
+input argument contains the
+.Va user-initial-policy-set
+according to RFC 5280 section 6.1.1(c).
+.Pp
+The
+.Fa flags
+argument can contain zero or more of the following constants, OR'ed together:
+.Bl -tag -width Ds
+.It Dv X509_V_FLAG_EXPLICIT_POLICY
+Set
+.Va initial-explicit-policy
+as defined by RFC 5280 paragraph 6.1.1(f).
+It requires the path to be valid for at least one of the
+.Fa policy_oids .
+.It Dv X509_V_FLAG_INHIBIT_ANY
+Set
+.Va initial-any-policy-inhibit
+as defined by RFC 5280 paragraph 6.1.1(g).
+It causes the
+.Sy anyPolicy
+OID to be skipped if it is encountered in a certificate.
+.It Dv X509_V_FLAG_INHIBIT_MAP
+Set
+.Va initial-policy-mapping-inhibit
+as defined by RFC 5280 paragraph 6.1.1(e).
+It disables policy mapping in the certification path.
+.El
+.Pp
+Upon success, a pointer to the
+.Vt valid_policy_tree
+output value mentioned in RFC 5280 section 6.1.6 is returned in
+.Pf * Fa ptree .
+It contains one level for each of the
+.Fa certs ,
+in reverse order: level 0 corresponds to the trust anchor,
+the last level corresponds to the target certificate.
+Level 0 is initialized to contain a single node with a
+.Fa valid_policy
+of
+.Sy anyPolicy ,
+an empty
+.Fa qualifier_set ,
+and an
+.Fa expected_policy_set
+containing only
+.Sy anyPolicy .
+.Pp
+The storage location pointed to by
+.Fa pexplicit_policy
+is set as specified in RFC 5280 paragraphs 6.1.2(d), 6.1.4(h), 6.1.4(i),
+6.1.5(a), and 6.1.5(b).
+In case of failure, it may or may not get set, representing a partial result.
+.Sh RETURN VALUES
+.Fn X509_policy_check
+returns these values:
+.Bl -tag -width 2n
+.It \-2
+Validation failed because
+.Dv X509_V_FLAG_EXPLICIT_POLICY
+was requested but the resulting policy tree
+or the resulting user policy set would have been empty.
+In this case,
+.Pf * Fa pexplicit_policy
+is set to 1.
+If the resulting tree is empty,
+.Pf * Fa ptree
+is set to
+.Dv NULL ;
+otherwise, it is set to the resulting tree.
+.It \-1
+At least one of the
+.Fa certs
+contains invalid or inconsistent extensions.
+.Pf * Fa ptree
+is set to
+.Dv NULL
+and
+.Pf * Fa pexplicit_policy
+to 0.
+.It 0
+Internal error.
+For example, setting up the policy caches failed, or memory allocation
+failed while constructing the tree.
+.Pf * Fa ptree
+is set to
+.Dv NULL
+and
+.Pf * Fa pexplicit_policy
+may be set to 0 or to a partial result.
+.It 1
+Validation succeeded and
+.Pf * Fa ptree
+and
+.Pf * Fa pexplicit_policy
+have been set.
+In the special cases that the
+.Fa certs
+argument contains exactly one certificate or that
+.Dv X509_V_FLAG_EXPLICIT_POLICY
+was not requested and the resulting policy tree would have been empty,
+.Pf * Fa ptree
+is set to
+.Dv NULL
+and
+.Pf * Fa pexplicit_policy
+to 0.
+.It 2
+.Dv X509_V_FLAG_EXPLICIT_POLICY
+was not requested and at least one of the certificates contains no
+certificate policies.
+.Pf * Fa ptree
+is set to
+.Dv NULL
+and
+.Pf * Fa pexplicit_policy
+to 0.
+.El
+.Sh SEE ALSO
+.Xr ASN1_OBJECT_new 3 ,
+.Xr OBJ_nid2obj 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_check_purpose 3 ,
+.Xr X509_check_trust 3 ,
+.Xr X509_new 3 ,
+.Xr X509_policy_tree_level_count 3 ,
+.Xr X509_verify_cert 3
+.Sh STANDARDS
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+and Certificate Revocation List (CRL) Profile,
+section 6.1: Basic Path Validation
+.Sh HISTORY
+.Fn X509_policy_check
+first appeared in OpenSSL 0.9.8 and has been available since
+.Ox 4.5 .
diff --git a/src/lib/libcrypto/man/X509_policy_tree_level_count.3 b/src/lib/libcrypto/man/X509_policy_tree_level_count.3
index 523cb55f1d..87fb423439 100644
--- a/src/lib/libcrypto/man/X509_policy_tree_level_count.3
+++ b/src/lib/libcrypto/man/X509_policy_tree_level_count.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.1 2021/07/26 14:03:43 schwarze Exp $
+.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.2 2021/07/27 13:27:46 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 26 2021 $
+.Dd $Mdocdate: July 27 2021 $
 .Dt X509_POLICY_TREE_LEVEL_COUNT 3
 .Os
 .Sh NAME
@@ -149,7 +149,8 @@ The parent node is always located on the previous level.
 .Xr OBJ_obj2txt 3 ,
 .Xr POLICYQUALINFO_new 3 ,
 .Xr STACK_OF 3 ,
-.Xr X509_new 3
+.Xr X509_new 3 ,
+.Xr X509_policy_check 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate
 and Certificate Revocation List (CRL) Profile,