.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.5 2022/09/10 08:50:53 jsg 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: September 10 2022 $
.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 .
If it is not 0, it equals the number of certificates in the
certification path the tree was created from, including both
the target certificate and the trust anchor.
.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 .
An
.Fa index
of 0 corresponds to the trust anchor
and the last level corresponds to the target certificate.
.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 .
It represents a single policy that is valid for the path
from the trust anchor to the certificate corresponding
to the level containing the
.Fa node .
.Pp
.Fn X509_policy_node_get0_qualifiers
returns an internal pointer to the
.Fa qualifier_set
child object of the node or
.Dv NULL
if the
.Fa node
argument is
.Dv NULL .
It contains the policy qualifiers associated with the
.Fa valid_policy
of the
.Fa node
in the certificate corresponding to the level containing the
.Fa node .
.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 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 ,
.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,
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 .