login_cap(3)

NAME

login_close, login_getcapbool, login_getcaplist,
login_getcapnum,
login_getcapstr, login_getcapsize, login_getcaptime,
login_getclass,
login_getclassbyname, login_getpwclass, login_getstyle, login_getuserclass, login_setcryptfmt - functions for ac
cessing the login class capabilities database

LIBRARY

System Utilities Library (libutil, -lutil)

SYNOPSIS

#include <sys/types.h>
#include <login_cap.h>
void
login_close(login_cap_t *lc);
login_cap_t *
login_getclassbyname(const  char  *nam,  const struct passwd
*pwd);
login_cap_t *
login_getclass(const char *nam);
login_cap_t *
login_getpwclass(const struct passwd *pwd);
login_cap_t *
login_getuserclass(const struct passwd *pwd);
const char *
login_getcapstr(login_cap_t *lc, const char *cap, const char
*def,
        const char *error);
char **
login_getcaplist(login_cap_t  *lc,  const  char  *cap, const
char *chars);
const char *
login_getpath(login_cap_t *lc, const char *cap,  const  char
*error);
rlim_t
login_getcaptime(login_cap_t  *lc,  const  char *cap, rlim_t
def,
        rlim_t error);
rlim_t
login_getcapnum(login_cap_t *lc,  const  char  *cap,  rlim_t
def,
        rlim_t error);
rlim_t
login_getcapsize(login_cap_t  *lc,  const  char *cap, rlim_t
def,
        rlim_t error);
int
login_getcapbool(login_cap_t *lc, const char *cap, int def);
const char *
login_getstyle(login_cap_t  *lc,  const  char  *style, const
char *auth);
const char *
login_setcryptfmt(login_cap_t *lc, const  char  *def,  const
char *error);

DESCRIPTION

