| 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 */ |