new manual page X509_policy_tree_level_count(3)

documenting the X509_POLICY_TREE object and its sub-objects

1 files changed, 159 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/X509_policy_tree_level_count.3 b/src/lib/libcrypto/man/X509_policy_tree_level_count.3
new file mode 100644
index 0000000000..523cb55f1d
--- /dev/null
+++ b/src/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 .