Technical Reference: Base Operating System and Extensions, Volume 1

authenticate Subroutine

Purpose

Verifies a user's name and password.

Library

Security Library (libc.a)

Syntax

int authenticate (UserName,  Response,  Reenter,  Message)
char *UserName;
char *Response;
int *Reenter;
char **Message;

Description

The authenticate subroutine maintains requirements users must satisfy to be authenticated to the system. It is a recallable interface that prompts for the user's name and password. The user must supply a character string at the prompt issued by the Message parameter. The Response parameter returns the user's response to the authenticate subroutine. The calling program makes no assumptions about the number of prompt messages the user must satisfy for authentication.

The Reenter parameter remains a nonzero value until the user satisfies all prompt messages or answers incorrectly. Once the Reenter parameter is zero, the return code signals whether authentication passed or failed.

The authenticate subroutine ascertains the authentication domains the user can attempt. The subroutine reads the SYSTEM line from the user's stanza in the /etc/security/user file. Each token that appears in the SYSTEM line corresponds to a method that can be dynamically loaded and processed. Likewise, the system can provide multiple or alternate authentication paths.

The authenticate routine maintains internal state information concerning the next prompt message presented to the user. If the calling program supplies a different user name before all prompts are complete for the user, the internal state information is reset and prompt messages begin again.

If the user has no defined password, or the SYSTEM grammar explicitly specifies no authentication required, the user is not required to respond to any prompt messages. Otherwise, the user is always initially prompted to supply a password.

The authenticate subroutine can be called initially with the cleartext password in the Response parameter. If the user supplies a password during the initial invocation but does not have a password, authentication fails. If the user wants the authenticate subroutine to supply a prompt message, the Response parameter is a null pointer on initial invocation.

The authenticate subroutine sets the AUTHSTATE environment variable used by name resolution subroutines, such as the getpwnam subroutine. This environment variable indicates the registry to which to user authenticated. Values for the AUTHSTATE environment variable include DCE, compat, and token names that appear in a SYSTEM grammar. A null value can exist if the cron daemon or other utilities that do not require authentication is called.

Parameters

UserName	Points to the user's name that is to be authenticated.
Response	Specifies a character string containing the user's response to an authentication prompt.
Reenter	Points to a Boolean value that signals whether the authenticate subroutine has completed processing. If the Reenter parameter is a nonzero value, the authenticate subroutine expects the user to satisfy the prompt message provided by the Message parameter. If the Reenter parameter is 0, the authenticate subroutine has completed processing.
Message	Points to a pointer that the authenticate subroutine allocates memory for and fills in. This string is suitable for printing and issues prompt messages (if the Reenter parameter is a nonzero value). It also issues informational messages such as why the user failed authentication (if the Reenter parameter is 0). The calling application is responsible for freeing this memory.

Return Values

Upon successful completion, the authenticate subroutine returns a value of 0. If this subroutine fails, it returns a value of 1.

Error Codes

The authenticate subroutine is unsuccessful if one of the following values is true:

ENOENT	Indicates that the user is unknown to the system.
ESAD	Indicates that authentication is denied.
EINVAL	Indicates that the parameters are not valid.
ENOMEM	Indicates that memory allocation (malloc) failed.

Note

The DCE mechanism requires credentials on successful authentication that apply only to the authenticate process and its children.

Related Information

The ckuserID (ckuserID Subroutine) subroutine.