NAME

pam_authenticate_secondary - perform authentication to a secondary domain within the PAM framework

SYNOPSIS

#include <security/pam_appl.h>

int pam_authenticate_secondary (
    pam_handle_t    *pamh,
    char            *target_username,
    char            *target_module_type,
    char            *target_authn_domain,
    char            *target_supp_data,
    unsigned char   *target_module_authtok,
    int              flags
);

DESCRIPTION

The pam_authenticate_secondary() function is called to authenticate the target_username in the domain specified by target_authn_domain independently of the primary user authentication and user session establishment. The caller will typically have previously retrieved the username and authentication token to be used with the target domain by calls to pam_get_mapped_username() and pam_get_mapped_authtok().

If the PAM framework cannot load the authentication module, then it will return [PAM_OPEN_ERR].

If PAM_DISALLOW_NULL_AUTHTOK is specified and target_module_authtok is NULL then the authentication will fail.

Callers should not assume that the target_module_authtok buffer will be cleared upon return from this function.

The arguments for pam_authenticate_secondary() are:

pamh (in)

The PAM authentication handle, returned from a previous call to pam_start().

target_username (in)

The username to be authenticated within the target domain. This will generally have been retrieved with a call to pam_get_mapped_username().

target_module_type (in)

The mechanism to be used for the authentication.

target_authn_domain (in)

The domain within which the secondary authentication is required.

target_supp_data (in)

Supplementary data to be used by the secondary authentication mechanism.

target_module_authtok (in)

The authentication data-specific to the type of mechanism and the domain within which authentication is required. This will generally have been retrieved with a call to pam_get_mapped_authtok().

flags (in)

Flags which determine the actions to be taken on authentication. These may be set to:

PAM_SILENT
The authentication service shall not display any messages.

PAM_DISALLOW_NULL_AUTHTOK
The authentication service should return [PAM_AUTH_ERROR] if the user has a null authentication token.

RETURN VALUE

One of the following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_AUTH_ERR]

There has been an error in authenticating the user. This occurs if the user submits an invalid authentication token, or if the PAM_DISALLOW_NULL_AUTHTOK flag is set and the user submits a NULL authentication token.

[PAM_CRED_INSUFFICIENT]

Cannot access authentication data due to insufficient credentials.

[PAM_USER_UNKNOWN]

The user is not known to the authentication module.

[PAM_OPEN_ERR]

Failure when dynamically loading the secondary authentication service module.

[PAM_SYMBOL_ERR]

Symbol not found in service module.

[PAM_SERVICE_ERR]

Error in service module.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[PAM_CONV_ERR]

Conversation error.

[PAM_PERM_DENIED]

Permission denied.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.