DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

smp_check_user(S)


smp_check_user -- register login or password change to be performed

Syntax

cc . . . -lprot
#include <sys/types.h>
#include <prot.h>

int smp_check_user(typ, name, term, invoker, usrpp, pwtryp, reasonp, from_nis, delayp) int typ; char *name; char *term; uid_t invoker; struct smp_user_info **usrpp; int *pwtryp; char **reasonp; int *from_nis; int *delayp;

Description

smp_check_user is used to initialise the SMP (Security Module Package) service. It allocates and initialises the smp_user_info data structure, which is used by the remaining SMP routines, returning a pointer to this structure in usrpp. The intent of the calling program to perform either a login or a password change is stored for later use. In addition, smp_check_user validates the login name, checks the terminal (if specified) against the device assignment and terminal control databases, retrieves any relevant information for the login name and invoker from the authentication databases and saves the information, pointed to by usrpp, for later use.

typ can be one of SMP_LOGIN or SMP_PASSWD depending on the service to be used by the caller. If typ is not set to SMP_PASSWD, the invoker parameter is not used and memory for the corresponding protected password information is not allocated.

term must be the full pathname of the login terminal (which can be determined using ttyname(S)). If term is not set to NULL, the device assignment database and terminal control database entries are queried. If term is found in the device assignment database then that entry is used as the tty login, otherwise the last pathname component of term is used. The terminal control database is checked to ensure that term can be used for login.

If any of the following occur, a flag is set indicating that the terminal is locked:


Password and protected password databases are queried for the given login name. If valid, the authentication data is stored for subsequent use. If the retrieved information indicates that the account has been retired, then a corresponding flag is set.

If typ is specified as SMP_PASSWD, invoker is the UID of the user who invoked the calling process (which can be determined using getuid(S)). If valid, the corresponding protected password information is retrieved and stored for use in subsequent password authority checks.

pwtryp points to an integer which represents the maximum number of attempts that can be made to pick an acceptable password. If this integer is zero it is replaced with the system default value. Setting pwtryp to a value greater than zero, allows the system default value to be overridden. In this case, the integer pointed to by pwtryp is set to the larger of the specified number and the system default minimum number of tries.

In the special case where name is equal to root and the derived value of the terminal specified by term is equal to the value of OVERRIDE (from /etc/default/login) or console by default, a flag is set which indicates that the calling program wishes the service to be provided for root on the system console. If this flag is set certain conditions which would normally prevent a login or password change (such as a corrupted database or a locked terminal) are ignored so that the condition can be corrected.

reasonp is used with certain return values to store a descriptive message.

