sofia-sip/auth_client.h File Reference


Detailed Description

Client-side authenticator library.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Wed Feb 14 17:09:44 2001 ppessi

#include <sofia-sip/msg_types.h>
#include <sofia-sip/url.h>

Include dependency graph for auth_client.h:

Go to the source code of this file.

Typedefs

typedef auth_client_s auth_client_t
 Authenticator object.

Functions

int auc_challenge (auth_client_t **auc, su_home_t *home, msg_auth_t const *auth, msg_hclass_t *crcl)
 Initialize authenticators.
int auc_credentials (auth_client_t **auc, su_home_t *home, char const *data)
 Feed authentication data to the authenticator.
int auc_info (auth_client_t **auc_list, msg_auth_info_t const *ai, msg_hclass_t *credential_class)
 Store authentication info to authenticators.
int auc_all_credentials (auth_client_t **auc_list, char const *scheme, char const *realm, char const *user, char const *pass)
 Feed authentication data to the authenticator.
int auc_clear_credentials (auth_client_t **auc_list, char const *scheme, char const *realm)
 Clear authentication data from the authenticator.
int auc_copy_credentials (auth_client_t **dst, auth_client_t const *src)
 Copy authentication data from src to dst.
int auc_has_authorization (auth_client_t **auc_list)
 Check if we have all required credentials.
int auc_authorization (auth_client_t **auc_list, msg_t *msg, msg_pub_t *pub, char const *method, url_t const *url, msg_payload_t const *body)
 Authorize a request.
int auc_authorization_headers (auth_client_t **auc_list, su_home_t *home, char const *method, url_t const *url, msg_payload_t const *body, msg_header_t **return_headers)
 Generate headers authorizing a request.
int auc_register_plugin (auth_client_plugin_t const *plugin)
 Register an authentication client plugin.


Function Documentation

int auc_all_credentials ( auth_client_t **  auc_list,
char const *  scheme,
char const *  realm,
char const *  user,
char const *  pass 
)

Feed authentication data to the authenticator.

The function auc_credentials() is used to provide the authenticators in with authentication tuple (scheme, realm, user name, secret).

scheme:"realm":user:pass

Todo:
The authentication data format sucks.
Parameters:
[in,out] auc_list list of authenticators
[in] scheme scheme to use (NULL, if any)
[in] realm realm to use (NULL, if any)
[in] user username
[in] pass password
Return values:
number of updated clients
0 when no client was updated
-1 upon an error

int auc_authorization ( auth_client_t **  auc_list,
msg_t msg,
msg_pub_t pub,
char const *  method,
url_t const *  url,
msg_payload_t const *  body 
)

Authorize a request.

The function auc_authorization() is used to add correct authentication headers to a request. The authentication headers will contain the credentials generated by the list of authenticators.

Parameters:
[in,out] auc_list list of authenticators
[out] msg message to be authenticated
[out] pub headers of the message
[in] method request method
[in] url request URI
[in] body message body (NULL if empty)
Return values:
1 when successful
0 when there is not enough credentials
-1 upon an error

int auc_authorization_headers ( auth_client_t **  auc_list,
su_home_t home,
char const *  method,
url_t const *  url,
msg_payload_t const *  body,
msg_header_t **  return_headers 
)

Generate headers authorizing a request.

The function auc_authorization_headers() is used to generate authentication headers for a request. The list of authentication headers will contain the credentials generated by the list of authenticators.

Parameters:
[in] auc_list list of authenticators
[in] home memory home used to allocate headers
[in] method request method
[in] url request URI
[in] body message body (NULL if empty)
[out] return_headers authorization headers return value
Return values:
1 when successful
0 when there is not enough credentials
-1 upon an error

int auc_challenge ( auth_client_t **  auc_list,
su_home_t home,
msg_auth_t const *  ch,
msg_hclass_t crcl 
)

Initialize authenticators.

The function auc_challenge() merges the challenge ch to the list of authenticators auc_list.

Parameters:
[in,out] auc_list list of authenticators to be updated
[in,out] home memory home used for allocating authenticators
[in] ch challenge to be processed
[in] crcl credential class
Return values:
1 when challenge was updated
0 when there was no new challenges
-1 upon an error

int auc_clear_credentials ( auth_client_t **  auc_list,
char const *  scheme,
char const *  realm 
)

Clear authentication data from the authenticator.

The function auc_clear_credentials() is used to remove the credentials from the authenticators.

Parameters:
[in,out] auc_list list of authenticators
[in] scheme scheme (if non-null, remove only matching credentials)
[in] realm realm (if non-null, remove only matching credentials)
Return values:
0 when successful
-1 upon an error

int auc_copy_credentials ( auth_client_t **  dst,
auth_client_t const *  src 
)

Copy authentication data from src to dst.

Return values:
>0 if credentials were copied
0 if there was no credentials to copy
<0 if an error occurred.

int auc_credentials ( auth_client_t **  auc_list,
su_home_t home,
char const *  data 
)

Feed authentication data to the authenticator.

The function auc_credentials() is used to provide the authenticators in with authentication data (user name, secret). The authentication data has format as follows:

scheme:"realm":user:pass

For instance, Basic:"nokia-proxy":ppessi:verysecret

Todo:
The authentication data format sucks.
Parameters:
[in,out] auc_list list of authenticators
[in,out] home memory home used for allocations
[in] data colon-separated authentication data
Return values:
0 when successful
-1 upon an error

int auc_has_authorization ( auth_client_t **  auc_list  ) 

Check if we have all required credentials.

Return values:
1 when authorization can proceed
0 when there is not enough credentials
Since:
New in 1.12.5

int auc_info ( auth_client_t **  auc_list,
msg_auth_info_t const *  info,
msg_hclass_t credential_class 
)

Store authentication info to authenticators.

The function auc_info() feeds the authentication data from the Authentication-Info header info to the list of authenticators auc_list.

Parameters:
[in,out] auc_list list of authenticators to be updated
[in] info info header to be processed
[in] credential_class corresponding credential class
The authentication info can be in either Authentication-Info or in Proxy-Authentication-Info headers. If the header is Authentication-Info, the credential_class should be sip_authorization_class or http_authorization_class. Likewise, If the header is Proxy-Authentication-Info, the credential_class should be sip_proxy_authorization_class or http_proxy_authorization_class.

The authentication into header usually contains next nonce or mutual authentication information. Currently, only the nextnonce parameter is processed.

Bug:
The result can be quite unexpected if there are more than one authenticator with the given type (specified by crcl). In principle, SIP allows more than one challenge for a single request.
Return values:
number of challenges to updated
0 when there was no challenge to update
-1 upon an error
Since:
New in 1.12.5


Sofia-SIP 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.