Loading...
Searching...
No Matches
auth_client.h File Reference

Client-side authenticator library. More...

`#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.

## Macros

#define | AUTH_CLIENT_H
| Defined when <sofia-sip/auth_client.h> has been included.

## 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 authenticators.
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 there are credentials for all challenges.
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.

## Detailed Description

Client-side authenticator library.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Wed Feb 14 17:09:44 2001 ppessi

## Function Documentation

## auc_all_credentials()

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

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

For Digest authentication scheme, it is possible to provide hashed password instead. The scheme should contain "HA1+Digest", and the password should be in hashed format prefixed with "HA1+".

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

  >0 | or number of updated clients when successful
  0 | when no client was updated
  -1 | upon an error

## auc_authorization()

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

## auc_authorization_headers()

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

## auc_challenge()

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 at least one challenge was updated
  0 | when there was no new challenges
  -1 | upon an error

## auc_clear_credentials()

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

## auc_copy_credentials()

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

Copy authentication data from src to dst.

Parameters

  [in,out] | dst | destination list of authenticators
  [in] | src | source list of authenticators

Return values

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

## auc_credentials()

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

For Digest authentication scheme, it is possible to provide hashed password instead. The scheme and hashed password should have prefix "HA1+". For instance, `HA1+Digest`:"realm":user1:HA1+c0890ff7a4fadc50c45f392ec4312965

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
  0 | if not authenticator matched with data
  -1 | upon an error

## auc_has_authorization()

int auc_has_authorization | ( | auth_client_t ** | auc_list | ) |

Check if there are credentials for all challenges.

Return values

  1 | when authorization can proceed
  0 | when there is not enough credentials

Since
  New in 1.12.5.

## auc_info()

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.

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