1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/certhigh/ocspt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,301 @@
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 + * Public header for exported OCSP types.
1.10 + */
1.11 +
1.12 +#ifndef _OCSPT_H_
1.13 +#define _OCSPT_H_
1.14 +
1.15 +/*
1.16 + * The following are all opaque types. If someone needs to get at
1.17 + * a field within, then we need to fix the API. Try very hard not
1.18 + * make the type available to them.
1.19 + */
1.20 +typedef struct CERTOCSPRequestStr CERTOCSPRequest;
1.21 +typedef struct CERTOCSPResponseStr CERTOCSPResponse;
1.22 +
1.23 +/*
1.24 + * XXX I think only those first two above should need to be exported,
1.25 + * but until I know for certain I am leaving the rest of these here, too.
1.26 + */
1.27 +typedef struct CERTOCSPCertIDStr CERTOCSPCertID;
1.28 +typedef struct CERTOCSPSingleResponseStr CERTOCSPSingleResponse;
1.29 +
1.30 +/*
1.31 + * This interface is described in terms of an HttpClient which
1.32 + * supports at least a specified set of functions. (An implementer may
1.33 + * provide HttpClients with additional functionality accessible only to
1.34 + * users with a particular implementation in mind.) The basic behavior
1.35 + * is provided by defining a set of functions, listed in an
1.36 + * SEC_HttpServerFcnStruct. If the implementor of a SpecificHttpClient
1.37 + * registers his SpecificHttpClient as the default HttpClient, then his
1.38 + * functions will be called by the user of an HttpClient, such as an
1.39 + * OCSPChecker.
1.40 + *
1.41 + * The implementer of a specific HttpClient (e.g., the NSS-provided
1.42 + * DefaultHttpClient), populates an SEC_HttpClientFcnStruct, uses it to
1.43 + * register his client, and waits for his functions to be called.
1.44 + *
1.45 + * For future expandability, the SEC_HttpClientFcnStruct is defined as a
1.46 + * union, with the version field acting as a selector. The proposed
1.47 + * initial version of the structure is given following the definition
1.48 + * of the union. The HttpClientState structure is implementation-
1.49 + * dependent, and should be opaque to the user.
1.50 + */
1.51 +
1.52 +typedef void * SEC_HTTP_SERVER_SESSION;
1.53 +typedef void * SEC_HTTP_REQUEST_SESSION;
1.54 +
1.55 +/*
1.56 + * This function creates a SEC_HTTP_SERVER_SESSION object. The implementer of a
1.57 + * specific HttpClient will allocate the necessary space, when this
1.58 + * function is called, and will free it when the corresponding FreeFcn
1.59 + * is called. The SEC_HTTP_SERVER_SESSION object is passed, as an opaque object,
1.60 + * to subsequent calls.
1.61 + *
1.62 + * If the function returns SECSuccess, the returned SEC_HTTP_SERVER_SESSION
1.63 + * must be cleaned up with a call to SEC_HttpServer_FreeSession,
1.64 + * after processing is finished.
1.65 + */
1.66 +typedef SECStatus (*SEC_HttpServer_CreateSessionFcn)(
1.67 + const char *host,
1.68 + PRUint16 portnum,
1.69 + SEC_HTTP_SERVER_SESSION *pSession);
1.70 +
1.71 +/*
1.72 + * This function is called to allow the implementation to attempt to keep
1.73 + * the connection alive. Depending on the underlying platform, it might
1.74 + * immediately return SECSuccess without having performed any operations.
1.75 + * (If a connection has not been kept alive, a subsequent call to
1.76 + * SEC_HttpRequest_TrySendAndReceiveFcn should reopen the connection
1.77 + * automatically.)
1.78 + *
1.79 + * If the connection uses nonblocking I/O, this function may return
1.80 + * SECWouldBlock and store a nonzero value at "pPollDesc". In that case
1.81 + * the caller may wait on the poll descriptor, and should call this function
1.82 + * again until SECSuccess (and a zero value at "pPollDesc") is obtained.
1.83 + */
1.84 +typedef SECStatus (*SEC_HttpServer_KeepAliveSessionFcn)(
1.85 + SEC_HTTP_SERVER_SESSION session,
1.86 + PRPollDesc **pPollDesc);
1.87 +
1.88 +/*
1.89 + * This function frees the client SEC_HTTP_SERVER_SESSION object, closes all
1.90 + * SEC_HTTP_REQUEST_SESSIONs created for that server, discards all partial results,
1.91 + * frees any memory that was allocated by the client, and invalidates any
1.92 + * response pointers that might have been returned by prior server or request
1.93 + * functions.
1.94 + */
1.95 +typedef SECStatus (*SEC_HttpServer_FreeSessionFcn)(
1.96 + SEC_HTTP_SERVER_SESSION session);
1.97 +
1.98 +/*
1.99 + * This function creates a SEC_HTTP_REQUEST_SESSION object. The implementer of a
1.100 + * specific HttpClient will allocate the necessary space, when this
1.101 + * function is called, and will free it when the corresponding FreeFcn
1.102 + * is called. The SEC_HTTP_REQUEST_SESSION object is passed, as an opaque object,
1.103 + * to subsequent calls.
1.104 + *
1.105 + * An implementation that does not support the requested protocol variant
1.106 + * (usually "http", but could eventually allow "https") or request method
1.107 + * should return SECFailure.
1.108 + *
1.109 + * Timeout values may include the constants PR_INTERVAL_NO_TIMEOUT (wait
1.110 + * forever) or PR_INTERVAL_NO_WAIT (nonblocking I/O).
1.111 + *
1.112 + * If the function returns SECSuccess, the returned SEC_HTTP_REQUEST_SESSION
1.113 + * must be cleaned up with a call to SEC_HttpRequest_FreeSession,
1.114 + * after processing is finished.
1.115 + */
1.116 +typedef SECStatus (*SEC_HttpRequest_CreateFcn)(
1.117 + SEC_HTTP_SERVER_SESSION session,
1.118 + const char *http_protocol_variant, /* usually "http" */
1.119 + const char *path_and_query_string,
1.120 + const char *http_request_method,
1.121 + const PRIntervalTime timeout,
1.122 + SEC_HTTP_REQUEST_SESSION *pRequest);
1.123 +
1.124 +/*
1.125 + * This function sets data to be sent to the server for an HTTP request
1.126 + * of http_request_method == POST. If a particular implementation
1.127 + * supports it, the details for the POST request can be set by calling
1.128 + * this function, prior to activating the request with TrySendAndReceiveFcn.
1.129 + *
1.130 + * An implementation that does not support the POST method should
1.131 + * implement a SetPostDataFcn function that returns immediately.
1.132 + *
1.133 + * Setting http_content_type is optional, the parameter may
1.134 + * by NULL or the empty string.
1.135 + */
1.136 +typedef SECStatus (*SEC_HttpRequest_SetPostDataFcn)(
1.137 + SEC_HTTP_REQUEST_SESSION request,
1.138 + const char *http_data,
1.139 + const PRUint32 http_data_len,
1.140 + const char *http_content_type);
1.141 +
1.142 +/*
1.143 + * This function sets an additional HTTP protocol request header.
1.144 + * If a particular implementation supports it, one or multiple headers
1.145 + * can be added to the request by calling this function once or multiple
1.146 + * times, prior to activating the request with TryFcn.
1.147 + *
1.148 + * An implementation that does not support setting additional headers
1.149 + * should implement an AddRequestHeaderFcn function that returns immediately.
1.150 + */
1.151 +typedef SECStatus (*SEC_HttpRequest_AddHeaderFcn)(
1.152 + SEC_HTTP_REQUEST_SESSION request,
1.153 + const char *http_header_name,
1.154 + const char *http_header_value);
1.155 +
1.156 +/*
1.157 + * This function initiates or continues an HTTP request. After
1.158 + * parameters have been set with the Create function and, optionally,
1.159 + * modified or enhanced with the AddParams function, this call creates
1.160 + * the socket connection and initiates the communication.
1.161 + *
1.162 + * If a timeout value of zero is specified, indicating non-blocking
1.163 + * I/O, the client creates a non-blocking socket, and returns a status
1.164 + * of SECWouldBlock and a non-NULL PRPollDesc if the operation is not
1.165 + * complete. In that case all other return parameters are undefined.
1.166 + * The caller is expected to repeat the call, possibly after using
1.167 + * PRPoll to determine that a completion has occurred, until a return
1.168 + * value of SECSuccess (and a NULL value for pPollDesc) or a return
1.169 + * value of SECFailure (indicating failure on the network level)
1.170 + * is obtained.
1.171 + *
1.172 + * http_response_data_len is both input and output parameter.
1.173 + * If a pointer to a PRUint32 is supplied, the http client is
1.174 + * expected to check the given integer value and always set an out
1.175 + * value, even on failure.
1.176 + * An input value of zero means, the caller will accept any response len.
1.177 + * A different input value indicates the maximum response value acceptable
1.178 + * to the caller.
1.179 + * If data is successfully read and the size is acceptable to the caller,
1.180 + * the function will return SECSuccess and set http_response_data_len to
1.181 + * the size of the block returned in http_response_data.
1.182 + * If the data read from the http server is larger than the acceptable
1.183 + * size, the function will return SECFailure.
1.184 + * http_response_data_len will be set to a value different from zero to
1.185 + * indicate the reason of the failure.
1.186 + * An out value of "0" means, the failure was unrelated to the
1.187 + * acceptable size.
1.188 + * An out value of "1" means, the result data is larger than the
1.189 + * accpeptable size, but the real size is not yet known to the http client
1.190 + * implementation and it stopped retrieving it,
1.191 + * Any other out value combined with a return value of SECFailure
1.192 + * will indicate the actual size of the server data.
1.193 + *
1.194 + * The caller is permitted to provide NULL values for any of the
1.195 + * http_response arguments, indicating the caller is not interested in
1.196 + * those values. If the caller does provide an address, the HttpClient
1.197 + * stores at that address a pointer to the corresponding argument, at
1.198 + * the completion of the operation.
1.199 + *
1.200 + * All returned pointers will be owned by the the HttpClient
1.201 + * implementation and will remain valid until the call to
1.202 + * SEC_HttpRequest_FreeFcn.
1.203 + */
1.204 +typedef SECStatus (*SEC_HttpRequest_TrySendAndReceiveFcn)(
1.205 + SEC_HTTP_REQUEST_SESSION request,
1.206 + PRPollDesc **pPollDesc,
1.207 + PRUint16 *http_response_code,
1.208 + const char **http_response_content_type,
1.209 + const char **http_response_headers,
1.210 + const char **http_response_data,
1.211 + PRUint32 *http_response_data_len);
1.212 +
1.213 +/*
1.214 + * Calling CancelFcn asks for premature termination of the request.
1.215 + *
1.216 + * Future calls to SEC_HttpRequest_TrySendAndReceive should
1.217 + * by avoided, but in this case the HttpClient implementation
1.218 + * is expected to return immediately with SECFailure.
1.219 + *
1.220 + * After calling CancelFcn, a separate call to SEC_HttpRequest_FreeFcn
1.221 + * is still necessary to free resources.
1.222 + */
1.223 +typedef SECStatus (*SEC_HttpRequest_CancelFcn)(
1.224 + SEC_HTTP_REQUEST_SESSION request);
1.225 +
1.226 +/*
1.227 + * Before calling this function, it must be assured the request
1.228 + * has been completed, i.e. either SEC_HttpRequest_TrySendAndReceiveFcn has
1.229 + * returned SECSuccess, or the request has been canceled with
1.230 + * a call to SEC_HttpRequest_CancelFcn.
1.231 + *
1.232 + * This function frees the client state object, closes all sockets,
1.233 + * discards all partial results, frees any memory that was allocated
1.234 + * by the client, and invalidates all response pointers that might
1.235 + * have been returned by SEC_HttpRequest_TrySendAndReceiveFcn
1.236 + */
1.237 +typedef SECStatus (*SEC_HttpRequest_FreeFcn)(
1.238 + SEC_HTTP_REQUEST_SESSION request);
1.239 +
1.240 +typedef struct SEC_HttpClientFcnV1Struct {
1.241 + SEC_HttpServer_CreateSessionFcn createSessionFcn;
1.242 + SEC_HttpServer_KeepAliveSessionFcn keepAliveSessionFcn;
1.243 + SEC_HttpServer_FreeSessionFcn freeSessionFcn;
1.244 + SEC_HttpRequest_CreateFcn createFcn;
1.245 + SEC_HttpRequest_SetPostDataFcn setPostDataFcn;
1.246 + SEC_HttpRequest_AddHeaderFcn addHeaderFcn;
1.247 + SEC_HttpRequest_TrySendAndReceiveFcn trySendAndReceiveFcn;
1.248 + SEC_HttpRequest_CancelFcn cancelFcn;
1.249 + SEC_HttpRequest_FreeFcn freeFcn;
1.250 +} SEC_HttpClientFcnV1;
1.251 +
1.252 +typedef struct SEC_HttpClientFcnStruct {
1.253 + PRInt16 version;
1.254 + union {
1.255 + SEC_HttpClientFcnV1 ftable1;
1.256 + /* SEC_HttpClientFcnV2 ftable2; */
1.257 + /* ... */
1.258 + } fcnTable;
1.259 +} SEC_HttpClientFcn;
1.260 +
1.261 +/*
1.262 + * ocspMode_FailureIsVerificationFailure:
1.263 + * This is the classic behaviour of NSS.
1.264 + * Any OCSP failure is a verification failure (classic mode, default).
1.265 + * Without a good response, OCSP networking will be retried each time
1.266 + * it is required for verifying a cert.
1.267 + *
1.268 + * ocspMode_FailureIsNotAVerificationFailure:
1.269 + * If we fail to obtain a valid OCSP response, consider the
1.270 + * cert as good.
1.271 + * Failed OCSP attempts might get cached and not retried until
1.272 + * minimumSecondsToNextFetchAttempt.
1.273 + * If we are able to obtain a valid response, the cert
1.274 + * will be considered good, if either status is "good"
1.275 + * or the cert was not yet revoked at verification time.
1.276 + *
1.277 + * Additional failure modes might be added in the future.
1.278 + */
1.279 +typedef enum {
1.280 + ocspMode_FailureIsVerificationFailure = 0,
1.281 + ocspMode_FailureIsNotAVerificationFailure = 1
1.282 +} SEC_OcspFailureMode;
1.283 +
1.284 +/*
1.285 + * A ResponderID identifies the responder -- or more correctly, the
1.286 + * signer of the response. The ASN.1 definition of a ResponderID is:
1.287 + *
1.288 + * ResponderID ::= CHOICE {
1.289 + * byName [1] EXPLICIT Name,
1.290 + * byKey [2] EXPLICIT KeyHash }
1.291 + *
1.292 + * Because it is CHOICE, the type of identification used and the
1.293 + * identification itself are actually encoded together. To represent
1.294 + * this same information internally, we explicitly define a type and
1.295 + * save it, along with the value, into a data structure.
1.296 + */
1.297 +
1.298 +typedef enum {
1.299 + ocspResponderID_other = -1, /* unknown kind of responderID */
1.300 + ocspResponderID_byName = 1,
1.301 + ocspResponderID_byKey = 2
1.302 +} CERTOCSPResponderIDType;
1.303 +
1.304 +#endif /* _OCSPT_H_ */
