Debian Codegraph @

deps/libneon/src/ne_session.h

raw
1 /*
2 HTTP session handling
3 Copyright (C) 1999-2009, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_SESSION_H
23 #define NE_SESSION_H 1
24
25 #include <sys/types.h>
26
27 #include "ne_ssl.h"
28 #include "ne_uri.h" /* for ne_uri */
29 #include "ne_defs.h"
30 #include "ne_socket.h"
31
32 NE_BEGIN_DECLS
33
34 typedef struct ne_session_s ne_session;
35
36 /* Create a session to the given server, using the given scheme. If
37 * "https" is passed as the scheme, SSL will be used to connect to the
38 * server. */
39 ne_session *ne_session_create(const char *scheme,
40 const char *hostname, unsigned int port);
41
42 /* Finish an HTTP session */
43 void ne_session_destroy(ne_session *sess);
44
45 /* Prematurely force the connection to be closed for the given
46 * session. */
47 void ne_close_connection(ne_session *sess);
48
49 /* Set the proxy server to be used for the session. This function
50 * will override (remove) any proxy servers previously configured, and
51 * must be called before any requests are created using this
52 * session. */
53 void ne_session_proxy(ne_session *sess,
54 const char *hostname, unsigned int port);
55
56 /* Configure a SOCKS proxy server which will be used for the session.
57 * The SOCKS protocol version 'vers' will be used to contact the
58 * proxy at given 'hostname' and 'port'.
59 *
60 * If SOCKSv4 or v4a are used, username must be non-NULL. For v5,
61 * username may be NULL, in which case, password is ignored. If
62 * username is non-NULL, password must also be non-NULL.
63 *
64 * This function will override (remove) any proxy servers previously
65 * configured, and must be called before any requests are created
66 * using this session. */
67 void ne_session_socks_proxy(ne_session *sess, enum ne_sock_sversion vers,
68 const char *hostname, unsigned int port,
69 const char *username, const char *password);
70
71 /* Configure use of proxy servers from any system-wide default sources
72 * which are configured at build time. This function will override
73 * (remove) any proxy servers previously configured, and must be
74 * called before any requests are created using this session. The
75 * 'flags' parameter must be zero. */
76 void ne_session_system_proxy(ne_session *sess, unsigned int flags);
77
78 /* Defined session flags: */
79 typedef enum ne_session_flag_e {
80 NE_SESSFLAG_PERSIST = 0, /* disable this flag to prevent use of
81 * persistent connections. */
82
83 NE_SESSFLAG_ICYPROTO, /* enable this flag to enable support for
84 * non-HTTP ShoutCast-style "ICY" responses. */
85
86 NE_SESSFLAG_SSLv2, /* disable this flag to disable support for
87 * SSLv2, if supported by the SSL library. */
88
89 NE_SESSFLAG_RFC4918, /* enable this flag to enable support for
90 * RFC4918-only WebDAV features; losing
91 * backwards-compatibility with RFC2518
92 * servers. */
93
94 NE_SESSFLAG_CONNAUTH, /* enable this flag if an awful, broken,
95 * RFC-violating, connection-based HTTP
96 * authentication scheme is in use. */
97
98 NE_SESSFLAG_TLS_SNI, /* disable this flag to disable use of the
99 * TLS Server Name Indication extension. */
100
101 NE_SESSFLAG_EXPECT100, /* enable this flag to enable the flag
102 * NE_REQFLAG_EXPECT100 for new requests. */
103
104 NE_SESSFLAG_LAST /* enum sentinel value */
105 } ne_session_flag;
106
107 /* Set a new value for a particular session flag. */
108 void ne_set_session_flag(ne_session *sess, ne_session_flag flag, int value);
109
110 /* Return 0 if the given flag is not set, >0 it is set, or -1 if the
111 * flag is not supported. */
112 int ne_get_session_flag(ne_session *sess, ne_session_flag flag);
113
114 /* Bypass the normal name resolution; force the use of specific set of
115 * addresses for this session, addrs[0]...addrs[n-1]. The 'addrs'
116 * array and pointed-to objects must remain valid until the session is
117 * destroyed. This function will override (remove) any proxy servers
118 * previously configured, and must be called before any requests are
119 * created using this session. */
120 void ne_set_addrlist(ne_session *sess, const ne_inet_addr **addrs, size_t n);
121
122 /* Bind connections to the specified local address. If the address
123 * determined for the remote host has a different family (type) to
124 * 'addr', 'addr' will be ignored. The 'addr' object must remain
125 * valid until the session is destroyed. */
126 void ne_set_localaddr(ne_session *sess, const ne_inet_addr *addr);
127
128 /* DEPRECATED: Progress callback. */
129 typedef void (*ne_progress)(void *userdata, ne_off_t progress, ne_off_t total);
130
131 /* DEPRECATED API: Set a progress callback for the session; this is
132 * deprecated in favour of ne_set_notifier(). The progress callback
133 * is invoked for after each block of the request and response body to
134 * indicate request and response progress (there is no way to
135 * distinguish between the two using this interface alone).
136 * If progress is NULL, any existing callback is deregistered and will
137 * no longer be invoked.
138 *
139 * NOTE: Use of this interface is mutually exclusive with the use of
140 * ne_set_notifier(). A call to ne_set_progress() removes the
141 * notifier callback, and vice versa. */
142 void ne_set_progress(ne_session *sess, ne_progress progress, void *userdata);
143
144 /* Store an opaque context for the session, 'priv' is returned by a
145 * call to ne_session_get_private with the same ID. */
146 void ne_set_session_private(ne_session *sess, const char *id, void *priv);
147 void *ne_get_session_private(ne_session *sess, const char *id);
148
149 /* Status event type. NOTE: More event types may be added in
150 * subsequent releases, so callers must ignore unknown status types
151 * for forwards-compatibility. */
152 typedef enum {
153 ne_status_lookup = 0, /* looking up hostname */
154 ne_status_connecting, /* connecting to host */
155 ne_status_connected, /* connected to host */
156 ne_status_sending, /* sending a request body */
157 ne_status_recving, /* receiving a response body */
158 ne_status_disconnected /* disconnected from host */
159 } ne_session_status;
160
161 /* Status event information union; the relevant structure within
162 * corresponds to the event type. WARNING: the size of this union is
163 * not limited by ABI constraint; it may be extended with additional
164 * members of different size, or existing members may be extended. */
165 typedef union ne_session_status_info_u {
166 struct /* ne_status_lookup */ {
167 /* The hostname which is being resolved: */
168 const char *hostname;
169 } lu;
170 struct /* ne_status_connecting */ {
171 /* The hostname and network address to which a connection
172 * attempt is being made: */
173 const char *hostname;
174 const ne_inet_addr *address;
175 } ci;
176 struct /* ne_status_connected, ne_status_disconnected */ {
177 /* The hostname to which a connection has just been
178 * established or closed: */
179 const char *hostname;
180 } cd;
181 struct /* ne_status_sending and ne_status_recving */ {
182 /* Request/response body transfer progress; if total == -1,
183 * the total size is unknown; otherwise, total gives the total
184 * number of bytes which will be transferred. progress gives
185 * the number of bytes transferred so far. */
186 ne_off_t progress, total;
187 } sr;
188 } ne_session_status_info;
189
190 /* Callback invoked to notify a new session status event, given by the
191 * 'status' argument. On invocation, the contents of exactly one of
192 * the structures in the info union will be valid, as indicated
193 * above. */
194 typedef void (*ne_notify_status)(void *userdata, ne_session_status status,
195 const ne_session_status_info *info);
196
197 /* Set a status notification callback for the session, to report
198 * session status events. Only one notification callback per session
199 * can be registered; the most recent of successive calls to this
200 * function takes effect. If status is NULL, any existing callback
201 * is deregistered and will no longer be invoked.
202 *
203 * NOTE: Use of this interface is mutually exclusive with the use of
204 * ne_set_progress(). A call to ne_set_notifier() removes the
205 * progress callback, and vice versa. */
206 void ne_set_notifier(ne_session *sess, ne_notify_status status, void *userdata);
207
208 /* Certificate verification failures. */
209
210 /* NE_SSL_NOTYETVALID: the certificate is not yet valid. */
211 #define NE_SSL_NOTYETVALID (0x01)
212
213 /* NE_SSL_EXPIRED: the certificate has expired. */
214 #define NE_SSL_EXPIRED (0x02)
215
216 /* NE_SSL_IDMISMATCH: the hostname for which the certificate was
217 * issued does not match the hostname of the server; this could mean
218 * that the connection is being intercepted. */
219 #define NE_SSL_IDMISMATCH (0x04)
220
221 /* NE_SSL_UNTRUSTED: the certificate authority which signed the server
222 * certificate is not trusted: there is no indicatation the server is
223 * who they claim to be: */
224 #define NE_SSL_UNTRUSTED (0x08)
225
226 /* NE_SSL_BADCHAIN: the certificate chain contained a certificate
227 * other than the server cert which failed verification for a reason
228 * other than lack of trust; for example, due to a CA cert being
229 * outside its validity period. */
230 #define NE_SSL_BADCHAIN (0x10)
231
232 /* N.B.: 0x20 is reserved. */
233
234 /* NE_SSL_REVOKED: the server certificate has been revoked by the
235 * issuing authority. */
236 #define NE_SSL_REVOKED (0x40)
237
238 /* For purposes of forwards-compatibility, the bitmask of all
239 * currently exposed failure bits is given as NE_SSL_FAILMASK. If the
240 * expression (failures & ~NE_SSL_FAILMASK) is non-zero a failure type
241 * is present which the application does not recognize but must treat
242 * as a verification failure nonetheless. */
243 #define NE_SSL_FAILMASK (0x5f)
244
245 /* A callback which is used when server certificate verification is
246 * needed. The reasons for verification failure are given in the
247 * 'failures' parameter, which is a binary OR of one or more of the
248 * above NE_SSL_* values. failures is guaranteed to be non-zero. The
249 * callback must return zero to accept the certificate: a non-zero
250 * return value will fail the SSL negotiation. */
251 typedef int (*ne_ssl_verify_fn)(void *userdata, int failures,
252 const ne_ssl_certificate *cert);
253
254 /* Install a callback to handle server certificate verification. This
255 * is required when the CA certificate is not known for the server
256 * certificate, or the server cert has other verification problems. */
257 void ne_ssl_set_verify(ne_session *sess, ne_ssl_verify_fn fn, void *userdata);
258
259 /* Use the given client certificate for the session. The client cert
260 * MUST be in the decrypted state, otherwise behaviour is undefined.
261 * The 'clicert' object is duplicated internally so can be destroyed
262 * by the caller. */
263 void ne_ssl_set_clicert(ne_session *sess, const ne_ssl_client_cert *clicert);
264
265 /* Indicate that the certificate 'cert' is trusted; the 'cert' object
266 * is duplicated internally so can be destroyed by the caller. This
267 * function has no effect for non-SSL sessions. */
268 void ne_ssl_trust_cert(ne_session *sess, const ne_ssl_certificate *cert);
269
270
271 /* If the SSL library provided a default set of CA certificates, trust
272 * this set of CAs. */
273 void ne_ssl_trust_default_ca(ne_session *sess);
274
275 /* load all the CA certificates in the directory 'path' and considers
276 * them as trusted
277 * return 0 if success */
278 int ne_ssl_truse_add_ca_path(ne_session* sess, const char* path);
279
280 /* Callback used to load a client certificate on demand. If dncount
281 * is > 0, the 'dnames' array dnames[0] through dnames[dncount-1]
282 * gives the list of CA names which the server indicated were
283 * acceptable. The callback should load an appropriate client
284 * certificate and then pass it to 'ne_ssl_set_clicert'. */
285 typedef void (*ne_ssl_provide_fn)(void *userdata, ne_session *sess,
286 const ne_ssl_dname *const *dnames,
287 int dncount);
288
289 /* Register a function to be called when the server requests a client
290 * certificate. */
291 void ne_ssl_provide_clicert(ne_session *sess,
292 ne_ssl_provide_fn fn, void *userdata);
293
294 /* Set the timeout (in seconds) used when reading from a socket. The
295 * timeout value must be greater than zero. */
296 void ne_set_read_timeout(ne_session *sess, int timeout);
297
298 /* Set the timeout (in seconds) used when making a connection. The
299 * timeout value must be greater than zero. */
300 void ne_set_connect_timeout(ne_session *sess, int timeout);
301
302 /* Sets the user-agent string. neon/VERSION will be appended, to make
303 * the full header "User-Agent: product neon/VERSION".
304 * If this function is not called, the User-Agent header is not sent.
305 * The product string must follow the RFC2616 format, i.e.
306 * product = token ["/" product-version]
307 * product-version = token
308 * where token is any alpha-numeric-y string [a-zA-Z0-9]* */
309 void ne_set_useragent(ne_session *sess, const char *product);
310
311 /* Returns non-zero if next-hop server does not claim compliance to
312 * HTTP/1.1 or later. */
313 int ne_version_pre_http11(ne_session *sess);
314
315 /* Returns the 'hostport' URI segment for the end-server, e.g.
316 * "my.server.com:8080". */
317 const char *ne_get_server_hostport(ne_session *sess);
318
319 /* Returns the URL scheme being used for the current session, omitting
320 * the trailing ':'; e.g. "http" or "https". */
321 const char *ne_get_scheme(ne_session *sess);
322
323 /* Sets the host, scheme, and port fields of the given URI structure
324 * to that of the configured server and scheme for the session; host
325 * and scheme are malloc-allocated. No other fields in the URI
326 * structure are changed. */
327 void ne_fill_server_uri(ne_session *sess, ne_uri *uri);
328
329 /* If a proxy is configured, sets the host and port fields in the
330 * given URI structure to that of the proxy. If multiple proxies are
331 * configured, the active is used if any, otherwise the first. The
332 * hostname is malloc-allocated. No other fields in the URI structure
333 * are changed; if no proxy is configured or a non-HTTP proxy is in
334 * use, no fields are changed. */
335 void ne_fill_proxy_uri(ne_session *sess, ne_uri *uri);
336
337 /* Set the error string for the session; takes printf-like format
338 * string. */
339 void ne_set_error(ne_session *sess, const char *format, ...)
340 ne_attribute((format (printf, 2, 3)));
341
342 /* Retrieve the error string for the session */
343 const char *ne_get_error(ne_session *sess);
344
345 NE_END_DECLS
346
347 #endif /* NE_SESSION_H */