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