lib/libutil/login_cap.3

.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, is permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice immediately at the beginning of the file, without modification,
.\"    this list of conditions, and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
.\"    is permitted provided this notation is included.
.\" 4. Absolutely no warranty of function or purpose is made by the author
.\"    David Nugent.
.\" 5. Modifications may be freely made to this file providing the above
.\"    conditions are met.
.\"
.Dd May 10, 2020
.Dt LOGIN_CAP 3
.Os
.Sh NAME
.Nm login_close ,
.Nm login_getcapbool ,
.Nm login_getcaplist ,
.Nm login_getcapnum ,
.Nm login_getcapenum ,
.Nm login_getcapstr ,
.Nm login_getcapsize ,
.Nm login_getcaptime ,
.Nm login_getclass ,
.Nm login_getclassbyname ,
.Nm login_getpwclass ,
.Nm login_getstyle ,
.Nm login_getuserclass ,
.Nm login_setcryptfmt
.Nd "functions for accessing the login class capabilities database"
.Sh LIBRARY
.Lb libutil
.Sh SYNOPSIS
.In sys/types.h
.In login_cap.h
.Ft void
.Fn login_close "login_cap_t *lc"
.Ft login_cap_t *
.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd"
.Ft login_cap_t *
.Fn login_getclass "const char *nam"
.Ft login_cap_t *
.Fn login_getpwclass "const struct passwd *pwd"
.Ft login_cap_t *
.Fn login_getuserclass "const struct passwd *pwd"
.Ft "const char *"
.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "const char *def" "const char *error"
.Ft "const char **"
.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars"
.Ft "const char *"
.Fn login_getpath "login_cap_t *lc" "const char *cap" "const char *error"
.Ft rlim_t
.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft rlim_t
.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft int
.Fn login_getcapenum "login_cap_t *lc" "const char *cap" "const char * const *values"
.Ft rlim_t
.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft int
.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def"
.Ft "const char *"
.Fn login_getstyle "login_cap_t *lc" "const char *style" "const char *auth"
.Ft const char *
.Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error"
.Sh DESCRIPTION
These functions represent a programming interface to the login
classes database provided in
.Xr 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 login class field within entries in
.Pa /etc/master.passwd .
.Pp
Entries in
.Xr login.conf 5
consist of colon
.Ql \&:
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
.Ql | ,
and may optionally include a description as
the last
.Sq name .
Remaining 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
.Xr termcap 5 ,
except that keywords are not limited to two significant characters,
and are usually longer for improved readability.
As with termcap entries, multiple records can be linked together
(one record including another) using a field containing
.Ql tc= Ns Va <recordid> .
The result is that the entire record referenced by
.Va <recordid>
replaces the
.Va tc=
field at the point at which it occurs.
See
.Xr getcap 3
for further details on the format and use of a capabilities database.
.Pp
The
.Nm login_cap
interface provides a convenient means of retrieving login class
records with all
.Va tc=
references expanded.
A program will typically call one of
.Fn login_getclass ,
.Fn login_getpwclass ,
.Fn login_getuserclass
or
.Fn login_getclassbyname
according to its requirements.
Each of these functions returns a login capabilities structure,
.Vt login_cap_t ,
which may subsequently be used to interrogate the database for
specific values using the rest of the API.
Once the
.Vt login_cap_t
is of no further use, the
.Fn login_close
function should be called to free all resources used.
.Pp
The structure of
.Vt login_cap_t
is defined in
.In login_cap.h ,
as:
.Bd -literal -offset indent
typedef struct {
	char *lc_class;
	char *lc_cap;
	char *lc_style;
} login_cap_t;
.Ed
.Pp
The
.Fa 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
.Fn login_getclassbyname ,
or indirectly via a user's login record using
.Fn login_getpwclass ,
by class name using
.Fn login_getclass .
If the referenced user has no login class specified in
.Pa /etc/master.passwd ,
the class name is
.Dv 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
.Ql default ,
with that name returned in the
.Fa lc_class
field.
In addition, if the referenced user has a UID of 0 (normally,
.Ql root ,
although the user name is not considered) then
.Fn login_getpwclass
will search for a record with an id of
.Ql root
before it searches
for the record with the id of
.Ql default .
.Pp
The
.Fa lc_cap
field is used internally by the library to contain the
expanded login capabilities record.
Programs with unusual requirements may wish to use this
with the lower-level
.Fn getcap
style functions to access the record directly.
.Pp
The
.Fa lc_style
field is set by the
.Fn login_getstyle
function to the authorisation style, according to the requirements
of the program handling a login itself.
.Pp
The
.Fn login_getclassbyname
function is the basic means to get a
.Vt login_cap_t
object.
It accepts two arguments: the first one,
.Fa name ,
is the record identifier of the
record to be retrieved; the second,
.Fa pwd ,
is an optional pointer to a
.Vt passwd
structure.
First of all, its arguments are used by the function
to choose between system and user modes of operation.
When in system mode, only the system login class database is used.
When in user mode, the supplemental login class database in the
user's home directory is allowed to override settings from the system
database in a limited way as noted below.
To minimize security implications, user mode is entered by
.Fn login_getclassbyname
if and only if
.Fa name
is
.Dv LOGIN_MECLASS
.Pq Ql me
and
.Fa pwd
is not
.Dv NULL .
Otherwise system mode is chosen.
.Pp
In system mode, any record in the system database
.Pa /etc/login.conf
can be accessed,
and a fallback to the default record is provided as follows.
If
.Fa name
is
.Dv NULL ,
an empty string, or a class that does not exist
in the login class database, then the
.Dv LOGIN_DEFCLASS
record
.Pq Ql default
is returned instead.
.Pp
In user mode, only the
.Dv LOGIN_MECLASS
record
.Pq Ql me
is accessed and no fallback to the
.Ql default
record is provided.
The directory specified by
.Fa pwd->pw_dir
is searched for
a login database file called
.Pa .login_conf ,
and only the
.Ql me
capability record
contained within it may override the system record with the same name
while other records are ignored.
Using this scheme, an application can explicitly
allow users to override a selected subset of login settings.
To do so, the application should obtain two
.Vt login_cap_t
objects, one in user mode and the other in system mode,
and then query the user object before the
system object for login parameters that are allowed to
be overridden by the user.
For example, the user's
.Pa .login_conf
can provide a convenient way for a user to set up their preferred
login environment before the shell is invoked on login if supported by
.Xr login 1 .
.Pp
Note that access to the
.Pa /etc/login.conf
and
.Pa .login_conf
files will only be performed subject to the security checks documented in
.Xr _secure_path 3
for the uids 0 and
.Fa pwd->pw_uid
respectively.
.Pp
If the specified record is
.Dv NULL ,
empty or does not exist, and the
system has no
.Ql default
record available to fall back to, there is a
memory allocation error or for some reason
.Xr cgetent 3
is unable to access the login capabilities database, this function
returns
.Dv NULL .
.Pp
The functions
.Fn login_getclass ,
.Fn login_getpwclass
and
.Fn login_getuserclass
retrieve the applicable login class record for the user's passwd
entry or class name by calling
.Fn login_getclassbyname .
On failure,
.Dv NULL
is returned.
The difference between these functions is that
.Fn login_getuserclass
includes the user's overriding
.Pa .login_conf
that exists in the user's home directory, and
.Fn login_getpwclass
and
.Fn login_getclass
restrict lookup only to the system login class database in
.Pa /etc/login.conf .
As explained earlier,
.Fn login_getpwclass
differs from
.Fn login_getclass
in that it allows the default class for a super-user as
.Ql root
if none has been specified in the password database.
Otherwise, if the passwd pointer is
.Dv NULL ,
or the user record
has no login class, then the system
.Ql default
entry is retrieved.
Essentially,
.Fn login_getclass name
is equivalent to
.Fn login_getclassbyname name NULL
and
.Fn login_getuserclass pwd
to
.Fn login_getclassbyname LOGIN_MECLASS pwd .
.Pp
Once a program no longer wishes to use a
.Vt login_cap_t
object,
.Fn login_close
may be called to free all resources used by the login class.
The
.Fn login_close
function may be passed a
.Dv NULL
pointer with no harmful side-effects.
.Pp
The remaining functions may be used to retrieve individual
capability records.
Each function takes a
.Vt login_cap_t
object as its first parameter,
a capability tag as the second, and remaining parameters being
default and error values that are returned if the capability is
not found.
The type of the additional parameters passed and returned depend
on the
.Em type
of capability each deals with, be it a simple string, a list,
a time value, a file or memory size value, a path (consisting of
a colon-separated list of directories) or a boolean flag.
The manpage for
.Xr login.conf 5
deals in specific tags and their type.
.Pp
Note that with all functions in this group, you should not call
.Xr 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
.Fn login_close .
.Bl -tag -width "login_getcaplist()"
.It Fn login_getcapstr
This function returns a simple string capability.
If the string is not found, then the value in
.Fa def
is returned as the default value, or if an error
occurs, the value in the
.Fa error
parameter is returned.
.It Fn login_getcaplist
This function returns the value corresponding to the named
capability tag as a list of values in a
.Dv NULL
terminated array.
Within the login class database, some tags are of type
.Vt list ,
which consist of one or more comma- or space separated
values.
Usually, this function is not called directly from an
application, but is used indirectly via
.Fn login_getstyle .
.It Fn login_getpath
This function returns a list of directories separated by colons
.Ql \&: .
Capability tags for which this function is called consist of a list of
directories separated by spaces.
.It Fn login_getcaptime
This function returns a
.Vt time value
associated 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:
.Ql S
for seconds,
.Ql M
for minutes,
.Ql H
for hours,
.Ql D
for days,
.Ql W
for weeks and
.Ql Y
for 365 day years.
Case of the units suffix is ignored.
.Pp
Time values are normally used for setting resource, accounting and
session limits.
If supported by the operating system and compiler (which is true of
.Fx ) ,
the value returned is a
.Vt quad
.Pq Vt long long ,
of type
.Vt rlim_t .
A value
.Ql inf
or
.Ql infinity
may be used to express an infinite
value, in which case
.Dv RLIM_INFINITY
is returned.
.It Fn login_getcapnum
This function returns a numeric value for a tag, expressed either as
.Ql tag=<value>
or the standard
.Fn cgetnum
format
.Ql tag#<value> .
The first format should be used in preference to the second, the
second format is provided for compatibility and consistency with the
.Xr getcap 3
database format where numeric types use the
.Ql \&#
as the delimiter for numeric values.
If in the first format, then the value given may be
.Ql inf
or
.Ql infinity
which results in a return value of
.Dv RLIM_INFINITY .
If the given capability tag cannot be found, the
.Fa def
parameter is returned, and if an error occurs, the
.Fa error
parameter is returned.
.It Fn login_getcapenum
This function returns whether the searched capability is a string with value
among a predefined set passed in argument
.Fa values
as a NULL-terminated array of strings.
.Pp
A non-negative value indicates a match and is the index of the capability's
value in array
.Fa values .
Other possible return values are:
.Bl -tag -width "-4"
.It -4
Returned if
.Fa lc
or
.Fa cap
are insufficiently initialized or invalid.
.It -3
Returned on allocation failure (out of memory).
.It -2
Returned if the capability isn't specified or its value is not a string.
.It -1
Returned if the capability is specified and a string but its value is not among
.Fa values .
.El
.It Fn login_getcapsize
.Fn login_getcapsize
returns a value representing 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
.Vt 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,
.Ql B
as 512-byte blocks,
.Ql K
as kilobytes,
.Ql M
as megabytes,
.Ql G
as gigabytes and
.Ql T
as terabytes.
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.
.It Fn login_getcapbool
This function returns a boolean value tied to a particular flag.
It returns 0 if the given capability tag is not present or is
negated by the presence of a
.Ql tag@
(see
.Xr getcap 3
for more information on boolean flags), and returns 1 if the tag
is found.
.It Fn login_getstyle
This function is used by the login authorisation system to determine
the style of login available in a particular case.
The function accepts three parameters, the
.Fa lc
entry itself and
two optional parameters, and authorisation type
.Fa auth
and
.Fa style ,
and
applies these to determine the authorisation style that best suites
these rules.
.Bl -bullet
.It
If
.Fa auth
is neither
.Dv NULL
nor an empty string, look for a tag of type
.Ql auth- Ns Fa <auth>
in the capability record.
If not present, then look for the default tag
.Va auth= .
.It
If no valid authorisation list was found from the previous step, then
default to
.Ql passwd
as the authorisation list.
.It
If
.Fa style
is not
.Dv NULL
or empty, look for it in the list of authorisation
methods found from the previous step.
If
.Fa style
is
.Dv NULL
or an empty string, then default to
.Ql passwd
authorisation.
.It
If
.Fa style
is found in the chosen list of authorisation methods, then
return that, otherwise return
.Dv NULL .
.El
.Pp
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
network, and standard methods via direct dialup or console
logins, significantly reducing the risk of password discovery
by "snooping" network packets.
.It Fn login_setcryptfmt
The
.Fn login_setcryptfmt
function is used to set the
.Xr crypt 3
format using the
.Va passwd_format
configuration entry.
If no entry is found,
.Fa def
is taken to be used as the fallback.
If calling
.Xr crypt_set_format 3
on the specifier fails,
.Fa error
is returned to indicate this.
.El
.Sh SEE ALSO
.Xr login 1 ,
.Xr crypt 3 ,
.Xr getcap 3 ,
.Xr login_class 3 ,
.Xr login.conf 5 ,
.Xr termcap 5
.Sh HISTORY
The functions
.Fn login_close ,
.Fn login_getcapbool ,
.Fn login_getcaplist ,
.Fn login_getcapnum ,
.Fn login_getcapstr ,
.Fn login_getcapsize ,
.Fn login_getcaptime ,
.Fn login_getclass ,
.Fn login_getclassbyname ,
.Fn login_getpwclass ,
.Fn login_getstyle ,
.Fn login_getuserclass
and
.Fn login_setcryptfmt
first appeared in
.Fx 2.1.5 .