new manual page X509_policy_tree_get0_policies(3),

also documenting X509_policy_tree_get0_user_policies(3)

4 files changed, 110 insertions, 6 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 6e8753b3791..4a22484ea30 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.210 2021/11/09 16:23:04 schwarze Exp $
+# $OpenBSD: Makefile,v 1.211 2021/11/11 12:06:25 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -352,6 +352,7 @@ MAN=	\
 	X509_new.3 \
 	X509_ocspid_print.3 \
 	X509_policy_check.3 \
+	X509_policy_tree_get0_policies.3 \
 	X509_policy_tree_level_count.3 \
 	X509_print_ex.3 \
 	X509_sign.3 \
diff --git a/lib/libcrypto/man/X509_policy_check.3 b/lib/libcrypto/man/X509_policy_check.3
index e4b3be0d437..5ea774a3eff 100644
--- a/lib/libcrypto/man/X509_policy_check.3
+++ b/lib/libcrypto/man/X509_policy_check.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_policy_check.3,v 1.5 2021/07/30 15:01:40 schwarze Exp $
+.\" $OpenBSD: X509_policy_check.3,v 1.6 2021/11/11 12:06:25 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 30 2021 $
+.Dd $Mdocdate: November 11 2021 $
 .Dt X509_POLICY_CHECK 3
 .Os
 .Sh NAME
@@ -177,6 +177,7 @@ to 0.
 .Xr X509_check_purpose 3 ,
 .Xr X509_check_trust 3 ,
 .Xr X509_new 3 ,
+.Xr X509_policy_tree_get0_policies 3 ,
 .Xr X509_policy_tree_level_count 3 ,
 .Xr X509_verify_cert 3
 .Sh STANDARDS
diff --git a/lib/libcrypto/man/X509_policy_tree_get0_policies.3 b/lib/libcrypto/man/X509_policy_tree_get0_policies.3
new file mode 100644
index 00000000000..cb0715d6cb1
--- /dev/null
+++ b/lib/libcrypto/man/X509_policy_tree_get0_policies.3
@@ -0,0 +1,101 @@
+.\" $OpenBSD: X509_policy_tree_get0_policies.3,v 1.1 2021/11/11 12:06:25 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: November 11 2021 $
+.Dt X509_POLICY_TREE_GET0_POLICIES 3
+.Os
+.Sh NAME
+.Nm X509_policy_tree_get0_policies ,
+.Nm X509_policy_tree_get0_user_policies
+.Nd retrieve arrays of policy tree nodes
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft STACK_OF(X509_POLICY_NODE) *
+.Fn X509_policy_tree_get0_policies "const X509_POLICY_TREE *tree"
+.Ft STACK_OF(X509_POLICY_NODE) *
+.Fn X509_policy_tree_get0_user_policies "const X509_POLICY_TREE *tree"
+.Sh DESCRIPTION
+The
+.Em authority set
+and the
+.Em user set
+are arrays of nodes from a policy
+.Fa tree .
+.Pp
+If the last level of a
+.Fa tree ,
+or equivalently, all levels of it, contain an
+.Sy anyPolicy
+node, the authority set contains
+only this anyPolicy node from the last level.
+Unless the array of
+.Fa policy_oids
+passed to
+.Xr X509_policy_check 3
+contained an anyPolicy object,
+the user set contains one node for each of the
+.Fa policy_oids ;
+specifically, the first matching node that is a child of an anyPolicy node.
+.Pp
+If the last level of the
+.Fa tree
+does not contain an
+.Sy anyPolicy
+node, the authority set contains
+all non-anyPolicy nodes that are children of anyPolicy nodes.
+For each element of the
+.Fa policy_oids ,
+the user set contains the first node from the authority set
+matching it, if any.
+.Pp
+These functions are intended to be called after
+.Xr X509_policy_check 3
+was called either directly or indirectly through
+.Xr X509_verify_cert 3 .
+.Sh RETURN VALUES
+.Fn X509_policy_tree_get0_policies
+returns an internal pointer to the authority set
+or
+.Dv NULL
+if the
+.Fa tree
+argument is
+.Dv NULL .
+.Pp
+.Fn X509_policy_tree_get0_user_policies
+returns an internal pointer to the user set or
+.Dv NULL
+if the
+.Fa tree
+argument is
+.Dv NULL
+or if the array of
+.Fa policy_oids
+passed to
+.Xr X509_policy_check 3
+was empty or contained an anyPolicy object.
+.Sh SEE ALSO
+.Xr STACK_OF 3 ,
+.Xr X509_policy_check 3 ,
+.Xr X509_policy_level_get0_node 3 ,
+.Xr X509_STORE_CTX_get0_policy_tree 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
+These function first appeared in OpenSSL 0.9.8 and have been available since
+.Ox 4.5 .
diff --git a/lib/libcrypto/man/X509_policy_tree_level_count.3 b/lib/libcrypto/man/X509_policy_tree_level_count.3
index f74754c362f..4b13e6a967c 100644
--- a/lib/libcrypto/man/X509_policy_tree_level_count.3
+++ b/lib/libcrypto/man/X509_policy_tree_level_count.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.3 2021/07/28 13:47:21 schwarze Exp $
+.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.4 2021/11/11 12:06:25 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 28 2021 $
+.Dd $Mdocdate: November 11 2021 $
 .Dt X509_POLICY_TREE_LEVEL_COUNT 3
 .Os
 .Sh NAME
@@ -167,7 +167,8 @@ The parent node is always located on the previous level.
 .Xr POLICYQUALINFO_new 3 ,
 .Xr STACK_OF 3 ,
 .Xr X509_new 3 ,
-.Xr X509_policy_check 3
+.Xr X509_policy_check 3 ,
+.Xr X509_policy_tree_get0_policies 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate
 and Certificate Revocation List (CRL) Profile,