1.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, is permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice immediately at the beginning of the file, without modification, 9.\" this list of conditions, and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. This work was done expressly for inclusion into FreeBSD. Other use 14.\" is permitted provided this notation is included. 15.\" 4. Absolutely no warranty of function or purpose is made by the author 16.\" David Nugent. 17.\" 5. Modifications may be freely made to this file providing the above 18.\" conditions are met. 19.\" 20.\" $FreeBSD: src/lib/libutil/login_cap.3,v 1.17.2.8 2002/12/29 16:35:36 schweikh Exp $ 21.\" $DragonFly: src/lib/libutil/login_cap.3,v 1.3 2004/03/11 12:28:53 hmp Exp $ 22.\" 23.Dd December 27, 1996 24.Os 25.Dt LOGIN_CAP 3 26.Sh NAME 27.Nm login_close , 28.Nm login_getcapbool , 29.Nm login_getcaplist , 30.Nm login_getcapnum , 31.Nm login_getcapstr , 32.Nm login_getcapsize , 33.Nm login_getcaptime , 34.Nm login_getclass , 35.Nm login_getclassbyname , 36.Nm login_getpwclass , 37.Nm login_getstyle , 38.Nm login_getuserclass , 39.Nm login_setcryptfmt 40.Nd "functions for accessing the login class capabilities database" 41.Sh LIBRARY 42.Lb libutil 43.Sh SYNOPSIS 44.In sys/types.h 45.In login_cap.h 46.Ft void 47.Fn login_close "login_cap_t *lc" 48.Ft login_cap_t * 49.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd" 50.Ft login_cap_t * 51.Fn login_getclass "const char *nam" 52.Ft login_cap_t * 53.Fn login_getpwclass "const struct passwd *pwd" 54.Ft login_cap_t * 55.Fn login_getuserclass "const struct passwd *pwd" 56.Ft char * 57.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *error" 58.Ft char ** 59.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars" 60.Ft char * 61.Fn login_getpath "login_cap_t *lc" "const char *cap" "char *error" 62.Ft rlim_t 63.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 64.Ft rlim_t 65.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 66.Ft rlim_t 67.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 68.Ft int 69.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def" 70.Ft char * 71.Fn login_getstyle "login_cap_t *lc" "char *style" "const char *auth" 72.Ft const char * 73.Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error" 74.Sh DESCRIPTION 75These functions represent a programming interface to the login 76classes database provided in 77.Xr login.conf 5 . 78This database contains capabilities, attributes and default environment 79and accounting settings for users and programs running as specific users, 80as determined by the login class field within entries in 81.Pa /etc/master.passwd . 82.Pp 83Entries in 84.Xr login.conf 5 85consist of colon 86.Ql \&: 87separated fields, the first field in each record being one or more 88identifiers for the record (which must be unique for the entire database), 89each separated by a '|', and may optionally include a description as 90the last 'name'. 91Remaining fields in the record consist of keyword/data pairs. 92Long lines may be continued with a backslash within empty entries, 93with the second and subsequent lines optionally indented for readability. 94This is similar to the format used in 95.Xr termcap 5 , 96except that keywords are not limited to two significant characters, 97and are usually longer for improved readability. 98As with termcap entries, multiple records can be linked together 99(one record including another) using a field containing tc=<recordid>. 100The result is that the entire record referenced by <recordid> replaces 101the tc= field at the point at which it occurs. 102See 103.Xr getcap 3 104for further details on the format and use of a capabilities database. 105.Pp 106The 107.Nm login_cap 108interface provides a convenient means of retrieving login class 109records with all tc= references expanded. 110A program will typically call one of 111.Fn login_getclass , 112.Fn login_getpwclass , 113.Fn login_getuserclass 114or 115.Fn login_getclassbyname 116according to its requirements. 117Each of these functions returns a login capabilities structure, 118.Ft login_cap_t , 119which may subsequently be used to interrogate the database for 120specific values using the rest of the API. 121Once the login_cap_t is of no further use, the 122.Fn login_close 123function should be called to free all resources used. 124.Pp 125The structure of login_cap_t is defined in login_cap.h, as: 126.Bd -literal -offset indent 127typedef struct { 128 char *lc_class; 129 char *lc_cap; 130 char *lc_style; 131} login_cap_t; 132.Ed 133.Pp 134The 135.Ar lc_class 136member contains a pointer to the name of the login class 137retrieved. 138This may not necessarily be the same as the one requested, 139either directly via 140.Fn login_getclassbyname , 141indirectly via a user's login record using 142.Fn login_getpwclass , 143by class name using 144.Fn login_getclass , 145or 146.Fn login_getuserclass . 147If the referenced user has no login class specified in 148.Pa /etc/master.passwd , 149the class name is NULL or an empty string. 150If the class 151specified does not exist in the database, each of these 152functions will search for a record with an id of "default", 153with that name returned in the 154.Ar lc_class 155field. 156In addition, if the referenced user has a UID of 0 (normally, 157"root", although the user name is not considered) then 158.Fn login_getpwclass 159will search for a record with an id of "root" before it searches 160for the record with the id of "default". 161.Pp 162The 163.Ar lc_cap 164field is used internally by the library to contain the 165expanded login capabilities record. 166Programs with unusual requirements may wish to use this 167with the lower-level 168.Fn getcap 169style functions to access the record directly. 170.Pp 171The 172.Ar lc_style 173field is set by the 174.Fn login_getstyle 175function to the authorisation style, according to the requirements 176of the program handling a login itself. 177.Pp 178As noted above, the 179.Fn get*class 180functions return a login_cap_t object which is used to access 181the matching or default record in the capabilities database. 182.Fn getclassbyname 183accepts two arguments: the first one is the record identifier of the 184record to be retrieved, the second is an optional directory name. 185If the first 186.Ar name 187argument is NULL, an empty string, or a class that does not exist 188in the supplemental or system login class database, then the system 189.Em default 190record is returned instead. 191If the second 192.Ar dir 193parameter is NULL, then only the system login class database is 194used, but when not NULL, the named directory is searched for 195a login database file called ".login_conf", and capability records 196contained within it may override the system defaults. 197This scheme allows users to override some login settings from 198those in the system login class database by creating class records 199for their own private class with a record id of `me'. 200In the context of a 201.Em login , 202it should be noted that some options cannot by overridden by 203users for two reasons; many options, such as resource settings 204and default process priorities, require root privileges 205in order to take effect, and other fields in the user's file are 206not be consulted at all during the early phases of login for 207security or administrative reasons. 208See 209.Xr login.conf 5 210for more information on which settings a user is able to override. 211Typically, these are limited purely to the user's default login 212environment which might otherwise have been overridden in shell 213startup scripts in any case. 214The user's 215.Pa .login_conf 216merely provides a convenient way for a user to set up their preferred 217login environment before the shell is invoked on login. 218.Pp 219If the specified record is NULL, empty or does not exist, and the 220system has no "default" record available to fall back to, there is a 221memory allocation error or for some reason 222.Xr cgetent 3 223is unable to access the login capabilities database, this function 224returns NULL. 225.Pp 226The functions 227.Fn login_getpwclass , 228.Fn login_getclass 229and 230.Fn login_getuserclass 231retrieve the applicable login class record for the user's passwd 232entry or class name by calling 233.Fn login_getclassbyname . 234On failure, NULL is returned. 235The difference between these functions is that 236.Fn login_getuserclass 237includes the user's overriding 238.Pa .login_conf 239that exists in the user's home directory, and 240.Fn login_getpwclass 241and 242.Fn login_getclass 243restrict lookup only to the system login class database in 244.Pa /etc/login.conf . 245As explained earlier, 246.Fn login_getpwclass 247only differs from 248.Fn login_getclass 249in that it allows the default class for user 'root' as "root" 250if none has been specified in the password database. 251Otherwise, if the passwd pointer is NULL, or the user record 252has no login class, then the system "default" entry is retrieved. 253.Pp 254Once a program no longer wishes to use a login_cap_t object, 255.Fn login_close 256may be called to free all resources used by the login class. 257.Fn login_close 258may be passed a NULL pointer with no harmful side-effects. 259.Pp 260The remaining functions may be used to retrieve individual 261capability records. 262Each function takes a login_cap_t object as its first parameter, 263a capability tag as the second, and remaining parameters being 264default and error values that are returned if the capability is 265not found. 266The type of the additional parameters passed and returned depend 267on the 268.Em type 269of capability each deals with, be it a simple string, a list, 270a time value, a file or memory size value, a path (consisting of 271a colon-separated list of directories) or a boolean flag. 272The manpage for 273.Xr login.conf 5 274deals in specific tags and their type. 275.Pp 276Note that with all functions in this group, you should not call 277.Xr free 3 278on any pointers returned. 279Memory allocated during retrieval or processing of capability 280tags is automatically reused by subsequent calls to functions 281in this group, or deallocated on calling 282.Fn login_close . 283.Bl -tag -width "login_getcaplist()" 284.It Fn login_getcapstr 285This function returns a simple string capability. 286If the string is not found, then the value in 287.Ar def 288is returned as the default value, or if an error 289occurs, the value in the 290.Ar error 291parameter is returned. 292.It Fn login_getcaplist 293This function returns the value corresponding to the named 294capability tag as a list of values in a NULL terminated 295array. 296Within the login class database, some tags are of type 297.Em list , 298which consist of one or more comma- or space separated 299values. 300Usually, this function is not called directly from an 301application, but is used indirectly via 302.Fn login_getstyle . 303.It Fn login_getpath 304This function returns a list of directories separated by colons 305.Ql &: . 306Capability tags for which this function is called consist of a list of 307directories separated by spaces. 308.It Fn login_getcaptime 309This function returns a 310.Em time value 311associated with a particular capability tag with the value expressed 312in seconds (the default), minutes, hours, days, weeks or (365 day) 313years or any combination of these. 314A suffix determines the units used: S for seconds, M for minutes, 315H for hours, D for days, W for weeks and Y for 365 day years. 316Case of the units suffix is ignored. 317.Pp 318Time values are normally used for setting resource, accounting and 319session limits. 320If supported by the operating system and compiler (which is true of 321.Dx ) , 322the value returned is a quad (long long), of type 323.Em rlim_t . 324A value "inf" or "infinity" may be used to express an infinite 325value, in which case RLIM_INFINITY is returned. 326.It Fn login_getcapnum 327This function returns a numeric value for a tag, expressed either as 328tag=<value> or the standard 329.Fn cgetnum 330format tag#<value>. 331The first format should be used in preference to the second, the 332second format is provided for compatibility and consistency with the 333.Xr getcap 3 334database format where numeric types use the 335.Ql \&# 336as the delimiter for numeric values. 337If in the first format, then the value given may be "inf" or 338"infinity" which results in a return value of RLIM_INFINITY. 339If the given capability tag cannot be found, the 340.Ar def 341parameter is returned, and if an error occurs, the 342.Ar error 343parameter is returned. 344.It Fn login_getcapsize 345.Fn login_getcapsize 346returns a value representing a size (typically, file or memory) 347which may be expressed as bytes (the default), 512 byte blocks, 348kilobytes, megabytes, gigabytes, and on systems that support the 349.Ar long long 350type, terabytes. 351The suffix used determines the units, and multiple values and 352units may be used in combination (e.g. 1m500k = 1.5 megabytes). 353A value with no suffix is interpreted as bytes, B as 512-byte 354blocks, K as kilobytes, M as megabytes, G as gigabytes and T as 355terabytes. 356Case is ignored. 357The error value is returned if there is a login capabilities database 358error, if an invalid suffix is used, or if a numeric value cannot be 359interpreted. 360.It Fn login_getcapbool 361This function returns a boolean value tied to a particular flag. 362It returns 0 if the given capability tag is not present or is 363negated by the presence of a "tag@" (See 364.Xr getcap 3 365for more information on boolean flags), and returns 1 if the tag 366is found. 367.It Fn login_getstyle 368This function is used by the login authorisation system to determine 369the style of login available in a particular case. 370The function accepts three parameters, the login_cap entry itself and 371two optional parameters, and authorisation type 'auth' and 'style', and 372applies these to determine the authorisation style that best suites 373these rules. 374.Bl -bullet 375.It 376If 'auth' is neither NULL nor an empty string, look for a tag of type 377"auth-<auth>" in the capability record. 378If not present, then look for the default tag "auth=". 379.It 380If no valid authorisation list was found from the previous step, then 381default to "passwd" as the authorisation list. 382.It 383If 'style' is not NULL or empty, look for it in the list of authorisation 384methods found from the pprevious step. 385If 'style' is NULL or an empty string, then default to "passwd" 386authorisation. 387.It 388If 'style' is found in the chosen list of authorisation methods, then 389return that, otherwise return NULL. 390.El 391.Pp 392This scheme allows the administrator to determine the types of 393authorisation methods accepted by the system, depending on the 394means by which the access occurs. 395For example, the administrator may require skey or kerberos as 396the authentication method used for access to the system via the 397network, and standard methods via direct dialup or console 398logins, significantly reducing the risk of password discovery 399by "snooping" network packets. 400.It Fn login_setcryptfmt 401The 402.Fn login_setcryptfmt 403function is used to set the 404.Xr crypt 3 405format using the 406.Ql passwd_format 407configuration entry. 408If no entry is found, 409.Fa def 410is taken to be used as the fallback. 411If calling 412.Xr crypt_set_format 3 413on the specifier fails, 414.Fa error 415is returned to indicate this. 416.El 417.Sh SEE ALSO 418.Xr crypt 3 , 419.Xr getcap 3 , 420.Xr login_class 3 , 421.Xr login.conf 5 , 422.Xr termcap 5 423