LOGIN_CAP(3)

okay so LOGIN_CAP(3) is one of those pages that looks scary and then turns out to be a whole friend group of tiny functions that all just want to read stuff out of your login class database 🫶 grab a snack, we're going through it together, and there's a part 2 so don't go anywhere.

✨ NAME ✨

login_close, login_getcapbool, login_getcaplist, login_getcapnum, login_getcapenum, login_getcapstr, login_getcapsize, login_getcaptime, login_getclass, login_getclassbyname, login_getpath, login_getpwclass, login_getstyle, login_getuserclass, login_setcryptfmt — functions for accessing the login class capabilities database 💅

🌈 LIBRARY 🌈

System Utilities Library (libutil, -lutil) — yes bestie, that's the whole line, it's giving minimalist icon ✨

🎀 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);

const 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);

int
login_getcapenum(login_cap_t *lc, const char *cap,
    const char * const *values);

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 💖

🌸 what even is this

These functions are basically a programming interface to the login classes database that lives in login.conf(5) 👑 That database is where all the capabilities, attributes and default environment and accounting settings for users and for programs running as specific users hang out — and which entry you get is decided by the login class field inside entries in /etc/master.passwd.

🌼 the file format, aka why your config looks like that

Entries in login.conf(5) are made of colon ‘:’ separated fields, and the first field of every record is one or more identifiers for that record (these have to be unique across the entire database, no sharing bestie), each one separated by a ‘|’, and it can optionally include a description as the last ‘name’. The rest of the fields in the record are keyword/data pairs. Long lines may be continued with a backslash within empty entries, and the second and subsequent lines can be indented for readability, because we are not monsters.

It's similar to the format used in termcap(5), except keywords here are not limited to two significant characters, and they're usually longer for improved readability ✨ And just like termcap entries, multiple records can be linked together (one record including another) using a field containing tc=<recordid>. The result? The entire record referenced by <recordid> replaces the tc= field right at the point where it occurs. See getcap(3) for the further details on the format and use of a capabilities database — that's the lore drop, go read it.

🦋 how you actually use this thing

The login_cap interface is the convenient way to get login class records with all the tc= references already expanded, which is the whole point, it's iconic.

A program will typically call one of login_getclass(), login_getpwclass(), login_getuserclass() or login_getclassbyname() depending on what it actually needs. Each of these returns a login capabilities structure, login_cap_t, which you can then use to interrogate the database for specific values using the rest of the API 🔥 Once your login_cap_t is of no further use, call login_close() to free all the resources it used, no cap.

💜 the struct, look at her

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;

🌟 lc_class

The lc_class member has a pointer to the name of the login class that got retrieved. And listen — this may not necessarily be the same as the one that was requested, whether that was directly via login_getclassbyname(), or indirectly via a user's login record using login_getpwclass(), or by class name using login_getclass().

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 doesn't exist in the database, each of these functions searches for a record with an id of ‘default’, and that name is what comes back in the lc_class field 💫 Plus! 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 ‘default’. main character privileges, honestly 👑

🌸 lc_cap

The lc_cap field is used internally by the library to hold the expanded login capabilities record. Programs with unusual requirements may want to use it with the lower-level getcap() style functions to access the record directly 👀

🎀 lc_style

The lc_style field gets set by the login_getstyle() function to the authorisation style, according to what the program handling the login itself requires.

---

🌈 login_getclassbyname() — the ✨basic✨ one

The login_getclassbyname() function is the basic means to get a login_cap_t object. It takes two arguments: the first, name, is the record identifier of the record you want retrieved; the second, pwd, is an optional pointer to a passwd structure.

First of all, the function uses its arguments to choose between system and user modes of operation:

• system mode — only the system login class database is used.
• 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 login_getclassbyname() if and only if name is LOGIN_MECLASS (‘me’) and pwd is not NULL. Otherwise system mode is chosen 💅

🫶 system mode

In system mode, any record in the system database /etc/login.conf can be accessed, and a fallback to the default record is provided like this: if name is NULL, an empty string, or a class that doesn't exist in the login class database, then the LOGIN_DEFCLASS record (‘default’) is returned instead.

🧚 user mode

In user mode, only the LOGIN_MECLASS record (‘me’) is accessed and no fallback to the ‘default’ record is provided — sorry bestie, that safety net is gone.

The directory specified by pwd->pw_dir is searched for a login database file called .login_conf, and only the ‘me’ capability record contained in 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 that, the application should grab two 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 the login parameters that are allowed to be overridden by the user. For example, the user's .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 login(1) 🌸

⚠️ note note note: access 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. iykyk, do not skip this part.

💀 when it just returns NULL

If the specified record is NULL, empty or doesn't exist, and the system has no ‘default’ record available to fall back to, or there's a memory allocation error, or for some reason cgetent(3) is unable to access the login capabilities database — this function returns NULL. that's the whole vibe check and it failed 😭

---

🦋 login_getclass(), login_getpwclass(), login_getuserclass()

These three 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 them is this, and it matters:

• login_getuserclass() includes the user's overriding .login_conf that exists in the user's home directory.
• login_getpwclass() and login_getclass() restrict lookup only to the system login class database in /etc/login.conf.

And as explained earlier, login_getpwclass() differs from login_getclass() in that it allows the default class for a super-user 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.