from_nis points to one of the following integers: ``1'' indicates that the returned smp_check_user structure was obtained from NIS; ``0'' indicates that the returned smp_check_user\*(> structure was obtained from local files. See ``Configuring the Network Information Service (NIS)'' in the Networking Guide for more information.

delayp points to an integer that returns the delay, in seconds, that should be enforced after a failed login attempt. This delay enhances system security by hindering automated password probing attempts. The value is set by the system administrator. See ``Setting login restrictions on terminals'' in the System Administration Guide for more information.

Return values

Note that smp_check_user also stores its return value for use in auditing of failures. The one exception to this is the case where SMP_FAIL is returned because memory cannot be allocated for the smp_usr_info structure itself.

SMP_ACCTLOCK
An attempt to log into the account will fail because the account is locked.

SMP_FAIL
The routine was unable to allocate the necessary memory for the smp_user_info structure. The operation should not continue.

SMP_NOTAUTH
The calling program has the effective group id (EGID) of neither auth nor root and therefore does not have sufficient privileges to read the authentication databases. This is fatal and the operation should not continue.

SMP_TERMLOCK
The terminal is locked and the ``root on console'' flag is not set. The operation should not continue.

SMP_BADUSER
The login name cannot be found in the file /etc/passwd. The operation should not continue.

SMP_NULLPW
The account exists and the user can log in without a password. The calling program is responsible for taking the appropriate action.

SMP_HASPW
The account and an encrypted password exist. The calling program should now ask the user to enter the password.

SMP_PWREQ
The user exists, and has no password. A new password should be requested by the calling program before login completes.

SMP_EXTFAIL
External failure - authentication information was not available. reasonp points to a character string explaining the cause of the error. The operation should not proceed.

SMP_OVERRIDE
This is returned in four cases:

  • the protected password database is corrupt

  • some condition exists in the protected password database entry for the account which would cause the account to be locked

  • the account has been retired

  • the terminal is locked

However, in all of the above cases the ``root on console'' flag has been set and login will be permitted in order to correct the problem. reasonp points to a character string explaining the type of failure.


SMP_RETIRED
SMP_PASSWD is specified for typ and the account specified by name has been retired. The operation should not proceed.

Diagnostics

All diagnostics are returned as strings pointed to by the argument reasonp. It is up to the calling program to display these for the user. In each case the return value is also noted.

Cannot access terminal control database entry
An entry for term cannot be found in the terminal control database, the u_integrity flag in the system defaults database is set and the ``root on console'' flag is not set. SMP_EXTFAIL is returned.

Security database corrupt
An entry for name cannot be found in the protected password database due to possible corruption. The ``root on console'' flag is set so login should be permitted to allow the problem to be fixed. SMP_OVERRIDE is returned.

Missing target protected password information
An entry for name could not be found in the protected password database. SMP_EXTFAIL is returned.

Missing subject protected password information
An entry for invoker could not be found in the protected password database. SMP_EXTFAIL is returned.

Account locked
The account is locked. The ``root on console'' flag is set so the login should be permitted to allow the problem to be fixed. SMP_OVERRIDE is returned.

Terminal locked
The terminal is already locked. However, the ``root on console'' flag is set so the login should be permitted to allow the problem to be fixed. SMP_OVERRIDE is returned.

Account retired
The account has been retired. However, the ``root on console'' flag is set so the login should be permitted to allow the problem to be fixed. SMP_OVERRIDE is returned.

Examples

The following example illustrates the usage of smp_check_user :
#include <sys/types.h>
#include <prot.h>
...
{
    char line[AUTH_MAX_PASSWD_LENGTH+1], newpw[AUTH_MAX_PASSWD_LENGTH+1];
    struct smp_user_info *userp;
    int pwtype, result, pwtries = 0;
    int from_nis, delay;

char *reason, **environ, *shell;

set_auth_parameters(argc, argv);

put("login: "); switch (smp_check_user(SMP_LOGIN, gets(line), ttyname(0), 0, &userp, &pwtries, &reason, &from_nis, &delay)) {

case SMP_FAIL: put("out of memory\n"); sleep(delay); exit(1); case SMP_EXTFAIL: put(reason); put("\n"); sleep(delay); exit(1); case SMP_NOTAUTH: put("not authorised\n"); /* can't read auth database */ sleep(delay); exit(1); case SMP_TERMLOCK: put("terminal locked\n"); smp_audit_fail(userp); sleep(delay); exit(1); case SMP_ACCTLOCK: put("account locked\n"); smp_audit_fail(userp); sleep(delay); exit(1); case SMP_RETIRED: put("account retired\n"); smp_audit_fail(userp); sleep(delay); exit(1); case SMP_OVERRIDE: put(reason); put("\nroot login on console is allowed\n"); case SMP_NULLPW: break; case SMP_BADUSER: case SMP_HASPW: noecho(); put("password: "); switch (smp_check_pw(gets(line), userp, &reason)) { /* either allow access, or say why not and sleep(delay) */ ... } echo(); case SMP_PWREQ: put("\nmust set password now\n"); if ((pwtype=smp_pw_choice(userp, &reason)) == SMP_CHOOSE) { ... } ... } ... }

Files


/lib/libprot.a
security subsystem library routines

/usr/lib/libp/libprot.a
as above but used for profiling

/usr/include/prot.h
defines the smp_user_info structure

/etc/default/login
default values for login process, see login(M)

/etc/default/passwd
passwd command defaults, see passwd(C)

/etc/auth/system/devassign
device assignment database, see devassign(F)

/etc/auth/system/ttys
terminal control database, see ttys(F)

/etc/auth/system/default
system default database, see default(F)

/etc/passwd
password file, see passwd(F)

/tcb/files/auth/?/*
protected password database, see prpw(F)

See also

smp_check_pw(S), smp_generate_pw(S), smp_get_messages(S), smp_pw_change(S), smp_pw_choice(S), smp_set_identity(S), smp_set_pw(S), smp_try_pw(S)

Standards conformance

smp_check_user is not part of any currently supported standard; it is an extension of AT&T System V provided by The Santa Cruz Operation, Inc.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003