DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Untracked file

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
/* 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/. */

/*
 * Public header for exported OCSP types.
 *
 * $Id: ocspt.h,v 1.12 2012/12/12 16:03:44 wtc%google.com Exp $
 */

#ifndef _OCSPT_H_
#define _OCSPT_H_

/*
 * The following are all opaque types.  If someone needs to get at
 * a field within, then we need to fix the API.  Try very hard not
 * make the type available to them.
 */
typedef struct CERTOCSPRequestStr CERTOCSPRequest;
typedef struct CERTOCSPResponseStr CERTOCSPResponse;

/*
 * XXX I think only those first two above should need to be exported,
 * but until I know for certain I am leaving the rest of these here, too.
 */
typedef struct CERTOCSPCertIDStr CERTOCSPCertID;
typedef struct CERTOCSPSingleResponseStr CERTOCSPSingleResponse;

/*
 * This interface is described in terms of an HttpClient which
 * supports at least a specified set of functions. (An implementer may
 * provide HttpClients with additional functionality accessible only to
 * users with a particular implementation in mind.) The basic behavior
 * is provided by defining a set of functions, listed in an
 * SEC_HttpServerFcnStruct. If the implementor of a SpecificHttpClient
 * registers his SpecificHttpClient as the default HttpClient, then his
 * functions will be called by the user of an HttpClient, such as an
 * OCSPChecker.
 *
 * The implementer of a specific HttpClient (e.g., the NSS-provided
 * DefaultHttpClient), populates an SEC_HttpClientFcnStruct, uses it to
 * register his client, and waits for his functions to be called.
 *
 * For future expandability, the SEC_HttpClientFcnStruct is defined as a
 * union, with the version field acting as a selector. The proposed
 * initial version of the structure is given following the definition
 * of the union. The HttpClientState structure is implementation-
 * dependent, and should be opaque to the user.
 */

typedef void * SEC_HTTP_SERVER_SESSION;
typedef void * SEC_HTTP_REQUEST_SESSION;

/*
 * This function creates a SEC_HTTP_SERVER_SESSION object. The implementer of a
 * specific HttpClient will allocate the necessary space, when this
 * function is called, and will free it when the corresponding FreeFcn
 * is called. The SEC_HTTP_SERVER_SESSION object is passed, as an opaque object,
 * to subsequent calls.
 *
 * If the function returns SECSuccess, the returned SEC_HTTP_SERVER_SESSION
 * must be cleaned up with a call to SEC_HttpServer_FreeSession,
 * after processing is finished.
 */
typedef SECStatus (*SEC_HttpServer_CreateSessionFcn)(
   const char *host,
   PRUint16 portnum,
   SEC_HTTP_SERVER_SESSION *pSession);

/*
 * This function is called to allow the implementation to attempt to keep
 * the connection alive. Depending on the underlying platform, it might
 * immediately return SECSuccess without having performed any operations.
 * (If a connection has not been kept alive, a subsequent call to
 * SEC_HttpRequest_TrySendAndReceiveFcn should reopen the connection
 * automatically.)
 *
 * If the connection uses nonblocking I/O, this function may return
 * SECWouldBlock and store a nonzero value at "pPollDesc". In that case
 * the caller may wait on the poll descriptor, and should call this function
 * again until SECSuccess (and a zero value at "pPollDesc") is obtained.
 */ 
typedef SECStatus (*SEC_HttpServer_KeepAliveSessionFcn)(
   SEC_HTTP_SERVER_SESSION session,
   PRPollDesc **pPollDesc);

/*
 * This function frees the client SEC_HTTP_SERVER_SESSION object, closes all
 * SEC_HTTP_REQUEST_SESSIONs created for that server, discards all partial results,
 * frees any memory that was allocated by the client, and invalidates any
 * response pointers that might have been returned by prior server or request
 * functions.
 */ 
typedef SECStatus (*SEC_HttpServer_FreeSessionFcn)(
   SEC_HTTP_SERVER_SESSION session);

