1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
.\" $OpenBSD: X509_policy_check.3,v 1.4 2021/07/29 12:39:47 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 29 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.
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).
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, 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
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
.Fn X509_policy_tree_free
releases all memory used by the
.Fa tree
and decrements the reference counts
of the certificates referenced from it by 1.
If
.Fa tree
is a
.Dv NULL
pointer, no action occurs.
.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_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 .
|