These functions represent a programming interface to the lo
gin classes database provided in login.conf(5). This database contains
capabilities, attributes and default environment and accounting settings
for users and programs running as specific users, as determined by the lo
gin class field within entries in /etc/master.passwd.
Entries in login.conf(5) consist of colon `:' separated
fields, the first field in each record being one or more identifiers for the
record (which must be unique for the entire database), each separated by a optionally include a description as the last 'name'. Re
maining fields in the record consist of keyword/data pairs. Long lines may be
continued with a backslash within empty entries, with the second and
subsequent lines optionally indented for readability. This is similar
to the format used in termcap(5), except that keywords are not limited to
two significant characters, and are usually longer for improved read
ability. As with termcap entries, multiple records can be linked togeth
er (one record including another) using a field containing tc=<recordid>.
The result is that the entire record referenced by <recordid> replaces the
tc= field at the point at which it occurs. See getcap(3) for further de
tails on the format and use of a capabilities database.
The login_cap interface provides a convenient means of re
trieving login class records with all tc= references expanded. A program
will typically
call one of login_getclass(), login_getpwclass(),
login_getuserclass() or
login_getclassbyname() according to its requirements. Each
of these functions returns a login capabilities structure,
login_cap_t, which may
subsequently be used to interrogate the database for specif
ic values using the rest of the API. Once the login_cap_t is of no
further use,
the login_close() function should be called to free all re
sources used.
The structure of login_cap_t is defined in login_cap.h, as:: typedef struct {
char *lc_class;
char *lc_cap;
char *lc_style;; } login_cap_t;
The lc_class member contains a pointer to the name of the
login class retrieved. This may not necessarily be the same as the one
requested,
either directly via login_getclassbyname(), indirectly via a
user's login
record using login_getpwclass(), by class name using
login_getclass(), or
login_getuserclass(). If the referenced user has no login
class specified in /etc/master.passwd, the class name is NULL or an
empty string. If the class specified does not exist in the database, each
of these functions will search for a record with an id of "default",
with that
name returned in the lc_class field. In addition, if the
referenced user has a UID of 0 (normally, "root", although the user name is
not considered) then login_getpwclass() will search for a record with
an id of "root" before it searches for the record with the id of "de
fault".
The lc_cap field is used internally by the library to con
tain the expanded login capabilities record. Programs with unusual
requirements
may wish to use this with the lower-level getcap() style
functions to access the record directly.
The lc_style field is set by the login_getstyle() function
to the authorisation style, according to the requirements of the program
handling a login itself.
As noted above, the login_get*class() functions return a lo
gin_cap_t object which is used to access the matching or default
record in the
capabilities database. The login_getclassbyname() function
accepts two arguments: the first one is the record identifier of the
record to be retrieved, the second is an optional pointer to a passwd
structure. If the first name argument is NULL, an empty string, or a class
that does not exist in the supplemental or system login class
database, then the system default record is returned instead. If the second
pwd parameter is NULL, then only the system login class database is used.
However, if
the pwd parameter and the value of pwd->pw_dir are both not
NULL, then
the directory contained in pwd->pw_dir is searched for a lo
gin database file called ".login_conf", and capability records contained
within it may override the system defaults. This scheme allows users to
override some login settings from those in the system login class database
by creating class records for their own private class with a record id
of `me'. In the context of a login, it should be noted that some options
cannot by overridden by users for two reasons; many options, such as
resource settings and default process priorities, require root privi
leges in order to take effect, and other fields in the user's file are not be
consulted at all during the early phases of login for security or admin
istrative reasons. See login.conf(5) for more information on which set
tings a user is able to override. Typically, these are limited purely to
the user's default login environment which might otherwise have been
overridden in
shell startup scripts in any case. The user's .login_conf
merely provides a convenient way for a user to set up their preferred
login environment before the shell is invoked on login. Note that ac
cess to the
/etc/login.conf and .login_conf files will only be performed
subject to the security checks documented in _secure_path(3) for the
uids 0 and
pwd->pw_uid respectively.
If the specified record is NULL, empty or does not exist,
and the system has no "default" record available to fall back to, there is
a memory allocation error or for some reason cgetent(3) is unable to
access the login capabilities database, this function returns NULL.
The functions login_getpwclass(), login_getclass() and login_getuserclass() retrieve the applicable login class
record for the user's passwd entry or class name by calling
login_getclassbyname(). On
failure, NULL is returned. The difference between these
functions is
that login_getuserclass() includes the user's overriding
.login_conf that
exists in the user's home directory, and login_getpwclass()
and
login_getclass() restrict lookup only to the system login
class database in /etc/login.conf. As explained earlier,
login_getpwclass() only differs from login_getclass() in that it allows the default
class for user 'root' as "root" if none has been specified in the password
database. Otherwise, if the passwd pointer is NULL, or the user record
has no login class, then the system "default" entry is retrieved.
Once a program no longer wishes to use a login_cap_t object,
login_close() may be called to free all resources used by
the login
class. The login_close() function may be passed a NULL
pointer with no harmful side-effects.
The remaining functions may be used to retrieve individual
capability records. Each function takes a login_cap_t object as its
first parameter, a capability tag as the second, and remaining parame
ters being default and error values that are returned if the capability
is not found. The type of the additional parameters passed and re
turned depend on the type of capability each deals with, be it a simple
string, a list, a time value, a file or memory size value, a path (consist
ing of a colonseparated list of directories) or a boolean flag. The man
page for login.conf(5) deals in specific tags and their type.
Note that with all functions in this group, you should not
call free(3) on any pointers returned. Memory allocated during retrieval
or processing of capability tags is automatically reused by subsequent
calls to functions in this group, or deallocated on calling
login_close().
login_getcapstr() This function returns a simple string
capability. If: the string is not found, then the value; in def is
returned as the default value, or if an; error occurs,
the value in the error parameter is re; turned.
login_getcaplist() This function returns the value corre
sponding to the: named capability tag as a list of values; in a NULL
terminated array. Within the login; class database,
some tags are of type list, which con; sist of one or
more comma- or space separated values.; Usually, this
function is not called directly from an; application,
but is used indirectly via; login_getstyle().
login_getpath() This function returns a list of directo
ries separated: by colons `:'. Capability tags for; which this function is called consist of a list of di; rectories separated by spaces.
login_getcaptime() This function returns a time value asso
ciated with a: particular capability tag with the value; expressed in
seconds (the default), minutes, hours,; days, weeks or
(365 day) years or any combination of; these. A suffix determines the units used: S for; seconds, M for
minutes, H for hours, D for days, W for; weeks and Y
for 365 day years. Case of the units; suffix is
ignored.; Time values are normally used for set; ting resource,
accounting and session limits. If sup; ported by the
operating system and compiler (which is; true of
FreeBSD), the value returned is a quad; (long long),
of type rlim_t. A value "inf" or "in; finity" may be
used to express an infinite value, in; which case
RLIM_INFINITY is returned.
login_getcapnum() This function returns a numeric value
for a tag,: expressed either as tag=<value> or the; standard
cgetnum() format tag#<value>. The first; format
should be used in preference to the sec; ond, the second format is provided for compatibility; and consistency with the getcap(3) database format; where
numeric types use the `#' as the delim; iter for
numeric values. If in the first format,; then the
value given may be "inf" or "infinity"; which results
in a return value of RLIM_INFINITY. If; the given
capability tag cannot be found, the def; parameter is
returned, and if an error occurs, the; error parameter
is returned.
login_getcapsize() login_getcapsize() returns a value rep
resenting a: size (typically, file or memory) which; may be
expressed as bytes (the default), 512; byte blocks,
kilobytes, megabytes, gigabytes, and on; systems that
support the long long type, terabytes.; The suffix
used determines the units, and multiple; values and
units may be used in combination (e.g.; 1m500k = 1.5
megabytes). A value with no suffix is; interpreted as
bytes, B as 512-byte blocks, K as kilo; bytes, M as
megabytes, G as gigabytes and T as ter; abytes. Case
is ignored. The error value is returned; if there is
a login capabilities database error, if; an invalid
suffix is used, or if a numeric value; cannot be
interpreted.
login_getcapbool() This function returns a boolean value
tied to a par: ticular flag. It returns 0 if the given; capability
tag is not present or is negated by the; presence of a
"tag@" (See getcap(3) for more informa; tion on boolean
flags), and returns 1 if the tag is; found.
login_getstyle() This function is used by the login au
thorisation sys: tem to determine the style of login; available in a
particular case. The function accepts; three parameters, the login_cap entry itself and two; optional
parameters, and authorisation type
'style', and applies these to determine; the authorisation style that best suites these; rules.; +o If 'auth' is neither NULL nor an; empty string,
look for a tag of type "auth-<auth>"

in the capability record. If not present, then

look for the
default tag "auth=".; +o If no valid authorisation list was; found from the
previous step, then default to

"passwd" as the
authorisation list.; +o If 'style' is not NULL or empty,; look for it in
the list of authorisation methods

found from the
previous step. If 'style' is NULL

or an empty
string, then default to "passwd" au

thorisation.; +o If 'style' is found in the chosen; list of autho
risation methods, then return that,

otherwise
return NULL.; This scheme allows the administrator to; determine the
types of authorisation methods accepted; by the system, depending on the means by which the; access
occurs. For example, the administrator; may require
skey or kerberos as the authentication; method used
for access to the system via the net; work, and standard methods via direct dialup or con; sole logins,
significantly reducing the risk of pass; word discovery
by "snooping" network packets.
login_setcryptfmt(): The login_setcryptfmt() function is used; to set the
crypt(3) format using the `passwd_for; mat' configuration entry. If no entry is found, def; is taken to be
used as the fallback. If calling; crypt_set_format(3)
on the specifier fails, error is re; turned to indicate
this.

docs.sk

comprehensive documentation repository

See also

login_cap(3)

NAME

LIBRARY

SYNOPSIS

DESCRIPTION

SEE ALSO