Essentially, login_getclass(name) is equivalent to login_getclassbyname(name, NULL) and login_getuserclass(pwd) to login_getclassbyname(LOGIN_MECLASS, pwd) ✨

---

🎀 login_close()

Once a program no longer wants to use a login_cap_t object, login_close() may be called to free all resources used by the login class. And good news: login_close() may be passed a NULL pointer with no harmful side-effects 🫶 clean up after yourself, it's called being an adult.

---

💅 the capability-getting besties

The remaining functions get individual capability records. Each one takes a login_cap_t object as its first parameter, a capability tag as the second, and the remaining parameters are default and error values that get returned if the capability isn't found.

The type of the additional parameters passed and returned depends on the type of capability each one 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 login.conf(5) deals in the specific tags and their type, so that's your tag directory, go off 👑

🚨 real talk warning: with all functions in this group, you should not call free(3) on any pointers returned. Memory allocated while retrieving or processing capability tags is automatically reused by subsequent calls to functions in this group, or deallocated when you call login_close(). so don't touch it, it's not yours, it's the library's 💀

🌟 login_getcapstr()

This function returns a simple string capability. If the string isn't found, then the value in def is returned as the default value — or if an error occurs, the value in the error parameter is returned. two escape hatches, iconic.

🌸 login_getcaplist()

This function returns the value corresponding 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 consist of one or more comma- or space separated values. Usually this function isn't called directly from an application — it's used indirectly via login_getstyle() 🦋

🌈 login_getpath()

This function returns a list of directories separated by colons ‘:’. Capability tags for which this function is called consist of a list of directories separated by spaces.

💖 login_getcaptime() 💖

Okay bestie, this one returns a time value tied to a particular capability tag, and that value can be expressed in seconds (the default), minutes, hours, days, weeks, or (365-day) years — or literally any combo of those. The suffix tells you the units: '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, so no stress about caps lock.

Time values are normally used for setting resource, accounting, and session limits. If the operating system and compiler support it — and yes, that's true of FreeBSD — the value returned is a quad (long long), of type rlim_t. And if you write 'inf' or 'infinity', that means infinite, and RLIM_INFINITY gets returned. Iconic.

🎀 login_getcapnum() 🎀

This cutie returns a numeric value for a tag, expressed either as 'tag=<value>' or the standard cgetnum() format 'tag#<value>'. Use the first format, please — it's the preferred one. The second format is there for compatibility and consistency with the getcap(3) database format, where numeric types use '#' as the delimiter for numeric values. If you're in the first format, the value can be 'inf' or 'infinity', which gives you back RLIM_INFINITY. If the capability tag can't be found, the def parameter is returned, and if an error happens, the error parameter is returned. Fr fr.

🦋 login_getcapenum() 🦋

This function returns whether the searched capability is a string whose value is among a predefined set passed in argument values as a NULL-terminated array of strings.

A non-negative value means a match happened, and that number is the index of the capability's value in array values. Other possible return values are:

• -4 — returned if lc or cap are insufficiently initialized or invalid.
• -3 — returned on allocation failure (out of memory).
• -2 — returned if the capability isn't specified or its value is not a string.
• -1 — returned if the capability is specified and is a string, but its value is not among values.

🌸 login_getcapsize() 🌸

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 long long type, terabytes. The suffix determines the units, and multiple values and units may be used in combination (e.g. 1m500k = 1.5 megabytes). No suffix means bytes, 'B' means 512-byte blocks, 'K' means kilobytes, 'M' means megabytes, 'G' means gigabytes, and 'T' means terabytes. Case is ignored. The error value is returned if there's a login capabilities database error, if an invalid suffix is used, or if a numeric value cannot be interpreted. No cap.

💅 login_getcapbool() 💅

This one 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 'tag@' — see getcap(3) for more info on boolean flags — and it returns 1 if the tag is found. Simple, clean, slay.

👑 login_getstyle() 👑

This function is used by the login authorisation system to determine the style of login available in a particular case. It accepts three parameters: the lc entry itself and two optional parameters, authorisation type auth and style, and it applies these to determine the authorisation style that best suites these rules:

• If auth is neither NULL nor an empty string, look for a tag of type 'auth-<auth>' in the capability record. If it's not present, then look for the default tag auth=.
• If no valid authorisation list was found from the previous step, then default to 'passwd' as the authorisation list.
• 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' authorisation.
• If style is found in the chosen list of authorisation methods, then return that; otherwise return NULL.

This scheme lets the administrator determine the types of authorisation methods accepted by the system, depending on the means by which the access occurs. 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. Highkey a glow-up for security.

🧚 login_setcryptfmt() 🧚

The login_setcryptfmt() function is used to set the crypt(3) format using the passwd_format 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 returned to indicate this. Cute and to the point.

---

✨ SEE ALSO ✨

login(1), crypt(3), getcap(3), login_class(3), login.conf(5), termcap(5)

🌈 HISTORY 🌈

The functions login_close(), login_getcapbool(), login_getcaplist(), login_getcapnum(), login_getcapstr(), login_getcapsize(), login_getcaptime(), login_getclass(), login_getclassbyname(), login_getpwclass(), login_getstyle(), login_getuserclass() and login_setcryptfmt() first appeared in FreeBSD 2.1.5. Periodt.

---

That's the whole page, bestie. Source/version vibes: Debian, dated May 10, 2020, and the page is LOGIN_CAP(3) — slay and goodbye 💅✨