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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/*
* This file defines functions associated with the PKIX_RevocationChecker
* type.
*
*/
#ifndef _PKIX_REVCHECKER_H
#define _PKIX_REVCHECKER_H
#include "pkixt.h"
#include "pkix_pl_pki.h"
#ifdef __cplusplus
extern "C" {
#endif
/* General
*
* Please refer to the libpkix Programmer's Guide for detailed information
* about how to use the libpkix library. Certain key warnings and notices from
* that document are repeated here for emphasis.
*
* All identifiers in this file (and all public identifiers defined in
* libpkix) begin with "PKIX_". Private identifiers only intended for use
* within the library begin with "pkix_".
*
* A function returns NULL upon success, and a PKIX_Error pointer upon failure.
*
* Unless otherwise noted, for all accessor (gettor) functions that return a
* PKIX_PL_Object pointer, callers should assume that this pointer refers to a
* shared object. Therefore, the caller should treat this shared object as
* read-only and should not modify this shared object. When done using the
* shared object, the caller should release the reference to the object by
* using the PKIX_PL_Object_DecRef function.
*
* While a function is executing, if its arguments (or anything referred to by
* its arguments) are modified, free'd, or destroyed, the function's behavior
* is undefined.
*
*/
/* PKIX_RevocationChecker
*
* PKIX_RevocationChecker provides a standard way of revocation checking.
* Caller should configure two set of tests(represented at lists of
* RevocationMethod objects) to be performed on the leaf and on the rest of
* the chain certificates.
*
* PKIX_RevocationMethods provide a standard way for the caller to insert
* their own custom revocation checks to verify the revocation status of
* certificates. This may be useful in many scenarios, including when the
* caller wishes to use their own revocation checking mechanism instead of (or
* in addition to) the default revocation checking mechanism provided by
* libpkix, which uses CRLs and OCSP.
*
* Once the caller has created the RevocationMethod object(s), the caller
* then specifies the RevocationMethod object(s) in a RevocationCheck object
* and sets it into a ProcessingParams.
*/
/*
* FUNCTION: PKIX_RevocationChecker_Create
* DESCRIPTION:
*
* Creates a revocation checker object with the given flags. Revocation will
* be checked at the current date.
*
* PARAMETERS:
* "leafMethodListFlags"
* Defines a set of method independent flags that will be used to check
* revocation of the leaf cert in the chain.
* "chainMethodListFlags"
* Defines a set of method independent flags that will be used to check
* revocation of the remaining certs in the chain.
* "pChecker"
* The return address of created checker.
* "plContext"
* Platform-specific context pointer.
* THREAD SAFETY:
* Thread Safe
*
* Multiple threads must be able to safely call this function without
* worrying about conflicts, even if they're operating on the same objects.
* RETURNS:
* Returns NULL if the function succeeds.
* Returns a RevocationChecker Error if the function fails in a non-fatal way.
* Returns a Fatal Error if the function fails in an unrecoverable way.
*/
PKIX_Error *
PKIX_RevocationChecker_Create(
PKIX_UInt32 leafMethodListFlags,
PKIX_UInt32 chainMethodListFlags,
PKIX_RevocationChecker **pChecker,
void *plContext);
/*
* FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
* DESCRIPTION:
*
* Creates revocation method object with given parameters and adds it
* to revocation checker method list.
*
* PARAMETERS:
* "revChecker"
* Address of revocation checker structure.
* "procParams"
* Address of ProcessingParams used to initialize the checker.
* Must be non-NULL.
* "methodType"
* Type of the method. Currently only two types are
* supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
* "methodFlags"
* Set of flags for the method.
* "methodPriority"
* Method priority. (0 corresponds to the highest priority)
* "verificationFn"
* User call back function that will perform validation of fetched
* revocation information(new crl or ocsp response)
* "isLeafMethod"
* Boolean flag that if set to true indicates that the method should
* should be used for leaf cert revocation test(false for chain set
* methods).
* "plContext"
* Platform-specific context pointer.
* THREAD SAFETY:
* Thread Safe
*
* Multiple threads must be able to safely call this function without
* worrying about conflicts, even if they're operating on the same objects.
* RETURNS:
* Returns NULL if the function succeeds.
* Returns a RevocationChecker Error if the function fails in a non-fatal way.
* Returns a Fatal Error if the function fails in an unrecoverable way.
*/
PKIX_Error *
PKIX_RevocationChecker_CreateAndAddMethod(
PKIX_RevocationChecker *revChecker,
PKIX_ProcessingParams *params,
PKIX_RevocationMethodType methodType,
PKIX_UInt32 methodFlags,
PKIX_UInt32 methodPriority,
PKIX_PL_VerifyCallback verificationFn,
PKIX_Boolean isLeafMethod,
void *plContext);
/*
* FUNCTION: PKIX_RevocationChecker_Check
* DESCRIPTION:
*
* Verifies revocation status of the certificate. Issuer cert is given to
* be used in verification of revocation information. Performed verification
* check depends on configured revocation methods(ocsp, crl. See
* PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
* building process at which PKIX_RevocationChecker_Check was invoked.
* For security reasons, the cert status is checked only against cached
* revocation information during chain building stage(no trust anchor yes has
* been found). The fresh revocation information fetching is done only at chain
* verification stage after trust anchor was identified.
*
* PARAMETERS:
* "cert"
* Address of Cert whose revocation status is to be determined.
* Must be non-NULL.
* "issuer"
* Issuer cert that potentially holds public key that will be used
* to verify revocation info.
* "revChecker"
* Address of revocation checker structure.
* "procParams"
* Address of ProcessingParams used to initialize the checker.
* Must be non-NULL.
* "chainVerificationState"
* Need to be set to true, if the check was called during chain verification
* as an opposite to chain building.
* "testingLeafCert"
* Set to true if verifying revocation status of a leaf cert.
* "revStatus"
* Address of the returned revocation status of the cert.
* "pResultCode"
* Address where revocation status will be stored. Must be non-NULL.
* "pNBIOContext"
* Address at which platform-dependent non-blocking I/O context is stored.
* Must be non-NULL.
* "plContext"
* Platform-specific context pointer.
* THREAD SAFETY:
* Thread Safe
*
* Multiple threads must be able to safely call this function without
* worrying about conflicts, even if they're operating on the same objects.
* RETURNS:
* Returns NULL if the function succeeds.
* Returns a RevocationChecker Error if the function fails in a non-fatal way.
* Returns a Fatal Error if the function fails in an unrecoverable way.
*/
PKIX_Error *
PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
PKIX_PL_Cert *issuer,
PKIX_RevocationChecker *revChecker,
PKIX_ProcessingParams *procParams,
PKIX_Boolean chainVerificationState,
PKIX_Boolean testingLeafCert,
PKIX_RevocationStatus *revStatus,
PKIX_UInt32 *pReasonCode,
void **pNbioContext,
void *plContext);
#ifdef __cplusplus
}
#endif
#endif /* _PKIX_REVCHECKER_H */
|
