Managing authentication: userid and passwords

Macros
#define	LINPHONE_AUTH_INFO(obj)   BELLE_SIP_CAST(obj, LinphoneAuthInfo)

Typedefs
typedef struct _LinphoneAuthInfo	LinphoneAuthInfo

Functions
LinphoneAuthInfo *	linphone_auth_info_new (const char *username, const char *userid, const char *passwd, const char *ha1, const char *realm, const char *domain)
LinphoneAuthInfo *	linphone_auth_info_clone (const LinphoneAuthInfo *source)
void	linphone_auth_info_set_passwd (LinphoneAuthInfo *info, const char *passwd)
void	linphone_auth_info_set_username (LinphoneAuthInfo *info, const char *username)
void	linphone_auth_info_set_userid (LinphoneAuthInfo *info, const char *userid)
void	linphone_auth_info_set_realm (LinphoneAuthInfo *info, const char *realm)
void	linphone_auth_info_set_domain (LinphoneAuthInfo *info, const char *domain)
void	linphone_auth_info_set_ha1 (LinphoneAuthInfo *info, const char *ha1)
void	linphone_auth_info_set_tls_cert (LinphoneAuthInfo *info, const char *tls_cert)
void	linphone_auth_info_set_tls_key (LinphoneAuthInfo *info, const char *tls_key)
void	linphone_auth_info_set_tls_cert_path (LinphoneAuthInfo *info, const char *tls_cert_path)
void	linphone_auth_info_set_tls_key_path (LinphoneAuthInfo *info, const char *tls_key_path)
const char *	linphone_auth_info_get_username (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_passwd (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_userid (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_realm (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_domain (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_ha1 (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_tls_cert (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_tls_key (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_tls_cert_path (const LinphoneAuthInfo *info)
const char *	linphone_auth_info_get_tls_key_path (const LinphoneAuthInfo *info)
void	linphone_auth_info_destroy (LinphoneAuthInfo *info)
LinphoneAuthInfo *	linphone_core_create_auth_info (LinphoneCore *lc, const char *username, const char *userid, const char *passwd, const char *ha1, const char *realm, const char *domain)
void	linphone_core_add_auth_info (LinphoneCore *lc, const LinphoneAuthInfo *info)
void	linphone_core_remove_auth_info (LinphoneCore *lc, const LinphoneAuthInfo *info)
const bctbx_list_t *	linphone_core_get_auth_info_list (const LinphoneCore *lc)
const LinphoneAuthInfo *	linphone_core_find_auth_info (LinphoneCore *lc, const char *realm, const char *username, const char *sip_domain)

Detailed Description

Macro Definition Documentation

LINPHONE_AUTH_INFO

#define LINPHONE_AUTH_INFO

(

obj

)

BELLE_SIP_CAST(obj, LinphoneAuthInfo)

Safely cast a belle_sip_object_t into LinphoneAuthInfo

Typedef Documentation

LinphoneAuthInfo

typedef struct _LinphoneAuthInfo LinphoneAuthInfo

Object holding authentication information.

Note

The object's fields should not be accessed directly. Prefer using the accessor methods.

In most case, authentication information consists of a username and password. Sometimes, a userid is required by proxy, and realm can be useful to discriminate different SIP domains.

Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in order to become known and used automatically when needed. Use linphone_core_add_auth_info() for that purpose.

The LinphoneCore object can take the initiative to request authentication information when needed to the application through the auth_info_requested callback of the LinphoneCoreVTable structure.

The application can respond to this information request later using linphone_core_add_auth_info(). This will unblock all pending authentication transactions and retry them with authentication headers.

Function Documentation

linphone_auth_info_clone()

LinphoneAuthInfo* linphone_auth_info_clone

(

const LinphoneAuthInfo *

source

)

Instantiates a new auth info with values from source.

Parameters

[in]

source

The LinphoneAuthInfo object to be cloned

Returns

The newly created LinphoneAuthInfo object.

linphone_auth_info_get_domain()

const char* linphone_auth_info_get_domain

(

const LinphoneAuthInfo *

info

)

Gets the domain.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The domain.

linphone_auth_info_get_ha1()

const char* linphone_auth_info_get_ha1

(

const LinphoneAuthInfo *

info

)

Gets the ha1.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The ha1.

linphone_auth_info_get_passwd()

const char* linphone_auth_info_get_passwd

(

const LinphoneAuthInfo *

info

)

Gets the password.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The password.

linphone_auth_info_get_realm()

const char* linphone_auth_info_get_realm

(

const LinphoneAuthInfo *

info

)

Gets the realm.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The realm.

linphone_auth_info_get_tls_cert()

const char* linphone_auth_info_get_tls_cert

(

const LinphoneAuthInfo *

info

)

Gets the TLS certificate.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The TLS certificate.

linphone_auth_info_get_tls_cert_path()

const char* linphone_auth_info_get_tls_cert_path

(

const LinphoneAuthInfo *

info

)

Gets the TLS certificate path.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The TLS certificate path.

linphone_auth_info_get_tls_key()

const char* linphone_auth_info_get_tls_key

(

const LinphoneAuthInfo *

info

)

Gets the TLS key.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The TLS key.

linphone_auth_info_get_tls_key_path()

const char* linphone_auth_info_get_tls_key_path

(

const LinphoneAuthInfo *

info

)

Gets the TLS key path.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The TLS key path.

linphone_auth_info_get_userid()

const char* linphone_auth_info_get_userid

(

const LinphoneAuthInfo *

info

)

Gets the userid.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The userid.

linphone_auth_info_get_username()

const char* linphone_auth_info_get_username

(

const LinphoneAuthInfo *

info

)

Gets the username.

Parameters

[in]

info

The LinphoneAuthInfo object

Returns

The username.

linphone_auth_info_new()

LinphoneAuthInfo* linphone_auth_info_new	(	const char *	username,
		const char *	userid,
		const char *	passwd,
		const char *	ha1,
		const char *	realm,
		const char *	domain
	)

Creates a LinphoneAuthInfo object with supplied information. The object can be created empty, that is with all arguments set to NULL. Username, userid, password, realm and domain can be set later using specific methods. At the end, username and passwd (or ha1) are required.

Parameters

username	The username that needs to be authenticated
userid	The userid used for authenticating (use NULL if you don't know what it is)
passwd	The password in clear text
ha1	The ha1-encrypted password if password is not given in clear text.
realm	The authentication domain (which can be larger than the sip domain. Unfortunately many SIP servers don't use this parameter.
domain	The SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.

Returns

A LinphoneAuthInfo object. linphone_auth_info_destroy() must be used to destroy it when no longer needed. The LinphoneCore makes a copy of LinphoneAuthInfo passed through linphone_core_add_auth_info().

linphone_auth_info_set_domain()

void linphone_auth_info_set_domain	(	LinphoneAuthInfo *	info,
		const char *	domain
	)

Sets the domain for which this authentication is valid.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	domain	The domain. This should not be necessary because realm is supposed to be unique and sufficient. However, many SIP servers don't set realm correctly, then domain has to be used to distinguish between several SIP account bearing the same username.

linphone_auth_info_set_ha1()

void linphone_auth_info_set_ha1	(	LinphoneAuthInfo *	info,
		const char *	ha1
	)

Sets the ha1.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	ha1	The ha1.

linphone_auth_info_set_passwd()

void linphone_auth_info_set_passwd	(	LinphoneAuthInfo *	info,
		const char *	passwd
	)

Sets the password.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	passwd	The password.

linphone_auth_info_set_realm()

void linphone_auth_info_set_realm	(	LinphoneAuthInfo *	info,
		const char *	realm
	)

Sets the realm.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	realm	The realm.

linphone_auth_info_set_tls_cert()

void linphone_auth_info_set_tls_cert	(	LinphoneAuthInfo *	info,
		const char *	tls_cert
	)

Sets the TLS certificate.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	tls_cert	The TLS certificate.

linphone_auth_info_set_tls_cert_path()

void linphone_auth_info_set_tls_cert_path	(	LinphoneAuthInfo *	info,
		const char *	tls_cert_path
	)

Sets the TLS certificate path.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	tls_cert_path	The TLS certificate path.

linphone_auth_info_set_tls_key()

void linphone_auth_info_set_tls_key	(	LinphoneAuthInfo *	info,
		const char *	tls_key
	)

Sets the TLS key.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	tls_key	The TLS key.

linphone_auth_info_set_tls_key_path()

void linphone_auth_info_set_tls_key_path	(	LinphoneAuthInfo *	info,
		const char *	tls_key_path
	)

Sets the TLS key path.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	tls_key_path	The TLS key path.

linphone_auth_info_set_userid()

void linphone_auth_info_set_userid	(	LinphoneAuthInfo *	info,
		const char *	userid
	)

Sets the userid.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	userid	The userid.

linphone_auth_info_set_username()

void linphone_auth_info_set_username	(	LinphoneAuthInfo *	info,
		const char *	username
	)

Sets the username.

Parameters

[in]	info	The LinphoneAuthInfo object
[in]	username	The username.

linphone_core_add_auth_info()

void linphone_core_add_auth_info	(	LinphoneCore *	lc,
		const LinphoneAuthInfo *	info
	)

Adds authentication information to the LinphoneCore. That piece of information will be used during all SIP transactions that require authentication.

Parameters

[in]	lc	The LinphoneCore.
[in]	info	The LinphoneAuthInfo to add.

linphone_core_create_auth_info()

LinphoneAuthInfo* linphone_core_create_auth_info	(	LinphoneCore *	lc,
		const char *	username,
		const char *	userid,
		const char *	passwd,
		const char *	ha1,
		const char *	realm,
		const char *	domain
	)

Create an authentication information with default values from Linphone core.

Parameters

[in]	lc	LinphoneCore object
[in]	username	String containing the username part of the authentication credentials
[in]	userid	String containing the username to use to calculate the authentication digest (optional)
[in]	passwd	String containing the password of the authentication credentials (optional, either passwd or ha1 must be set)
[in]	ha1	String containing a ha1 hash of the password (optional, either passwd or ha1 must be set)
[in]	realm	String used to discriminate different SIP authentication domains (optional)
[in]	domain	String containing the SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.

Returns

LinphoneAuthInfo with default values set

linphone_core_find_auth_info()

const LinphoneAuthInfo* linphone_core_find_auth_info	(	LinphoneCore *	lc,
		const char *	realm,
		const char *	username,
		const char *	sip_domain
	)

Find authentication info matching realm, username, domain criteria. First of all, (realm,username) pair are searched. If multiple results (which should not happen because realm are supposed to be unique), then domain is added to the search.

Parameters

lc	the LinphoneCore
realm	the authentication 'realm' (optional)
username	the SIP username to be authenticated (mandatory)
sip_domain	the SIP domain name (optional)

Returns

a LinphoneAuthInfo

linphone_core_get_auth_info_list()

const bctbx_list_t* linphone_core_get_auth_info_list

(

const LinphoneCore *

lc

)

Returns an unmodifiable list of currently entered LinphoneAuthInfo.

Parameters

[in]

lc

The LinphoneCore object.

Returns

A list of LinphoneAuthInfo objects.

linphone_core_remove_auth_info()

void linphone_core_remove_auth_info	(	LinphoneCore *	lc,
		const LinphoneAuthInfo *	info
	)

Removes an authentication information object.

Parameters

[in]	lc	The LinphoneCore from which the LinphoneAuthInfo will be removed.
[in]	info	The LinphoneAuthInfo to remove.