--- /dev/null
+.\" $OpenBSD: X509_policy_check.3,v 1.1 2021/07/27 13:27:46 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 27 2021 $
+.Dt X509_POLICY_CHECK 3
+.Os
+.Sh NAME
+.Nm X509_policy_check
+.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
+.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.
+If a policy tree is returned, the reference count of each of the
+.Fa certs
+is incremented by 1.
+.Pp
+The
+.Fa policy_oids
+input argument contains the
+.Va user-initial-policy-set
+according to RFC 5280 section 6.1.1(c).
+.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, 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 ,
+an empty
+.Fa qualifier_set ,
+and an
+.Fa expected_policy_set
+containing only
+.Sy anyPolicy .
+.Pp
+The storage location pointed to by
+.Fa pexplicit_policy
+is set as specified in RFC 5280 paragraphs 6.1.2(d), 6.1.4(h), 6.1.4(i),
+6.1.5(a), and 6.1.5(b).
+In case of failure, it may or may not get set, representing a partial result.
+.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 be set to 0 or to a partial result.
+.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 the resulting policy tree would have been empty,
+.Pf * Fa ptree
+is set to
+.Dv NULL
+and
+.Pf * Fa pexplicit_policy
+to 0.
+.It 2
+.Dv X509_V_FLAG_EXPLICIT_POLICY
+was not requested and at least one of the certificates contains no
+certificate policies.
+.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_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
+first appeared in OpenSSL 0.9.8 and has been available since
+.Ox 4.5 .
projects / openbsd / commitdiff