authenticate_user(3x)authenticate_user(3x)Nameauthenticate_user - authenticate user
Syntax
#include <pwd.h>
#include <auth.h> /* For error codes */
int authenticate_user(user, password, line)
struct passwd *user;
char *password;
char *line;
Arguments
user
A pointer to the passwd entry.
password
A pointer to the password.
line
The name of the terminal line as it is listed in the file.
Description
The routine authenticates a user name or UID against a supplied pass‐
word and returns a nonnegative integer on success. The value returned
is the number of failed login authentication attempts since the last
successful login authentication (or zero if this feature is not
enabled). This routine is found in the library and loaded with the
-lauth option.
At all security levels higher than BSD, the login fail count in the
auth database is incremented if authentication fails, and cleared if it
succeeds. In addition, the account must be marked enabled for logins
as defined by the Account Mask value for A_LOGIN. See for information
about the Account Mask values.
If a non-NULL value is supplied for the argument and the argument is
not the empty string, the function also verifies that the specified
user is allowed access through that line. In particular, accounts with
a UID equal to zero will return success only if the specified line is
marked secure in the file.
Restrictions
The process must have read access to the auth database to authenticate
users in a secure environment.
The process must have read/write access to the auth database to update
the authentication fail count.
If auth information is being served through BIND, the process is
required to obtain a Kerberos ticket for that service before invoking
this function.
Example
extern int errno;
struct passwd *pwd;
int status;
pwd = getpwnam("root");
status = authenticate_user(pwd, "rootpass", "/dev/console");
if(status < 0)
if(errno == EPERM)
puts("Login failed");
else
perror("authenticate_user");
else
if(status > 0)
printf("%d failed attempts\n", status);
Return Values
When successful, the routine returns the number of failed login authen‐
tication attempts since last successful login authentication.
When an error occurs, errno is set and a negative error code is
returned. The error code returned may be the same as errno or it may be
an extended error code defined in
Diagnostics
On error return errno may be set to one of the following values:
[EPERM] Either the password is incorrect, the password is
expired, the specified line needs to be secure and is
not, or the account is disabled and a login authenti‐
cation is required.
[EINVAL] No authentication information for user.
[ENOSYS] Security subsystem not configured correctly.
[EACCES] Process does not have read access to the necessary
information.
On error return the return value may be the same as errno or, if errno
is [EPERM], it may be one of the following additional values defined in
[A_EBADPASS] The supplied password was incorrect.
[A_ESOFTEXP] The account's password expired recently.
[A_EHARDEXP] The account's password expired quite some time ago.
[A_ENOLOGIN] The account is not enabled.
[A_EOPENLINE] The account requires a secure line and the specified
line was not marked that way in the file.
FilesEnvironment
If the system is operating in the BSD security level, the password
expiration, login fail count, and account disabling features are not
available (and therefore are not used in authentication computations).
See Alsogetauthent(3x), getpwent(3), auth(5), passwd(5yp), ttys(5)authenticate_user(3x)
