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