зеркало из https://github.com/mozilla/gecko-dev.git
724 строки
28 KiB
C
724 строки
28 KiB
C
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
/*
|
|
* Interface to the OCSP implementation.
|
|
*/
|
|
|
|
#ifndef _OCSP_H_
|
|
#define _OCSP_H_
|
|
|
|
#include "plarena.h"
|
|
#include "seccomon.h"
|
|
#include "secoidt.h"
|
|
#include "keyt.h"
|
|
#include "certt.h"
|
|
#include "ocspt.h"
|
|
|
|
/************************************************************************/
|
|
SEC_BEGIN_PROTOS
|
|
|
|
/*
|
|
* This function registers the HttpClient with whose functions the
|
|
* HttpClientFcn structure has been populated as the default Http
|
|
* client.
|
|
*
|
|
* The function table must be a global object.
|
|
* The caller must ensure that NSS will be able to call
|
|
* the registered functions for the lifetime of the process.
|
|
*/
|
|
extern SECStatus
|
|
SEC_RegisterDefaultHttpClient(const SEC_HttpClientFcn *fcnTable);
|
|
|
|
/*
|
|
* This function obtains the HttpClient which has been registered
|
|
* by an earlier call to SEC_RegisterDefaultHttpClient.
|
|
*/
|
|
extern const SEC_HttpClientFcn *
|
|
SEC_GetRegisteredHttpClient(void);
|
|
|
|
/*
|
|
* Sets parameters that control NSS' internal OCSP cache.
|
|
* maxCacheEntries, special varlues are:
|
|
* -1 disable cache
|
|
* 0 unlimited cache entries
|
|
* minimumSecondsToNextFetchAttempt:
|
|
* whenever an OCSP request was attempted or completed over the network,
|
|
* wait at least this number of seconds before trying to fetch again.
|
|
* maximumSecondsToNextFetchAttempt:
|
|
* this is the maximum age of a cached response we allow, until we try
|
|
* to fetch an updated response, even if the OCSP responder expects
|
|
* that newer information update will not be available yet.
|
|
*/
|
|
extern SECStatus
|
|
CERT_OCSPCacheSettings(PRInt32 maxCacheEntries,
|
|
PRUint32 minimumSecondsToNextFetchAttempt,
|
|
PRUint32 maximumSecondsToNextFetchAttempt);
|
|
|
|
/*
|
|
* Set the desired behaviour on OCSP failures.
|
|
* See definition of ocspFailureMode for allowed choices.
|
|
*/
|
|
extern SECStatus
|
|
CERT_SetOCSPFailureMode(SEC_OcspFailureMode ocspFailureMode);
|
|
|
|
/*
|
|
* Configure the maximum time NSS will wait for an OCSP response.
|
|
*/
|
|
extern SECStatus
|
|
CERT_SetOCSPTimeout(PRUint32 seconds);
|
|
|
|
/*
|
|
* Removes all items currently stored in the OCSP cache.
|
|
*/
|
|
extern SECStatus
|
|
CERT_ClearOCSPCache(void);
|
|
|
|
/*
|
|
* FUNCTION: CERT_EnableOCSPChecking
|
|
* Turns on OCSP checking for the given certificate database.
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* Certificate database for which OCSP checking will be enabled.
|
|
* RETURN:
|
|
* Returns SECFailure if an error occurred (likely only problem
|
|
* allocating memory); SECSuccess otherwise.
|
|
*/
|
|
extern SECStatus
|
|
CERT_EnableOCSPChecking(CERTCertDBHandle *handle);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DisableOCSPChecking
|
|
* Turns off OCSP checking for the given certificate database.
|
|
* This routine disables OCSP checking. Though it will return
|
|
* SECFailure if OCSP checking is not enabled, it is "safe" to
|
|
* call it that way and just ignore the return value, if it is
|
|
* easier to just call it than to "remember" whether it is enabled.
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* Certificate database for which OCSP checking will be disabled.
|
|
* RETURN:
|
|
* Returns SECFailure if an error occurred (usually means that OCSP
|
|
* checking was not enabled or status contexts were not initialized --
|
|
* error set will be SEC_ERROR_OCSP_NOT_ENABLED); SECSuccess otherwise.
|
|
*/
|
|
extern SECStatus
|
|
CERT_DisableOCSPChecking(CERTCertDBHandle *handle);
|
|
|
|
/*
|
|
* FUNCTION: CERT_SetOCSPDefaultResponder
|
|
* Specify the location and cert of the default responder.
|
|
* If OCSP checking is already enabled *and* use of a default responder
|
|
* is also already enabled, all OCSP checking from now on will go directly
|
|
* to the specified responder. If OCSP checking is not enabled, or if
|
|
* it is but use of a default responder is not enabled, the information
|
|
* will be recorded and take effect whenever both are enabled.
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* Cert database on which OCSP checking should use the default responder.
|
|
* const char *url
|
|
* The location of the default responder (e.g. "http://foo.com:80/ocsp")
|
|
* Note that the location will not be tested until the first attempt
|
|
* to send a request there.
|
|
* const char *name
|
|
* The nickname of the cert to trust (expected) to sign the OCSP responses.
|
|
* If the corresponding cert cannot be found, SECFailure is returned.
|
|
* RETURN:
|
|
* Returns SECFailure if an error occurred; SECSuccess otherwise.
|
|
* The most likely error is that the cert for "name" could not be found
|
|
* (probably SEC_ERROR_UNKNOWN_CERT). Other errors are low-level (no memory,
|
|
* bad database, etc.).
|
|
*/
|
|
extern SECStatus
|
|
CERT_SetOCSPDefaultResponder(CERTCertDBHandle *handle,
|
|
const char *url, const char *name);
|
|
|
|
/*
|
|
* FUNCTION: CERT_EnableOCSPDefaultResponder
|
|
* Turns on use of a default responder when OCSP checking.
|
|
* If OCSP checking is already enabled, this will make subsequent checks
|
|
* go directly to the default responder. (The location of the responder
|
|
* and the nickname of the responder cert must already be specified.)
|
|
* If OCSP checking is not enabled, this will be recorded and take effect
|
|
* whenever it is enabled.
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* Cert database on which OCSP checking should use the default responder.
|
|
* RETURN:
|
|
* Returns SECFailure if an error occurred; SECSuccess otherwise.
|
|
* No errors are especially likely unless the caller did not previously
|
|
* perform a successful call to SetOCSPDefaultResponder (in which case
|
|
* the error set will be SEC_ERROR_OCSP_NO_DEFAULT_RESPONDER).
|
|
*/
|
|
extern SECStatus
|
|
CERT_EnableOCSPDefaultResponder(CERTCertDBHandle *handle);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DisableOCSPDefaultResponder
|
|
* Turns off use of a default responder when OCSP checking.
|
|
* (Does nothing if use of a default responder is not enabled.)
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* Cert database on which OCSP checking should stop using a default
|
|
* responder.
|
|
* RETURN:
|
|
* Returns SECFailure if an error occurred; SECSuccess otherwise.
|
|
* Errors very unlikely (like random memory corruption...).
|
|
*/
|
|
extern SECStatus
|
|
CERT_DisableOCSPDefaultResponder(CERTCertDBHandle *handle);
|
|
|
|
/* If forcePost is set, OCSP requests will only be sent using the HTTP POST
|
|
* method. When forcePost is not set, OCSP requests will be sent using the
|
|
* HTTP GET method, with a fallback to POST when we fail to receive a response
|
|
* and/or when we receive an uncacheable response like "Unknown."
|
|
*
|
|
* The default is to use GET and fallback to POST.
|
|
*/
|
|
extern SECStatus CERT_ForcePostMethodForOCSP(PRBool forcePost);
|
|
|
|
/*
|
|
* -------------------------------------------------------
|
|
* The Functions above are those expected to be used by a client
|
|
* providing OCSP status checking along with every cert verification.
|
|
* The functions below are for OCSP testing, debugging, or clients
|
|
* or servers performing more specialized OCSP tasks.
|
|
* -------------------------------------------------------
|
|
*/
|
|
|
|
/*
|
|
* FUNCTION: CERT_CreateOCSPRequest
|
|
* Creates a CERTOCSPRequest, requesting the status of the certs in
|
|
* the given list.
|
|
* INPUTS:
|
|
* CERTCertList *certList
|
|
* A list of certs for which status will be requested.
|
|
* Note that all of these certificates should have the same issuer,
|
|
* or it's expected the response will be signed by a trusted responder.
|
|
* If the certs need to be broken up into multiple requests, that
|
|
* must be handled by the caller (and thus by having multiple calls
|
|
* to this routine), who knows about where the request(s) are being
|
|
* sent and whether there are any trusted responders in place.
|
|
* PRTime time
|
|
* Indicates the time for which the certificate status is to be
|
|
* determined -- this may be used in the search for the cert's issuer
|
|
* but has no effect on the request itself.
|
|
* PRBool addServiceLocator
|
|
* If true, the Service Locator extension should be added to the
|
|
* single request(s) for each cert.
|
|
* CERTCertificate *signerCert
|
|
* If non-NULL, means sign the request using this cert. Otherwise,
|
|
* do not sign.
|
|
* XXX note that request signing is not yet supported; see comment in code
|
|
* RETURN:
|
|
* A pointer to a CERTOCSPRequest structure containing an OCSP request
|
|
* for the cert list. On error, null is returned, with an error set
|
|
* indicating the reason. This is likely SEC_ERROR_UNKNOWN_ISSUER.
|
|
* (The issuer is needed to create a request for the certificate.)
|
|
* Other errors are low-level problems (no memory, bad database, etc.).
|
|
*/
|
|
extern CERTOCSPRequest *
|
|
CERT_CreateOCSPRequest(CERTCertList *certList, PRTime time,
|
|
PRBool addServiceLocator,
|
|
CERTCertificate *signerCert);
|
|
|
|
/*
|
|
* FUNCTION: CERT_AddOCSPAcceptableResponses
|
|
* Add the AcceptableResponses extension to an OCSP Request.
|
|
* INPUTS:
|
|
* CERTOCSPRequest *request
|
|
* The request to which the extension should be added.
|
|
* SECOidTag responseType0, ...
|
|
* A list (of one or more) of SECOidTag -- each of the response types
|
|
* to be added. The last OID *must* be SEC_OID_PKIX_OCSP_BASIC_RESPONSE.
|
|
* (This marks the end of the list, and it must be specified because a
|
|
* client conforming to the OCSP standard is required to handle the basic
|
|
* response type.) The OIDs are not checked in any way.
|
|
* RETURN:
|
|
* SECSuccess if the extension is added; SECFailure if anything goes wrong.
|
|
* All errors are internal or low-level problems (e.g. no memory).
|
|
*/
|
|
extern SECStatus
|
|
CERT_AddOCSPAcceptableResponses(CERTOCSPRequest *request,
|
|
SECOidTag responseType0, ...);
|
|
|
|
/*
|
|
* FUNCTION: CERT_EncodeOCSPRequest
|
|
* DER encodes an OCSP Request, possibly adding a signature as well.
|
|
* XXX Signing is not yet supported, however; see comments in code.
|
|
* INPUTS:
|
|
* PLArenaPool *arena
|
|
* The return value is allocated from here.
|
|
* If a NULL is passed in, allocation is done from the heap instead.
|
|
* CERTOCSPRequest *request
|
|
* The request to be encoded.
|
|
* void *pwArg
|
|
* Pointer to argument for password prompting, if needed. (Definitely
|
|
* not needed if not signing.)
|
|
* RETURN:
|
|
* Returns a NULL on error and a pointer to the SECItem with the
|
|
* encoded value otherwise. Any error is likely to be low-level
|
|
* (e.g. no memory).
|
|
*/
|
|
extern SECItem *
|
|
CERT_EncodeOCSPRequest(PLArenaPool *arena, CERTOCSPRequest *request,
|
|
void *pwArg);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DecodeOCSPRequest
|
|
* Decode a DER encoded OCSP Request.
|
|
* INPUTS:
|
|
* SECItem *src
|
|
* Pointer to a SECItem holding DER encoded OCSP Request.
|
|
* RETURN:
|
|
* Returns a pointer to a CERTOCSPRequest containing the decoded request.
|
|
* On error, returns NULL. Most likely error is trouble decoding
|
|
* (SEC_ERROR_OCSP_MALFORMED_REQUEST), or low-level problem (no memory).
|
|
*/
|
|
extern CERTOCSPRequest *
|
|
CERT_DecodeOCSPRequest(const SECItem *src);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DestroyOCSPRequest
|
|
* Frees an OCSP Request structure.
|
|
* INPUTS:
|
|
* CERTOCSPRequest *request
|
|
* Pointer to CERTOCSPRequest to be freed.
|
|
* RETURN:
|
|
* No return value; no errors.
|
|
*/
|
|
extern void
|
|
CERT_DestroyOCSPRequest(CERTOCSPRequest *request);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DecodeOCSPResponse
|
|
* Decode a DER encoded OCSP Response.
|
|
* INPUTS:
|
|
* SECItem *src
|
|
* Pointer to a SECItem holding DER encoded OCSP Response.
|
|
* RETURN:
|
|
* Returns a pointer to a CERTOCSPResponse (the decoded OCSP Response);
|
|
* the caller is responsible for destroying it. Or NULL if error (either
|
|
* response could not be decoded (SEC_ERROR_OCSP_MALFORMED_RESPONSE),
|
|
* it was of an unexpected type (SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE),
|
|
* or a low-level or internal error occurred).
|
|
*/
|
|
extern CERTOCSPResponse *
|
|
CERT_DecodeOCSPResponse(const SECItem *src);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DestroyOCSPResponse
|
|
* Frees an OCSP Response structure.
|
|
* INPUTS:
|
|
* CERTOCSPResponse *request
|
|
* Pointer to CERTOCSPResponse to be freed.
|
|
* RETURN:
|
|
* No return value; no errors.
|
|
*/
|
|
extern void
|
|
CERT_DestroyOCSPResponse(CERTOCSPResponse *response);
|
|
|
|
/*
|
|
* FUNCTION: CERT_GetEncodedOCSPResponse
|
|
* Creates and sends a request to an OCSP responder, then reads and
|
|
* returns the (encoded) response.
|
|
* INPUTS:
|
|
* PLArenaPool *arena
|
|
* Pointer to arena from which return value will be allocated.
|
|
* If NULL, result will be allocated from the heap (and thus should
|
|
* be freed via SECITEM_FreeItem).
|
|
* CERTCertList *certList
|
|
* A list of certs for which status will be requested.
|
|
* Note that all of these certificates should have the same issuer,
|
|
* or it's expected the response will be signed by a trusted responder.
|
|
* If the certs need to be broken up into multiple requests, that
|
|
* must be handled by the caller (and thus by having multiple calls
|
|
* to this routine), who knows about where the request(s) are being
|
|
* sent and whether there are any trusted responders in place.
|
|
* const char *location
|
|
* The location of the OCSP responder (a URL).
|
|
* PRTime time
|
|
* Indicates the time for which the certificate status is to be
|
|
* determined -- this may be used in the search for the cert's issuer
|
|
* but has no other bearing on the operation.
|
|
* PRBool addServiceLocator
|
|
* If true, the Service Locator extension should be added to the
|
|
* single request(s) for each cert.
|
|
* CERTCertificate *signerCert
|
|
* If non-NULL, means sign the request using this cert. Otherwise,
|
|
* do not sign.
|
|
* void *pwArg
|
|
* Pointer to argument for password prompting, if needed. (Definitely
|
|
* not needed if not signing.)
|
|
* OUTPUTS:
|
|
* CERTOCSPRequest **pRequest
|
|
* Pointer in which to store the OCSP request created for the given
|
|
* list of certificates. It is only filled in if the entire operation
|
|
* is successful and the pointer is not null -- and in that case the
|
|
* caller is then reponsible for destroying it.
|
|
* RETURN:
|
|
* Returns a pointer to the SECItem holding the response.
|
|
* On error, returns null with error set describing the reason:
|
|
* SEC_ERROR_UNKNOWN_ISSUER
|
|
* SEC_ERROR_CERT_BAD_ACCESS_LOCATION
|
|
* SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
|
|
* Other errors are low-level problems (no memory, bad database, etc.).
|
|
*/
|
|
extern SECItem *
|
|
CERT_GetEncodedOCSPResponse(PLArenaPool *arena, CERTCertList *certList,
|
|
const char *location, PRTime time,
|
|
PRBool addServiceLocator,
|
|
CERTCertificate *signerCert, void *pwArg,
|
|
CERTOCSPRequest **pRequest);
|
|
|
|
/*
|
|
* FUNCTION: CERT_VerifyOCSPResponseSignature
|
|
* Check the signature on an OCSP Response. Will also perform a
|
|
* verification of the signer's certificate. Note, however, that a
|
|
* successful verification does not make any statement about the
|
|
* signer's *authority* to provide status for the certificate(s),
|
|
* that must be checked individually for each certificate.
|
|
* INPUTS:
|
|
* CERTOCSPResponse *response
|
|
* Pointer to response structure with signature to be checked.
|
|
* CERTCertDBHandle *handle
|
|
* Pointer to CERTCertDBHandle for certificate DB to use for verification.
|
|
* void *pwArg
|
|
* Pointer to argument for password prompting, if needed.
|
|
* CERTCertificate *issuerCert
|
|
* Issuer of the certificate that generated the OCSP request.
|
|
* OUTPUTS:
|
|
* CERTCertificate **pSignerCert
|
|
* Pointer in which to store signer's certificate; only filled-in if
|
|
* non-null.
|
|
* RETURN:
|
|
* Returns SECSuccess when signature is valid, anything else means invalid.
|
|
* Possible errors set:
|
|
* SEC_ERROR_OCSP_MALFORMED_RESPONSE - unknown type of ResponderID
|
|
* SEC_ERROR_INVALID_TIME - bad format of "ProducedAt" time
|
|
* SEC_ERROR_UNKNOWN_SIGNER - signer's cert could not be found
|
|
* SEC_ERROR_BAD_SIGNATURE - the signature did not verify
|
|
* Other errors are any of the many possible failures in cert verification
|
|
* (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
|
|
* verifying the signer's cert, or low-level problems (no memory, etc.)
|
|
*/
|
|
extern SECStatus
|
|
CERT_VerifyOCSPResponseSignature(CERTOCSPResponse *response,
|
|
CERTCertDBHandle *handle, void *pwArg,
|
|
CERTCertificate **pSignerCert,
|
|
CERTCertificate *issuerCert);
|
|
|
|
/*
|
|
* FUNCTION: CERT_GetOCSPAuthorityInfoAccessLocation
|
|
* Get the value of the URI of the OCSP responder for the given cert.
|
|
* This is found in the (optional) Authority Information Access extension
|
|
* in the cert.
|
|
* INPUTS:
|
|
* CERTCertificate *cert
|
|
* The certificate being examined.
|
|
* RETURN:
|
|
* char *
|
|
* A copy of the URI for the OCSP method, if found. If either the
|
|
* extension is not present or it does not contain an entry for OCSP,
|
|
* SEC_ERROR_EXTENSION_NOT_FOUND will be set and a NULL returned.
|
|
* Any other error will also result in a NULL being returned.
|
|
*
|
|
* This result should be freed (via PORT_Free) when no longer in use.
|
|
*/
|
|
extern char *
|
|
CERT_GetOCSPAuthorityInfoAccessLocation(const CERTCertificate *cert);
|
|
|
|
/*
|
|
* FUNCTION: CERT_RegisterAlternateOCSPAIAInfoCallBack
|
|
* This function serves two purposes.
|
|
* 1) It registers the address of a callback function that will be
|
|
* called for certs that have no OCSP AIA extension, to see if the
|
|
* callback wishes to supply an alternative URL for such an OCSP inquiry.
|
|
* 2) It outputs the previously registered function's address to the
|
|
* address supplied by the caller, unless that is NULL.
|
|
* The registered callback function returns NULL, or an allocated string
|
|
* that may be subsequently freed by calling PORT_Free().
|
|
* RETURN:
|
|
* SECSuccess or SECFailure (if the library is not yet intialized)
|
|
*/
|
|
extern SECStatus
|
|
CERT_RegisterAlternateOCSPAIAInfoCallBack(
|
|
CERT_StringFromCertFcn newCallback,
|
|
CERT_StringFromCertFcn *oldCallback);
|
|
|
|
/*
|
|
* FUNCTION: CERT_ParseURL
|
|
* Parse a URI into hostname, port, and path. The scheme in the URI must
|
|
* be "http".
|
|
* INPUTS:
|
|
* const char *url
|
|
* The URI to be parsed
|
|
* OUTPUTS:
|
|
* char **pHostname
|
|
* Pointer to store the hostname obtained from the URI.
|
|
* This result should be freed (via PORT_Free) when no longer in use.
|
|
* PRUint16 *pPort
|
|
* Pointer to store the port number obtained from the URI.
|
|
* char **pPath
|
|
* Pointer to store the path obtained from the URI.
|
|
* This result should be freed (via PORT_Free) when no longer in use.
|
|
* RETURN:
|
|
* Returns SECSuccess when parsing was successful. Returns SECFailure when
|
|
* problems were encountered.
|
|
*/
|
|
extern SECStatus
|
|
CERT_ParseURL(const char *url, char **pHostname, PRUint16 *pPort, char **pPath);
|
|
|
|
/*
|
|
* FUNCTION: CERT_CheckOCSPStatus
|
|
* Checks the status of a certificate via OCSP. Will only check status for
|
|
* a certificate that has an AIA (Authority Information Access) extension
|
|
* for OCSP *or* when a "default responder" is specified and enabled.
|
|
* (If no AIA extension for OCSP and no default responder in place, the
|
|
* cert is considered to have a good status and SECSuccess is returned.)
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* certificate DB of the cert that is being checked
|
|
* CERTCertificate *cert
|
|
* the certificate being checked
|
|
* XXX in the long term also need a boolean parameter that specifies
|
|
* whether to check the cert chain, as well; for now we check only
|
|
* the leaf (the specified certificate)
|
|
* PRTime time
|
|
* time for which status is to be determined
|
|
* void *pwArg
|
|
* argument for password prompting, if needed
|
|
* RETURN:
|
|
* Returns SECSuccess if an approved OCSP responder "knows" the cert
|
|
* *and* returns a non-revoked status for it; SECFailure otherwise,
|
|
* with an error set describing the reason:
|
|
*
|
|
* SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
|
|
* SEC_ERROR_OCSP_FUTURE_RESPONSE
|
|
* SEC_ERROR_OCSP_MALFORMED_REQUEST
|
|
* SEC_ERROR_OCSP_MALFORMED_RESPONSE
|
|
* SEC_ERROR_OCSP_OLD_RESPONSE
|
|
* SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
|
|
* SEC_ERROR_OCSP_SERVER_ERROR
|
|
* SEC_ERROR_OCSP_TRY_SERVER_LATER
|
|
* SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
|
|
* SEC_ERROR_OCSP_UNAUTHORIZED_RESPONSE
|
|
* SEC_ERROR_OCSP_UNKNOWN_CERT
|
|
* SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
|
|
* SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE
|
|
*
|
|
* SEC_ERROR_BAD_SIGNATURE
|
|
* SEC_ERROR_CERT_BAD_ACCESS_LOCATION
|
|
* SEC_ERROR_INVALID_TIME
|
|
* SEC_ERROR_REVOKED_CERTIFICATE
|
|
* SEC_ERROR_UNKNOWN_ISSUER
|
|
* SEC_ERROR_UNKNOWN_SIGNER
|
|
*
|
|
* Other errors are any of the many possible failures in cert verification
|
|
* (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
|
|
* verifying the signer's cert, or low-level problems (error allocating
|
|
* memory, error performing ASN.1 decoding, etc.).
|
|
*/
|
|
extern SECStatus
|
|
CERT_CheckOCSPStatus(CERTCertDBHandle *handle, CERTCertificate *cert,
|
|
PRTime time, void *pwArg);
|
|
|
|
/*
|
|
* FUNCTION: CERT_CacheOCSPResponseFromSideChannel
|
|
* First, this function checks the OCSP cache to see if a good response
|
|
* for the given certificate already exists. If it does, then the function
|
|
* returns successfully.
|
|
*
|
|
* If not, then it validates that the given OCSP response is a valid,
|
|
* good response for the given certificate and inserts it into the
|
|
* cache.
|
|
*
|
|
* This function is intended for use when OCSP responses are provided via a
|
|
* side-channel, i.e. TLS OCSP stapling (a.k.a. the status_request extension).
|
|
*
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* certificate DB of the cert that is being checked
|
|
* CERTCertificate *cert
|
|
* the certificate being checked
|
|
* PRTime time
|
|
* time for which status is to be determined
|
|
* SECItem *encodedResponse
|
|
* the DER encoded bytes of the OCSP response
|
|
* void *pwArg
|
|
* argument for password prompting, if needed
|
|
* RETURN:
|
|
* SECSuccess if the cert was found in the cache, or if the OCSP response was
|
|
* found to be valid and inserted into the cache. SECFailure otherwise.
|
|
*/
|
|
extern SECStatus
|
|
CERT_CacheOCSPResponseFromSideChannel(CERTCertDBHandle *handle,
|
|
CERTCertificate *cert,
|
|
PRTime time,
|
|
const SECItem *encodedResponse,
|
|
void *pwArg);
|
|
|
|
/*
|
|
* FUNCTION: CERT_GetOCSPStatusForCertID
|
|
* Returns the OCSP status contained in the passed in parameter response
|
|
* that corresponds to the certID passed in.
|
|
* INPUTS:
|
|
* CERTCertDBHandle *handle
|
|
* certificate DB of the cert that is being checked
|
|
* CERTOCSPResponse *response
|
|
* the OCSP response we want to retrieve status from.
|
|
* CERTOCSPCertID *certID
|
|
* the ID we want to look for from the response.
|
|
* CERTCertificate *signerCert
|
|
* the certificate that was used to sign the OCSP response.
|
|
* must be obtained via a call to CERT_VerifyOCSPResponseSignature.
|
|
* PRTime time
|
|
* The time at which we're checking the status for.
|
|
* RETURN:
|
|
* Return values are the same as those for CERT_CheckOCSPStatus
|
|
*/
|
|
extern SECStatus
|
|
CERT_GetOCSPStatusForCertID(CERTCertDBHandle *handle,
|
|
CERTOCSPResponse *response,
|
|
CERTOCSPCertID *certID,
|
|
CERTCertificate *signerCert,
|
|
PRTime time);
|
|
|
|
/*
|
|
* FUNCTION CERT_GetOCSPResponseStatus
|
|
* Returns the response status for the response passed.
|
|
* INPUTS:
|
|
* CERTOCSPResponse *response
|
|
* The response to query for status
|
|
* RETURN:
|
|
* Returns SECSuccess if the response has a successful status value.
|
|
* Otherwise it returns SECFailure and sets one of the following error
|
|
* codes via PORT_SetError
|
|
* SEC_ERROR_OCSP_MALFORMED_REQUEST
|
|
* SEC_ERROR_OCSP_SERVER_ERROR
|
|
* SEC_ERROR_OCSP_TRY_SERVER_LATER
|
|
* SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
|
|
* SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
|
|
* SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
|
|
*/
|
|
extern SECStatus
|
|
CERT_GetOCSPResponseStatus(CERTOCSPResponse *response);
|
|
|
|
/*
|
|
* FUNCTION CERT_CreateOCSPCertID
|
|
* Returns the OCSP certID for the certificate passed in.
|
|
* INPUTS:
|
|
* CERTCertificate *cert
|
|
* The certificate for which to create the certID for.
|
|
* PRTime time
|
|
* The time at which the id is requested for. This is used
|
|
* to determine the appropriate issuer for the cert since
|
|
* the issuing CA may be an older expired certificate.
|
|
* RETURN:
|
|
* A new copy of a CERTOCSPCertID*. The memory for this certID
|
|
* should be freed by calling CERT_DestroyOCSPCertID when the
|
|
* certID is no longer necessary.
|
|
*/
|
|
extern CERTOCSPCertID *
|
|
CERT_CreateOCSPCertID(CERTCertificate *cert, PRTime time);
|
|
|
|
/*
|
|
* FUNCTION: CERT_DestroyOCSPCertID
|
|
* Frees the memory associated with the certID passed in.
|
|
* INPUTS:
|
|
* CERTOCSPCertID* certID
|
|
* The certID that the caller no longer needs and wants to
|
|
* free the associated memory.
|
|
* RETURN:
|
|
* SECSuccess if freeing the memory was successful. Returns
|
|
* SECFailure if the memory passed in was not allocated with
|
|
* a call to CERT_CreateOCSPCertID.
|
|
*/
|
|
extern SECStatus
|
|
CERT_DestroyOCSPCertID(CERTOCSPCertID *certID);
|
|
|
|
extern CERTOCSPSingleResponse *
|
|
CERT_CreateOCSPSingleResponseGood(PLArenaPool *arena,
|
|
CERTOCSPCertID *id,
|
|
PRTime thisUpdate,
|
|
const PRTime *nextUpdate);
|
|
|
|
extern CERTOCSPSingleResponse *
|
|
CERT_CreateOCSPSingleResponseUnknown(PLArenaPool *arena,
|
|
CERTOCSPCertID *id,
|
|
PRTime thisUpdate,
|
|
const PRTime *nextUpdate);
|
|
|
|
extern CERTOCSPSingleResponse *
|
|
CERT_CreateOCSPSingleResponseRevoked(
|
|
PLArenaPool *arena,
|
|
CERTOCSPCertID *id,
|
|
PRTime thisUpdate,
|
|
const PRTime *nextUpdate,
|
|
PRTime revocationTime,
|
|
const CERTCRLEntryReasonCode *revocationReason);
|
|
|
|
extern SECItem *
|
|
CERT_CreateEncodedOCSPSuccessResponse(
|
|
PLArenaPool *arena,
|
|
CERTCertificate *responderCert,
|
|
CERTOCSPResponderIDType responderIDType,
|
|
PRTime producedAt,
|
|
CERTOCSPSingleResponse **responses,
|
|
void *wincx);
|
|
|
|
/*
|
|
* FUNCTION: CERT_CreateEncodedOCSPErrorResponse
|
|
* Creates an encoded OCSP response with an error response status.
|
|
* INPUTS:
|
|
* PLArenaPool *arena
|
|
* The return value is allocated from here.
|
|
* If a NULL is passed in, allocation is done from the heap instead.
|
|
* int error
|
|
* An NSS error code indicating an error response status. The error
|
|
* code is mapped to an OCSP response status as follows:
|
|
* SEC_ERROR_OCSP_MALFORMED_REQUEST -> malformedRequest
|
|
* SEC_ERROR_OCSP_SERVER_ERROR -> internalError
|
|
* SEC_ERROR_OCSP_TRY_SERVER_LATER -> tryLater
|
|
* SEC_ERROR_OCSP_REQUEST_NEEDS_SIG -> sigRequired
|
|
* SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST -> unauthorized
|
|
* where the OCSP response status is an enumerated type defined in
|
|
* RFC 2560:
|
|
* OCSPResponseStatus ::= ENUMERATED {
|
|
* successful (0), --Response has valid confirmations
|
|
* malformedRequest (1), --Illegal confirmation request
|
|
* internalError (2), --Internal error in issuer
|
|
* tryLater (3), --Try again later
|
|
* --(4) is not used
|
|
* sigRequired (5), --Must sign the request
|
|
* unauthorized (6) --Request unauthorized
|
|
* }
|
|
* RETURN:
|
|
* Returns a pointer to the SECItem holding the response.
|
|
* On error, returns null with error set describing the reason:
|
|
* SEC_ERROR_INVALID_ARGS
|
|
* Other errors are low-level problems (no memory, bad database, etc.).
|
|
*/
|
|
extern SECItem *
|
|
CERT_CreateEncodedOCSPErrorResponse(PLArenaPool *arena, int error);
|
|
|
|
/* Sends an OCSP request using the HTTP POST method to the location addressed
|
|
* by the URL in |location| parameter. The request body will be
|
|
* |encodedRequest|, which must be a valid encoded OCSP request. On success,
|
|
* the server's response is returned and the caller must free it using
|
|
* SECITEM_FreeItem. On failure, NULL is returned. No parsing or validation of
|
|
* the HTTP response is done.
|
|
*
|
|
* If a default HTTP client has been registered with
|
|
* SEC_RegisterDefaultHttpClient then that client is used. Otherwise, an
|
|
* internal HTTP client is used.
|
|
*/
|
|
SECItem *CERT_PostOCSPRequest(PLArenaPool *arena, const char *location,
|
|
const SECItem *encodedRequest);
|
|
|
|
/************************************************************************/
|
|
SEC_END_PROTOS
|
|
|
|
#endif /* _OCSP_H_ */
|