Verifies a user's name and password.
int authenticate (UserName, Response, Reenter, Message)
wchar_t *UserName;
wchar_t *Response;
int *Reenter;
wchar_t **Message;
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.
Upon successful completion, the authenticate subroutine returns a value of 0. If this subroutine fails, it returns a value of 1.
The authenticate subroutine is unsuccessful if one of the following values is true:
Note: The DCE mechanism requires credentials on successful authentication that apply only to the authenticate process and its children.
This subroutine is part of Base Operating System (BOS) Runtime.
The ckuserID subroutine.