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