1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/certhigh/ocsp.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,726 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 + * Interface to the OCSP implementation.
1.10 + */
1.11 +
1.12 +#ifndef _OCSP_H_
1.13 +#define _OCSP_H_
1.14 +
1.15 +
1.16 +#include "plarena.h"
1.17 +#include "seccomon.h"
1.18 +#include "secoidt.h"
1.19 +#include "keyt.h"
1.20 +#include "certt.h"
1.21 +#include "ocspt.h"
1.22 +
1.23 +
1.24 +/************************************************************************/
1.25 +SEC_BEGIN_PROTOS
1.26 +
1.27 +/*
1.28 + * This function registers the HttpClient with whose functions the
1.29 + * HttpClientFcn structure has been populated as the default Http
1.30 + * client.
1.31 + *
1.32 + * The function table must be a global object.
1.33 + * The caller must ensure that NSS will be able to call
1.34 + * the registered functions for the lifetime of the process.
1.35 + */
1.36 +extern SECStatus
1.37 +SEC_RegisterDefaultHttpClient(const SEC_HttpClientFcn *fcnTable);
1.38 +
1.39 +/*
1.40 + * This function obtains the HttpClient which has been registered
1.41 + * by an earlier call to SEC_RegisterDefaultHttpClient.
1.42 + */
1.43 +extern const SEC_HttpClientFcn *
1.44 +SEC_GetRegisteredHttpClient(void);
1.45 +
1.46 +/*
1.47 + * Sets parameters that control NSS' internal OCSP cache.
1.48 + * maxCacheEntries, special varlues are:
1.49 + * -1 disable cache
1.50 + * 0 unlimited cache entries
1.51 + * minimumSecondsToNextFetchAttempt:
1.52 + * whenever an OCSP request was attempted or completed over the network,
1.53 + * wait at least this number of seconds before trying to fetch again.
1.54 + * maximumSecondsToNextFetchAttempt:
1.55 + * this is the maximum age of a cached response we allow, until we try
1.56 + * to fetch an updated response, even if the OCSP responder expects
1.57 + * that newer information update will not be available yet.
1.58 + */
1.59 +extern SECStatus
1.60 +CERT_OCSPCacheSettings(PRInt32 maxCacheEntries,
1.61 + PRUint32 minimumSecondsToNextFetchAttempt,
1.62 + PRUint32 maximumSecondsToNextFetchAttempt);
1.63 +
1.64 +/*
1.65 + * Set the desired behaviour on OCSP failures.
1.66 + * See definition of ocspFailureMode for allowed choices.
1.67 + */
1.68 +extern SECStatus
1.69 +CERT_SetOCSPFailureMode(SEC_OcspFailureMode ocspFailureMode);
1.70 +
1.71 +/*
1.72 + * Configure the maximum time NSS will wait for an OCSP response.
1.73 + */
1.74 +extern SECStatus
1.75 +CERT_SetOCSPTimeout(PRUint32 seconds);
1.76 +
1.77 +/*
1.78 + * Removes all items currently stored in the OCSP cache.
1.79 + */
1.80 +extern SECStatus
1.81 +CERT_ClearOCSPCache(void);
1.82 +
1.83 +/*
1.84 + * FUNCTION: CERT_EnableOCSPChecking
1.85 + * Turns on OCSP checking for the given certificate database.
1.86 + * INPUTS:
1.87 + * CERTCertDBHandle *handle
1.88 + * Certificate database for which OCSP checking will be enabled.
1.89 + * RETURN:
1.90 + * Returns SECFailure if an error occurred (likely only problem
1.91 + * allocating memory); SECSuccess otherwise.
1.92 + */
1.93 +extern SECStatus
1.94 +CERT_EnableOCSPChecking(CERTCertDBHandle *handle);
1.95 +
1.96 +/*
1.97 + * FUNCTION: CERT_DisableOCSPChecking
1.98 + * Turns off OCSP checking for the given certificate database.
1.99 + * This routine disables OCSP checking. Though it will return
1.100 + * SECFailure if OCSP checking is not enabled, it is "safe" to
1.101 + * call it that way and just ignore the return value, if it is
1.102 + * easier to just call it than to "remember" whether it is enabled.
1.103 + * INPUTS:
1.104 + * CERTCertDBHandle *handle
1.105 + * Certificate database for which OCSP checking will be disabled.
1.106 + * RETURN:
1.107 + * Returns SECFailure if an error occurred (usually means that OCSP
1.108 + * checking was not enabled or status contexts were not initialized --
1.109 + * error set will be SEC_ERROR_OCSP_NOT_ENABLED); SECSuccess otherwise.
1.110 + */
1.111 +extern SECStatus
1.112 +CERT_DisableOCSPChecking(CERTCertDBHandle *handle);
1.113 +
1.114 +/*
1.115 + * FUNCTION: CERT_SetOCSPDefaultResponder
1.116 + * Specify the location and cert of the default responder.
1.117 + * If OCSP checking is already enabled *and* use of a default responder
1.118 + * is also already enabled, all OCSP checking from now on will go directly
1.119 + * to the specified responder. If OCSP checking is not enabled, or if
1.120 + * it is but use of a default responder is not enabled, the information
1.121 + * will be recorded and take effect whenever both are enabled.
1.122 + * INPUTS:
1.123 + * CERTCertDBHandle *handle
1.124 + * Cert database on which OCSP checking should use the default responder.
1.125 + * const char *url
1.126 + * The location of the default responder (e.g. "http://foo.com:80/ocsp")
1.127 + * Note that the location will not be tested until the first attempt
1.128 + * to send a request there.
1.129 + * const char *name
1.130 + * The nickname of the cert to trust (expected) to sign the OCSP responses.
1.131 + * If the corresponding cert cannot be found, SECFailure is returned.
1.132 + * RETURN:
1.133 + * Returns SECFailure if an error occurred; SECSuccess otherwise.
1.134 + * The most likely error is that the cert for "name" could not be found
1.135 + * (probably SEC_ERROR_UNKNOWN_CERT). Other errors are low-level (no memory,
1.136 + * bad database, etc.).
1.137 + */
1.138 +extern SECStatus
1.139 +CERT_SetOCSPDefaultResponder(CERTCertDBHandle *handle,
1.140 + const char *url, const char *name);
1.141 +
1.142 +/*
1.143 + * FUNCTION: CERT_EnableOCSPDefaultResponder
1.144 + * Turns on use of a default responder when OCSP checking.
1.145 + * If OCSP checking is already enabled, this will make subsequent checks
1.146 + * go directly to the default responder. (The location of the responder
1.147 + * and the nickname of the responder cert must already be specified.)
1.148 + * If OCSP checking is not enabled, this will be recorded and take effect
1.149 + * whenever it is enabled.
1.150 + * INPUTS:
1.151 + * CERTCertDBHandle *handle
1.152 + * Cert database on which OCSP checking should use the default responder.
1.153 + * RETURN:
1.154 + * Returns SECFailure if an error occurred; SECSuccess otherwise.
1.155 + * No errors are especially likely unless the caller did not previously
1.156 + * perform a successful call to SetOCSPDefaultResponder (in which case
1.157 + * the error set will be SEC_ERROR_OCSP_NO_DEFAULT_RESPONDER).
1.158 + */
1.159 +extern SECStatus
1.160 +CERT_EnableOCSPDefaultResponder(CERTCertDBHandle *handle);
1.161 +
1.162 +/*
1.163 + * FUNCTION: CERT_DisableOCSPDefaultResponder
1.164 + * Turns off use of a default responder when OCSP checking.
1.165 + * (Does nothing if use of a default responder is not enabled.)
1.166 + * INPUTS:
1.167 + * CERTCertDBHandle *handle
1.168 + * Cert database on which OCSP checking should stop using a default
1.169 + * responder.
1.170 + * RETURN:
1.171 + * Returns SECFailure if an error occurred; SECSuccess otherwise.
1.172 + * Errors very unlikely (like random memory corruption...).
1.173 + */
1.174 +extern SECStatus
1.175 +CERT_DisableOCSPDefaultResponder(CERTCertDBHandle *handle);
1.176 +
1.177 +/* If forcePost is set, OCSP requests will only be sent using the HTTP POST
1.178 + * method. When forcePost is not set, OCSP requests will be sent using the
1.179 + * HTTP GET method, with a fallback to POST when we fail to receive a response
1.180 + * and/or when we receive an uncacheable response like "Unknown."
1.181 + *
1.182 + * The default is to use GET and fallback to POST.
1.183 + */
1.184 +extern SECStatus CERT_ForcePostMethodForOCSP(PRBool forcePost);
1.185 +
1.186 +/*
1.187 + * -------------------------------------------------------
1.188 + * The Functions above are those expected to be used by a client
1.189 + * providing OCSP status checking along with every cert verification.
1.190 + * The functions below are for OCSP testing, debugging, or clients
1.191 + * or servers performing more specialized OCSP tasks.
1.192 + * -------------------------------------------------------
1.193 + */
1.194 +
1.195 +/*
1.196 + * FUNCTION: CERT_CreateOCSPRequest
1.197 + * Creates a CERTOCSPRequest, requesting the status of the certs in
1.198 + * the given list.
1.199 + * INPUTS:
1.200 + * CERTCertList *certList
1.201 + * A list of certs for which status will be requested.
1.202 + * Note that all of these certificates should have the same issuer,
1.203 + * or it's expected the response will be signed by a trusted responder.
1.204 + * If the certs need to be broken up into multiple requests, that
1.205 + * must be handled by the caller (and thus by having multiple calls
1.206 + * to this routine), who knows about where the request(s) are being
1.207 + * sent and whether there are any trusted responders in place.
1.208 + * PRTime time
1.209 + * Indicates the time for which the certificate status is to be
1.210 + * determined -- this may be used in the search for the cert's issuer
1.211 + * but has no effect on the request itself.
1.212 + * PRBool addServiceLocator
1.213 + * If true, the Service Locator extension should be added to the
1.214 + * single request(s) for each cert.
1.215 + * CERTCertificate *signerCert
1.216 + * If non-NULL, means sign the request using this cert. Otherwise,
1.217 + * do not sign.
1.218 + * XXX note that request signing is not yet supported; see comment in code
1.219 + * RETURN:
1.220 + * A pointer to a CERTOCSPRequest structure containing an OCSP request
1.221 + * for the cert list. On error, null is returned, with an error set
1.222 + * indicating the reason. This is likely SEC_ERROR_UNKNOWN_ISSUER.
1.223 + * (The issuer is needed to create a request for the certificate.)
1.224 + * Other errors are low-level problems (no memory, bad database, etc.).
1.225 + */
1.226 +extern CERTOCSPRequest *
1.227 +CERT_CreateOCSPRequest(CERTCertList *certList, PRTime time,
1.228 + PRBool addServiceLocator,
1.229 + CERTCertificate *signerCert);
1.230 +
1.231 +/*
1.232 + * FUNCTION: CERT_AddOCSPAcceptableResponses
1.233 + * Add the AcceptableResponses extension to an OCSP Request.
1.234 + * INPUTS:
1.235 + * CERTOCSPRequest *request
1.236 + * The request to which the extension should be added.
1.237 + * SECOidTag responseType0, ...
1.238 + * A list (of one or more) of SECOidTag -- each of the response types
1.239 + * to be added. The last OID *must* be SEC_OID_PKIX_OCSP_BASIC_RESPONSE.
1.240 + * (This marks the end of the list, and it must be specified because a
1.241 + * client conforming to the OCSP standard is required to handle the basic
1.242 + * response type.) The OIDs are not checked in any way.
1.243 + * RETURN:
1.244 + * SECSuccess if the extension is added; SECFailure if anything goes wrong.
1.245 + * All errors are internal or low-level problems (e.g. no memory).
1.246 + */
1.247 +extern SECStatus
1.248 +CERT_AddOCSPAcceptableResponses(CERTOCSPRequest *request,
1.249 + SECOidTag responseType0, ...);
1.250 +
1.251 +/*
1.252 + * FUNCTION: CERT_EncodeOCSPRequest
1.253 + * DER encodes an OCSP Request, possibly adding a signature as well.
1.254 + * XXX Signing is not yet supported, however; see comments in code.
1.255 + * INPUTS:
1.256 + * PLArenaPool *arena
1.257 + * The return value is allocated from here.
1.258 + * If a NULL is passed in, allocation is done from the heap instead.
1.259 + * CERTOCSPRequest *request
1.260 + * The request to be encoded.
1.261 + * void *pwArg
1.262 + * Pointer to argument for password prompting, if needed. (Definitely
1.263 + * not needed if not signing.)
1.264 + * RETURN:
1.265 + * Returns a NULL on error and a pointer to the SECItem with the
1.266 + * encoded value otherwise. Any error is likely to be low-level
1.267 + * (e.g. no memory).
1.268 + */
1.269 +extern SECItem *
1.270 +CERT_EncodeOCSPRequest(PLArenaPool *arena, CERTOCSPRequest *request,
1.271 + void *pwArg);
1.272 +
1.273 +/*
1.274 + * FUNCTION: CERT_DecodeOCSPRequest
1.275 + * Decode a DER encoded OCSP Request.
1.276 + * INPUTS:
1.277 + * SECItem *src
1.278 + * Pointer to a SECItem holding DER encoded OCSP Request.
1.279 + * RETURN:
1.280 + * Returns a pointer to a CERTOCSPRequest containing the decoded request.
1.281 + * On error, returns NULL. Most likely error is trouble decoding
1.282 + * (SEC_ERROR_OCSP_MALFORMED_REQUEST), or low-level problem (no memory).
1.283 + */
1.284 +extern CERTOCSPRequest *
1.285 +CERT_DecodeOCSPRequest(const SECItem *src);
1.286 +
1.287 +/*
1.288 + * FUNCTION: CERT_DestroyOCSPRequest
1.289 + * Frees an OCSP Request structure.
1.290 + * INPUTS:
1.291 + * CERTOCSPRequest *request
1.292 + * Pointer to CERTOCSPRequest to be freed.
1.293 + * RETURN:
1.294 + * No return value; no errors.
1.295 + */
1.296 +extern void
1.297 +CERT_DestroyOCSPRequest(CERTOCSPRequest *request);
1.298 +
1.299 +/*
1.300 + * FUNCTION: CERT_DecodeOCSPResponse
1.301 + * Decode a DER encoded OCSP Response.
1.302 + * INPUTS:
1.303 + * SECItem *src
1.304 + * Pointer to a SECItem holding DER encoded OCSP Response.
1.305 + * RETURN:
1.306 + * Returns a pointer to a CERTOCSPResponse (the decoded OCSP Response);
1.307 + * the caller is responsible for destroying it. Or NULL if error (either
1.308 + * response could not be decoded (SEC_ERROR_OCSP_MALFORMED_RESPONSE),
1.309 + * it was of an unexpected type (SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE),
1.310 + * or a low-level or internal error occurred).
1.311 + */
1.312 +extern CERTOCSPResponse *
1.313 +CERT_DecodeOCSPResponse(const SECItem *src);
1.314 +
1.315 +/*
1.316 + * FUNCTION: CERT_DestroyOCSPResponse
1.317 + * Frees an OCSP Response structure.
1.318 + * INPUTS:
1.319 + * CERTOCSPResponse *request
1.320 + * Pointer to CERTOCSPResponse to be freed.
1.321 + * RETURN:
1.322 + * No return value; no errors.
1.323 + */
1.324 +extern void
1.325 +CERT_DestroyOCSPResponse(CERTOCSPResponse *response);
1.326 +
1.327 +/*
1.328 + * FUNCTION: CERT_GetEncodedOCSPResponse
1.329 + * Creates and sends a request to an OCSP responder, then reads and
1.330 + * returns the (encoded) response.
1.331 + * INPUTS:
1.332 + * PLArenaPool *arena
1.333 + * Pointer to arena from which return value will be allocated.
1.334 + * If NULL, result will be allocated from the heap (and thus should
1.335 + * be freed via SECITEM_FreeItem).
1.336 + * CERTCertList *certList
1.337 + * A list of certs for which status will be requested.
1.338 + * Note that all of these certificates should have the same issuer,
1.339 + * or it's expected the response will be signed by a trusted responder.
1.340 + * If the certs need to be broken up into multiple requests, that
1.341 + * must be handled by the caller (and thus by having multiple calls
1.342 + * to this routine), who knows about where the request(s) are being
1.343 + * sent and whether there are any trusted responders in place.
1.344 + * const char *location
1.345 + * The location of the OCSP responder (a URL).
1.346 + * PRTime time
1.347 + * Indicates the time for which the certificate status is to be
1.348 + * determined -- this may be used in the search for the cert's issuer
1.349 + * but has no other bearing on the operation.
1.350 + * PRBool addServiceLocator
1.351 + * If true, the Service Locator extension should be added to the
1.352 + * single request(s) for each cert.
1.353 + * CERTCertificate *signerCert
1.354 + * If non-NULL, means sign the request using this cert. Otherwise,
1.355 + * do not sign.
1.356 + * void *pwArg
1.357 + * Pointer to argument for password prompting, if needed. (Definitely
1.358 + * not needed if not signing.)
1.359 + * OUTPUTS:
1.360 + * CERTOCSPRequest **pRequest
1.361 + * Pointer in which to store the OCSP request created for the given
1.362 + * list of certificates. It is only filled in if the entire operation
1.363 + * is successful and the pointer is not null -- and in that case the
1.364 + * caller is then reponsible for destroying it.
1.365 + * RETURN:
1.366 + * Returns a pointer to the SECItem holding the response.
1.367 + * On error, returns null with error set describing the reason:
1.368 + * SEC_ERROR_UNKNOWN_ISSUER
1.369 + * SEC_ERROR_CERT_BAD_ACCESS_LOCATION
1.370 + * SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
1.371 + * Other errors are low-level problems (no memory, bad database, etc.).
1.372 + */
1.373 +extern SECItem *
1.374 +CERT_GetEncodedOCSPResponse(PLArenaPool *arena, CERTCertList *certList,
1.375 + const char *location, PRTime time,
1.376 + PRBool addServiceLocator,
1.377 + CERTCertificate *signerCert, void *pwArg,
1.378 + CERTOCSPRequest **pRequest);
1.379 +
1.380 +/*
1.381 + * FUNCTION: CERT_VerifyOCSPResponseSignature
1.382 + * Check the signature on an OCSP Response. Will also perform a
1.383 + * verification of the signer's certificate. Note, however, that a
1.384 + * successful verification does not make any statement about the
1.385 + * signer's *authority* to provide status for the certificate(s),
1.386 + * that must be checked individually for each certificate.
1.387 + * INPUTS:
1.388 + * CERTOCSPResponse *response
1.389 + * Pointer to response structure with signature to be checked.
1.390 + * CERTCertDBHandle *handle
1.391 + * Pointer to CERTCertDBHandle for certificate DB to use for verification.
1.392 + * void *pwArg
1.393 + * Pointer to argument for password prompting, if needed.
1.394 + * CERTCertificate *issuerCert
1.395 + * Issuer of the certificate that generated the OCSP request.
1.396 + * OUTPUTS:
1.397 + * CERTCertificate **pSignerCert
1.398 + * Pointer in which to store signer's certificate; only filled-in if
1.399 + * non-null.
1.400 + * RETURN:
1.401 + * Returns SECSuccess when signature is valid, anything else means invalid.
1.402 + * Possible errors set:
1.403 + * SEC_ERROR_OCSP_MALFORMED_RESPONSE - unknown type of ResponderID
1.404 + * SEC_ERROR_INVALID_TIME - bad format of "ProducedAt" time
1.405 + * SEC_ERROR_UNKNOWN_SIGNER - signer's cert could not be found
1.406 + * SEC_ERROR_BAD_SIGNATURE - the signature did not verify
1.407 + * Other errors are any of the many possible failures in cert verification
1.408 + * (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
1.409 + * verifying the signer's cert, or low-level problems (no memory, etc.)
1.410 + */
1.411 +extern SECStatus
1.412 +CERT_VerifyOCSPResponseSignature(CERTOCSPResponse *response,
1.413 + CERTCertDBHandle *handle, void *pwArg,
1.414 + CERTCertificate **pSignerCert,
1.415 + CERTCertificate *issuerCert);
1.416 +
1.417 +/*
1.418 + * FUNCTION: CERT_GetOCSPAuthorityInfoAccessLocation
1.419 + * Get the value of the URI of the OCSP responder for the given cert.
1.420 + * This is found in the (optional) Authority Information Access extension
1.421 + * in the cert.
1.422 + * INPUTS:
1.423 + * CERTCertificate *cert
1.424 + * The certificate being examined.
1.425 + * RETURN:
1.426 + * char *
1.427 + * A copy of the URI for the OCSP method, if found. If either the
1.428 + * extension is not present or it does not contain an entry for OCSP,
1.429 + * SEC_ERROR_EXTENSION_NOT_FOUND will be set and a NULL returned.
1.430 + * Any other error will also result in a NULL being returned.
1.431 + *
1.432 + * This result should be freed (via PORT_Free) when no longer in use.
1.433 + */
1.434 +extern char *
1.435 +CERT_GetOCSPAuthorityInfoAccessLocation(const CERTCertificate *cert);
1.436 +
1.437 +/*
1.438 + * FUNCTION: CERT_RegisterAlternateOCSPAIAInfoCallBack
1.439 + * This function serves two purposes.
1.440 + * 1) It registers the address of a callback function that will be
1.441 + * called for certs that have no OCSP AIA extension, to see if the
1.442 + * callback wishes to supply an alternative URL for such an OCSP inquiry.
1.443 + * 2) It outputs the previously registered function's address to the
1.444 + * address supplied by the caller, unless that is NULL.
1.445 + * The registered callback function returns NULL, or an allocated string
1.446 + * that may be subsequently freed by calling PORT_Free().
1.447 + * RETURN:
1.448 + * SECSuccess or SECFailure (if the library is not yet intialized)
1.449 + */
1.450 +extern SECStatus
1.451 +CERT_RegisterAlternateOCSPAIAInfoCallBack(
1.452 + CERT_StringFromCertFcn newCallback,
1.453 + CERT_StringFromCertFcn * oldCallback);
1.454 +
1.455 +/*
1.456 + * FUNCTION: CERT_ParseURL
1.457 + * Parse a URI into hostname, port, and path. The scheme in the URI must
1.458 + * be "http".
1.459 + * INPUTS:
1.460 + * const char *url
1.461 + * The URI to be parsed
1.462 + * OUTPUTS:
1.463 + * char **pHostname
1.464 + * Pointer to store the hostname obtained from the URI.
1.465 + * This result should be freed (via PORT_Free) when no longer in use.
1.466 + * PRUint16 *pPort
1.467 + * Pointer to store the port number obtained from the URI.
1.468 + * char **pPath
1.469 + * Pointer to store the path obtained from the URI.
1.470 + * This result should be freed (via PORT_Free) when no longer in use.
1.471 + * RETURN:
1.472 + * Returns SECSuccess when parsing was successful. Returns SECFailure when
1.473 + * problems were encountered.
1.474 + */
1.475 +extern SECStatus
1.476 +CERT_ParseURL(const char *url, char **pHostname, PRUint16 *pPort, char **pPath);
1.477 +
1.478 +/*
1.479 + * FUNCTION: CERT_CheckOCSPStatus
1.480 + * Checks the status of a certificate via OCSP. Will only check status for
1.481 + * a certificate that has an AIA (Authority Information Access) extension
1.482 + * for OCSP *or* when a "default responder" is specified and enabled.
1.483 + * (If no AIA extension for OCSP and no default responder in place, the
1.484 + * cert is considered to have a good status and SECSuccess is returned.)
1.485 + * INPUTS:
1.486 + * CERTCertDBHandle *handle
1.487 + * certificate DB of the cert that is being checked
1.488 + * CERTCertificate *cert
1.489 + * the certificate being checked
1.490 + * XXX in the long term also need a boolean parameter that specifies
1.491 + * whether to check the cert chain, as well; for now we check only
1.492 + * the leaf (the specified certificate)
1.493 + * PRTime time
1.494 + * time for which status is to be determined
1.495 + * void *pwArg
1.496 + * argument for password prompting, if needed
1.497 + * RETURN:
1.498 + * Returns SECSuccess if an approved OCSP responder "knows" the cert
1.499 + * *and* returns a non-revoked status for it; SECFailure otherwise,
1.500 + * with an error set describing the reason:
1.501 + *
1.502 + * SEC_ERROR_OCSP_BAD_HTTP_RESPONSE
1.503 + * SEC_ERROR_OCSP_FUTURE_RESPONSE
1.504 + * SEC_ERROR_OCSP_MALFORMED_REQUEST
1.505 + * SEC_ERROR_OCSP_MALFORMED_RESPONSE
1.506 + * SEC_ERROR_OCSP_OLD_RESPONSE
1.507 + * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
1.508 + * SEC_ERROR_OCSP_SERVER_ERROR
1.509 + * SEC_ERROR_OCSP_TRY_SERVER_LATER
1.510 + * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
1.511 + * SEC_ERROR_OCSP_UNAUTHORIZED_RESPONSE
1.512 + * SEC_ERROR_OCSP_UNKNOWN_CERT
1.513 + * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
1.514 + * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_TYPE
1.515 + *
1.516 + * SEC_ERROR_BAD_SIGNATURE
1.517 + * SEC_ERROR_CERT_BAD_ACCESS_LOCATION
1.518 + * SEC_ERROR_INVALID_TIME
1.519 + * SEC_ERROR_REVOKED_CERTIFICATE
1.520 + * SEC_ERROR_UNKNOWN_ISSUER
1.521 + * SEC_ERROR_UNKNOWN_SIGNER
1.522 + *
1.523 + * Other errors are any of the many possible failures in cert verification
1.524 + * (e.g. SEC_ERROR_REVOKED_CERTIFICATE, SEC_ERROR_UNTRUSTED_ISSUER) when
1.525 + * verifying the signer's cert, or low-level problems (error allocating
1.526 + * memory, error performing ASN.1 decoding, etc.).
1.527 + */
1.528 +extern SECStatus
1.529 +CERT_CheckOCSPStatus(CERTCertDBHandle *handle, CERTCertificate *cert,
1.530 + PRTime time, void *pwArg);
1.531 +
1.532 +/*
1.533 + * FUNCTION: CERT_CacheOCSPResponseFromSideChannel
1.534 + * First, this function checks the OCSP cache to see if a good response
1.535 + * for the given certificate already exists. If it does, then the function
1.536 + * returns successfully.
1.537 + *
1.538 + * If not, then it validates that the given OCSP response is a valid,
1.539 + * good response for the given certificate and inserts it into the
1.540 + * cache.
1.541 + *
1.542 + * This function is intended for use when OCSP responses are provided via a
1.543 + * side-channel, i.e. TLS OCSP stapling (a.k.a. the status_request extension).
1.544 + *
1.545 + * INPUTS:
1.546 + * CERTCertDBHandle *handle
1.547 + * certificate DB of the cert that is being checked
1.548 + * CERTCertificate *cert
1.549 + * the certificate being checked
1.550 + * PRTime time
1.551 + * time for which status is to be determined
1.552 + * SECItem *encodedResponse
1.553 + * the DER encoded bytes of the OCSP response
1.554 + * void *pwArg
1.555 + * argument for password prompting, if needed
1.556 + * RETURN:
1.557 + * SECSuccess if the cert was found in the cache, or if the OCSP response was
1.558 + * found to be valid and inserted into the cache. SECFailure otherwise.
1.559 + */
1.560 +extern SECStatus
1.561 +CERT_CacheOCSPResponseFromSideChannel(CERTCertDBHandle *handle,
1.562 + CERTCertificate *cert,
1.563 + PRTime time,
1.564 + const SECItem *encodedResponse,
1.565 + void *pwArg);
1.566 +
1.567 +/*
1.568 + * FUNCTION: CERT_GetOCSPStatusForCertID
1.569 + * Returns the OCSP status contained in the passed in parameter response
1.570 + * that corresponds to the certID passed in.
1.571 + * INPUTS:
1.572 + * CERTCertDBHandle *handle
1.573 + * certificate DB of the cert that is being checked
1.574 + * CERTOCSPResponse *response
1.575 + * the OCSP response we want to retrieve status from.
1.576 + * CERTOCSPCertID *certID
1.577 + * the ID we want to look for from the response.
1.578 + * CERTCertificate *signerCert
1.579 + * the certificate that was used to sign the OCSP response.
1.580 + * must be obtained via a call to CERT_VerifyOCSPResponseSignature.
1.581 + * PRTime time
1.582 + * The time at which we're checking the status for.
1.583 + * RETURN:
1.584 + * Return values are the same as those for CERT_CheckOCSPStatus
1.585 + */
1.586 +extern SECStatus
1.587 +CERT_GetOCSPStatusForCertID(CERTCertDBHandle *handle,
1.588 + CERTOCSPResponse *response,
1.589 + CERTOCSPCertID *certID,
1.590 + CERTCertificate *signerCert,
1.591 + PRTime time);
1.592 +
1.593 +/*
1.594 + * FUNCTION CERT_GetOCSPResponseStatus
1.595 + * Returns the response status for the response passed.
1.596 + * INPUTS:
1.597 + * CERTOCSPResponse *response
1.598 + * The response to query for status
1.599 + * RETURN:
1.600 + * Returns SECSuccess if the response has a successful status value.
1.601 + * Otherwise it returns SECFailure and sets one of the following error
1.602 + * codes via PORT_SetError
1.603 + * SEC_ERROR_OCSP_MALFORMED_REQUEST
1.604 + * SEC_ERROR_OCSP_SERVER_ERROR
1.605 + * SEC_ERROR_OCSP_TRY_SERVER_LATER
1.606 + * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG
1.607 + * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST
1.608 + * SEC_ERROR_OCSP_UNKNOWN_RESPONSE_STATUS
1.609 + */
1.610 +extern SECStatus
1.611 +CERT_GetOCSPResponseStatus(CERTOCSPResponse *response);
1.612 +
1.613 +/*
1.614 + * FUNCTION CERT_CreateOCSPCertID
1.615 + * Returns the OCSP certID for the certificate passed in.
1.616 + * INPUTS:
1.617 + * CERTCertificate *cert
1.618 + * The certificate for which to create the certID for.
1.619 + * PRTime time
1.620 + * The time at which the id is requested for. This is used
1.621 + * to determine the appropriate issuer for the cert since
1.622 + * the issuing CA may be an older expired certificate.
1.623 + * RETURN:
1.624 + * A new copy of a CERTOCSPCertID*. The memory for this certID
1.625 + * should be freed by calling CERT_DestroyOCSPCertID when the
1.626 + * certID is no longer necessary.
1.627 + */
1.628 +extern CERTOCSPCertID*
1.629 +CERT_CreateOCSPCertID(CERTCertificate *cert, PRTime time);
1.630 +
1.631 +/*
1.632 + * FUNCTION: CERT_DestroyOCSPCertID
1.633 + * Frees the memory associated with the certID passed in.
1.634 + * INPUTS:
1.635 + * CERTOCSPCertID* certID
1.636 + * The certID that the caller no longer needs and wants to
1.637 + * free the associated memory.
1.638 + * RETURN:
1.639 + * SECSuccess if freeing the memory was successful. Returns
1.640 + * SECFailure if the memory passed in was not allocated with
1.641 + * a call to CERT_CreateOCSPCertID.
1.642 + */
1.643 +extern SECStatus
1.644 +CERT_DestroyOCSPCertID(CERTOCSPCertID* certID);
1.645 +
1.646 +
1.647 +extern CERTOCSPSingleResponse*
1.648 +CERT_CreateOCSPSingleResponseGood(PLArenaPool *arena,
1.649 + CERTOCSPCertID *id,
1.650 + PRTime thisUpdate,
1.651 + const PRTime *nextUpdate);
1.652 +
1.653 +extern CERTOCSPSingleResponse*
1.654 +CERT_CreateOCSPSingleResponseUnknown(PLArenaPool *arena,
1.655 + CERTOCSPCertID *id,
1.656 + PRTime thisUpdate,
1.657 + const PRTime *nextUpdate);
1.658 +
1.659 +extern CERTOCSPSingleResponse*
1.660 +CERT_CreateOCSPSingleResponseRevoked(
1.661 + PLArenaPool *arena,
1.662 + CERTOCSPCertID *id,
1.663 + PRTime thisUpdate,
1.664 + const PRTime *nextUpdate,
1.665 + PRTime revocationTime,
1.666 + const CERTCRLEntryReasonCode* revocationReason);
1.667 +
1.668 +extern SECItem*
1.669 +CERT_CreateEncodedOCSPSuccessResponse(
1.670 + PLArenaPool *arena,
1.671 + CERTCertificate *responderCert,
1.672 + CERTOCSPResponderIDType responderIDType,
1.673 + PRTime producedAt,
1.674 + CERTOCSPSingleResponse **responses,
1.675 + void *wincx);
1.676 +
1.677 +/*
1.678 + * FUNCTION: CERT_CreateEncodedOCSPErrorResponse
1.679 + * Creates an encoded OCSP response with an error response status.
1.680 + * INPUTS:
1.681 + * PLArenaPool *arena
1.682 + * The return value is allocated from here.
1.683 + * If a NULL is passed in, allocation is done from the heap instead.
1.684 + * int error
1.685 + * An NSS error code indicating an error response status. The error
1.686 + * code is mapped to an OCSP response status as follows:
1.687 + * SEC_ERROR_OCSP_MALFORMED_REQUEST -> malformedRequest
1.688 + * SEC_ERROR_OCSP_SERVER_ERROR -> internalError
1.689 + * SEC_ERROR_OCSP_TRY_SERVER_LATER -> tryLater
1.690 + * SEC_ERROR_OCSP_REQUEST_NEEDS_SIG -> sigRequired
1.691 + * SEC_ERROR_OCSP_UNAUTHORIZED_REQUEST -> unauthorized
1.692 + * where the OCSP response status is an enumerated type defined in
1.693 + * RFC 2560:
1.694 + * OCSPResponseStatus ::= ENUMERATED {
1.695 + * successful (0), --Response has valid confirmations
1.696 + * malformedRequest (1), --Illegal confirmation request
1.697 + * internalError (2), --Internal error in issuer
1.698 + * tryLater (3), --Try again later
1.699 + * --(4) is not used
1.700 + * sigRequired (5), --Must sign the request
1.701 + * unauthorized (6) --Request unauthorized
1.702 + * }
1.703 + * RETURN:
1.704 + * Returns a pointer to the SECItem holding the response.
1.705 + * On error, returns null with error set describing the reason:
1.706 + * SEC_ERROR_INVALID_ARGS
1.707 + * Other errors are low-level problems (no memory, bad database, etc.).
1.708 + */
1.709 +extern SECItem*
1.710 +CERT_CreateEncodedOCSPErrorResponse(PLArenaPool *arena, int error);
1.711 +
1.712 +/* Sends an OCSP request using the HTTP POST method to the location addressed
1.713 + * by the URL in |location| parameter. The request body will be
1.714 + * |encodedRequest|, which must be a valid encoded OCSP request. On success,
1.715 + * the server's response is returned and the caller must free it using
1.716 + * SECITEM_FreeItem. On failure, NULL is returned. No parsing or validation of
1.717 + * the HTTP response is done.
1.718 + *
1.719 + * If a default HTTP client has been registered with
1.720 + * SEC_RegisterDefaultHttpClient then that client is used. Otherwise, an
1.721 + * internal HTTP client is used.
1.722 + */
1.723 +SECItem* CERT_PostOCSPRequest(PLArenaPool *arena, const char *location,
1.724 + const SECItem *encodedRequest);
1.725 +
1.726 +/************************************************************************/
1.727 +SEC_END_PROTOS
1.728 +
1.729 +#endif /* _OCSP_H_ */
