| /* 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. |
| */ |
| |
| #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_ */ |