/*
 * This function creates a SEC_HTTP_REQUEST_SESSION object. The implementer of a
 * specific HttpClient will allocate the necessary space, when this
 * function is called, and will free it when the corresponding FreeFcn
 * is called. The SEC_HTTP_REQUEST_SESSION object is passed, as an opaque object,
 * to subsequent calls.
 *
 * An implementation that does not support the requested protocol variant
 * (usually "http", but could eventually allow "https") or request method
 * should return SECFailure.
 *
 * Timeout values may include the constants PR_INTERVAL_NO_TIMEOUT (wait
 * forever) or PR_INTERVAL_NO_WAIT (nonblocking I/O).
 *
 * If the function returns SECSuccess, the returned SEC_HTTP_REQUEST_SESSION
 * must be cleaned up with a call to SEC_HttpRequest_FreeSession,
 * after processing is finished.
 */
typedef SECStatus (*SEC_HttpRequest_CreateFcn)(
   SEC_HTTP_SERVER_SESSION session,
   const char *http_protocol_variant, /* usually "http" */
   const char *path_and_query_string,
   const char *http_request_method, 
   const PRIntervalTime timeout, 
   SEC_HTTP_REQUEST_SESSION *pRequest);

/*
 * This function sets data to be sent to the server for an HTTP request
 * of http_request_method == POST. If a particular implementation 
 * supports it, the details for the POST request can be set by calling 
 * this function, prior to activating the request with TrySendAndReceiveFcn.
 *
 * An implementation that does not support the POST method should 
 * implement a SetPostDataFcn function that returns immediately.
 *
 * Setting http_content_type is optional, the parameter may
 * by NULL or the empty string.
 */ 
typedef SECStatus (*SEC_HttpRequest_SetPostDataFcn)(
   SEC_HTTP_REQUEST_SESSION request,
   const char *http_data, 
   const PRUint32 http_data_len,
   const char *http_content_type);

/*
 * This function sets an additional HTTP protocol request header.
 * If a particular implementation supports it, one or multiple headers
 * can be added to the request by calling this function once or multiple
 * times, prior to activating the request with TryFcn.
 *
 * An implementation that does not support setting additional headers
 * should implement an AddRequestHeaderFcn function that returns immediately.
 */ 
typedef SECStatus (*SEC_HttpRequest_AddHeaderFcn)(
   SEC_HTTP_REQUEST_SESSION request,
   const char *http_header_name, 
   const char *http_header_value);

/*
 * This function initiates or continues an HTTP request. After
 * parameters have been set with the Create function and, optionally,
 * modified or enhanced with the AddParams function, this call creates
 * the socket connection and initiates the communication.
 *
 * If a timeout value of zero is specified, indicating non-blocking
 * I/O, the client creates a non-blocking socket, and returns a status
 * of SECWouldBlock and a non-NULL PRPollDesc if the operation is not
 * complete. In that case all other return parameters are undefined.
 * The caller is expected to repeat the call, possibly after using
 * PRPoll to determine that a completion has occurred, until a return
 * value of SECSuccess (and a NULL value for pPollDesc) or a return
 * value of SECFailure (indicating failure on the network level)
 * is obtained.
 *
 * http_response_data_len is both input and output parameter.
 * If a pointer to a PRUint32 is supplied, the http client is
 * expected to check the given integer value and always set an out
 * value, even on failure.
 * An input value of zero means, the caller will accept any response len.
 * A different input value indicates the maximum response value acceptable
 * to the caller.
 * If data is successfully read and the size is acceptable to the caller,
 * the function will return SECSuccess and set http_response_data_len to
 * the size of the block returned in http_response_data.
 * If the data read from the http server is larger than the acceptable
 * size, the function will return SECFailure.
 * http_response_data_len will be set to a value different from zero to
 * indicate the reason of the failure.
 * An out value of "0" means, the failure was unrelated to the 
 * acceptable size.
 * An out value of "1" means, the result data is larger than the
 * accpeptable size, but the real size is not yet known to the http client 
 * implementation and it stopped retrieving it,
 * Any other out value combined with a return value of SECFailure
 * will indicate the actual size of the server data.
 *
 * The caller is permitted to provide NULL values for any of the
 * http_response arguments, indicating the caller is not interested in
 * those values. If the caller does provide an address, the HttpClient
 * stores at that address a pointer to the corresponding argument, at
 * the completion of the operation.
 *
 * All returned pointers will be owned by the the HttpClient
 * implementation and will remain valid until the call to 
 * SEC_HttpRequest_FreeFcn.
 */ 
