security/nss/lib/certhigh/ocsp.h

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