source: trunk/athena/lib/al/al_login_allowed.3 @ 12154

.\" $Id: al_login_allowed.3,v 1.5 1998-11-19 22:06:22 ghudson Exp $
.\"
.\" Copyright 1997, 1998 by the Massachusetts Institute of
.\" Technology.
.\"
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright
.\" notice and this permission notice appear in supporting
.\" documentation, and that the name of M.I.T. not be used in
.\" advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.
.\" M.I.T. makes no representations about the suitability of
.\" this software for any purpose.  It is provided "as is"
.\" without express or implied warranty.
.\"
.TH AL_LOGIN_ALLOWED 3 "4 April 1998"
.SH NAME
al_login_allowed \- Determine if a user is allowed to log in
.SH SYNOPSIS
.nf
.B #include <al.h>
.PP
.B int al_login_allowed(const char *\fIusername\fP, int *\fIlocal_acct\fP,
.B      int \fIisremote\fP, char **\fItext\fP)
.PP
.B cc file.c -lal -lhesiod
.fi
.SH DESCRIPTION
This function determines whether the user
.I username
is allowed to log in according to the Athena security model.  A user
may be denied access if:
.TP 2
*
.I /etc/nologin
exists and
.I username
is not listed as having uid 0 in the local passwd file.
.TP 2
*
.I username
is not listed in the local passwd file and there is no Hesiod passwd
entry for
.IR username .
.TP 2
*
.I username
is not listed in the local passwd file and the Hesiod passwd entry for
.I username
has the same uid as some entry in the local passwd file.
.TP 2
*
.I username
is not allowed local or remote access (as appropriate) according to
the Athena access control file
.I /etc/athena/access
(see access(5)).
.PP
If the access control file
.I /etc/athena/access
does not exist, then
.I al_login_allowed
looks for the presence of two files
.I /etc/noremote
and
.I /etc/nocreate
to determine which users are authorized to log in locally and
remotely.  If
.I /etc/noremote
is present, only users in the local passwd file may log in remotely.
If
.I /etc/nocreate
is present, only users in the local passwd file may log in at all.
.PP
If the user is denied access due to
.I /etc/athena/access
and explanatory text was given on the relevant line, then the variable
pointed to by
.I text
is set to an allocated string (which must be freed by the caller)
containing the explanatory text followed by a newline.  If the user
was denied access due to
.IR /etc/nologin ,
.IR /etc/noremote ,
or
.I /etc/nocreate
and the relevant file is of nonzero length, then the variable
pointed to by
.I text
is set to the text of the file.  Otherwise, the variable pointed to by
.I text
is set to NULL.  If the caller does not care about explanatory text,
it can pass NULL for
.IR text .
.PP
On successful return, the variable pointed to by
.I local_acct
is set to 1 if the user is root or has a local account according to
.I /etc/athena/access
or 0 if not.  The root account is always treated as local.  If a user
has a local account, the login program should suppress Athena-specific
login behavior including the retrieval of Kerberos tickets.
.SS EXAMPLE
The following example function might be appropriate for a remote login
program to determine if a user is allowed to log in.  The example
assumes that
.I respond
is a function with printf-like arguments which transmits text to the
client side of the connection.  The function returns only if the user
is allowed to log in, and its return value indicates whether or not
the user's account is local.
.PP
.RS
.nf
int check_access(const char *username)
{
  int local, status;
  char *text, *errmem;

  status = al_login_allowed(username, 1, &local, &text);
  if (status != AL_SUCCESS)
    {
      respond("Access denied: %s\\n", al_strerror(status, &errmem));
      if (text)
        respond("%s", text);
      free(text);
      al_free_errmem(errmem);
      exit(0);
    }
  return local;
}
.fi
.RE
.SH RETURN VALUES
.I al_login_allowed
may return the following values:
.TP 15
.I AL_SUCCESS
The user may log in.
.TP 15
.I AL_ENOUSER
There is no local or Hesiod passwd entry for
.IR username .
.TP 15
.I AL_EBADHES
The Hesiod passwd entry for
.I username
conflicts with a local passwd entry.
.TP 15
.I AL_ENOLOGIN
The user may not log in because of
.IR /etc/nologin .
.TP 15
.I AL_ENOREMOTE
The user may not log in because of
.I /etc/athena/access
(when local access is allowed for a user but remote access is denied)
or because of
.IR /etc/noremote .
.TP 15
.I AL_ENOCREATE
The user may not log in because of
.I /etc/athena/access
or because of
.IR /etc/nocreate .
.TP 15
.I AL_ENOMEM
Memory was exhausted.
.SH FILES
/etc/athena/access, /etc/nocreate, /etc/noremote, /etc/nologin
.SH SEE ALSO
al_acct_create(3), al_strerror(3)
.SH AUTHOR
Greg Hudson, MIT Information Systems
.br
Copyright 1997, 1998 by the Massachusetts Institute of Technology.