new manual page X509_policy_tree_level_count(3)

documenting the X509_POLICY_TREE object and its sub-objects

4 files changed, 168 insertions, 6 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index c3dcaa06a3f..a1ea6af33ab 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.186 2021/07/24 14:33:14 schwarze Exp $
+# $OpenBSD: Makefile,v 1.187 2021/07/26 14:03:43 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -327,6 +327,7 @@ MAN=	\
 	X509_get1_email.3 \
 	X509_keyid_set1.3 \
 	X509_new.3 \
+	X509_policy_tree_level_count.3 \
 	X509_print_ex.3 \
 	X509_sign.3 \
 	X509_signature_dump.3 \
diff --git a/lib/libcrypto/man/POLICYINFO_new.3 b/lib/libcrypto/man/POLICYINFO_new.3
index 4b88cf00eba..7938ed591d6 100644
--- a/lib/libcrypto/man/POLICYINFO_new.3
+++ b/lib/libcrypto/man/POLICYINFO_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: POLICYINFO_new.3,v 1.7 2019/06/06 17:41:43 schwarze Exp $
+.\"	$OpenBSD: POLICYINFO_new.3,v 1.8 2021/07/26 14:03:43 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 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: June 6 2019 $
+.Dd $Mdocdate: July 26 2021 $
 .Dt POLICYINFO_NEW 3
 .Os
 .Sh NAME
@@ -178,7 +178,8 @@ if an error occurs.
 .Xr d2i_POLICYINFO 3 ,
 .Xr NAME_CONSTRAINTS_new 3 ,
 .Xr X509_EXTENSION_new 3 ,
-.Xr X509_new 3
+.Xr X509_new 3 ,
+.Xr X509_policy_tree_level_count 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 Certificate Revocation List (CRL) Profile:
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index e06203f87c6..304045f6577 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.26 2021/07/24 14:33:14 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.27 2021/07/26 14:03:43 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 24 2021 $
+.Dd $Mdocdate: July 26 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_tree_level_count 3 ,
 .Xr X509_print_ex 3 ,
 .Xr X509_PUBKEY_new 3 ,
 .Xr X509_PURPOSE_set 3 ,
diff --git a/lib/libcrypto/man/X509_policy_tree_level_count.3 b/lib/libcrypto/man/X509_policy_tree_level_count.3
new file mode 100644
index 00000000000..523cb55f1d0
--- /dev/null
+++ b/lib/libcrypto/man/X509_policy_tree_level_count.3
@@ -0,0 +1,159 @@
+.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.1 2021/07/26 14:03:43 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 26 2021 $
+.Dt X509_POLICY_TREE_LEVEL_COUNT 3
+.Os
+.Sh NAME
+.Nm X509_policy_tree_level_count ,
+.Nm X509_policy_tree_get0_level ,
+.Nm X509_policy_level_node_count ,
+.Nm X509_policy_level_get0_node ,
+.Nm X509_policy_node_get0_policy ,
+.Nm X509_policy_node_get0_qualifiers ,
+.Nm X509_policy_node_get0_parent
+.Nd inspect X.509 policy tree objects
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft int
+.Fn X509_policy_tree_level_count "const X509_POLICY_TREE *tree"
+.Ft X509_POLICY_LEVEL *
+.Fn X509_policy_tree_get0_level "const X509_POLICY_TREE *tree" "int index"
+.Ft int
+.Fn X509_policy_level_node_count "X509_POLICY_LEVEL *level"
+.Ft X509_POLICY_NODE *
+.Fn X509_policy_level_get0_node "X509_POLICY_LEVEL *level" "int index"
+.Ft const ASN1_OBJECT *
+.Fn X509_policy_node_get0_policy "const X509_POLICY_NODE *node"
+.Ft STACK_OF(POLICYQUALINFO) *
+.Fn X509_policy_node_get0_qualifiers "const X509_POLICY_NODE *node"
+.Ft const X509_POLICY_NODE *
+.Fn X509_policy_node_get0_parent "const X509_POLICY_NODE *node"
+.Sh DESCRIPTION
+The
+.Vt X509_POLICY_TREE
+object represents a
+.Vt valid_policy_tree
+as described in RFC 5280 section 6.1.
+.Pp
+The
+.Vt X509_POLICY_LEVEL
+object represents one level of such a tree,
+corresponding to one certificate.
+.Pp
+The
+.Vt X509_POLICY_NODE
+object represents one node in the tree.
+.Sh RETURN VALUES
+.Fn X509_policy_tree_level_count
+returns the number of levels in the
+.Fa tree
+or 0 if the
+.Fa tree
+argument is
+.Dv NULL .
+.Pp
+.Fn X509_policy_tree_get0_level
+returns an internal pointer to the level of the
+.Fa tree
+with the given
+.Fa index
+or
+.Dv NULL
+if the
+.Fa tree
+argument is
+.Dv NULL
+or the
+.Fa index
+is less than 0 or greater than or equal to the number of levels in the
+.Fa tree .
+.Pp
+.Fn X509_policy_level_node_count
+returns the number of nodes on the
+.Fa level ,
+including an
+.Sy anyPolicy
+node if it is present, or 0 if the
+.Fa level
+argument is
+.Dv NULL .
+.Pp
+.Fn X509_policy_level_get0_node
+returns an internal pointer to the node on the
+.Fa level
+with the given
+.Fa index
+or
+.Dv NULL
+if the
+.Fa level
+argument is
+.Dv NULL
+or the
+.Fa index
+is less than 0 or greater than or equal to the number of nodes on the level.
+If an
+.Sy anyPolicy
+node is present on the level, it can be retrieved by passing an
+.Fa index
+of 0.
+.Pp
+.Fn X509_policy_node_get0_policy
+returns an internal pointer to the
+.Fa valid_policy
+child object of the node or
+.Dv NULL
+if the
+.Fa node
+argument is
+.Dv NULL .
+.Pp
+.Fn X509_policy_node_get0_qualifiers
+returns an an internal pointer to the
+.Fa qualifier_set
+child object of the node or
+.Dv NULL
+if the
+.Fa node
+argument is
+.Dv NULL .
+.Pp
+.Fn X509_policy_node_get0_parent
+returns
+.Dv NULL
+if the
+.Fa node
+argument is
+.Dv NULL
+or located on level 0.
+Otherwise, it returns an an internal pointer to the parent node of the
+.Fa node
+argument.
+The parent node is always located on the previous level.
+.Sh SEE ALSO
+.Xr ASN1_OBJECT_new 3 ,
+.Xr OBJ_obj2txt 3 ,
+.Xr POLICYQUALINFO_new 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_new 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 .