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$ 21.\" 22.Dd June 14, 2007 23.Dt LOGIN_CAP 3 24.Os 25.Sh NAME 26.Nm login_close , 27.Nm login_getcapbool , 28.Nm login_getcaplist , 29.Nm login_getcapnum , 30.Nm login_getcapstr , 31.Nm login_getcapsize , 32.Nm login_getcaptime , 33.Nm login_getclass , 34.Nm login_getclassbyname , 35.Nm login_getpwclass , 36.Nm login_getstyle , 37.Nm login_getuserclass , 38.Nm login_setcryptfmt 39.Nd "functions for accessing the login class capabilities database" 40.Sh LIBRARY 41.Lb libutil 42.Sh SYNOPSIS 43.In sys/types.h 44.In login_cap.h 45.Ft void 46.Fn login_close "login_cap_t *lc" 47.Ft login_cap_t * 48.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd" 49.Ft login_cap_t * 50.Fn login_getclass "const char *nam" 51.Ft login_cap_t * 52.Fn login_getpwclass "const struct passwd *pwd" 53.Ft login_cap_t * 54.Fn login_getuserclass "const struct passwd *pwd" 55.Ft "const char *" 56.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "const char *def" "const char *error" 57.Ft "const char **" 58.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars" 59.Ft "const char *" 60.Fn login_getpath "login_cap_t *lc" "const char *cap" "const char *error" 61.Ft rlim_t 62.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 63.Ft rlim_t 64.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 65.Ft rlim_t 66.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" 67.Ft int 68.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def" 69.Ft "const char *" 70.Fn login_getstyle "login_cap_t *lc" "const char *style" "const char *auth" 71.Ft const char * 72.Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error" 73.Sh DESCRIPTION 74These functions represent a programming interface to the login 75classes database provided in 76.Xr login.conf 5 . 77This database contains capabilities, attributes and default environment 78and accounting settings for users and programs running as specific users, 79as determined by the login class field within entries in 80.Pa /etc/master.passwd . 81.Pp 82Entries in 83.Xr login.conf 5 84consist of colon 85.Ql \&: 86separated fields, the first field in each record being one or more 87identifiers for the record (which must be unique for the entire database), 88each separated by a 89.Ql | , 90and may optionally include a description as 91the last 92.Sq name . 93Remaining fields in the record consist of keyword/data pairs. 94Long lines may be continued with a backslash within empty entries, 95with the second and subsequent lines optionally indented for readability. 96This is similar to the format used in 97.Xr termcap 5 , 98except that keywords are not limited to two significant characters, 99and are usually longer for improved readability. 100As with termcap entries, multiple records can be linked together 101(one record including another) using a field containing 102.Ql tc= Ns Va <recordid> . 103The result is that the entire record referenced by 104.Va <recordid> 105replaces the 106.Va tc= 107field at the point at which it occurs. 108See 109.Xr getcap 3 110for further details on the format and use of a capabilities database. 111.Pp 112The 113.Nm login_cap 114interface provides a convenient means of retrieving login class 115records with all 116.Va tc= 117references expanded. 118A program will typically call one of 119.Fn login_getclass , 120.Fn login_getpwclass , 121.Fn login_getuserclass 122or 123.Fn login_getclassbyname 124according to its requirements. 125Each of these functions returns a login capabilities structure, 126.Vt login_cap_t , 127which may subsequently be used to interrogate the database for 128specific values using the rest of the API. 129Once the 130.Vt login_cap_t 131is of no further use, the 132.Fn login_close 133function should be called to free all resources used. 134.Pp 135The structure of 136.Vt login_cap_t 137is defined in 138.In login_cap.h , 139as: 140.Bd -literal -offset indent 141typedef struct { 142 char *lc_class; 143 char *lc_cap; 144 char *lc_style; 145} login_cap_t; 146.Ed 147.Pp 148The 149.Fa lc_class 150member contains a pointer to the name of the login class 151retrieved. 152This may not necessarily be the same as the one requested, 153either directly via 154.Fn login_getclassbyname , 155or indirectly via a user's login record using 156.Fn login_getpwclass , 157by class name using 158.Fn login_getclass . 159If the referenced user has no login class specified in 160.Pa /etc/master.passwd , 161the class name is 162.Dv NULL 163or an empty string. 164If the class 165specified does not exist in the database, each of these 166functions will search for a record with an id of 167.Ql default , 168with that name returned in the 169.Fa lc_class 170field. 171In addition, if the referenced user has a UID of 0 (normally, 172.Ql root , 173although the user name is not considered) then 174.Fn login_getpwclass 175will search for a record with an id of 176.Ql root 177before it searches 178for the record with the id of 179.Ql default . 180.Pp 181The 182.Fa lc_cap 183field is used internally by the library to contain the 184expanded login capabilities record. 185Programs with unusual requirements may wish to use this 186with the lower-level 187.Fn getcap 188style functions to access the record directly. 189.Pp 190The 191.Fa lc_style 192field is set by the 193.Fn login_getstyle 194function to the authorisation style, according to the requirements 195of the program handling a login itself. 196.Pp 197The 198.Fn login_getclassbyname 199function is the basic means to get a 200.Vt login_cap_t 201object. 202It accepts two arguments: the first one, 203.Fa name , 204is the record identifier of the 205record to be retrieved; the second, 206.Fa pwd , 207is an optional pointer to a 208.Vt passwd 209structure. 210First of all, its arguments are used by the function 211to choose between system and user modes of operation. 212When in system mode, only the system login class database is used. 213When in user mode, the supplemental login class database in the 214user's home directory is allowed to override settings from the system 215database in a limited way as noted below. 216To minimize security implications, user mode is entered by 217.Fn login_getclassbyname 218if and only if 219.Fa name 220is 221.Dv LOGIN_MECLASS 222.Pq Ql me 223and 224.Fa pwd 225is not 226.Dv NULL . 227Otherwise system mode is chosen. 228.Pp 229In system mode, any record in the system database 230.Pa /etc/login.conf 231can be accessed, 232and a fallback to the default record is provided as follows. 233If 234.Fa name 235is 236.Dv NULL , 237an empty string, or a class that does not exist 238in the login class database, then the 239.Dv LOGIN_DEFCLASS 240record 241.Pq Ql default 242is returned instead. 243.Pp 244In user mode, only the 245.Dv LOGIN_MECLASS 246record 247.Pq Ql me 248is accessed and no fallback to the 249.Ql default 250record is provided. 251The directory specified by 252.Fa pwd->pw_dir 253is searched for 254a login database file called 255.Pa .login_conf , 256and only the 257.Ql me 258capability record 259contained within it may override the system record with the same name 260while other records are ignored. 261Using this scheme, an application can explicitly 262allow users to override a selected subset of login settings. 263To do so, the application should obtain two 264.Vt login_cap_t 265objects, one in user mode and the other in system mode, 266and then query the user object before the 267system object for login parameters that are allowed to 268be overridden by the user. 269For example, the user's 270.Pa .login_conf 271can provide a convenient way for a user to set up their preferred 272login environment before the shell is invoked on login if supported by 273.Xr login 1 . 274.Pp 275Note that access to the 276.Pa /etc/login.conf 277and 278.Pa .login_conf 279files will only be performed subject to the security checks documented in 280.Xr _secure_path 3 281for the uids 0 and 282.Fa pwd->pw_uid 283respectively. 284.Pp 285If the specified record is 286.Dv NULL , 287empty or does not exist, and the 288system has no 289.Ql default 290record available to fall back to, there is a 291memory allocation error or for some reason 292.Xr cgetent 3 293is unable to access the login capabilities database, this function 294returns 295.Dv NULL . 296.Pp 297The functions 298.Fn login_getclass , 299.Fn login_getpwclass 300and 301.Fn login_getuserclass 302retrieve the applicable login class record for the user's passwd 303entry or class name by calling 304.Fn login_getclassbyname . 305On failure, 306.Dv NULL 307is returned. 308The difference between these functions is that 309.Fn login_getuserclass 310includes the user's overriding 311.Pa .login_conf 312that exists in the user's home directory, and 313.Fn login_getpwclass 314and 315.Fn login_getclass 316restrict lookup only to the system login class database in 317.Pa /etc/login.conf . 318As explained earlier, 319.Fn login_getpwclass 320differs from 321.Fn login_getclass 322in that it allows the default class for a super-user as 323.Ql root 324if none has been specified in the password database. 325Otherwise, if the passwd pointer is 326.Dv NULL , 327or the user record 328has no login class, then the system 329.Ql default 330entry is retrieved. 331Essentially, 332.Fn login_getclass name 333is equivalent to 334.Fn login_getclassbyname name NULL 335and 336.Fn login_getuserclass pwd 337to 338.Fn login_getclassbyname LOGIN_MECLASS pwd . 339.Pp 340Once a program no longer wishes to use a 341.Vt login_cap_t 342object, 343.Fn login_close 344may be called to free all resources used by the login class. 345The 346.Fn login_close 347function may be passed a 348.Dv NULL 349pointer with no harmful side-effects. 350.Pp 351The remaining functions may be used to retrieve individual 352capability records. 353Each function takes a 354.Vt login_cap_t 355object as its first parameter, 356a capability tag as the second, and remaining parameters being 357default and error values that are returned if the capability is 358not found. 359The type of the additional parameters passed and returned depend 360on the 361.Em type 362of capability each deals with, be it a simple string, a list, 363a time value, a file or memory size value, a path (consisting of 364a colon-separated list of directories) or a boolean flag. 365The manpage for 366.Xr login.conf 5 367deals in specific tags and their type. 368.Pp 369Note that with all functions in this group, you should not call 370.Xr free 3 371on any pointers returned. 372Memory allocated during retrieval or processing of capability 373tags is automatically reused by subsequent calls to functions 374in this group, or deallocated on calling 375.Fn login_close . 376.Bl -tag -width "login_getcaplist()" 377.It Fn login_getcapstr 378This function returns a simple string capability. 379If the string is not found, then the value in 380.Fa def 381is returned as the default value, or if an error 382occurs, the value in the 383.Fa error 384parameter is returned. 385.It Fn login_getcaplist 386This function returns the value corresponding to the named 387capability tag as a list of values in a 388.Dv NULL 389terminated array. 390Within the login class database, some tags are of type 391.Vt list , 392which consist of one or more comma- or space separated 393values. 394Usually, this function is not called directly from an 395application, but is used indirectly via 396.Fn login_getstyle . 397.It Fn login_getpath 398This function returns a list of directories separated by colons 399.Ql \&: . 400Capability tags for which this function is called consist of a list of 401directories separated by spaces. 402.It Fn login_getcaptime 403This function returns a 404.Vt time value 405associated with a particular capability tag with the value expressed 406in seconds (the default), minutes, hours, days, weeks or (365 day) 407years or any combination of these. 408A suffix determines the units used: 409.Ql S 410for seconds, 411.Ql M 412for minutes, 413.Ql H 414for hours, 415.Ql D 416for days, 417.Ql W 418for weeks and 419.Ql Y 420for 365 day years. 421Case of the units suffix is ignored. 422.Pp 423Time values are normally used for setting resource, accounting and 424session limits. 425If supported by the operating system and compiler (which is true of 426.Fx ) , 427the value returned is a 428.Vt quad 429.Pq Vt long long , 430of type 431.Vt rlim_t . 432A value 433.Ql inf 434or 435.Ql infinity 436may be used to express an infinite 437value, in which case 438.Dv RLIM_INFINITY 439is returned. 440.It Fn login_getcapnum 441This function returns a numeric value for a tag, expressed either as 442.Ql tag=<value> 443or the standard 444.Fn cgetnum 445format 446.Ql tag#<value> . 447The first format should be used in preference to the second, the 448second format is provided for compatibility and consistency with the 449.Xr getcap 3 450database format where numeric types use the 451.Ql \&# 452as the delimiter for numeric values. 453If in the first format, then the value given may be 454.Ql inf 455or 456.Ql infinity 457which results in a return value of 458.Dv RLIM_INFINITY . 459If the given capability tag cannot be found, the 460.Fa def 461parameter is returned, and if an error occurs, the 462.Fa error 463parameter is returned. 464.It Fn login_getcapsize 465.Fn login_getcapsize 466returns a value representing a size (typically, file or memory) 467which may be expressed as bytes (the default), 512 byte blocks, 468kilobytes, megabytes, gigabytes, and on systems that support the 469.Vt long long 470type, terabytes. 471The suffix used determines the units, and multiple values and 472units may be used in combination (e.g.\& 1m500k = 1.5 megabytes). 473A value with no suffix is interpreted as bytes, 474.Ql B 475as 512-byte blocks, 476.Ql K 477as kilobytes, 478.Ql M 479as megabytes, 480.Ql G 481as gigabytes and 482.Ql T 483as terabytes. 484Case is ignored. 485The error value is returned if there is a login capabilities database 486error, if an invalid suffix is used, or if a numeric value cannot be 487interpreted. 488.It Fn login_getcapbool 489This function returns a boolean value tied to a particular flag. 490It returns 0 if the given capability tag is not present or is 491negated by the presence of a 492.Ql tag@ 493(see 494.Xr getcap 3 495for more information on boolean flags), and returns 1 if the tag 496is found. 497.It Fn login_getstyle 498This function is used by the login authorisation system to determine 499the style of login available in a particular case. 500The function accepts three parameters, the 501.Fa lc 502entry itself and 503two optional parameters, and authorisation type 504.Fa auth 505and 506.Fa style , 507and 508applies these to determine the authorisation style that best suites 509these rules. 510.Bl -bullet 511.It 512If 513.Fa auth 514is neither 515.Dv NULL 516nor an empty string, look for a tag of type 517.Ql auth- Ns Fa <auth> 518in the capability record. 519If not present, then look for the default tag 520.Va auth= . 521.It 522If no valid authorisation list was found from the previous step, then 523default to 524.Ql passwd 525as the authorisation list. 526.It 527If 528.Fa style 529is not 530.Dv NULL 531or empty, look for it in the list of authorisation 532methods found from the previous step. 533If 534.Fa style 535is 536.Dv NULL 537or an empty string, then default to 538.Ql passwd 539authorisation. 540.It 541If 542.Fa style 543is found in the chosen list of authorisation methods, then 544return that, otherwise return 545.Dv NULL . 546.El 547.Pp 548This scheme allows the administrator to determine the types of 549authorisation methods accepted by the system, depending on the 550means by which the access occurs. 551For example, the administrator may require skey or kerberos as 552the authentication method used for access to the system via the 553network, and standard methods via direct dialup or console 554logins, significantly reducing the risk of password discovery 555by "snooping" network packets. 556.It Fn login_setcryptfmt 557The 558.Fn login_setcryptfmt 559function is used to set the 560.Xr crypt 3 561format using the 562.Va passwd_format 563configuration entry. 564If no entry is found, 565.Fa def 566is taken to be used as the fallback. 567If calling 568.Xr crypt_set_format 3 569on the specifier fails, 570.Fa error 571is returned to indicate this. 572.El 573.Sh SEE ALSO 574.Xr login 1 , 575.Xr crypt 3 , 576.Xr getcap 3 , 577.Xr login_class 3 , 578.Xr login.conf 5 , 579.Xr termcap 5 580