Technical Reference: Base Operating System and Extensions, Volume 1

loginfailed Subroutine

Purpose

Records an unsuccessful login attempt.

Library

Security Library (libc.a)

Syntax

#include <usersec.h> int loginfailed ( User, Host, Tty, Reason) char *User; char *Host; char *Tty;
int Reason;

Note

This subroutine is not thread-safe.

Description

The loginfailed subroutine performs the processing necessary when an unsuccessful login attempt occurs. If the specified user name is not valid, the UNKNOWN_USER value is substituted for the user name. This substitution prevents passwords entered as the user name from appearing on screen.

The following attributes in /etc/security/lastlog file are updated for the specified user, if the user name is valid:

time_last_unsuccessful_login	Contains the current time.
tty_last_unsuccessful_login	Contains the value specified by the Tty parameter.
host_last_unsuccessful_login	Contains the value specified by the Host parameter, or the local hostname if the Host parameter is a null value.
unsuccessful_login_count	Indicates the number of unsuccessful login attempts. The loginfailed subroutine increments this attribute by one for each failed attempt.

A login failure audit record is cut to indicate that an unsuccessful login attempt occurred. A utmp entry is appended to /etc/security/failedlogin file, which tracks all failed login attempts.

If the current unsuccessful login and the previously recorded unsuccessful logins constitute too many unsuccessful login attempts within too short of a time period (as specified by the logindisable and logininterval port attributes), the port is locked. When a port is locked, a PORT_Locked audit record is written to inform the system administrator that the port has been locked.

If the login retry delay is enabled (as specified by the logindelay port attribute), a sleep occurs before this subroutine returns. The length of the sleep (in seconds) is determined by the logindelay value multiplied by the number of unsuccessful login attempts that occurred in this process.

Parameters

User	Specifies the user's login name who has unsuccessfully attempted to login.
Host	Specifies the name of the host from which the user attempted to login. If the Host parameter is Null, the name of the local host is used.
Tty	Specifies the name of the terminal on which the user attempted to login.
Reason	Specifies a reason code for the login failure. Valid values are AUDIT_FAIL and AUDIT_FAIL_AUTH defined in the sys/audit.h file.

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.

File Accessed:

Mode	File
r	/etc/security/user
rw	/etc/security/lastlog
r	/etc/security/login.cfg
rw	/etc/security/portlog
w	/etc/security/failedlogin

Auditing Events:

Event	Information
USER_Login	username
PORT_Locked	portname

Return Values

Upon successful completion, the loginfailed subroutine returns a value of 0. If an error occurs, a value of -1 is returned and errno is set to indicate the error.

Error Codes

The loginfailed subroutine fails if one or more of the following values is true:

EACCES	The current process does not have access to the user or port database.
EPERM	The current process does not have permission to write an audit record.

Related Information

The authenticate (authenticate Subroutine) subroutine, getpcred (getpcred Subroutine) subroutine, getpenv (getpenv Subroutine) subroutine, loginrestrictions (loginrestrictions Subroutine) subroutine, loginsuccess (loginsuccess Subroutine) subroutine, setpcred subroutine, setpenv subroutine.

List of Security and Auditing Services in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.