sofia-sip/auth_client.h File Reference

Detailed Description

Defined when <sofia-sip/auth_client.h> has been included.

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 struct 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.

Typedef Documentation

typedef struct auth_client_s auth_client_t

Authenticator object.

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:: In principle, SIP allows more than one challenge for a single request. For example, there can be multiple proxies that each challenge the client. The result of storing authentication info can be quite unexpected if there are more than one authenticator with the given type (specified by credential_class).

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.


Typedefs
typedef struct 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.