1/*
2   HTTP authentication routines
3   Copyright (C) 1999-2009, Joe Orton <joe@manyfish.co.uk>
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
27NE_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. */
50typedef 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. */
56void ne_set_server_auth(ne_session *sess, ne_auth_creds creds, void *userdata);
57void 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. */
121void ne_add_server_auth(ne_session *sess, unsigned protocol,
122                        ne_auth_creds creds, void *userdata);
123void 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. */
128void ne_forget_auth(ne_session *sess);
129
130NE_END_DECLS
131
132#endif /* NE_AUTH_H */
133