PageRenderTime 104ms CodeModel.GetById 60ms app.highlight 9ms RepoModel.GetById 31ms app.codeStats 0ms

/gecko_api/include/ocspt.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 316 lines | 68 code | 19 blank | 229 comment | 0 complexity | f98f96f59691122deef69a627a72d939 MD5 | raw file
  1/* ***** BEGIN LICENSE BLOCK *****
  2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3 *
  4 * The contents of this file are subject to the Mozilla Public License Version
  5 * 1.1 (the "License"); you may not use this file except in compliance with
  6 * the License. You may obtain a copy of the License at
  7 * http://www.mozilla.org/MPL/
  8 *
  9 * Software distributed under the License is distributed on an "AS IS" basis,
 10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 11 * for the specific language governing rights and limitations under the
 12 * License.
 13 *
 14 * The Original Code is the Netscape security libraries.
 15 *
 16 * The Initial Developer of the Original Code is
 17 * Netscape Communications Corporation.
 18 * Portions created by the Initial Developer are Copyright (C) 1994-2000
 19 * the Initial Developer. All Rights Reserved.
 20 *
 21 * Contributor(s):
 22 *
 23 * Alternatively, the contents of this file may be used under the terms of
 24 * either the GNU General Public License Version 2 or later (the "GPL"), or
 25 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 26 * in which case the provisions of the GPL or the LGPL are applicable instead
 27 * of those above. If you wish to allow use of your version of this file only
 28 * under the terms of either the GPL or the LGPL, and not to allow others to
 29 * use your version of this file under the terms of the MPL, indicate your
 30 * decision by deleting the provisions above and replace them with the notice
 31 * and other provisions required by the GPL or the LGPL. If you do not delete
 32 * the provisions above, a recipient may use your version of this file under
 33 * the terms of any one of the MPL, the GPL or the LGPL.
 34 *
 35 * ***** END LICENSE BLOCK ***** */
 36
 37/*
 38 * Public header for exported OCSP types.
 39 *
 40 * $Id: ocspt.h,v 1.9 2007/03/23 06:57:57 kaie%kuix.de Exp $
 41 */
 42
 43#ifndef _OCSPT_H_
 44#define _OCSPT_H_
 45
 46/*
 47 * The following are all opaque types.  If someone needs to get at
 48 * a field within, then we need to fix the API.  Try very hard not
 49 * make the type available to them.
 50 */
 51typedef struct CERTOCSPRequestStr CERTOCSPRequest;
 52typedef struct CERTOCSPResponseStr CERTOCSPResponse;
 53
 54/*
 55 * XXX I think only those first two above should need to be exported,
 56 * but until I know for certain I am leaving the rest of these here, too.
 57 */
 58typedef struct CERTOCSPCertIDStr CERTOCSPCertID;
 59typedef struct CERTOCSPCertStatusStr CERTOCSPCertStatus;
 60typedef struct CERTOCSPSingleResponseStr CERTOCSPSingleResponse;
 61
 62/*
 63 * This interface is described in terms of an HttpClient which
 64 * supports at least a specified set of functions. (An implementer may
 65 * provide HttpClients with additional functionality accessible only to
 66 * users with a particular implementation in mind.) The basic behavior
 67 * is provided by defining a set of functions, listed in an
 68 * SEC_HttpServerFcnStruct. If the implementor of a SpecificHttpClient
 69 * registers his SpecificHttpClient as the default HttpClient, then his
 70 * functions will be called by the user of an HttpClient, such as an
 71 * OCSPChecker.
 72 *
 73 * The implementer of a specific HttpClient (e.g., the NSS-provided
 74 * DefaultHttpClient), populates an SEC_HttpClientFcnStruct, uses it to
 75 * register his client, and waits for his functions to be called.
 76 *
 77 * For future expandability, the SEC_HttpClientFcnStruct is defined as a
 78 * union, with the version field acting as a selector. The proposed
 79 * initial version of the structure is given following the definition
 80 * of the union. The HttpClientState structure is implementation-
 81 * dependent, and should be opaque to the user.
 82 */
 83
 84typedef void * SEC_HTTP_SERVER_SESSION;
 85typedef void * SEC_HTTP_REQUEST_SESSION;
 86
 87/*
 88 * This function creates a SEC_HTTP_SERVER_SESSION object. The implementer of a
 89 * specific HttpClient will allocate the necessary space, when this
 90 * function is called, and will free it when the corresponding FreeFcn
 91 * is called. The SEC_HTTP_SERVER_SESSION object is passed, as an opaque object,
 92 * to subsequent calls.
 93 *
 94 * If the function returns SECSuccess, the returned SEC_HTTP_SERVER_SESSION
 95 * must be cleaned up with a call to SEC_HttpServer_FreeSession,
 96 * after processing is finished.
 97 */
 98typedef SECStatus (*SEC_HttpServer_CreateSessionFcn)(
 99   const char *host,
100   PRUint16 portnum,
101   SEC_HTTP_SERVER_SESSION *pSession);
102
103/*
104 * This function is called to allow the implementation to attempt to keep
105 * the connection alive. Depending on the underlying platform, it might
106 * immediately return SECSuccess without having performed any operations.
107 * (If a connection has not been kept alive, a subsequent call to
108 * SEC_HttpRequest_TrySendAndReceiveFcn should reopen the connection
109 * automatically.)
110 *
111 * If the connection uses nonblocking I/O, this function may return
112 * SECWouldBlock and store a nonzero value at "pPollDesc". In that case
113 * the caller may wait on the poll descriptor, and should call this function
114 * again until SECSuccess (and a zero value at "pPollDesc") is obtained.
115 */ 
116typedef SECStatus (*SEC_HttpServer_KeepAliveSessionFcn)(
117   SEC_HTTP_SERVER_SESSION session,
118   PRPollDesc **pPollDesc);
119
120/*
121 * This function frees the client SEC_HTTP_SERVER_SESSION object, closes all
122 * SEC_HTTP_REQUEST_SESSIONs created for that server, discards all partial results,
123 * frees any memory that was allocated by the client, and invalidates any
124 * response pointers that might have been returned by prior server or request
125 * functions.
126 */ 
127typedef SECStatus (*SEC_HttpServer_FreeSessionFcn)(
128   SEC_HTTP_SERVER_SESSION session);
129
130/*
131 * This function creates a SEC_HTTP_REQUEST_SESSION object. The implementer of a
132 * specific HttpClient will allocate the necessary space, when this
133 * function is called, and will free it when the corresponding FreeFcn
134 * is called. The SEC_HTTP_REQUEST_SESSION object is passed, as an opaque object,
135 * to subsequent calls.
136 *
137 * An implementation that does not support the requested protocol variant
138 * (usually "http", but could eventually allow "https") or request method
139 * should return SECFailure.
140 *
141 * Timeout values may include the constants PR_INTERVAL_NO_TIMEOUT (wait
142 * forever) or PR_INTERVAL_NO_WAIT (nonblocking I/O).
143 *
144 * If the function returns SECSuccess, the returned SEC_HTTP_REQUEST_SESSION
145 * must be cleaned up with a call to SEC_HttpRequest_FreeSession,
146 * after processing is finished.
147 */
148typedef SECStatus (*SEC_HttpRequest_CreateFcn)(
149   SEC_HTTP_SERVER_SESSION session,
150   const char *http_protocol_variant, /* usually "http" */
151   const char *path_and_query_string,
152   const char *http_request_method, 
153   const PRIntervalTime timeout, 
154   SEC_HTTP_REQUEST_SESSION *pRequest);
155
156/*
157 * This function sets data to be sent to the server for an HTTP request
158 * of http_request_method == POST. If a particular implementation 
159 * supports it, the details for the POST request can be set by calling 
160 * this function, prior to activating the request with TrySendAndReceiveFcn.
161 *
162 * An implementation that does not support the POST method should 
163 * implement a SetPostDataFcn function that returns immediately.
164 *
165 * Setting http_content_type is optional, the parameter may
166 * by NULL or the empty string.
167 */ 
168typedef SECStatus (*SEC_HttpRequest_SetPostDataFcn)(
169   SEC_HTTP_REQUEST_SESSION request,
170   const char *http_data, 
171   const PRUint32 http_data_len,
172   const char *http_content_type);
173
174/*
175 * This function sets an additional HTTP protocol request header.
176 * If a particular implementation supports it, one or multiple headers
177 * can be added to the request by calling this function once or multiple
178 * times, prior to activating the request with TryFcn.
179 *
180 * An implementation that does not support setting additional headers
181 * should implement an AddRequestHeaderFcn function that returns immediately.
182 */ 
183typedef SECStatus (*SEC_HttpRequest_AddHeaderFcn)(
184   SEC_HTTP_REQUEST_SESSION request,
185   const char *http_header_name, 
186   const char *http_header_value);
187
188/*
189 * This function initiates or continues an HTTP request. After
190 * parameters have been set with the Create function and, optionally,
191 * modified or enhanced with the AddParams function, this call creates
192 * the socket connection and initiates the communication.
193 *
194 * If a timeout value of zero is specified, indicating non-blocking
195 * I/O, the client creates a non-blocking socket, and returns a status
196 * of SECWouldBlock and a non-NULL PRPollDesc if the operation is not
197 * complete. In that case all other return parameters are undefined.
198 * The caller is expected to repeat the call, possibly after using
199 * PRPoll to determine that a completion has occurred, until a return
200 * value of SECSuccess (and a NULL value for pPollDesc) or a return
201 * value of SECFailure (indicating failure on the network level)
202 * is obtained.
203 *
204 * http_response_data_len is both input and output parameter.
205 * If a pointer to a PRUint32 is supplied, the http client is
206 * expected to check the given integer value and always set an out
207 * value, even on failure.
208 * An input value of zero means, the caller will accept any response len.
209 * A different input value indicates the maximum response value acceptable
210 * to the caller.
211 * If data is successfully read and the size is acceptable to the caller,
212 * the function will return SECSuccess and set http_response_data_len to
213 * the size of the block returned in http_response_data.
214 * If the data read from the http server is larger than the acceptable
215 * size, the function will return SECFailure.
216 * http_response_data_len will be set to a value different from zero to
217 * indicate the reason of the failure.
218 * An out value of "0" means, the failure was unrelated to the 
219 * acceptable size.
220 * An out value of "1" means, the result data is larger than the
221 * accpeptable size, but the real size is not yet known to the http client 
222 * implementation and it stopped retrieving it,
223 * Any other out value combined with a return value of SECFailure
224 * will indicate the actual size of the server data.
225 *
226 * The caller is permitted to provide NULL values for any of the
227 * http_response arguments, indicating the caller is not interested in
228 * those values. If the caller does provide an address, the HttpClient
229 * stores at that address a pointer to the corresponding argument, at
230 * the completion of the operation.
231 *
232 * All returned pointers will be owned by the the HttpClient
233 * implementation and will remain valid until the call to 
234 * SEC_HttpRequest_FreeFcn.
235 */ 
236typedef SECStatus (*SEC_HttpRequest_TrySendAndReceiveFcn)(
237   SEC_HTTP_REQUEST_SESSION request,
238   PRPollDesc **pPollDesc,
239   PRUint16 *http_response_code, 
240   const char **http_response_content_type, 
241   const char **http_response_headers, 
242   const char **http_response_data, 
243   PRUint32 *http_response_data_len); 
244
245/*
246 * Calling CancelFcn asks for premature termination of the request.
247 *
248 * Future calls to SEC_HttpRequest_TrySendAndReceive should
249 * by avoided, but in this case the HttpClient implementation 
250 * is expected to return immediately with SECFailure.
251 *
252 * After calling CancelFcn, a separate call to SEC_HttpRequest_FreeFcn 
253 * is still necessary to free resources.
254 */ 
255typedef SECStatus (*SEC_HttpRequest_CancelFcn)(
256   SEC_HTTP_REQUEST_SESSION request);
257
258/*
259 * Before calling this function, it must be assured the request
260 * has been completed, i.e. either SEC_HttpRequest_TrySendAndReceiveFcn has
261 * returned SECSuccess, or the request has been canceled with
262 * a call to SEC_HttpRequest_CancelFcn.
263 * 
264 * This function frees the client state object, closes all sockets, 
265 * discards all partial results, frees any memory that was allocated 
266 * by the client, and invalidates all response pointers that might
267 * have been returned by SEC_HttpRequest_TrySendAndReceiveFcn
268 */ 
269typedef SECStatus (*SEC_HttpRequest_FreeFcn)(
270   SEC_HTTP_REQUEST_SESSION request);
271
272typedef struct SEC_HttpClientFcnV1Struct {
273   SEC_HttpServer_CreateSessionFcn createSessionFcn;
274   SEC_HttpServer_KeepAliveSessionFcn keepAliveSessionFcn;
275   SEC_HttpServer_FreeSessionFcn freeSessionFcn;
276   SEC_HttpRequest_CreateFcn createFcn;
277   SEC_HttpRequest_SetPostDataFcn setPostDataFcn;
278   SEC_HttpRequest_AddHeaderFcn addHeaderFcn;
279   SEC_HttpRequest_TrySendAndReceiveFcn trySendAndReceiveFcn;
280   SEC_HttpRequest_CancelFcn cancelFcn;
281   SEC_HttpRequest_FreeFcn freeFcn;
282} SEC_HttpClientFcnV1;
283
284typedef struct SEC_HttpClientFcnStruct {
285   PRInt16 version;
286   union {
287      SEC_HttpClientFcnV1 ftable1;
288      /* SEC_HttpClientFcnV2 ftable2; */
289      /* ...                      */
290   } fcnTable;
291} SEC_HttpClientFcn;
292
293/*
294 * ocspMode_FailureIsVerificationFailure:
295 * This is the classic behaviour of NSS.
296 * Any OCSP failure is a verification failure (classic mode, default).
297 * Without a good response, OCSP networking will be retried each time
298 * it is required for verifying a cert.
299 *
300 * ocspMode_FailureIsNotAVerificationFailure:
301 * If we fail to obtain a valid OCSP response, consider the
302 * cert as good.
303 * Failed OCSP attempts might get cached and not retried until
304 * minimumSecondsToNextFetchAttempt.
305 * If we are able to obtain a valid response, the cert
306 * will be considered good, if either status is "good"
307 * or the cert was not yet revoked at verification time.
308 *
309 * Additional failure modes might be added in the future.
310 */
311typedef enum {
312    ocspMode_FailureIsVerificationFailure = 0,
313    ocspMode_FailureIsNotAVerificationFailure = 1
314} SEC_OcspFailureMode;
315
316#endif /* _OCSPT_H_ */