index.rst (5638B)
1 .. _mozilla_projects_nss_http_delegation: 2 3 HTTP delegation 4 =============== 5 6 `Background <#background>`__ 7 ---------------------------- 8 9 .. container:: 10 11 Up to version 3.11, :ref:`mozilla_projects_nss` connects directly over 12 `HTTP <https://developer.mozilla.org/en-US/docs/Web/HTTP>`__ to an OCSP responder to make the 13 request and fetch the response. It does so in a blocking fashion, and also directly to the 14 responder, ignoring any proxy the application may wish to use. This causes OCSP requests to fail 15 if the network environment requires the use of a proxy. 16 17 There are two possible solutions to this limitation. Instead of improving the simple HTTP client 18 in NSS, the NSS team has decided to provide an NSS API to register application callback 19 functions. If provided by the application, NSS will use the registered HTTP client for querying 20 an OSCP responder. 21 22 This NSS feature is currently targeted to first appear in NSS version 3.11.1. More details can be 23 found in `bug 152426 <https://bugzilla.mozilla.org/show_bug.cgi?id=152426>`__. 24 25 In order to use the HTTP Delegation feature in your NSS-based application, you need to implement 26 several callback functions. Your callback functions might be a full implementation of a HTTP 27 client. Or you might choose to leverage an existing HTTP client library and implement the 28 callback functions as a thin layer that forwards requests from NSS to the HTTP client library. 29 30 To learn about all the details, please read the documentation contained in the NSS C header 31 files. Look for function SEC_RegisterDefaultHttpClient and all functions having names that start 32 with SEC_Http. 33 34 To find an example implementation, you may look at 35 `bug 111384 <https://bugzilla.mozilla.org/show_bug.cgi?id=111384>`__, which tracks the 36 implementation in Mozilla client applications. 37 38 .. _instructions_for_specifying_an_ocsp_proxy: 39 40 `Specifying an OCSP proxy <#instructions_for_specifying_an_ocsp_proxy>`__ 41 ------------------------------------------------------------------------- 42 43 .. container:: 44 45 The remainder of this document is a short HOWTO. 46 47 One might expect the API defines a simple function that accepts the URI and data to be sent, and 48 returns the result data. But there is no such simple interface. 49 50 The API should allow NSS to use the HTTP client either asynchronously or synchronously. In 51 addition, during an application session with OCSP enabled, a large number of OCSP requests might 52 have to be sent. Therefore the API should allow for keep-alive (persistent) HTTP connections. 53 54 HTTP URIs consist of host:port and a path, e.g. 55 http://ocsp.provider.com:80/cgi-bin/ocsp-responder 56 57 If NSS needs to access a HTTP server, it will request that an "http server session object" be 58 created (SEC_HttpServer_CreateSessionFcn). 59 60 The http server session object is logically associated with host and port destination 61 information, in our example this is "host ocsp.provider.com port 80". The object may be used by 62 the application to associate it with a physical network connection. 63 64 (NSS might choose to be smart, and only create a single http server session object for each 65 server encountered. NSS might also choose to be simple, and request multiple objects for the same 66 server. The application must support both strategies.) 67 68 The logical http server session object is expected to remain valid until explicitly destroyed 69 (SEC_HttpServer_FreeSessionFcn). Should the application be unable to keep a physical connection 70 alive all the time, the application is expected to create new connections automatically. 71 72 NSS may choose to repeatedly call a "network connection keep alive" function 73 (SEC_HttpServer_KeepAliveSessionFcn) on the server session object, giving application code a 74 chance to do whatever is required. 75 76 For each individual HTTP request, NSS will request the creation of a "http request object" 77 (SEC_HttpRequest_CreateFcn). No full URI is provided as a parameter. Instead, the parameters are 78 a server session object (that carries host and port information already) and the request path. In 79 our example the path is "/cgi-bin/ocsp-responder". (When issueing GET requests, the 80 "?query-string=data" portion should already be appended to the request path) 81 82 After creation, NSS might call functions to provide additional details of the HTTP request (e.g. 83 SEC_HttpRequest_SetPostDataFcn). The application is expected to collect the details for later 84 use. 85 86 Once NSS is finished providing all details, it will request to initiate the actual network 87 communication (SEC_HttpRequest_TrySendAndReceiveFcn). The application should try to reuse 88 existing network connections associated with the server session object. 89 90 Once the HTTP response has been obtained from the HTTP server, the function will provide the 91 results in its "out parameters". 92 93 Please read the source code documentation to learn how to use this API synchronously or 94 asynchronously. 95 96 Now that we have explained the interaction between NSS, the callback functions and the 97 application, let's look at the steps required by the application to initially register the 98 callbacks. 99 100 Make sure you have completed the NSS initialization before you attempt to register the callbacks. 101 102 Look at SEC_HttpClientFcn, which is a (versioned) table of function pointers. Create an instance 103 of this type and supply a pointer to your implementation for each entry in the function table. 104 105 Finally register your HTTP client implementation with a call to SEC_RegisterDefaultHttpClient.