NAME

X509_policy_check, X509_policy_tree_free — construct X.509 valid policy tree

SYNOPSIS

#include <openssl/x509_vfy.h> int
X509_policy_check(X509_POLICY_TREE **ptree, int *pexplicit_policy, STACK_OF(X509) *certs, STACK_OF(ASN1_OBJECT) *policy_oids, unsigned int flags); void
X509_policy_tree_free(X509_POLICY_TREE *tree);

DESCRIPTION

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. The 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. The policy_oids input argument contains the 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. The flags argument can contain zero or more of the following constants, OR'ed together:

X509_V_FLAG_EXPLICIT_POLICY

Set 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 policy_oids.

X509_V_FLAG_INHIBIT_ANY

Set initial-any-policy-inhibit as defined by RFC 5280 paragraph 6.1.1(g). It causes the anyPolicy OID to be skipped if it is encountered in a certificate.

X509_V_FLAG_INHIBIT_MAP

Set initial-policy-mapping-inhibit as defined by RFC 5280 paragraph 6.1.1(e). It disables policy mapping in the certification path.

Upon success and in some cases of failure, the storage location pointed to by pexplicit_policy is set to 1 if X509_V_FLAG_EXPLICIT_POLICY was requested. Otherwise, it is set to 0. In many cases of success and in a few cases of failure, a pointer to the valid_policy_tree output value mentioned in RFC 5280 section 6.1.6 is returned in *ptree. It contains one level for each of the 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 valid_policy of anyPolicy and an empty qualifier_set. If a policy tree is returned, the reference count of each of the certs is incremented by 1. In that case, the caller is responsible for calling X509_policy_tree_free() to release all memory used by the tree and to decrement the reference counts of the certificates referenced from it by 1. If tree is a NULL pointer, X509_policy_tree_free() has no effect.

RETURN VALUES

X509_policy_check() returns these values:

-2

Validation failed because 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, *pexplicit_policy is set to 1. If the resulting tree is empty, *ptree is set to NULL; otherwise, it is set to the resulting tree.

-1

At least one of the certs contains invalid or inconsistent extensions. *ptree is set to NULL and *pexplicit_policy to 0.

0

Internal error. For example, setting up the policy caches failed, or memory allocation failed while constructing the tree. *ptree is set to NULL and *pexplicit_policy may or may not be set.

1

Validation succeeded and *ptree and *pexplicit_policy have been set. In the special cases that the certs argument contains exactly one certificate or that 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, *ptree is set to NULL and *pexplicit_policy to 0.

SEE ALSO

ASN1_OBJECT_new(3), OBJ_nid2obj(3), STACK_OF(3), X509_check_purpose(3), X509_check_trust(3), X509_new(3), X509_policy_tree_get0_policies(3), X509_policy_tree_level_count(3), X509_verify_cert(3)

STANDARDS

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, section 6.1: Basic Path Validation

HISTORY

X509_policy_check() and X509_policy_tree_free() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5.