authenticatex Subroutine

Purpose

Verifies a user's name and password.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>
int authenticatex (UserName, Response, Reenter, Message, State)
char *UserName;
char *Response;
int *Reenter;
char **Message;
void **State;

Description

The authenticatex subroutine maintains requirements that 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 authenticatex subroutine. The calling program makes no assumptions about the number of prompt messages the user must satisfy for authentication. The authenticatex subroutine maintains information about the results of each part of the authentication process in the State parameter. This parameter can be shared with the chpassx, loginrestrictionsx and passwdexpiredx subroutines. The proper sequence of library routines for authenticating a user in order to create a new session is:
  1. Call the loginrestrictionsx subroutine to determine which administrative domains allow the user to log in.
  2. Call the authenticatex subroutine to perform authentication using those administrative domains that grant login access.
  3. Call the passwdexpiredx subroutine to determine if any of the passwords used during the authentication process have expired and must be changed in order for the user to be granted access.
  4. If the passwdexpiredx subroutine indicated that one or more passwords have expired and must be changed by the user, call the chpassx subroutine to update all of the passwords that were used for the authentication process.

The Reenter parameter remains a nonzero value until the user satisfies all prompt messages or answers incorrectly. When the Reenter parameter is 0, the return code signals whether authentication passed or failed. The value of the Reenter parameter must be 0 on the initial call. A nonzero value for the Reenter parameter must be passed to the authenticatex subroutine on subsequent calls. A new authentication can be begun by calling the authenticatex subroutine with a 0 value for the Reenter parameter or by using a different value for UserName.

The State parameter contains information about the authentication process. The State parameter from an earlier call to loginrestrictionsx can be used to control how authentication is performed. Administrative domains that do not permit the user to log in cause those administrative domains to be ignored during authentication even if the user has the correct authentication information.

The authenticatex subroutine ascertains the authentication domains the user can attempt. The subroutine uses the SYSTEM attribute for the user. Each token that is displayed 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 authenticatex subroutine 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 authenticatex subroutine requires that the State parameter be initialized to reference a null value when changing user names or that the State parameter from an earlier call to loginrestrictionsx for the new user be provided.

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 authenticatex 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 authenticatex subroutine to supply a prompt message, the Response parameter is a null pointer on initial invocation.

The authenticatex subroutine sets the AUTHSTATE environment variable used by name resolution subroutines, such as the getpwnam subroutine. This environment variable indicates the first registry to which the 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 another utility that does not require authentication is called.

Parameters

Item Description
Message Points to a pointer that the authenticatex 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.
Reenter Points to an integer value that signals whether the authenticatex subroutine has completed processing. If the integer referenced by the Reenter parameter is a nonzero value, the authenticatex subroutine expects the user to satisfy the prompt message provided by the Message parameter. If the integer referenced by the Reenter parameter is 0, the authenticatex subroutine has completed processing. The initial value of the integer referenced by Reenter must be 0 when the authenticatex function is initially invoked and must not be modified by the calling application until the authenticationx subroutine has completed processing.
Response Specifies a character string containing the user's response to an authentication prompt.
State Points to a pointer that the authenticatex subroutine allocates memory for and fills in. The State parameter can also be the result of an earlier call to the loginrestrictionsx subroutine. This parameter contains information about the results of the authentication process for each term in the user's SYSTEM attribute. The calling application is responsible for freeing this memory when it is no longer needed for a subsequent call to the passwdexpiredx or chpassx subroutines.
UserName Points to the user's name that is to be authenticated.

Return Values

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

Error Codes

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

Item Description
EINVAL The parameters are not valid.
ENOENT The user is unknown to the system.
ENOMEM Memory allocation (malloc) failed.
ESAD Authentication is denied.
Note: Additional information about the behavior of a loadable authentication module can be found in the documentation for that module.