typedef SECStatus (*SEC_HttpRequest_TrySendAndReceiveFcn)(
   SEC_HTTP_REQUEST_SESSION request,
   PRPollDesc **pPollDesc,
   PRUint16 *http_response_code, 
   const char **http_response_content_type, 
   const char **http_response_headers, 
   const char **http_response_data, 
   PRUint32 *http_response_data_len); 

/*
 * Calling CancelFcn asks for premature termination of the request.
 *
 * Future calls to SEC_HttpRequest_TrySendAndReceive should
 * by avoided, but in this case the HttpClient implementation 
 * is expected to return immediately with SECFailure.
 *
 * After calling CancelFcn, a separate call to SEC_HttpRequest_FreeFcn 
 * is still necessary to free resources.
 */ 
typedef SECStatus (*SEC_HttpRequest_CancelFcn)(
   SEC_HTTP_REQUEST_SESSION request);

/*
 * Before calling this function, it must be assured the request
 * has been completed, i.e. either SEC_HttpRequest_TrySendAndReceiveFcn has
 * returned SECSuccess, or the request has been canceled with
 * a call to SEC_HttpRequest_CancelFcn.
 * 
 * This function frees the client state object, closes all sockets, 
 * discards all partial results, frees any memory that was allocated 
 * by the client, and invalidates all response pointers that might
 * have been returned by SEC_HttpRequest_TrySendAndReceiveFcn
 */ 
typedef SECStatus (*SEC_HttpRequest_FreeFcn)(
   SEC_HTTP_REQUEST_SESSION request);

typedef struct SEC_HttpClientFcnV1Struct {
   SEC_HttpServer_CreateSessionFcn createSessionFcn;
   SEC_HttpServer_KeepAliveSessionFcn keepAliveSessionFcn;
   SEC_HttpServer_FreeSessionFcn freeSessionFcn;
   SEC_HttpRequest_CreateFcn createFcn;
   SEC_HttpRequest_SetPostDataFcn setPostDataFcn;
   SEC_HttpRequest_AddHeaderFcn addHeaderFcn;
   SEC_HttpRequest_TrySendAndReceiveFcn trySendAndReceiveFcn;
   SEC_HttpRequest_CancelFcn cancelFcn;
   SEC_HttpRequest_FreeFcn freeFcn;
} SEC_HttpClientFcnV1;

typedef struct SEC_HttpClientFcnStruct {
   PRInt16 version;
   union {
      SEC_HttpClientFcnV1 ftable1;
      /* SEC_HttpClientFcnV2 ftable2; */
      /* ...                      */
   } fcnTable;
} SEC_HttpClientFcn;

/*
 * ocspMode_FailureIsVerificationFailure:
 * This is the classic behaviour of NSS.
 * Any OCSP failure is a verification failure (classic mode, default).
 * Without a good response, OCSP networking will be retried each time
 * it is required for verifying a cert.
 *
 * ocspMode_FailureIsNotAVerificationFailure:
 * If we fail to obtain a valid OCSP response, consider the
 * cert as good.
 * Failed OCSP attempts might get cached and not retried until
 * minimumSecondsToNextFetchAttempt.
 * If we are able to obtain a valid response, the cert
 * will be considered good, if either status is "good"
 * or the cert was not yet revoked at verification time.
 *
 * Additional failure modes might be added in the future.
 */
typedef enum {
    ocspMode_FailureIsVerificationFailure = 0,
    ocspMode_FailureIsNotAVerificationFailure = 1
} SEC_OcspFailureMode;

/*
 * A ResponderID identifies the responder -- or more correctly, the
 * signer of the response.  The ASN.1 definition of a ResponderID is:
 *
 * ResponderID	::=	CHOICE {
 *	byName			[1] EXPLICIT Name,
 *	byKey			[2] EXPLICIT KeyHash }
 *
 * Because it is CHOICE, the type of identification used and the
 * identification itself are actually encoded together.  To represent
 * this same information internally, we explicitly define a type and
 * save it, along with the value, into a data structure.
 */

typedef enum {
    ocspResponderID_other = -1,		/* unknown kind of responderID */
    ocspResponderID_byName = 1,
    ocspResponderID_byKey = 2
} CERTOCSPResponderIDType;

#endif /* _OCSPT_H_ */