auth_tag.c 7.98 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7
/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

/**@CFILE auth_tag.c
 * @brief Tags for authentication verification module for NTA servers.
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>.
 *
 * @date Created: Wed Apr 11 15:14:03 2001 ppessi
 */

#include "config.h"

#define TAG_NAMESPACE "auth"

37
#include "sofia-sip/auth_module.h"
Pekka Pessi's avatar
Pekka Pessi committed
38

39 40
#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/url_tag_class.h>
Pekka Pessi's avatar
Pekka Pessi committed
41

42
/**@def AUTHTAG_ANY()
43
 *
44 45 46 47
 * Filter tag matching any AUTHTAG_*().
 */
tag_typedef_t authtag_any = NSTAG_TYPEDEF(*);

Pekka Pessi's avatar
Pekka Pessi committed
48
/**@def AUTHTAG_MODULE()
49 50
 *
 * Pointer to an authentication server module (auth_mod_t).
Pekka Pessi's avatar
Pekka Pessi committed
51 52 53 54 55 56 57 58 59 60
 *
 * The tag item AUTHTAG_MODULE() contains pointer to an authentication server
 * module. It is used to pass an already initialized authentication module
 * to a server object (like web server or registrar object).
 */
tag_typedef_t authtag_module = PTRTAG_TYPEDEF(module);

/**@def AUTHTAG_METHOD()
 *
 * Name of the authentication scheme.
61
 *
Pekka Pessi's avatar
Pekka Pessi committed
62 63 64
 * The tag AUTHTAG_METHOD() specifies the authentication module and scheme
 * to be used by the auth_module. The name can specify a basic
 * authentication module, like "Digest" or "Basic", or an plugin module,
65
 * like "SGMF+Digest".
Pekka Pessi's avatar
Pekka Pessi committed
66
 *
67
 * @sa See <sofia-sip/auth_plugin.h> for plugin interface.
Pekka Pessi's avatar
Pekka Pessi committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
 */
tag_typedef_t authtag_method = STRTAG_TYPEDEF(method);

/**@def AUTHTAG_REALM()
 *
 * Authentication realm used by authentication server.
 *
 * The tag authtag_method specifies the authentication realm used by the @b
 * auth_module.  For servers, the domain name in the request URI is inserted
 * in the realm returned to the client if the realm string contains an
 * asterisk @c "*".  Only the first asterisk is replaced by request domain
 * name.
 *
 * @p Default Value
 * "*".
 */
tag_typedef_t authtag_realm = STRTAG_TYPEDEF(realm);

/**@def AUTHTAG_OPAQUE()
 *
 * Opaque data used by authentication server.
 *
90
 * The tag authtag_opaque is used to pass opaque data to the @b auth_module.
Pekka Pessi's avatar
Pekka Pessi committed
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
 * The opaque data will be included in all the challenges (however, the data
 * is prefixed with a "." and other opaque data used by the algorithms.
 *
 * @p Default Value
 * "".
 */
tag_typedef_t authtag_opaque = STRTAG_TYPEDEF(opaque);

/**@def AUTHTAG_DB()
 *
 * Name of authentication database used by authentication server.
 *
 * The tag AUTHTAG_DB() specifies the file name used to store the
 * authentication data. The file contains triplets as follows:
 *
 * @code
 * user:password:realm
 * @endcode
 *
 * @note
 * Currently, the passwords are stored as plaintext.
 */
tag_typedef_t authtag_db = STRTAG_TYPEDEF(db);

/**@def AUTHTAG_QOP()
 *
 * Quality-of-protection used by Digest authentication.
118
 *
Pekka Pessi's avatar
Pekka Pessi committed
119 120 121 122 123 124 125 126
 * The tag AUTHTAG_QOP() specifies the qop scheme to be used by the
 * digest authentication.
 */
tag_typedef_t authtag_qop = STRTAG_TYPEDEF(qop);

/**@def AUTHTAG_ALGORITHM()
 *
 * Authentication algorithm used by Digest authentication.
127
 *
Pekka Pessi's avatar
Pekka Pessi committed
128 129 130 131 132 133 134 135
 * The tag AUTHTAG_ALGORITHM() specifies the qop scheme to be used by the
 * digest authentication.
 */
tag_typedef_t authtag_algorithm = STRTAG_TYPEDEF(algorithm);

/**@def AUTHTAG_EXPIRES()
 *
 * Nonce expiration time for Digest authentication.
136
 *
Pekka Pessi's avatar
Pekka Pessi committed
137 138 139 140 141 142 143 144 145
 * The tag AUTHTAG_EXPIRES() specifies the time in seconds that a nonce is
 * considered valid. If 0, the nonce lifetime unbounded. The default time is
 * 3600 seconds.
 */
tag_typedef_t authtag_expires = UINTTAG_TYPEDEF(expires);

/**@def AUTHTAG_NEXT_EXPIRES()
 *
 * Next nonce expiration time for Digest authentication.
146
 *
Pekka Pessi's avatar
Pekka Pessi committed
147 148 149 150 151 152
 * The tag AUTHTAG_NEXT_EXPIRES() specifies the time in seconds that a
 * nextnonce sent in Authentication-Info header is considered valid. If 0,
 * the nonce lifetime is unbounded. The default time is 3600 seconds.
 */
