authenticate Subroutine
Purpose
Verifies a user's name and password.
Library
Security Library (libc.a)
Syntax
#include <usersec.h>
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 indicates when a user has satisfied all prompt messages. The parameter remains nonzero until a user has passed all prompts. After the returned value of Reenter is 0, the return code signals whether authentication has succeeded or failed. When progressing through prompts for a user, the value of Reenter must be maintained by the caller between invocations of authenticate.
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. The calling program maintains the value of the Reenter parameter while processing prompts for a given user.
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
| Item | Description |
|---|---|
| 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:
| Item | Description |
|---|---|
| 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. |