Authentication verification interface. More...
#include <sofia-sip/su_tag.h>#include <sofia-sip/su_wait.h>#include <sofia-sip/msg_types.h>#include <sofia-sip/url.h>#include <sofia-sip/url_tag.h>
Go to the source code of this file.
Data Structures | |
| struct | auth_status_t |
| Authentication operation result. More... | |
| struct | auth_challenger |
| Authentication challenge. More... | |
Defines | |
| #define | AUTH_MODULE_H |
| Defined when <sofia-sip/auth_module.h> has been included. | |
| #define | AUTHTAG_ANY() |
| Filter tag matching any AUTHTAG_*(). | |
| #define | AUTHTAG_MODULE(x) |
| Pointer to an authentication server (auth_mod_t). | |
| #define | AUTHTAG_METHOD(x) |
| Authentication scheme used by authentication module. | |
| #define | AUTHTAG_REALM(x) |
| Authentication realm used by authentication server. | |
| #define | AUTHTAG_OPAQUE(x) |
| Opaque authentication data always included in challenge. | |
| #define | AUTHTAG_DB(x) |
| Name of authentication database used by authentication server. | |
| #define | AUTHTAG_QOP(x) |
| Quality-of-protection used by digest authentication. | |
| #define | AUTHTAG_ALGORITHM(x) |
| Algorithm used by digest authentication. | |
| #define | AUTHTAG_EXPIRES(x) |
| Nonce lifetime. | |
| #define | AUTHTAG_NEXT_EXPIRES(x) |
| Lifetime for nextnonce, 0 disables nextnonce. | |
| #define | AUTHTAG_MAX_NCOUNT(x) |
| Maximum nonce count allowed. | |
| #define | AUTHTAG_BLACKLIST(x) |
| Extra delay when responding if provided invalid credentials or nonce. | |
| #define | AUTHTAG_FORBIDDEN(x) |
| Respond with 403 Forbidden if given invalid credentials. | |
| #define | AUTHTAG_ANONYMOUS(x) |
| Allow anonymous access. | |
| #define | AUTHTAG_HSS(x) |
| HSS client structure. | |
| #define | AUTHTAG_REMOTE(x) |
| Remote authenticator URL. | |
| #define | AUTHTAG_ALLOW(x) |
| Comma-separated list of methods never challenged. | |
| #define | AUTHTAG_FAKE(x) |
| Check that user exists, don't do authentication. | |
| #define | AUTHTAG_MASTER_KEY(x) |
| Master key in base64 for the authentication module. | |
| #define | AUTHTAG_CACHE_USERS(x) |
| Cache time for authentication data. | |
| #define | AUTHTAG_CACHE_ERRORS(x) |
| Cache time for errors. | |
Typedefs | |
| typedef struct auth_status_t | auth_status_t |
| Authentication operation. | |
| typedef struct auth_scheme const | auth_scheme_t |
| Virtual table for authentication plugin. | |
| typedef struct auth_plugin_t | auth_plugin_t |
| Opaque data used by authentication plugin module. | |
| typedef struct auth_splugin_t | auth_splugin_t |
| Opaque user data used by plugin module. | |
| typedef struct auth_uplugin_t | auth_uplugin_t |
| Opaque authentication operation data used by plugin module. | |
| typedef void | auth_callback_t (auth_magic_t *, auth_status_t *) |
| Callback from completeted asynchronous authentication operation. | |
| typedef struct auth_challenger | auth_challenger_t |
| Authentication challenge. | |
Functions | |
| int | auth_mod_register_plugin (auth_scheme_t *asch) |
| Register an authentication plugin. | |
| auth_mod_t * | auth_mod_create (su_root_t *root, tag_type_t, tag_value_t,...) |
| Create an authentication plugin module. | |
| void | auth_mod_destroy (auth_mod_t *) |
| Destroy (a reference to) an authentication module. | |
| auth_mod_t * | auth_mod_ref (auth_mod_t *am) |
| Create a new reference to authentication module. | |
| void | auth_mod_unref (auth_mod_t *am) |
| Destroy a reference to an authentication module. | |
| char const * | auth_mod_name (auth_mod_t *am) |
| Get authenticatin module name. | |
| void | auth_mod_verify (auth_mod_t *am, auth_status_t *as, msg_auth_t *credentials, auth_challenger_t const *ach) |
| Authenticate user. | |
| void | auth_mod_challenge (auth_mod_t *am, auth_status_t *as, auth_challenger_t const *ach) |
| Make a challenge header. | |
| void | auth_mod_cancel (auth_mod_t *am, auth_status_t *as) |
| Cancel asynchronous authentication. | |
Authentication verification interface.
| #define AUTH_MODULE_H |
Defined when <sofia-sip/auth_module.h> has been included.
| #define AUTHTAG_ALGORITHM | ( | x | ) |
Algorithm used by digest authentication.
Authentication algorithm used by Digest authentication.
The tag AUTHTAG_ALGORITHM() specifies the qop scheme to be used by the digest authentication.
| #define AUTHTAG_ALLOW | ( | x | ) |
Comma-separated list of methods never challenged.
Comma-separated list of methods that are not challenged.
The tag AUTHTAG_ALLOW() takes its argument a string containing a comma-separated list of methods, for example,
AUTHTAG_ALLOW("ACK, BYE, CANCEL").
The specified methods are not challenged by the authentication module. For example, this may include SIP ACK method or SIP methods only used within an already established dialog.
| #define AUTHTAG_ANONYMOUS | ( | x | ) |
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.
| #define AUTHTAG_BLACKLIST | ( | x | ) |
Extra delay when responding if provided invalid credentials or nonce.
Blacklist time.
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.
| #define AUTHTAG_CACHE_ERRORS | ( | x | ) |
Cache time for errors.
Time to cache errors.
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.
| #define AUTHTAG_CACHE_USERS | ( | x | ) |
Cache time for authentication data.
Time to cache user data.
The tag AUTHTAG_CACHE_USERS() specifies how many seconds the user data is cached locally. Default value is typically 30 minutes.
| #define AUTHTAG_DB | ( | x | ) |
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:
user:password:realm
| #define AUTHTAG_EXPIRES | ( | x | ) |
Nonce lifetime.
Nonce expiration time for Digest authentication.
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.
| #define AUTHTAG_FAKE | ( | x | ) |
Check that user exists, don't do authentication.
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.
| #define AUTHTAG_FORBIDDEN | ( | x | ) |
Respond with 403 Forbidden if given invalid credentials.
Respond with 403 Forbidden.
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.
| #define AUTHTAG_HSS | ( | x | ) |
HSS client structure.
| #define AUTHTAG_MASTER_KEY | ( | x | ) |
Master key in base64 for the authentication module.
Private master key for the authentication module.
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).
| #define AUTHTAG_MAX_NCOUNT | ( | x | ) |
Maximum nonce count allowed.
Max nonce count value.
The tag AUTHTAG_MAX_NCOUNT() specifies the maximum number of times a nonce should be used.
| #define AUTHTAG_METHOD | ( | x | ) |
Authentication scheme used by authentication module.
Name of the authentication scheme.
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, like "SGMF+Digest".
| #define AUTHTAG_MODULE | ( | x | ) |
Pointer to an authentication server (auth_mod_t).
Pointer to an authentication server module (auth_mod_t).
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).
| #define AUTHTAG_NEXT_EXPIRES | ( | x | ) |
Lifetime for nextnonce, 0 disables nextnonce.
Next nonce expiration time for Digest authentication.
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.
| #define AUTHTAG_OPAQUE | ( | x | ) |
Opaque authentication data always included in challenge.
Opaque data used by authentication server.
The tag authtag_opaque is used to pass opaque data to the auth_module. 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.
Default Value "".
| #define AUTHTAG_QOP | ( | x | ) |
Quality-of-protection used by digest authentication.
Quality-of-protection used by Digest authentication.
The tag AUTHTAG_QOP() specifies the qop scheme to be used by the digest authentication.
| #define AUTHTAG_REALM | ( | x | ) |
Authentication realm used by authentication server.
The tag authtag_method specifies the authentication realm used by the 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 "*". Only the first asterisk is replaced by request domain name.
Default Value "*".
| #define AUTHTAG_REMOTE | ( | x | ) |
Remote authenticator URL.
The tag AUTHTAG_REMOTE() is used to specify URL for remote authenticator. The meaning of the URL is specific to the authentication module. The authentication module is selected by AUTHTAG_METHOD().
| typedef void auth_callback_t(auth_magic_t *, auth_status_t *) |
Callback from completeted asynchronous authentication operation.
| typedef struct auth_challenger auth_challenger_t |
Authentication challenge.
This structure defines what kind of response and challenge header is returned to the user. For example, a server authentication is implemented with 401 response code and phrase along with header class for WWW-Authenticate header in the ach structure.
| typedef struct auth_plugin_t auth_plugin_t |
Opaque data used by authentication plugin module.
| typedef struct auth_scheme const auth_scheme_t |
Virtual table for authentication plugin.
| typedef struct auth_splugin_t auth_splugin_t |
Opaque user data used by plugin module.
| typedef struct auth_status_t auth_status_t |
Authentication operation.
| typedef struct auth_uplugin_t auth_uplugin_t |
Opaque authentication operation data used by plugin module.
| void auth_mod_cancel | ( | auth_mod_t * | am, | |
| auth_status_t * | as | |||
| ) |
Cancel asynchronous authentication.
The auth_mod_cancel() function cancels a pending authentication. Application can reclaim the authentication status, credential and challenger objects by using auth_mod_cancel().
| void auth_mod_challenge | ( | auth_mod_t * | am, | |
| auth_status_t * | as, | |||
| auth_challenger_t const * | ach | |||
| ) |
Make a challenge header.
This function invokes plugin-specific member function generating a challenge header. Client uses the challenge header contents when prompting the user for a username and password then generates its credential header using the parameters given in the challenge header.
| am | pointer to authentication module object | |
| as | pointer to authentication status structure (return-value) | |
| ach | pointer to a structure describing challenge |
The auth_mod_challenge() returns the challenge header, appropriate response code and reason phrase in the auth_status_t structure. The auth_mod_challenge() is currently always synchronous function.
| auth_mod_t* auth_mod_create | ( | su_root_t * | root, | |
| tag_type_t | tag, | |||
| tag_value_t | value, | |||
| ... | ||||
| ) |
Create an authentication plugin module.
The function auth_mod_create() creates a module used to authenticate the requests.
| root | pointer to a su_root_t object | |
| tag,value,... | tagged argument list |
| void auth_mod_destroy | ( | auth_mod_t * | am | ) |
Destroy (a reference to) an authentication module.
| char const* auth_mod_name | ( | auth_mod_t * | am | ) |
Get authenticatin module name.
| auth_mod_t* auth_mod_ref | ( | auth_mod_t * | am | ) |
Create a new reference to authentication module.
| int auth_mod_register_plugin | ( | auth_scheme_t * | asch | ) |
Register an authentication plugin.
| 0 | when successful | |
| -1 | upon an error |
| void auth_mod_unref | ( | auth_mod_t * | am | ) |
Destroy a reference to an authentication module.
| void auth_mod_verify | ( | auth_mod_t * | am, | |
| auth_status_t * | as, | |||
| msg_auth_t * | credentials, | |||
| auth_challenger_t const * | ach | |||
| ) |
Authenticate user.
The function auth_mod_method() invokes scheme-specific authentication operation where the user's credentials are checked using scheme-specific method. The authentication result along with an optional challenge header is stored in the as structure.
| am | pointer to authentication module object [in] | |
| as | pointer to authentication status structure [in/out] | |
| credentials | pointer to a header with user's credentials [in] | |
| ach | pointer to a structure describing challenge [in] |
The ach structure defines what kind of response and challenge header is returned to the user. For example, a server authentication is implemented with 401 response code and phrase along with WWW-Authenticate header template in the ach structure.
The auth_mod_method() returns the authentication result in the auth_mod_t as structure. The as->as_status describes the result as follows:
When the authentication is left pending, the client must set the as_callback pointer in as structure to an appropriate callback function. The callback is invoked when the authentication is completed, either successfully or with an error.
Note that the authentication module may generate a new challenge each time authentication is used (e.g., Digest using MD5 algorithm). Such a challenge header is stored in the as->as_response return-value field.