loginrestrictionsx Subroutine

Purpose

Determines, in multiple methods, if a user is allowed to access the system.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>
#include <login.h>

int loginrestrictionsx (Name, Mode, Tty, Message, State)
char * Name;
int  Mode;
char *Tty;
char **Message;
char **State;

Description

The loginrestrictionsx subroutine determines if the user specified by the Name parameter is allowed to access the system. The Mode parameter gives the mode of account usage, and the Tty parameter defines the terminal used for access. The Msg parameter returns an informational message explaining why the loginrestrictionsx subroutine failed. The user's SYSTEM attribute determines the administrative domains to examine for permission.

The State parameter contains information about the login restrictions for the user. A call to the authenticatex subroutine will not use an administrative domain for authentication if an earlier call to loginrestrictionsx indicated that the user was unable to log in using that administrative domain's authentication data. The result is that administrative domains that are used for authentication must permit the user to log in. The State parameter returned by loginrestrictionsx can be used as input to a subsequent call to the authenticatex subroutine.

This subroutine is unsuccessful if any of the following conditions exists:
  • The user's account has been locked as defined by the account_locked user attribute.
  • The user's account has expired as defined by the expires user attribute.
  • The Mode parameter is set to the S_LOGIN value or the S_RLOGIN value, and too many users are logged in as defined by the maxlogins system attribute.
  • The Mode parameter is not set to the S_SU or S_DAEMON value, and the user is not allowed to log in to the current host as defined by the user's hostallowedlogin and hostdeniedlogin attributes.
  • The user is not allowed to access the system at the present time as defined by the logintimes user attribute.
  • The user attempted too many unsuccessful logins as defined by the loginretries user attribute.
  • The user is not allowed to access the given terminal or network protocol as defined by the ttys user attribute. This test is not performed when the Mode parameter is set to the S_DAEMON value.
  • The Mode parameter is set to the S_LOGIN value, and the user is not allowed to log in as defined by the login user attribute.
  • The Mode parameter is set to the S_RLOGIN value and the user is not allowed to log in from the network as defined by the rlogin user attribute.
  • The Mode parameter is set to the S_SU value, and other users are not allowed to use the su command as defined by the su user attribute; or, the group ID of the current process cannot use the su command to switch to this user as defined by the sugroups user attribute.
  • The Mode parameter is set to the S_DAEMON value, and the user is not allowed to run processes from the cron or src subsystem as defined by the daemon user attribute.
  • The terminal is locked as defined by the locktime port attribute.
  • The user cannot use the terminal to access the system at the present time as defined by the logintimes port attribute.
  • The user is not the root user, and the /etc/nologin file exists.

Additional restrictions can be enforced by loadable authentication modules for any administrative domain used in the user's SYSTEM attribute.

Parameters

Item Description
Name Specifies the user's login name whose account is to be validated.
Mode Specifies the mode of usage. The valid values in the following list are defined in the login.h file. The Mode parameter has a value of 0 or one of the following values:
S_LOGIN
Verifies that local logins are permitted for this account.
S_SU
Verifies that the su command is permitted and the current process has a group ID that can invoke the su command to switch to the account.
S_DAEMON
Verifies that the account can invoke daemon or batch programs through the src or cron subsystems.
S_RLOGIN
Verifies that the account can be used for remote logins through the rlogind or telnetd programs.
Tty Specifies the terminal of the originating activity. If this parameter is a null pointer or a null string, no tty origin checking is done. The Tty parameter can also have the value RSH or REXEC to indicate that the caller is the rsh or rexec command.
Message Returns an informative message indicating why the loginrestrictionsx subroutine failed. Upon return, the value is either a pointer to a valid string within memory-allocated storage or a null value. If a message is displayed, it is provided based on the user interface.
State Points to a pointer that the loginrestrictionsx subroutine allocates memory for and fills in. The State parameter can also be the result of an earlier call to the authenticatex subroutine. The State parameter contains information about the results of the loginrestrictionsx subroutine 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 authenticatex, passwdexpiredx, or chpassx subroutines.

Security

Access Control: The calling process must have access to the account information in the user database and the port information in the port database.

Files accessed:

Item Description
Mode File
r /etc/security/user
r /etc/security/login.cfg
r /etc/security/portlog
r /etc/passwd

Return Values

If the account is valid for the specified usage, the loginrestrictionsx subroutine returns a value of 0. Otherwise, a value of -1 is returned, the errno global value is set to the appropriate error code, and the Message parameter returns an informative message explaining why the specified account usage is invalid.

Error Codes

If the loginrestrictionsx subroutine fails if one of the following values is true:

Item Description
EACCES One of the following conditions exists:
  • The specified terminal does not have access to the specified account.
  • The Mode parameter is the S_SU value, and the current process is not permitted to use the su command to access the specified user.
  • Access to the account is not permitted in the specified mode.
  • Access to the account is not permitted at the current time.
  • Access to the system with the specified terminal is not permitted at the current time.
EAGAIN The Mode parameter is either the S_LOGIN value or the S_RLOGIN value, and all the user licenses are in use.
EINVAL The Mode parameter has a value other than S_LOGIN, S_SU, S_DAEMON, S_RLOGIN, or 0.
ENOENT The user specified does not have an account.
EPERM The user's account is locked, the specified terminal is locked, the user has had too many unsuccessful login attempts, or the user cannot log in because the /etc/nologin file exists.
ESTALE The user's account is expired.