| 1 |
/* |
| 2 |
HTTP authentication routines |
| 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_AUTH_H |
| 23 |
#define NE_AUTH_H |
| 24 |
|
| 25 |
#include "ne_session.h" /* for ne_session */ |
| 26 |
|
| 27 |
NE_BEGIN_DECLS |
| 28 |
|
| 29 |
/* Size of username/password buffers passed to ne_auth_creds |
| 30 |
* callback. */ |
| 31 |
#define NE_ABUFSIZ (256) |
| 32 |
|
| 33 |
/* The callback used to request the username and password in the given |
| 34 |
* realm. The username and password must be copied into the buffers |
| 35 |
* which are both of size NE_ABUFSIZ. The 'attempt' parameter is zero |
| 36 |
* on the first call to the callback, and increases by one each time |
| 37 |
* an attempt to authenticate fails. |
| 38 |
* |
| 39 |
* The callback must return zero to indicate that authentication |
| 40 |
* should be attempted with the username/password, or non-zero to |
| 41 |
* cancel the request. (if non-zero, username and password are |
| 42 |
* ignored.) |
| 43 |
* |
| 44 |
* IMPORTANT NOTE: The callback will be invoked repeatedly until |
| 45 |
* either it returns non-zero, or authentication is successful. |
| 46 |
* |
| 47 |
* Hint: if you just wish to attempt authentication just once (even if |
| 48 |
* the user gets the username/password wrong), have the callback |
| 49 |
* function use 'attempt' value as the function return value. */ |
| 50 |
typedef int (*ne_auth_creds)(void *userdata, const char *realm, int attempt, |
| 51 |
char *username, char *password); |
| 52 |
|
| 53 |
/* Set callbacks to provide credentials for server and proxy |
| 54 |
* authentication, using the default set of authentication protocols. |
| 55 |
* userdata is passed as the first argument to the callback. */ |
| 56 |
void ne_set_server_auth(ne_session *sess, ne_auth_creds creds, void *userdata); |
| 57 |
void ne_set_proxy_auth(ne_session *sess, ne_auth_creds creds, void *userdata); |
| 58 |
|
| 59 |
/* As an alternative to using ne_set_server_auth and |
| 60 |
* ne_set_proxy_auth, the following interfaces may be used; these |
| 61 |
* allow control over which authentication protocol is used. */ |
| 62 |
|
| 63 |
/* NE_AUTH_BASIC: Basic authentication transmits the username and |
| 64 |
* password unprotected over the channel; this allows a passive attack |
| 65 |
* to steal the credentials if using an unsecured channel |
| 66 |
* (i.e. non-SSL). */ |
| 67 |
#define NE_AUTH_BASIC (0x0001) |
| 68 |
|
| 69 |
/* NE_AUTH_DIGEST: Digest authentication uses a hash of the username, |
| 70 |
* password, and certain aspects of the request, so prevents passive |
| 71 |
* attackers from obtaining the credentials; active attackers can |
| 72 |
* still modify most of the request/response if using an unsecured |
| 73 |
* channel. */ |
| 74 |
#define NE_AUTH_DIGEST (0x0002) |
| 75 |
|
| 76 |
/* NE_AUTH_NEGOTIATE: Negotiate uses GSSAPI/SSPI, or NTLM, to |
| 77 |
* authenticate the user; an active attacker can modify any of the |
| 78 |
* request/response at will, so this must not be used over an |
| 79 |
* unsecured channel. NE_AUTH_NEGOTIATE is currently equivalent to |
| 80 |
* use of (NE_AUTH_GSSAPI | NE_AUTH_NTLM). */ |
| 81 |
#define NE_AUTH_NEGOTIATE (0x0004) |
| 82 |
|
| 83 |
/* NE_AUTH_GSSAPI: Use GSSAPI or SSPI to authenticate the user; an |
| 84 |
* active attacker can modify any of the request/response at will, so |
| 85 |
* this must not be used over an unsecured channel. */ |
| 86 |
#define NE_AUTH_GSSAPI (0x0008) |
| 87 |
|
| 88 |
/* NE_AUTH_NTLM: Use NTLM to authenticate the user; an active attacker |
| 89 |
* can modify any of the request/response at will, so this must not be |
| 90 |
* used over an unsecured channel. */ |
| 91 |
#define NE_AUTH_NTLM (0x0010) |
| 92 |
|
| 93 |
/* The default set of supported protocols, as deemed appropriate for |
| 94 |
* the given session scheme. */ |
| 95 |
#define NE_AUTH_DEFAULT (0x1000) |
| 96 |
|
| 97 |
/* All protocols supported by the library. */ |
| 98 |
#define NE_AUTH_ALL (0x2000) |
| 99 |
|
| 100 |
/* Add a callback to provide credentials for server and proxy |
| 101 |
* authentication using a particular auth protocol or set of |
| 102 |
* protocols. The protocol is supplied as a bitmask of NE_AUTH_* |
| 103 |
* values. For NE_AUTH_NEGOTIATE, the creds and userdata arguments |
| 104 |
* are ignored and may be NULL. |
| 105 |
* |
| 106 |
* These functions may be called multiple times per session to |
| 107 |
* register callbacks for different protocols. If the server presents |
| 108 |
* more than one protocol in an auth challenge, the following |
| 109 |
* algorithm will be used to determine which callback is used: |
| 110 |
* |
| 111 |
* - iterate over the registered callbacks in the order registered |
| 112 |
* - for each each callback, iterate over the known set of protocols |
| 113 |
* in order of algorithm strength (strongest first). |
| 114 |
* - if the protocol mask for that callback matches the protocol, |
| 115 |
* attempt authentication using this protocol. |
| 116 |
* |
| 117 |
* Therefore, if multiple calls to ne_add_server_auth or |
| 118 |
* ne_add_proxy_auth are used for a given session, the caller must |
| 119 |
* ensure that the order in which those calls are made reflects the |
| 120 |
* precedence of protocols to be used. */ |
| 121 |
void ne_add_server_auth(ne_session *sess, unsigned protocol, |
| 122 |
ne_auth_creds creds, void *userdata); |
| 123 |
void ne_add_proxy_auth(ne_session *sess, unsigned protocol, |
| 124 |
ne_auth_creds creds, void *userdata); |
| 125 |
|
| 126 |
/* Clear any cached authentication credentials for the given |
| 127 |
* session. */ |
| 128 |
void ne_forget_auth(ne_session *sess); |
| 129 |
|
| 130 |
NE_END_DECLS |
| 131 |
|
| 132 |
#endif /* NE_AUTH_H */ |