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