Back to index

lightning-sunbird  0.9+nobinonly
ocsp.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * Interface to the OCSP implementation.
00039  *
00040  * $Id: ocsp.h,v 1.6.28.2 2007/04/25 01:05:06 kaie%kuix.de Exp $
00041  */
00042 
00043 #ifndef _OCSP_H_
00044 #define _OCSP_H_
00045 
00046 
00047 #include "plarena.h"
00048 #include "seccomon.h"
00049 #include "secoidt.h"
00050 #include "keyt.h"
00051 #include "certt.h"
00052 #include "ocspt.h"
00053 
00054 
00055 /************************************************************************/
00056 SEC_BEGIN_PROTOS
00057 
00058 /*
00059  * This function registers the HttpClient with whose functions the
00060  * HttpClientFcn structure have been populated as the default Http
00061  * client.
00062  *
00063  * The function table must be a global object.
00064  * The caller must ensure that NSS will be able to call
00065  * the registered functions for the lifetime of the process.
00066  */
00067 extern SECStatus
00068 SEC_RegisterDefaultHttpClient(const SEC_HttpClientFcn *fcnTable);
00069 
00070 /*
00071  * Sets parameters that control NSS' internal OCSP cache.
00072  * maxCacheEntries, special varlues are:
00073  *   -1 disable cache
00074  *   0 unlimited cache entries
00075  * minimumSecondsToNextFetchAttempt:
00076  *   whenever an OCSP request was attempted or completed over the network,
00077  *   wait at least this number of seconds before trying to fetch again.
00078  * maximumSecondsToNextFetchAttempt:
00079  *   this is the maximum age of a cached response we allow, until we try
00080  *   to fetch an updated response, even if the OCSP responder expects
00081  *   that newer information update will not be available yet.
00082  */
00083 extern SECStatus
00084 CERT_OCSPCacheSettings(PRInt32 maxCacheEntries,
00085                        PRUint32 minimumSecondsToNextFetchAttempt,
00086                        PRUint32 maximumSecondsToNextFetchAttempt);
00087 
00088 /*
00089  * Set the desired behaviour on OCSP failures.
00090  * See definition of ocspFailureMode for allowed choices.
00091  */
00092 extern SECStatus
00093 CERT_SetOCSPFailureMode(SEC_OcspFailureMode ocspFailureMode);
00094 
00095 /*
00096  * Removes all items currently stored in the OCSP cache.
00097  */
00098 extern SECStatus
00099 CERT_ClearOCSPCache(void);
00100 
00101 /*
00102  * FUNCTION: CERT_EnableOCSPChecking
00103  *   Turns on OCSP checking for the given certificate database.
00104  * INPUTS:
00105  *   CERTCertDBHandle *handle
00106  *     Certificate database for which OCSP checking will be enabled.
00107  * RETURN:
00108  *   Returns SECFailure if an error occurred (likely only problem
00109  *   allocating memory); SECSuccess otherwise.
00110  */
00111 extern SECStatus
00112 CERT_EnableOCSPChecking(CERTCertDBHandle *handle);
00113 
00114 /*
00115  * FUNCTION: CERT_DisableOCSPChecking
00116  *   Turns off OCSP checking for the given certificate database.
00117  *   This routine disables OCSP checking.  Though it will return
00118  *   SECFailure if OCSP checking is not enabled, it is "safe" to
00119  *   call it that way and just ignore the return value, if it is
00120  *   easier to just call it than to "remember" whether it is enabled.
00121  * INPUTS:
00122  *   CERTCertDBHandle *handle
00123  *     Certificate database for which OCSP checking will be disabled.
00124  * RETURN:
00125  *   Returns SECFailure if an error occurred (usually means that OCSP
00126  *   checking was not enabled or status contexts were not initialized --
00127  *   error set will be SEC_ERROR_OCSP_NOT_ENABLED); SECSuccess otherwise.
00128  */
00129 extern SECStatus
00130 CERT_DisableOCSPChecking(CERTCertDBHandle *handle);
00131 
00132 /*
00133  * FUNCTION: CERT_SetOCSPDefaultResponder
00134  *   Specify the location and cert of the default responder.
00135  *   If OCSP checking is already enabled *and* use of a default responder
00136  *   is also already enabled, all OCSP checking from now on will go directly
00137  *   to the specified responder.  If OCSP checking is not enabled, or if
00138  *   it is but use of a default responder is not enabled, the information
00139  *   will be recorded and take effect whenever both are enabled.
00140  * INPUTS:
00141  *   CERTCertDBHandle *handle
00142  *     Cert database on which OCSP checking should use the default responder.
00143  *   char *url
00144  *     The location of the default responder (e.g. "http://foo.com:80/ocsp")
00145  *     Note that the location will not be tested until the first attempt
00146  *     to send a request there.
00147  *   char *name
00148  *     The nickname of the cert to trust (expected) to sign the OCSP responses.
00149  *     If the corresponding cert cannot be found, SECFailure is returned.
00150  * RETURN:
00151  *   Returns SECFailure if an error occurred; SECSuccess otherwise.
00152  *   The most likely error is that the cert for "name" could not be found
00153  *   (probably SEC_ERROR_UNKNOWN_CERT).  Other errors are low-level (no memory,
00154  *   bad database, etc.).
00155  */
00156 extern SECStatus
00157 CERT_SetOCSPDefaultResponder(CERTCertDBHandle *handle,
00158                           const char *url, const char *name);
00159 
00160 /*
00161  * FUNCTION: CERT_EnableOCSPDefaultResponder
00162  *   Turns on use of a default responder when OCSP checking.
00163  *   If OCSP checking is already enabled, this will make subsequent checks
00164  *   go directly to the default responder.  (The location of the responder
00165  *   and the nickname of the responder cert must already be specified.)
00166  *   If OCSP checking is not enabled, this will be recorded and take effect
00167  *   whenever it is enabled.
00168  * INPUTS:
00169  *   CERTCertDBHandle *handle
00170  *     Cert database on which OCSP checking should use the default responder.
00171  * RETURN:
00172  *   Returns SECFailure if an error occurred; SECSuccess otherwise.
00173  *   No errors are especially likely unless the caller did not previously
00174  *   perform a successful call to SetOCSPDefaultResponder (in which case
00175  *   the error set will be SEC_ERROR_OCSP_NO_DEFAULT_RESPONDER).
00176  */
00177 extern SECStatus
00178 CERT_EnableOCSPDefaultResponder(CERTCertDBHandle *handle);
00179 
00180 /*
00181  * FUNCTION: CERT_DisableOCSPDefaultResponder
00182  *   Turns off use of a default responder when OCSP checking.
00183  *   (Does nothing if use of a default responder is not enabled.)
00184  * INPUTS:
00185  *   CERTCertDBHandle *handle
00186  *     Cert database on which OCSP checking should stop using a default
00187  *     responder.
00188  * RETURN:
00189  *   Returns SECFailure if an error occurred; SECSuccess otherwise.
00190  *   Errors very unlikely (like random memory corruption...).
00191  */
00192 extern SECStatus
00193 CERT_DisableOCSPDefaultResponder(CERTCertDBHandle *handle);
00194 
00195 /*
00196  * -------------------------------------------------------
00197  * The Functions above are those expected to be used by a client
00198  * providing OCSP status checking along with every cert verification.
00199  * The functions below are for OCSP testing, debugging, or clients
00200  * or servers performing more specialized OCSP tasks.
00201  * -------------------------------------------------------
00202  */
00203 
00204 /*
00205  * FUNCTION: CERT_CreateOCSPRequest
00206  *   Creates a CERTOCSPRequest, requesting the status of the certs in 
00207  *   the given list.
00208  * INPUTS:
00209  *   CERTCertList *certList
00210  *     A list of certs for which status will be requested.
00211  *     Note that all of these certificates should have the same issuer,
00212  *     or it's expected the response will be signed by a trusted responder.
00213  *     If the certs need to be broken up into multiple requests, that
00214  *     must be handled by the caller (and thus by having multiple calls
00215  *     to this routine), who knows about where the request(s) are being
00216  *     sent and whether there are any trusted responders in place.
00217  *   int64 time
00218  *     Indicates the time for which the certificate status is to be 
00219  *     determined -- this may be used in the search for the cert's issuer
00220  *     but has no effect on the request itself.
00221  *   PRBool addServiceLocator
00222  *     If true, the Service Locator extension should be added to the
00223  *     single request(s) for each cert.
00224  *   CERTCertificate *signerCert
00225  *     If non-NULL, means sign the request using this cert.  Otherwise,
00226  *     do not sign.
00227  *     XXX note that request signing is not yet supported; see comment in code
00228  * RETURN:
00229  *   A pointer to a CERTOCSPRequest structure containing an OCSP request
00230  *   for the cert list.  On error, null is returned, with an error set
00231  *   indicating the reason.  This is likely SEC_ERROR_UNKNOWN_ISSUER.
00232  *   (The issuer is needed to create a request for the certificate.)
00233  *   Other errors are low-level problems (no memory, bad database, etc.).
00234  */
00235 extern CERTOCSPRequest *
00236 CERT_CreateOCSPRequest(CERTCertList *certList, int64 time, 
00237                      PRBool addServiceLocator,
00238                      CERTCertificate *signerCert);
00239 
00240 /*
00241  * FUNCTION: CERT_AddOCSPAcceptableResponses
00242  *   Add the AcceptableResponses extension to an OCSP Request.
00243  * INPUTS:
00244  *   CERTOCSPRequest *request
00245  *     The request to which the extension should be added.
00246  *   SECOidTag responseType0, ...
00247  *     A list (of one or more) of SECOidTag -- each of the response types
00248  *     to be added.  The last OID *must* be SEC_OID_PKIX_OCSP_BASIC_RESPONSE.
00249  *     (This marks the end of the list, and it must be specified because a
00250  *     client conforming to the OCSP standard is required to handle the basic
00251  *     response type.)  The OIDs are not checked in any way.
00252  * RETURN:
00253  *   SECSuccess if the extension is added; SECFailure if anything goes wrong.
00254  *   All errors are internal or low-level problems (e.g. no memory).
00255  */
00256 extern SECStatus
00257 CERT_AddOCSPAcceptableResponses(CERTOCSPRequest *request,
00258                             SECOidTag responseType0, ...);
00259 
00260 /* 
00261  * FUNCTION: CERT_EncodeOCSPRequest
00262  *   DER encodes an OCSP Request, possibly adding a signature as well.
00263  *   XXX Signing is not yet supported, however; see comments in code.
00264  * INPUTS: 
00265  *   PRArenaPool *arena
00266  *     The return value is allocated from here.
00267  *     If a NULL is passed in, allocation is done from the heap instead.
00268  *   CERTOCSPRequest *request
00269  *     The request to be encoded.
00270  *   void *pwArg
00271  *     Pointer to argument for password prompting, if needed.  (Definitely
00272  *     not needed if not signing.)
00273  * RETURN:
00274  *   Returns a NULL on error and a pointer to the SECItem with the
00275  *   encoded value otherwise.  Any error is likely to be low-level
00276  *   (e.g. no memory).
00277  */
00278 extern SECItem *
00279 CERT_EncodeOCSPRequest(PRArenaPool *arena, CERTOCSPRequest *request, 
00280                      void *pwArg);
00281 
00282 /*
00283  * FUNCTION: CERT_DecodeOCSPRequest
00284  *   Decode a DER encoded OCSP Request.
00285  * INPUTS:
00286  *   SECItem *src
00287  *     Pointer to a SECItem holding DER encoded OCSP Request.
00288  * RETURN:
00289  *   Returns a pointer to a CERTOCSPRequest containing the decoded request.
00290  *   On error, returns NULL.  Most likely error is trouble decoding
00291  *   (SEC_ERROR_OCSP_MALFORMED_REQUEST), or low-level problem (no memory).
00292  */
00293 extern CERTOCSPRequest *
00294 CERT_DecodeOCSPRequest(SECItem *src);
00295 
00296 /*
00297  * FUNCTION: CERT_DestroyOCSPRequest
00298  *   Frees an OCSP Request structure.
00299  * INPUTS:
00300  *   CERTOCSPRequest *request
00301  *     Pointer to CERTOCSPRequest to be freed.
00302  * RETURN:
00303  *   No return value; no errors.
00304  */
00305 extern void
00306 CERT_DestroyOCSPRequest(CERTOCSPRequest *request);
00307 
00308 /*
00309  * FUNCTION: CERT_DecodeOCSPResponse
00310  *   Decode a DER encoded OCSP Response.
00311  * INPUTS:
00312  *   SECItem *src
00313  *     Pointer to a SECItem holding DER encoded OCSP Response.
00314  * RETURN:
00315  *   Returns a pointer to a CERTOCSPResponse (the decoded OCSP Response);
00316  *   the caller is responsible for destroying it.  Or NULL if error (either
00317  *   response could not be decoded (SEC_ERROR_OCSP_MALFORMED_RESPONSE),
00318  *   it was of an unexpected type (SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE),
00319  *   or a low-level or internal error occurred).
00320  */
00321 extern CERTOCSPResponse *
00322 CERT_DecodeOCSPResponse(SECItem *src);
00323 
00324 /*
00325  * FUNCTION: CERT_DestroyOCSPResponse
00326  *   Frees an OCSP Response structure.
00327  * INPUTS:
00328  *   CERTOCSPResponse *request
00329  *     Pointer to CERTOCSPResponse to be freed.
00330  * RETURN:
00331  *   No return value; no errors.
00332  */
00333 extern void
00334 CERT_DestroyOCSPResponse(CERTOCSPResponse *response);
00335 
00336 /*
00337  * FUNCTION: CERT_GetEncodedOCSPResponse
00338  *   Creates and sends a request to an OCSP responder, then reads and
00339  *   returns the (encoded) response.
00340  * INPUTS:
00341  *   PRArenaPool *arena
00342  *     Pointer to arena from which return value will be allocated.
00343  *     If NULL, result will be allocated from the heap (and thus should
00344  *     be freed via SECITEM_FreeItem).
00345  *   CERTCertList *certList
00346  *     A list of certs for which status will be requested.
00347  *     Note that all of these certificates should have the same issuer,
00348  *     or it's expected the response will be signed by a trusted responder.
00349  *     If the certs need to be broken up into multiple requests, that
00350  *     must be handled by the caller (and thus by having multiple calls
00351  *     to this routine), who knows about where the request(s) are being
00352  *     sent and whether there are any trusted responders in place.
00353  *   char *location
00354  *     The location of the OCSP responder (a URL).
00355  *   int64 time
00356  *     Indicates the time for which the certificate status is to be 
00357  *     determined -- this may be used in the search for the cert's issuer
00358  *     but has no other bearing on the operation.
00359  *   PRBool addServiceLocator
00360  *     If true, the Service Locator extension should be added to the
00361  *     single request(s) for each cert.
00362  *   CERTCertificate *signerCert
00363  *     If non-NULL, means sign the request using this cert.  Otherwise,
00364  *     do not sign.
00365  *   void *pwArg
00366  *     Pointer to argument for password prompting, if needed.  (Definitely
00367  *     not needed if not signing.)
00368  * OUTPUTS:
00369  *   CERTOCSPRequest **pRequest
00370  *     Pointer in which to store the OCSP request created for the given
00371  *     list of certificates.  It is only filled in if the entire operation
00372  *     is successful and the pointer is not null -- and in that case the
00373  *     caller is then reponsible for destroying it.
00374  * RETURN:
00375  *   Returns a pointer to the SECItem holding the response.
00376  *   On error, returns null with error set describing the reason:
00377  *     SEC_ERROR_UNKNOWN_ISSUER
00378  *     SEC_ERROR_CERT_BAD_ACCESS_LOCATION
00379  *     SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
00380  *   Other errors are low-level problems (no memory, bad database, etc.).
00381  */
00382 extern SECItem *
00383 CERT_GetEncodedOCSPResponse(PRArenaPool *arena, CERTCertList *certList,
00384                          char *location, int64 time,
00385                          PRBool addServiceLocator,
00386                          CERTCertificate *signerCert, void *pwArg,
00387                          CERTOCSPRequest **pRequest);
00388 
00389 /*
00390  * FUNCTION: CERT_VerifyOCSPResponseSignature
00391  *   Check the signature on an OCSP Response.  Will also perform a
00392  *   verification of the signer's certificate.  Note, however, that a
00393  *   successful verification does not make any statement about the
00394  *   signer's *authority* to provide status for the certificate(s),
00395  *   that must be checked individually for each certificate.
00396  * INPUTS:
00397  *   CERTOCSPResponse *response
00398  *     Pointer to response structure with signature to be checked.
00399  *   CERTCertDBHandle *handle
00400  *     Pointer to CERTCertDBHandle for certificate DB to use for verification.
00401  *   void *pwArg
00402  *     Pointer to argument for password prompting, if needed.
00403  *   CERTCertificate *issuerCert
00404  *     Issuer of the certificate that generated the OCSP request.
00405  * OUTPUTS:
00406  *   CERTCertificate **pSignerCert
00407  *     Pointer in which to store signer's certificate; only filled-in if
00408  *     non-null.
00409  * RETURN:
00410  *   Returns SECSuccess when signature is valid, anything else means invalid.
00411  *   Possible errors set:
00412  *     SEC_ERROR_OCSP_MALFORMED_RESPONSE - unknown type of ResponderID
00413  *     SEC_ERROR_INVALID_TIME - bad format of "ProducedAt" time
00414  *     SEC_ERROR_UNKNOWN_SIGNER - signer's cert could not be found
00415  *     SEC_ERROR_BAD_SIGNATURE - the signature did not verify
00416  *   Other errors are any of the many possible failures in cert verification
00417  *   (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
00418  *   verifying the signer's cert, or low-level problems (no memory, etc.)
00419  */
00420 extern SECStatus
00421 CERT_VerifyOCSPResponseSignature(CERTOCSPResponse *response,   
00422                              CERTCertDBHandle *handle, void *pwArg,
00423                              CERTCertificate **pSignerCert,
00424                              CERTCertificate *issuerCert);
00425 
00426 /*
00427  * FUNCTION: CERT_GetOCSPAuthorityInfoAccessLocation
00428  *   Get the value of the URI of the OCSP responder for the given cert.
00429  *   This is found in the (optional) Authority Information Access extension
00430  *   in the cert.
00431  * INPUTS:
00432  *   CERTCertificate *cert
00433  *     The certificate being examined.
00434  * RETURN:
00435  *   char *
00436  *     A copy of the URI for the OCSP method, if found.  If either the
00437  *     extension is not present or it does not contain an entry for OCSP,
00438  *     SEC_ERROR_EXTENSION_NOT_FOUND will be set and a NULL returned.
00439  *     Any other error will also result in a NULL being returned.
00440  *     
00441  *     This result should be freed (via PORT_Free) when no longer in use.
00442  */
00443 extern char *
00444 CERT_GetOCSPAuthorityInfoAccessLocation(CERTCertificate *cert);
00445 
00446 /*
00447  * FUNCTION: CERT_CheckOCSPStatus
00448  *   Checks the status of a certificate via OCSP.  Will only check status for
00449  *   a certificate that has an AIA (Authority Information Access) extension
00450  *   for OCSP *or* when a "default responder" is specified and enabled.
00451  *   (If no AIA extension for OCSP and no default responder in place, the
00452  *   cert is considered to have a good status and SECSuccess is returned.)
00453  * INPUTS:
00454  *   CERTCertDBHandle *handle
00455  *     certificate DB of the cert that is being checked
00456  *   CERTCertificate *cert
00457  *     the certificate being checked
00458  *   XXX in the long term also need a boolean parameter that specifies
00459  *     whether to check the cert chain, as well; for now we check only
00460  *     the leaf (the specified certificate)
00461  *   int64 time
00462  *     time for which status is to be determined
00463  *   void *pwArg
00464  *     argument for password prompting, if needed
00465  * RETURN:
00466  *   Returns SECSuccess if an approved OCSP responder "knows" the cert
00467  *   *and* returns a non-revoked status for it; SECFailure otherwise,
00468  *   with an error set describing the reason:
00469  *
00470  *     SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
00471  *     SEC_ERROR_OCSP_FUTURE_RESPONSE
00472  *     SEC_ERROR_OCSP_MALFORMED_REQUEST
00473  *     SEC_ERROR_OCSP_MALFORMED_RESPONSE
00474  *     SEC_ERROR_OCSP_OLD_RESPONSE
00475  *     SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
00476  *     SEC_ERROR_OCSP_SERVER_ERROR
00477  *     SEC_ERROR_OCSP_TRY_SERVER_LATER
00478  *     SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
00479  *     SEC_ERROR_OCSP_UNAUTHORIZED_RESPONSE
00480  *     SEC_ERROR_OCSP_UNKNOWN_CERT
00481  *     SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
00482  *     SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE
00483  *
00484  *     SEC_ERROR_BAD_SIGNATURE
00485  *     SEC_ERROR_CERT_BAD_ACCESS_LOCATION
00486  *     SEC_ERROR_INVALID_TIME
00487  *     SEC_ERROR_REVOKED_CERTIFICATE
00488  *     SEC_ERROR_UNKNOWN_ISSUER
00489  *     SEC_ERROR_UNKNOWN_SIGNER
00490  *
00491  *   Other errors are any of the many possible failures in cert verification
00492  *   (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
00493  *   verifying the signer's cert, or low-level problems (error allocating
00494  *   memory, error performing ASN.1 decoding, etc.).
00495  */    
00496 extern SECStatus 
00497 CERT_CheckOCSPStatus(CERTCertDBHandle *handle, CERTCertificate *cert,
00498                    int64 time, void *pwArg);
00499 /*
00500  * FUNCTION: CERT_GetOCSPStatusForCertID
00501  *  Returns the OCSP status contained in the passed in paramter response
00502  *  that corresponds to the certID passed in.
00503  * INPUTS:
00504  *  CERTCertDBHandle *handle
00505  *    certificate DB of the cert that is being checked
00506  *  CERTOCSPResponse *response
00507  *    the OCSP response we want to retrieve status from.
00508  *  CERTOCSPCertID *certID
00509  *    the ID we want to look for from the response.
00510  *  CERTCertificate *signerCert
00511  *    the certificate that was used to sign the OCSP response.
00512  *    must be obtained via a call to CERT_VerifyOCSPResponseSignature.
00513  *  int64 time
00514  *    The time at which we're checking the status for.
00515  *  RETURN:
00516  *    Return values are the same as those for CERT_CheckOCSPStatus
00517  */
00518 extern SECStatus
00519 CERT_GetOCSPStatusForCertID(CERTCertDBHandle *handle, 
00520                          CERTOCSPResponse *response,
00521                          CERTOCSPCertID   *certID,
00522                          CERTCertificate  *signerCert,
00523                             int64             time);
00524 
00525 /*
00526  * FUNCTION CERT_GetOCSPResponseStatus
00527  *   Returns the response status for the response passed.
00528  * INPUTS:
00529  *   CERTOCSPResponse *response
00530  *     The response to query for status
00531  *  RETURN:
00532  *    Returns SECSuccess if the response has a successful status value.
00533  *    Otherwise it returns SECFailure and sets one of the following error
00534  *    codes via PORT_SetError
00535  *        SEC_ERROR_OCSP_MALFORMED_REQUEST
00536  *        SEC_ERROR_OCSP_SERVER_ERROR
00537  *        SEC_ERROR_OCSP_TRY_SERVER_LATER
00538  *        SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
00539  *        SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
00540  *        SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
00541  */
00542 extern SECStatus
00543 CERT_GetOCSPResponseStatus(CERTOCSPResponse *response);
00544 
00545 /*
00546  * FUNCTION CERT_CreateOCSPCertID
00547  *  Returns the OCSP certID for the certificate passed in.
00548  * INPUTS:
00549  *  CERTCertificate *cert
00550  *    The certificate for which to create the certID for.
00551  *  int64 time
00552  *    The time at which the id is requested for.  This is used
00553  *    to determine the appropriate issuer for the cert since
00554  *    the issuing CA may be an older expired certificate.
00555  *  RETURN:
00556  *    A new copy of a CERTOCSPCertID*.  The memory for this certID
00557  *    should be freed by calling CERT_DestroyOCSPCertID when the 
00558  *    certID is no longer necessary.
00559  */
00560 extern CERTOCSPCertID*
00561 CERT_CreateOCSPCertID(CERTCertificate *cert, int64 time);
00562 
00563 /*
00564  * FUNCTION: CERT_DestroyOCSPCertID
00565  *  Frees the memory associated with the certID passed in.
00566  * INPUTS:
00567  *  CERTOCSPCertID* certID
00568  *    The certID that the caller no longer needs and wants to 
00569  *    free the associated memory.
00570  * RETURN:
00571  *  SECSuccess if freeing the memory was successful.  Returns
00572  *  SECFailure if the memory passed in was not allocated with
00573  *  a call to CERT_CreateOCSPCertID.
00574  */
00575 extern SECStatus
00576 CERT_DestroyOCSPCertID(CERTOCSPCertID* certID);
00577 /************************************************************************/
00578 SEC_END_PROTOS
00579 
00580 #endif /* _OCSP_H_ */