tag_typedef_t authtag_next_expires = UINTTAG_TYPEDEF(next_expires);

153 154 155
/**@def AUTHTAG_MAX_NCOUNT()
 *
 * Max nonce count value.
156
 *
157
 * The tag AUTHTAG_MAX_NCOUNT() specifies the maximum number of times a
158
 * nonce should be used.
159 160 161 162 163
 *
 * @todo Count actual usages and don't trust "nc" parameter only.
 */
tag_typedef_t authtag_max_ncount = UINTTAG_TYPEDEF(max_ncount);

Pekka Pessi's avatar
Pekka Pessi committed
164 165 166
/**@def AUTHTAG_BLACKLIST()
 *
 * Blacklist time.
167
 *
Pekka Pessi's avatar
Pekka Pessi committed
168 169 170 171 172 173 174 175 176 177 178
 * The tag AUTHTAG_BLACKLIST() specifies the time the server delays its
 * response if it is given bad credentials or malformed nonce. The default
 * time is 5 seconds.
 *
 * @todo Implement delayed response.
 */
tag_typedef_t authtag_blacklist = UINTTAG_TYPEDEF(blacklist);

/**@def AUTHTAG_FORBIDDEN()
 *
 * Respond with 403 Forbidden.
179
 *
Pekka Pessi's avatar
Pekka Pessi committed
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
 * When given a true argument, the tag AUTHTAG_FORBIDDEN() specifies that the
 * server responds with 403 Forbidden (instead of 401/407) when it receives
 * bad credentials.
 */
tag_typedef_t authtag_forbidden = BOOLTAG_TYPEDEF(forbidden);

/**@def AUTHTAG_ANONYMOUS()
 *
 * Allow anonymous access.
 *
 * When given a true argument, the tag AUTHTAG_ANONYMOUS() allows
 * authentication module to accept the account "anonymous" with an empty
 * password. The auth_status_t::as_anonymous flag is set in auth_status_t
 * structure after anonymous authentication.
 */
tag_typedef_t authtag_anonymous = BOOLTAG_TYPEDEF(anonymous);

/**@def AUTHTAG_FAKE()
 *
 * Fake authentication process.
 *
 * When given a true argument, the tag AUTHTAG_FAKE() causes authentication
 * module to allow access with any password when the username is valid. The
 * auth_status_t::as_fake flag is set in auth_status_t structure after a
 * fake authentication.
 */
tag_typedef_t authtag_fake = BOOLTAG_TYPEDEF(fake);

/**@def AUTHTAG_REMOTE()
 *
 * Remote authenticator URL.
211 212
 *
 * The tag AUTHTAG_REMOTE() is used to specify URL for remote authenticator.
Pekka Pessi's avatar
Pekka Pessi committed
213 214 215 216 217 218 219
 * The meaning of the URL is specific to the authentication module. The
 * authentication module is selected by AUTHTAG_METHOD().
 */
tag_typedef_t authtag_remote = URLTAG_TYPEDEF(remote);

/**@def AUTHTAG_ALLOW()
 *
220 221
 * Comma-separated list of methods that are not challenged.
 *
Pekka Pessi's avatar
Pekka Pessi committed
222 223 224 225 226 227
 * The tag AUTHTAG_ALLOW() takes its argument a string containing a
 * comma-separated list of methods, for example,
 * @code
 * AUTHTAG_ALLOW("ACK, BYE, CANCEL").
 * @endcode
 *
228
 * The specified methods are not challenged by the authentication module.
Pekka Pessi's avatar
Pekka Pessi committed
229 230 231 232 233 234 235 236
 * For example, this may include SIP ACK method or SIP methods only used
 * within an already established dialog.
 */
tag_typedef_t authtag_allow = STRTAG_TYPEDEF(allow);

/**@def AUTHTAG_MASTER_KEY()
 *
 * Private master key for the authentication module.
237
 *
Pekka Pessi's avatar
Pekka Pessi committed
238 239 240 241 242 243 244 245 246
 * The tag AUTHTAG_MASTER_KEY() specifies a private master key that can be
 * used by the authentication module for various purposes (for instance,
 * validating that nonces are really generated by it).
 */
tag_typedef_t authtag_master_key = STRTAG_TYPEDEF(master_key);

/**@def AUTHTAG_CACHE_USERS()
 *
 * Time to cache user data.
247
 *
Pekka Pessi's avatar
Pekka Pessi committed
248 249 250 251 252 253 254 255
 * The tag AUTHTAG_CACHE_USERS() specifies how many seconds the user data is
 * cached locally. Default value is typically 30 minutes.
 */
tag_typedef_t authtag_cache_users = UINTTAG_TYPEDEF(cache_users);

/**@def AUTHTAG_CACHE_ERRORS()
 *
 * Time to cache errors.
256
 *
Pekka Pessi's avatar
Pekka Pessi committed
257 258 259 260 261 262 263
 * The tag AUTHTAG_CACHE_ERRORS() specifies the lifetime in seconds for
 * errors in the local authentication data cache. Note that the errors
 * generated locally (e.g., because of connectivity problem with
 * authentication server) have maximum lifetime of 2 minutes.
 */
tag_typedef_t authtag_cache_errors = UINTTAG_TYPEDEF(cache_errors);