The Tor Browser / file comparison

comparison: security/nss/lib/certhigh/ocsp.h

security/nss/lib/certhigh/ocsp.h

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:7341f22cfe3f
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5 /*
6 * Interface to the OCSP implementation.
7 */
8
9 #ifndef _OCSP_H_
10 #define _OCSP_H_
11
12
13 #include "plarena.h"
14 #include "seccomon.h"
15 #include "secoidt.h"
16 #include "keyt.h"
17 #include "certt.h"
18 #include "ocspt.h"
19
20
21 /************************************************************************/
22 SEC_BEGIN_PROTOS
23
24 /*
25 * This function registers the HttpClient with whose functions the
26 * HttpClientFcn structure has been populated as the default Http
27 * client.
28 *
29 * The function table must be a global object.
30 * The caller must ensure that NSS will be able to call
31 * the registered functions for the lifetime of the process.
32 */
33 extern SECStatus
34 SEC_RegisterDefaultHttpClient(const SEC_HttpClientFcn *fcnTable);
35
36 /*
37 * This function obtains the HttpClient which has been registered
38 * by an earlier call to SEC_RegisterDefaultHttpClient.
39 */
40 extern const SEC_HttpClientFcn *
41 SEC_GetRegisteredHttpClient(void);
42
43 /*
44 * Sets parameters that control NSS' internal OCSP cache.
45 * maxCacheEntries, special varlues are:
46 * -1 disable cache
47 * 0 unlimited cache entries
48 * minimumSecondsToNextFetchAttempt:
49 * whenever an OCSP request was attempted or completed over the network,
50 * wait at least this number of seconds before trying to fetch again.
51 * maximumSecondsToNextFetchAttempt:
52 * this is the maximum age of a cached response we allow, until we try
53 * to fetch an updated response, even if the OCSP responder expects
54 * that newer information update will not be available yet.
55 */
56 extern SECStatus
57 CERT_OCSPCacheSettings(PRInt32 maxCacheEntries,
58 PRUint32 minimumSecondsToNextFetchAttempt,
59 PRUint32 maximumSecondsToNextFetchAttempt);
60
61 /*
62 * Set the desired behaviour on OCSP failures.
63 * See definition of ocspFailureMode for allowed choices.
64 */
65 extern SECStatus
66 CERT_SetOCSPFailureMode(SEC_OcspFailureMode ocspFailureMode);
67
68 /*
69 * Configure the maximum time NSS will wait for an OCSP response.
70 */
71 extern SECStatus
72 CERT_SetOCSPTimeout(PRUint32 seconds);
73
74 /*
75 * Removes all items currently stored in the OCSP cache.
76 */
77 extern SECStatus
78 CERT_ClearOCSPCache(void);
79
80 /*
81 * FUNCTION: CERT_EnableOCSPChecking
82 * Turns on OCSP checking for the given certificate database.
83 * INPUTS:
84 * CERTCertDBHandle *handle
85 * Certificate database for which OCSP checking will be enabled.
86 * RETURN:
87 * Returns SECFailure if an error occurred (likely only problem
88 * allocating memory); SECSuccess otherwise.
89 */
90 extern SECStatus
91 CERT_EnableOCSPChecking(CERTCertDBHandle *handle);
92
93 /*
94 * FUNCTION: CERT_DisableOCSPChecking
95 * Turns off OCSP checking for the given certificate database.
96 * This routine disables OCSP checking. Though it will return
97 * SECFailure if OCSP checking is not enabled, it is "safe" to
98 * call it that way and just ignore the return value, if it is
99 * easier to just call it than to "remember" whether it is enabled.
100 * INPUTS:
101 * CERTCertDBHandle *handle
102 * Certificate database for which OCSP checking will be disabled.
103 * RETURN:
104 * Returns SECFailure if an error occurred (usually means that OCSP
105 * checking was not enabled or status contexts were not initialized --
106 * error set will be SEC_ERROR_OCSP_NOT_ENABLED); SECSuccess otherwise.
107 */
108 extern SECStatus
109 CERT_DisableOCSPChecking(CERTCertDBHandle *handle);
110
111 /*
112 * FUNCTION: CERT_SetOCSPDefaultResponder
113 * Specify the location and cert of the default responder.
114 * If OCSP checking is already enabled *and* use of a default responder
115 * is also already enabled, all OCSP checking from now on will go directly
116 * to the specified responder. If OCSP checking is not enabled, or if
117 * it is but use of a default responder is not enabled, the information
118 * will be recorded and take effect whenever both are enabled.
119 * INPUTS:
120 * CERTCertDBHandle *handle
121 * Cert database on which OCSP checking should use the default responder.
122 * const char *url
123 * The location of the default responder (e.g. "http://foo.com:80/ocsp")
124 * Note that the location will not be tested until the first attempt
125 * to send a request there.
126 * const char *name
127 * The nickname of the cert to trust (expected) to sign the OCSP responses.
128 * If the corresponding cert cannot be found, SECFailure is returned.
129 * RETURN:
130 * Returns SECFailure if an error occurred; SECSuccess otherwise.
131 * The most likely error is that the cert for "name" could not be found
132 * (probably SEC_ERROR_UNKNOWN_CERT). Other errors are low-level (no memory,
133 * bad database, etc.).
134 */
135 extern SECStatus
136 CERT_SetOCSPDefaultResponder(CERTCertDBHandle *handle,
137 const char *url, const char *name);
138
139 /*
140 * FUNCTION: CERT_EnableOCSPDefaultResponder
141 * Turns on use of a default responder when OCSP checking.
142 * If OCSP checking is already enabled, this will make subsequent checks
143 * go directly to the default responder. (The location of the responder
144 * and the nickname of the responder cert must already be specified.)
145 * If OCSP checking is not enabled, this will be recorded and take effect
146 * whenever it is enabled.
147 * INPUTS:
148 * CERTCertDBHandle *handle
149 * Cert database on which OCSP checking should use the default responder.
150 * RETURN:
151 * Returns SECFailure if an error occurred; SECSuccess otherwise.
152 * No errors are especially likely unless the caller did not previously
153 * perform a successful call to SetOCSPDefaultResponder (in which case
154 * the error set will be SEC_ERROR_OCSP_NO_DEFAULT_RESPONDER).
155 */
156 extern SECStatus
157 CERT_EnableOCSPDefaultResponder(CERTCertDBHandle *handle);
158
159 /*
160 * FUNCTION: CERT_DisableOCSPDefaultResponder
161 * Turns off use of a default responder when OCSP checking.
162 * (Does nothing if use of a default responder is not enabled.)
163 * INPUTS:
164 * CERTCertDBHandle *handle
165 * Cert database on which OCSP checking should stop using a default
166 * responder.
167 * RETURN:
168 * Returns SECFailure if an error occurred; SECSuccess otherwise.
169 * Errors very unlikely (like random memory corruption...).
170 */
171 extern SECStatus
172 CERT_DisableOCSPDefaultResponder(CERTCertDBHandle *handle);
173
174 /* If forcePost is set, OCSP requests will only be sent using the HTTP POST
175 * method. When forcePost is not set, OCSP requests will be sent using the
176 * HTTP GET method, with a fallback to POST when we fail to receive a response
177 * and/or when we receive an uncacheable response like "Unknown."
178 *
179 * The default is to use GET and fallback to POST.
180 */
181 extern SECStatus CERT_ForcePostMethodForOCSP(PRBool forcePost);
182
183 /*
184 * -------------------------------------------------------
185 * The Functions above are those expected to be used by a client
186 * providing OCSP status checking along with every cert verification.
187 * The functions below are for OCSP testing, debugging, or clients
188 * or servers performing more specialized OCSP tasks.
189 * -------------------------------------------------------
190 */
191
192 /*
193 * FUNCTION: CERT_CreateOCSPRequest
194 * Creates a CERTOCSPRequest, requesting the status of the certs in
195 * the given list.
196 * INPUTS:
197 * CERTCertList *certList
198 * A list of certs for which status will be requested.
199 * Note that all of these certificates should have the same issuer,
200 * or it's expected the response will be signed by a trusted responder.
201 * If the certs need to be broken up into multiple requests, that
202 * must be handled by the caller (and thus by having multiple calls
203 * to this routine), who knows about where the request(s) are being
204 * sent and whether there are any trusted responders in place.
205 * PRTime time
206 * Indicates the time for which the certificate status is to be
207 * determined -- this may be used in the search for the cert's issuer
208 * but has no effect on the request itself.
209 * PRBool addServiceLocator
210 * If true, the Service Locator extension should be added to the
211 * single request(s) for each cert.
212 * CERTCertificate *signerCert
213 * If non-NULL, means sign the request using this cert. Otherwise,
214 * do not sign.
215 * XXX note that request signing is not yet supported; see comment in code
216 * RETURN:
217 * A pointer to a CERTOCSPRequest structure containing an OCSP request
218 * for the cert list. On error, null is returned, with an error set
219 * indicating the reason. This is likely SEC_ERROR_UNKNOWN_ISSUER.
220 * (The issuer is needed to create a request for the certificate.)
221 * Other errors are low-level problems (no memory, bad database, etc.).
222 */
223 extern CERTOCSPRequest *
224 CERT_CreateOCSPRequest(CERTCertList *certList, PRTime time,
225 PRBool addServiceLocator,
226 CERTCertificate *signerCert);
227
228 /*
229 * FUNCTION: CERT_AddOCSPAcceptableResponses
230 * Add the AcceptableResponses extension to an OCSP Request.
231 * INPUTS:
232 * CERTOCSPRequest *request
233 * The request to which the extension should be added.
234 * SECOidTag responseType0, ...
235 * A list (of one or more) of SECOidTag -- each of the response types
236 * to be added. The last OID *must* be SEC_OID_PKIX_OCSP_BASIC_RESPONSE.
237 * (This marks the end of the list, and it must be specified because a
238 * client conforming to the OCSP standard is required to handle the basic
239 * response type.) The OIDs are not checked in any way.
240 * RETURN:
241 * SECSuccess if the extension is added; SECFailure if anything goes wrong.
242 * All errors are internal or low-level problems (e.g. no memory).
243 */
244 extern SECStatus
245 CERT_AddOCSPAcceptableResponses(CERTOCSPRequest *request,
246 SECOidTag responseType0, ...);
247
248 /*
249 * FUNCTION: CERT_EncodeOCSPRequest
250 * DER encodes an OCSP Request, possibly adding a signature as well.
251 * XXX Signing is not yet supported, however; see comments in code.
252 * INPUTS:
253 * PLArenaPool *arena
254 * The return value is allocated from here.
255 * If a NULL is passed in, allocation is done from the heap instead.
256 * CERTOCSPRequest *request
257 * The request to be encoded.
258 * void *pwArg
259 * Pointer to argument for password prompting, if needed. (Definitely
260 * not needed if not signing.)
261 * RETURN:
262 * Returns a NULL on error and a pointer to the SECItem with the
263 * encoded value otherwise. Any error is likely to be low-level
264 * (e.g. no memory).
265 */
266 extern SECItem *
267 CERT_EncodeOCSPRequest(PLArenaPool *arena, CERTOCSPRequest *request,
268 void *pwArg);
269
270 /*
271 * FUNCTION: CERT_DecodeOCSPRequest
272 * Decode a DER encoded OCSP Request.
273 * INPUTS:
274 * SECItem *src
275 * Pointer to a SECItem holding DER encoded OCSP Request.
276 * RETURN:
277 * Returns a pointer to a CERTOCSPRequest containing the decoded request.
278 * On error, returns NULL. Most likely error is trouble decoding
279 * (SEC_ERROR_OCSP_MALFORMED_REQUEST), or low-level problem (no memory).
280 */
281 extern CERTOCSPRequest *
282 CERT_DecodeOCSPRequest(const SECItem *src);
283
284 /*
285 * FUNCTION: CERT_DestroyOCSPRequest
286 * Frees an OCSP Request structure.
287 * INPUTS:
288 * CERTOCSPRequest *request
289 * Pointer to CERTOCSPRequest to be freed.
290 * RETURN:
291 * No return value; no errors.
292 */
293 extern void
294 CERT_DestroyOCSPRequest(CERTOCSPRequest *request);
295
296 /*
297 * FUNCTION: CERT_DecodeOCSPResponse
298 * Decode a DER encoded OCSP Response.
299 * INPUTS:
300 * SECItem *src
301 * Pointer to a SECItem holding DER encoded OCSP Response.
302 * RETURN:
303 * Returns a pointer to a CERTOCSPResponse (the decoded OCSP Response);
304 * the caller is responsible for destroying it. Or NULL if error (either
305 * response could not be decoded (SEC_ERROR_OCSP_MALFORMED_RESPONSE),
306 * it was of an unexpected type (SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE),
307 * or a low-level or internal error occurred).
308 */
309 extern CERTOCSPResponse *
310 CERT_DecodeOCSPResponse(const SECItem *src);
311
312 /*
313 * FUNCTION: CERT_DestroyOCSPResponse
314 * Frees an OCSP Response structure.
315 * INPUTS:
316 * CERTOCSPResponse *request
317 * Pointer to CERTOCSPResponse to be freed.
318 * RETURN:
319 * No return value; no errors.
320 */
321 extern void
322 CERT_DestroyOCSPResponse(CERTOCSPResponse *response);
323
324 /*
325 * FUNCTION: CERT_GetEncodedOCSPResponse
326 * Creates and sends a request to an OCSP responder, then reads and
327 * returns the (encoded) response.
328 * INPUTS:
329 * PLArenaPool *arena
330 * Pointer to arena from which return value will be allocated.
331 * If NULL, result will be allocated from the heap (and thus should
332 * be freed via SECITEM_FreeItem).
333 * CERTCertList *certList
334 * A list of certs for which status will be requested.
335 * Note that all of these certificates should have the same issuer,
336 * or it's expected the response will be signed by a trusted responder.
337 * If the certs need to be broken up into multiple requests, that
338 * must be handled by the caller (and thus by having multiple calls
339 * to this routine), who knows about where the request(s) are being
340 * sent and whether there are any trusted responders in place.
341 * const char *location
342 * The location of the OCSP responder (a URL).
343 * PRTime time
344 * Indicates the time for which the certificate status is to be
345 * determined -- this may be used in the search for the cert's issuer
346 * but has no other bearing on the operation.
347 * PRBool addServiceLocator
348 * If true, the Service Locator extension should be added to the
349 * single request(s) for each cert.
350 * CERTCertificate *signerCert
351 * If non-NULL, means sign the request using this cert. Otherwise,
352 * do not sign.
353 * void *pwArg
354 * Pointer to argument for password prompting, if needed. (Definitely
355 * not needed if not signing.)
356 * OUTPUTS:
357 * CERTOCSPRequest **pRequest
358 * Pointer in which to store the OCSP request created for the given
359 * list of certificates. It is only filled in if the entire operation
360 * is successful and the pointer is not null -- and in that case the
361 * caller is then reponsible for destroying it.
362 * RETURN:
363 * Returns a pointer to the SECItem holding the response.
364 * On error, returns null with error set describing the reason:
365 * SEC_ERROR_UNKNOWN_ISSUER
366 * SEC_ERROR_CERT_BAD_ACCESS_LOCATION
367 * SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
368 * Other errors are low-level problems (no memory, bad database, etc.).
369 */
370 extern SECItem *
371 CERT_GetEncodedOCSPResponse(PLArenaPool *arena, CERTCertList *certList,
372 const char *location, PRTime time,
373 PRBool addServiceLocator,
374 CERTCertificate *signerCert, void *pwArg,
375 CERTOCSPRequest **pRequest);
376
377 /*
378 * FUNCTION: CERT_VerifyOCSPResponseSignature
379 * Check the signature on an OCSP Response. Will also perform a
380 * verification of the signer's certificate. Note, however, that a
381 * successful verification does not make any statement about the
382 * signer's *authority* to provide status for the certificate(s),
383 * that must be checked individually for each certificate.
384 * INPUTS:
385 * CERTOCSPResponse *response
386 * Pointer to response structure with signature to be checked.
387 * CERTCertDBHandle *handle
388 * Pointer to CERTCertDBHandle for certificate DB to use for verification.
389 * void *pwArg
390 * Pointer to argument for password prompting, if needed.
391 * CERTCertificate *issuerCert
392 * Issuer of the certificate that generated the OCSP request.
393 * OUTPUTS:
394 * CERTCertificate **pSignerCert
395 * Pointer in which to store signer's certificate; only filled-in if
396 * non-null.
397 * RETURN:
398 * Returns SECSuccess when signature is valid, anything else means invalid.
399 * Possible errors set:
400 * SEC_ERROR_OCSP_MALFORMED_RESPONSE - unknown type of ResponderID
401 * SEC_ERROR_INVALID_TIME - bad format of "ProducedAt" time
402 * SEC_ERROR_UNKNOWN_SIGNER - signer's cert could not be found
403 * SEC_ERROR_BAD_SIGNATURE - the signature did not verify
404 * Other errors are any of the many possible failures in cert verification
405 * (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
406 * verifying the signer's cert, or low-level problems (no memory, etc.)
407 */
408 extern SECStatus
409 CERT_VerifyOCSPResponseSignature(CERTOCSPResponse *response,
410 CERTCertDBHandle *handle, void *pwArg,
411 CERTCertificate **pSignerCert,
412 CERTCertificate *issuerCert);
413
414 /*
415 * FUNCTION: CERT_GetOCSPAuthorityInfoAccessLocation
416 * Get the value of the URI of the OCSP responder for the given cert.
417 * This is found in the (optional) Authority Information Access extension
418 * in the cert.
419 * INPUTS:
420 * CERTCertificate *cert
421 * The certificate being examined.
422 * RETURN:
423 * char *
424 * A copy of the URI for the OCSP method, if found. If either the
425 * extension is not present or it does not contain an entry for OCSP,
426 * SEC_ERROR_EXTENSION_NOT_FOUND will be set and a NULL returned.
427 * Any other error will also result in a NULL being returned.
428 *
429 * This result should be freed (via PORT_Free) when no longer in use.
430 */
431 extern char *
432 CERT_GetOCSPAuthorityInfoAccessLocation(const CERTCertificate *cert);
433
434 /*
435 * FUNCTION: CERT_RegisterAlternateOCSPAIAInfoCallBack
436 * This function serves two purposes.
437 * 1) It registers the address of a callback function that will be
438 * called for certs that have no OCSP AIA extension, to see if the
439 * callback wishes to supply an alternative URL for such an OCSP inquiry.
440 * 2) It outputs the previously registered function's address to the
441 * address supplied by the caller, unless that is NULL.
442 * The registered callback function returns NULL, or an allocated string
443 * that may be subsequently freed by calling PORT_Free().
444 * RETURN:
445 * SECSuccess or SECFailure (if the library is not yet intialized)
446 */
447 extern SECStatus
448 CERT_RegisterAlternateOCSPAIAInfoCallBack(
449 CERT_StringFromCertFcn newCallback,
450 CERT_StringFromCertFcn * oldCallback);
451
452 /*
453 * FUNCTION: CERT_ParseURL
454 * Parse a URI into hostname, port, and path. The scheme in the URI must
455 * be "http".
456 * INPUTS:
457 * const char *url
458 * The URI to be parsed
459 * OUTPUTS:
460 * char **pHostname
461 * Pointer to store the hostname obtained from the URI.
462 * This result should be freed (via PORT_Free) when no longer in use.
463 * PRUint16 *pPort
464 * Pointer to store the port number obtained from the URI.
465 * char **pPath
466 * Pointer to store the path obtained from the URI.
467 * This result should be freed (via PORT_Free) when no longer in use.
468 * RETURN:
469 * Returns SECSuccess when parsing was successful. Returns SECFailure when
470 * problems were encountered.
471 */
472 extern SECStatus
473 CERT_ParseURL(const char *url, char **pHostname, PRUint16 *pPort, char **pPath);
474
475 /*
476 * FUNCTION: CERT_CheckOCSPStatus
477 * Checks the status of a certificate via OCSP. Will only check status for
478 * a certificate that has an AIA (Authority Information Access) extension
479 * for OCSP *or* when a "default responder" is specified and enabled.
480 * (If no AIA extension for OCSP and no default responder in place, the
481 * cert is considered to have a good status and SECSuccess is returned.)
482 * INPUTS:
483 * CERTCertDBHandle *handle
484 * certificate DB of the cert that is being checked
485 * CERTCertificate *cert
486 * the certificate being checked
487 * XXX in the long term also need a boolean parameter that specifies
488 * whether to check the cert chain, as well; for now we check only
489 * the leaf (the specified certificate)
490 * PRTime time
491 * time for which status is to be determined
492 * void *pwArg
493 * argument for password prompting, if needed
494 * RETURN:
495 * Returns SECSuccess if an approved OCSP responder "knows" the cert
496 * *and* returns a non-revoked status for it; SECFailure otherwise,
497 * with an error set describing the reason:
498 *
499 * SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
500 * SEC_ERROR_OCSP_FUTURE_RESPONSE
501 * SEC_ERROR_OCSP_MALFORMED_REQUEST
502 * SEC_ERROR_OCSP_MALFORMED_RESPONSE
503 * SEC_ERROR_OCSP_OLD_RESPONSE
504 * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
505 * SEC_ERROR_OCSP_SERVER_ERROR
506 * SEC_ERROR_OCSP_TRY_SERVER_LATER
507 * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
508 * SEC_ERROR_OCSP_UNAUTHORIZED_RESPONSE
509 * SEC_ERROR_OCSP_UNKNOWN_CERT
510 * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
511 * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE
512 *
513 * SEC_ERROR_BAD_SIGNATURE
514 * SEC_ERROR_CERT_BAD_ACCESS_LOCATION
515 * SEC_ERROR_INVALID_TIME
516 * SEC_ERROR_REVOKED_CERTIFICATE
517 * SEC_ERROR_UNKNOWN_ISSUER
518 * SEC_ERROR_UNKNOWN_SIGNER
519 *
520 * Other errors are any of the many possible failures in cert verification
521 * (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
522 * verifying the signer's cert, or low-level problems (error allocating
523 * memory, error performing ASN.1 decoding, etc.).
524 */
525 extern SECStatus
526 CERT_CheckOCSPStatus(CERTCertDBHandle *handle, CERTCertificate *cert,
527 PRTime time, void *pwArg);
528
529 /*
530 * FUNCTION: CERT_CacheOCSPResponseFromSideChannel
531 * First, this function checks the OCSP cache to see if a good response
532 * for the given certificate already exists. If it does, then the function
533 * returns successfully.
534 *
535 * If not, then it validates that the given OCSP response is a valid,
536 * good response for the given certificate and inserts it into the
537 * cache.
538 *
539 * This function is intended for use when OCSP responses are provided via a
540 * side-channel, i.e. TLS OCSP stapling (a.k.a. the status_request extension).
541 *
542 * INPUTS:
543 * CERTCertDBHandle *handle
544 * certificate DB of the cert that is being checked
545 * CERTCertificate *cert
546 * the certificate being checked
547 * PRTime time
548 * time for which status is to be determined
549 * SECItem *encodedResponse
550 * the DER encoded bytes of the OCSP response
551 * void *pwArg
552 * argument for password prompting, if needed
553 * RETURN:
554 * SECSuccess if the cert was found in the cache, or if the OCSP response was
555 * found to be valid and inserted into the cache. SECFailure otherwise.
556 */
557 extern SECStatus
558 CERT_CacheOCSPResponseFromSideChannel(CERTCertDBHandle *handle,
559 CERTCertificate *cert,
560 PRTime time,
561 const SECItem *encodedResponse,
562 void *pwArg);
563
564 /*
565 * FUNCTION: CERT_GetOCSPStatusForCertID
566 * Returns the OCSP status contained in the passed in parameter response
567 * that corresponds to the certID passed in.
568 * INPUTS:
569 * CERTCertDBHandle *handle
570 * certificate DB of the cert that is being checked
571 * CERTOCSPResponse *response
572 * the OCSP response we want to retrieve status from.
573 * CERTOCSPCertID *certID
574 * the ID we want to look for from the response.
575 * CERTCertificate *signerCert
576 * the certificate that was used to sign the OCSP response.
577 * must be obtained via a call to CERT_VerifyOCSPResponseSignature.
578 * PRTime time
579 * The time at which we're checking the status for.
580 * RETURN:
581 * Return values are the same as those for CERT_CheckOCSPStatus
582 */
583 extern SECStatus
584 CERT_GetOCSPStatusForCertID(CERTCertDBHandle *handle,
585 CERTOCSPResponse *response,
586 CERTOCSPCertID *certID,
587 CERTCertificate *signerCert,
588 PRTime time);
589
590 /*
591 * FUNCTION CERT_GetOCSPResponseStatus
592 * Returns the response status for the response passed.
593 * INPUTS:
594 * CERTOCSPResponse *response
595 * The response to query for status
596 * RETURN:
597 * Returns SECSuccess if the response has a successful status value.
598 * Otherwise it returns SECFailure and sets one of the following error
599 * codes via PORT_SetError
600 * SEC_ERROR_OCSP_MALFORMED_REQUEST
601 * SEC_ERROR_OCSP_SERVER_ERROR
602 * SEC_ERROR_OCSP_TRY_SERVER_LATER
603 * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
604 * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
605 * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
606 */
607 extern SECStatus
608 CERT_GetOCSPResponseStatus(CERTOCSPResponse *response);
609
610 /*
611 * FUNCTION CERT_CreateOCSPCertID
612 * Returns the OCSP certID for the certificate passed in.
613 * INPUTS:
614 * CERTCertificate *cert
615 * The certificate for which to create the certID for.
616 * PRTime time
617 * The time at which the id is requested for. This is used
618 * to determine the appropriate issuer for the cert since
619 * the issuing CA may be an older expired certificate.
620 * RETURN:
621 * A new copy of a CERTOCSPCertID*. The memory for this certID
622 * should be freed by calling CERT_DestroyOCSPCertID when the
623 * certID is no longer necessary.
624 */
625 extern CERTOCSPCertID*
626 CERT_CreateOCSPCertID(CERTCertificate *cert, PRTime time);
627
628 /*
629 * FUNCTION: CERT_DestroyOCSPCertID
630 * Frees the memory associated with the certID passed in.
631 * INPUTS:
632 * CERTOCSPCertID* certID
633 * The certID that the caller no longer needs and wants to
634 * free the associated memory.
635 * RETURN:
636 * SECSuccess if freeing the memory was successful. Returns
637 * SECFailure if the memory passed in was not allocated with
638 * a call to CERT_CreateOCSPCertID.
639 */
640 extern SECStatus
641 CERT_DestroyOCSPCertID(CERTOCSPCertID* certID);
642
643
644 extern CERTOCSPSingleResponse*
645 CERT_CreateOCSPSingleResponseGood(PLArenaPool *arena,
646 CERTOCSPCertID *id,
647 PRTime thisUpdate,
648 const PRTime *nextUpdate);
649
650 extern CERTOCSPSingleResponse*
651 CERT_CreateOCSPSingleResponseUnknown(PLArenaPool *arena,
652 CERTOCSPCertID *id,
653 PRTime thisUpdate,
654 const PRTime *nextUpdate);
655
656 extern CERTOCSPSingleResponse*
657 CERT_CreateOCSPSingleResponseRevoked(
658 PLArenaPool *arena,
659 CERTOCSPCertID *id,
660 PRTime thisUpdate,
661 const PRTime *nextUpdate,
662 PRTime revocationTime,
663 const CERTCRLEntryReasonCode* revocationReason);
664
665 extern SECItem*
666 CERT_CreateEncodedOCSPSuccessResponse(
667 PLArenaPool *arena,
668 CERTCertificate *responderCert,
669 CERTOCSPResponderIDType responderIDType,
670 PRTime producedAt,
671 CERTOCSPSingleResponse **responses,
672 void *wincx);
673
674 /*
675 * FUNCTION: CERT_CreateEncodedOCSPErrorResponse
676 * Creates an encoded OCSP response with an error response status.
677 * INPUTS:
678 * PLArenaPool *arena
679 * The return value is allocated from here.
680 * If a NULL is passed in, allocation is done from the heap instead.
681 * int error
682 * An NSS error code indicating an error response status. The error
683 * code is mapped to an OCSP response status as follows:
684 * SEC_ERROR_OCSP_MALFORMED_REQUEST -> malformedRequest
685 * SEC_ERROR_OCSP_SERVER_ERROR -> internalError
686 * SEC_ERROR_OCSP_TRY_SERVER_LATER -> tryLater
687 * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG -> sigRequired
688 * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST -> unauthorized
689 * where the OCSP response status is an enumerated type defined in
690 * RFC 2560:
691 * OCSPResponseStatus ::= ENUMERATED {
692 * successful (0), --Response has valid confirmations
693 * malformedRequest (1), --Illegal confirmation request
694 * internalError (2), --Internal error in issuer
695 * tryLater (3), --Try again later
696 * --(4) is not used
697 * sigRequired (5), --Must sign the request
698 * unauthorized (6) --Request unauthorized
699 * }
700 * RETURN:
701 * Returns a pointer to the SECItem holding the response.
702 * On error, returns null with error set describing the reason:
703 * SEC_ERROR_INVALID_ARGS
704 * Other errors are low-level problems (no memory, bad database, etc.).
705 */
706 extern SECItem*
707 CERT_CreateEncodedOCSPErrorResponse(PLArenaPool *arena, int error);
708
709 /* Sends an OCSP request using the HTTP POST method to the location addressed
710 * by the URL in |location| parameter. The request body will be
711 * |encodedRequest|, which must be a valid encoded OCSP request. On success,
712 * the server's response is returned and the caller must free it using
713 * SECITEM_FreeItem. On failure, NULL is returned. No parsing or validation of
714 * the HTTP response is done.
715 *
716 * If a default HTTP client has been registered with
717 * SEC_RegisterDefaultHttpClient then that client is used. Otherwise, an
718 * internal HTTP client is used.
719 */
720 SECItem* CERT_PostOCSPRequest(PLArenaPool *arena, const char *location,
721 const SECItem *encodedRequest);
722
723 /************************************************************************/
724 SEC_END_PROTOS
725
726 #endif /* _OCSP_H_ */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial