.\" $OpenBSD: X509_policy_check.3,v 1.6 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_CHECK 3
.Os
.Sh NAME
.Nm X509_policy_check ,
.Nm X509_policy_tree_free
.Nd construct X.509 valid policy tree
.Sh SYNOPSIS
.In openssl/x509_vfy.h
.Ft int
.Fo X509_policy_check
.Fa "X509_POLICY_TREE **ptree"
.Fa "int *pexplicit_policy"
.Fa "STACK_OF(X509) *certs"
.Fa "STACK_OF(ASN1_OBJECT) *policy_oids"
.Fa "unsigned int flags"
.Fc
.Ft void
.Fn X509_policy_tree_free "X509_POLICY_TREE *tree"
.Sh DESCRIPTION
.Fn X509_policy_check
performs those parts of Basic Certification Path Validation
described in RFC 5280 section 6.1 that are related to the
construction of the valid policy tree.
.Pp
The
.Fa certs
input argument contains the prospective certification path
according to RFC 5280 paragraph 6.1.1(a), starting with the
target certificate and ending with the trust anchor.
.Pp
The
.Fa policy_oids
input argument contains the
.Va user-initial-policy-set
according to RFC 5280 section 6.1.1(c).
It specifies a set of certificate policies acceptable to the certificate user.
.Pp
The
.Fa flags
argument can contain zero or more of the following constants, OR'ed together:
.Bl -tag -width Ds
.It Dv X509_V_FLAG_EXPLICIT_POLICY
Set
.Va initial-explicit-policy
as defined by RFC 5280 paragraph 6.1.1(f).
It requires the path to be valid for at least one of the
.Fa policy_oids .
.It Dv X509_V_FLAG_INHIBIT_ANY
Set
.Va initial-any-policy-inhibit
as defined by RFC 5280 paragraph 6.1.1(g).
It causes the
.Sy anyPolicy
OID to be skipped if it is encountered in a certificate.
.It Dv X509_V_FLAG_INHIBIT_MAP
Set
.Va initial-policy-mapping-inhibit
as defined by RFC 5280 paragraph 6.1.1(e).
It disables policy mapping in the certification path.
.El
.Pp
Upon success and in some cases of failure, the storage location pointed to by
.Fa pexplicit_policy
is set to 1 if
.Dv X509_V_FLAG_EXPLICIT_POLICY
was requested.
Otherwise, it is set to 0.
.Pp
In many cases of success and in a few cases of failure, a pointer to the
.Vt valid_policy_tree
output value mentioned in RFC 5280 section 6.1.6 is returned in
.Pf * Fa ptree .
It contains one level for each of the
.Fa certs ,
in reverse order: level 0 corresponds to the trust anchor,
the last level corresponds to the target certificate.
Level 0 is initialized to contain a single node with a
.Fa valid_policy
of
.Sy anyPolicy
and an empty
.Fa qualifier_set .
.Pp
If a policy tree is returned, the reference count of each of the
.Fa certs
is incremented by 1.
In that case, the caller is responsible for calling
.Fn X509_policy_tree_free
to release all memory used by the
.Fa tree
and to decrement the reference counts
of the certificates referenced from it by 1.
If
.Fa tree
is a
.Dv NULL
pointer,
.Fn X509_policy_tree_free
has no effect.
.Sh RETURN VALUES
.Fn X509_policy_check
returns these values:
.Bl -tag -width 2n
.It \-2
Validation failed because
.Dv X509_V_FLAG_EXPLICIT_POLICY
was requested but the resulting policy tree
or the resulting user policy set would have been empty.
In this case,
.Pf * Fa pexplicit_policy
is set to 1.
If the resulting tree is empty,
.Pf * Fa ptree
is set to
.Dv NULL ;
otherwise, it is set to the resulting tree.
.It \-1
At least one of the
.Fa certs
contains invalid or inconsistent extensions.
.Pf * Fa ptree
is set to
.Dv NULL
and
.Pf * Fa pexplicit_policy
to 0.
.It 0
Internal error.
For example, setting up the policy caches failed, or memory allocation
failed while constructing the tree.
.Pf * Fa ptree
is set to
.Dv NULL
and
.Pf * Fa pexplicit_policy
may or may not be set.
.It 1
Validation succeeded and
.Pf * Fa ptree
and
.Pf * Fa pexplicit_policy
have been set.
In the special cases that the
.Fa certs
argument contains exactly one certificate or that
.Dv X509_V_FLAG_EXPLICIT_POLICY
was not requested and at least one of the certificates contains no
certificate policies or the resulting policy tree would have been empty,
.Pf * Fa ptree
is set to
.Dv NULL
and
.Pf * Fa pexplicit_policy
to 0.
.El
.Sh SEE ALSO
.Xr ASN1_OBJECT_new 3 ,
.Xr OBJ_nid2obj 3 ,
.Xr STACK_OF 3 ,
.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
RFC 5280: Internet X.509 Public Key Infrastructure Certificate
and Certificate Revocation List (CRL) Profile,
section 6.1: Basic Path Validation
.Sh HISTORY
.Fn X509_policy_check
and
.Fn X509_policy_tree_free
first appeared in OpenSSL 0.9.8 and have been available since
.Ox 4.5 .