diff options
Diffstat (limited to 'security/nss/lib/certhigh/ocsp.h')
| -rw-r--r-- | security/nss/lib/certhigh/ocsp.h | 723 |
1 files changed, 723 insertions, 0 deletions
diff --git a/security/nss/lib/certhigh/ocsp.h b/security/nss/lib/certhigh/ocsp.h new file mode 100644 index 000000000..ac9dd6465 --- /dev/null +++ b/security/nss/lib/certhigh/ocsp.h @@ -0,0 +1,723 @@ +/* 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_ */ |