.\" $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 .