Back to index

lightning-sunbird  0.9+nobinonly
ocspt.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * Public header for exported OCSP types.
00039  *
00040  * $Id: ocspt.h,v 1.4.28.2 2006/02/03 20:24:21 kaie%kuix.de Exp $
00041  */
00042 
00043 #ifndef _OCSPT_H_
00044 #define _OCSPT_H_
00045 
00046 /*
00047  * The following are all opaque types.  If someone needs to get at
00048  * a field within, then we need to fix the API.  Try very hard not
00049  * make the type available to them.
00050  */
00051 typedef struct CERTOCSPRequestStr CERTOCSPRequest;
00052 typedef struct CERTOCSPResponseStr CERTOCSPResponse;
00053 
00054 /*
00055  * XXX I think only those first two above should need to be exported,
00056  * but until I know for certain I am leaving the rest of these here, too.
00057  */
00058 typedef struct CERTOCSPCertIDStr CERTOCSPCertID;
00059 typedef struct CERTOCSPCertStatusStr CERTOCSPCertStatus;
00060 typedef struct CERTOCSPSingleResponseStr CERTOCSPSingleResponse;
00061 
00062 /*
00063  * This interface is described in terms of an HttpClient which
00064  * supports at least a specified set of functions. (An implementer may
00065  * provide HttpClients with additional functionality accessible only to
00066  * users with a particular implementation in mind.) The basic behavior
00067  * is provided by defining a set of functions, listed in an
00068  * SEC_HttpServerFcnStruct. If the implementor of a SpecificHttpClient
00069  * registers his SpecificHttpClient as the default HttpClient, then his
00070  * functions will be called by the user of an HttpClient, such as an
00071  * OCSPChecker.
00072  *
00073  * The implementer of a specific HttpClient (e.g., the NSS-provided
00074  * DefaultHttpClient), populates an SEC_HttpClientFcnStruct, uses it to
00075  * register his client, and waits for his functions to be called.
00076  *
00077  * For future expandability, the SEC_HttpClientFcnStruct is defined as a
00078  * union, with the version field acting as a selector. The proposed
00079  * initial version of the structure is given following the definition
00080  * of the union. The HttpClientState structure is implementation-
00081  * dependent, and should be opaque to the user.
00082  */
00083 
00084 typedef void * SEC_HTTP_SERVER_SESSION;
00085 typedef void * SEC_HTTP_REQUEST_SESSION;
00086 
00087 /*
00088  * This function creates a SEC_HTTP_SERVER_SESSION object. The implementer of a
00089  * specific HttpClient will allocate the necessary space, when this
00090  * function is called, and will free it when the corresponding FreeFcn
00091  * is called. The SEC_HTTP_SERVER_SESSION object is passed, as an opaque object,
00092  * to subsequent calls.
00093  *
00094  * If the function returns SECSuccess, the returned SEC_HTTP_SERVER_SESSION
00095  * must be cleaned up with a call to SEC_HttpServer_FreeSession,
00096  * after processing is finished.
00097  */
00098 typedef SECStatus (*SEC_HttpServer_CreateSessionFcn)(
00099    const char *host,
00100    PRUint16 portnum,
00101    SEC_HTTP_SERVER_SESSION *pSession);
00102 
00103 /*
00104  * This function is called to allow the implementation to attempt to keep
00105  * the connection alive. Depending on the underlying platform, it might
00106  * immediately return SECSuccess without having performed any operations.
00107  * (If a connection has not been kept alive, a subsequent call to
00108  * SEC_HttpRequest_TrySendAndReceiveFcn should reopen the connection
00109  * automatically.)
00110  *
00111  * If the connection uses nonblocking I/O, this function may return
00112  * SECWouldBlock and store a nonzero value at "pPollDesc". In that case
00113  * the caller may wait on the poll descriptor, and should call this function
00114  * again until SECSuccess (and a zero value at "pPollDesc") is obtained.
00115  */ 
00116 typedef SECStatus (*SEC_HttpServer_KeepAliveSessionFcn)(
00117    SEC_HTTP_SERVER_SESSION session,
00118    PRPollDesc **pPollDesc);
00119 
00120 /*
00121  * This function frees the client SEC_HTTP_SERVER_SESSION object, closes all
00122  * SEC_HTTP_REQUEST_SESSIONs created for that server, discards all partial results,
00123  * frees any memory that was allocated by the client, and invalidates any
00124  * response pointers that might have been returned by prior server or request
00125  * functions.
00126  */ 
00127 typedef SECStatus (*SEC_HttpServer_FreeSessionFcn)(
00128    SEC_HTTP_SERVER_SESSION session);
00129 
00130 /*
00131  * This function creates a SEC_HTTP_REQUEST_SESSION object. The implementer of a
00132  * specific HttpClient will allocate the necessary space, when this
00133  * function is called, and will free it when the corresponding FreeFcn
00134  * is called. The SEC_HTTP_REQUEST_SESSION object is passed, as an opaque object,
00135  * to subsequent calls.
00136  *
00137  * An implementation that does not support the requested protocol variant
00138  * (usually "http", but could eventually allow "https") or request method
00139  * should return SECFailure.
00140  *
00141  * Timeout values may include the constants PR_INTERVAL_NO_TIMEOUT (wait
00142  * forever) or PR_INTERVAL_NO_WAIT (nonblocking I/O).
00143  *
00144  * If the function returns SECSuccess, the returned SEC_HTTP_REQUEST_SESSION
00145  * must be cleaned up with a call to SEC_HttpRequest_FreeSession,
00146  * after processing is finished.
00147  */
00148 typedef SECStatus (*SEC_HttpRequest_CreateFcn)(
00149    SEC_HTTP_SERVER_SESSION session,
00150    const char *http_protocol_variant, /* usually "http" */
00151    const char *path_and_query_string,
00152    const char *http_request_method, 
00153    const PRIntervalTime timeout, 
00154    SEC_HTTP_REQUEST_SESSION *pRequest);
00155 
00156 /*
00157  * This function sets data to be sent to the server for an HTTP request
00158  * of http_request_method == POST. If a particular implementation 
00159  * supports it, the details for the POST request can be set by calling 
00160  * this function, prior to activating the request with TrySendAndReceiveFcn.
00161  *
00162  * An implementation that does not support the POST method should 
00163  * implement a SetPostDataFcn function that returns immediately.
00164  *
00165  * Setting http_content_type is optional, the parameter may
00166  * by NULL or the empty string.
00167  */ 
00168 typedef SECStatus (*SEC_HttpRequest_SetPostDataFcn)(
00169    SEC_HTTP_REQUEST_SESSION request,
00170    const char *http_data, 
00171    const PRUint32 http_data_len,
00172    const char *http_content_type);
00173 
00174 /*
00175  * This function sets an additional HTTP protocol request header.
00176  * If a particular implementation supports it, one or multiple headers
00177  * can be added to the request by calling this function once or multiple
00178  * times, prior to activating the request with TryFcn.
00179  *
00180  * An implementation that does not support setting additional headers
00181  * should implement an AddRequestHeaderFcn function that returns immediately.
00182  */ 
00183 typedef SECStatus (*SEC_HttpRequest_AddHeaderFcn)(
00184    SEC_HTTP_REQUEST_SESSION request,
00185    const char *http_header_name, 
00186    const char *http_header_value);
00187 
00188 /*
00189  * This function initiates or continues an HTTP request. After
00190  * parameters have been set with the Create function and, optionally,
00191  * modified or enhanced with the AddParams function, this call creates
00192  * the socket connection and initiates the communication.
00193  *
00194  * If a timeout value of zero is specified, indicating non-blocking
00195  * I/O, the client creates a non-blocking socket, and returns a status
00196  * of SECWouldBlock and a non-NULL PRPollDesc if the operation is not
00197  * complete. In that case all other return parameters are undefined.
00198  * The caller is expected to repeat the call, possibly after using
00199  * PRPoll to determine that a completion has occurred, until a return
00200  * value of SECSuccess (and a NULL value for pPollDesc) or a return
00201  * value of SECFailure (indicating failure on the network level)
00202  * is obtained.
00203  *
00204  * http_response_data_len is both input and output parameter.
00205  * If a pointer to a PRUint32 is supplied, the http client is
00206  * expected to check the given integer value and always set an out
00207  * value, even on failure.
00208  * An input value of zero means, the caller will accept any response len.
00209  * A different input value indicates the maximum response value acceptable
00210  * to the caller.
00211  * If data is successfully read and the size is acceptable to the caller,
00212  * the function will return SECSuccess and set http_response_data_len to
00213  * the size of the block returned in http_response_data.
00214  * If the data read from the http server is larger than the acceptable
00215  * size, the function will return SECFailure.
00216  * http_response_data_len will be set to a value different from zero to
00217  * indicate the reason of the failure.
00218  * An out value of "0" means, the failure was unrelated to the 
00219  * acceptable size.
00220  * An out value of "1" means, the result data is larger than the
00221  * accpeptable size, but the real size is not yet known to the http client 
00222  * implementation and it stopped retrieving it,
00223  * Any other out value combined with a return value of SECFailure
00224  * will indicate the actual size of the server data.
00225  *
00226  * The caller is permitted to provide NULL values for any of the
00227  * http_response arguments, indicating the caller is not interested in
00228  * those values. If the caller does provide an address, the HttpClient
00229  * stores at that address a pointer to the corresponding argument, at
00230  * the completion of the operation.
00231  *
00232  * All returned pointers will be owned by the the HttpClient
00233  * implementation and will remain valid until the call to 
00234  * SEC_HttpRequest_FreeFcn.
00235  */ 
00236 typedef SECStatus (*SEC_HttpRequest_TrySendAndReceiveFcn)(
00237    SEC_HTTP_REQUEST_SESSION request,
00238    PRPollDesc **pPollDesc,
00239    PRUint16 *http_response_code, 
00240    const char **http_response_content_type, 
00241    const char **http_response_headers, 
00242    const char **http_response_data, 
00243    PRUint32 *http_response_data_len); 
00244 
00245 /*
00246  * Calling CancelFcn asks for premature termination of the request.
00247  *
00248  * Future calls to SEC_HttpRequest_TrySendAndReceive should
00249  * by avoided, but in this case the HttpClient implementation 
00250  * is expected to return immediately with SECFailure.
00251  *
00252  * After calling CancelFcn, a separate call to SEC_HttpRequest_FreeFcn 
00253  * is still necessary to free resources.
00254  */ 
00255 typedef SECStatus (*SEC_HttpRequest_CancelFcn)(
00256    SEC_HTTP_REQUEST_SESSION request);
00257 
00258 /*
00259  * Before calling this function, it must be assured the request
00260  * has been completed, i.e. either SEC_HttpRequest_TrySendAndReceiveFcn has
00261  * returned SECSuccess, or the request has been canceled with
00262  * a call to SEC_HttpRequest_CancelFcn.
00263  * 
00264  * This function frees the client state object, closes all sockets, 
00265  * discards all partial results, frees any memory that was allocated 
00266  * by the client, and invalidates all response pointers that might
00267  * have been returned by SEC_HttpRequest_TrySendAndReceiveFcn
00268  */ 
00269 typedef SECStatus (*SEC_HttpRequest_FreeFcn)(
00270    SEC_HTTP_REQUEST_SESSION request);
00271 
00272 typedef struct SEC_HttpClientFcnV1Struct {
00273    SEC_HttpServer_CreateSessionFcn createSessionFcn;
00274    SEC_HttpServer_KeepAliveSessionFcn keepAliveSessionFcn;
00275    SEC_HttpServer_FreeSessionFcn freeSessionFcn;
00276    SEC_HttpRequest_CreateFcn createFcn;
00277    SEC_HttpRequest_SetPostDataFcn setPostDataFcn;
00278    SEC_HttpRequest_AddHeaderFcn addHeaderFcn;
00279    SEC_HttpRequest_TrySendAndReceiveFcn trySendAndReceiveFcn;
00280    SEC_HttpRequest_CancelFcn cancelFcn;
00281    SEC_HttpRequest_FreeFcn freeFcn;
00282 } SEC_HttpClientFcnV1;
00283 
00284 typedef struct SEC_HttpClientFcnStruct {
00285    PRInt16 version;
00286    union {
00287       SEC_HttpClientFcnV1 ftable1;
00288       /* SEC_HttpClientFcnV2 ftable2; */
00289       /* ...                      */
00290    } fcnTable;
00291 } SEC_HttpClientFcn;
00292 
00293 #endif /* _OCSPT_H_ */