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.7 2008/11/23 21:55:52 swildner 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 126.In login_cap.h , 127as: 128.Bd -literal -offset indent 129typedef struct { 130 char *lc_class; 131 char *lc_cap; 132 char *lc_style; 133} login_cap_t; 134.Ed 135.Pp 136The 137.Ar lc_class 138member contains a pointer to the name of the login class 139retrieved. 140This may not necessarily be the same as the one requested, 141either directly via 142.Fn login_getclassbyname , 143indirectly via a user's login record using 144.Fn login_getpwclass , 145by class name using 146.Fn login_getclass , 147or 148.Fn login_getuserclass . 149If the referenced user has no login class specified in 150.Pa /etc/master.passwd , 151the class name is NULL or an empty string. 152If the class 153specified does not exist in the database, each of these 154functions will search for a record with an id of "default", 155with that name returned in the 156.Ar lc_class 157field. 158In addition, if the referenced user has a UID of 0 (normally, 159"root", although the user name is not considered) then 160.Fn login_getpwclass 161will search for a record with an id of "root" before it searches 162for the record with the id of "default". 163.Pp 164The 165.Ar lc_cap 166field is used internally by the library to contain the 167expanded login capabilities record. 168Programs with unusual requirements may wish to use this 169with the lower-level 170.Xr getcap 3 171style functions to access the record directly. 172.Pp 173The 174.Ar lc_style 175field is set by the 176.Fn login_getstyle 177function to the authorisation style, according to the requirements 178of the program handling a login itself. 179.Pp 180As noted above, the 181.Fn login_get*class 182functions return a login_cap_t object which is used to access 183the matching or default record in the capabilities database. 184.Fn login_getclassbyname 185accepts two arguments: the first one is the record identifier of the 186record to be retrieved, the second is an optional directory name. 187If the first 188.Ar name 189argument is NULL, an empty string, or a class that does not exist 190in the supplemental or system login class database, then the system 191.Em default 192record is returned instead. 193If the second 194.Ar dir 195parameter is NULL, then only the system login class database is 196used, but when not NULL, the named directory is searched for 197a login database file called ".login_conf", and capability records 198contained within it may override the system defaults. 199This scheme allows users to override some login settings from 200those in the system login class database by creating class records 201for their own private class with a record id of `me'. 202In the context of a 203.Em login , 204it should be noted that some options cannot by overridden by 205users for two reasons; many options, such as resource settings 206and default process priorities, require root privileges 207in order to take effect, and other fields in the user's file are 208not be consulted at all during the early phases of login for 209security or administrative reasons. 210See 211.Xr login.conf 5 212for more information on which settings a user is able to override. 213Typically, these are limited purely to the user's default login 214environment which might otherwise have been overridden in shell 215startup scripts in any case. 216The user's 217.Pa .login_conf 218merely provides a convenient way for a user to set up their preferred 219login environment before the shell is invoked on login. 220.Pp 221If the specified record is NULL, empty or does not exist, and the 222system has no "default" record available to fall back to, there is a 223memory allocation error or for some reason 224.Xr cgetent 3 225is unable to access the login capabilities database, this function 226returns NULL. 227.Pp 228The functions 229.Fn login_getpwclass , 230.Fn login_getclass 231and 232.Fn login_getuserclass 233retrieve the applicable login class record for the user's passwd 234entry or class name by calling 235.Fn login_getclassbyname . 236On failure, NULL is returned. 237The difference between these functions is that 238.Fn login_getuserclass 239includes the user's overriding 240.Pa .login_conf 241that exists in the user's home directory, and 242.Fn login_getpwclass 243and 244.Fn login_getclass 245restrict lookup only to the system login class database in 246.Pa /etc/login.conf . 247As explained earlier, 248.Fn login_getpwclass 249only differs from 250.Fn login_getclass 251in that it allows the default class for user 'root' as "root" 252if none has been specified in the password database. 253Otherwise, if the passwd pointer is NULL, or the user record 254has no login class, then the system "default" entry is retrieved. 255.Pp 256Once a program no longer wishes to use a login_cap_t object, 257.Fn login_close 258may be called to free all resources used by the login class. 259.Fn login_close 260may be passed a NULL pointer with no harmful side-effects. 261.Pp 262The remaining functions may be used to retrieve individual 263capability records. 264Each function takes a login_cap_t object as its first parameter, 265a capability tag as the second, and remaining parameters being 266default and error values that are returned if the capability is 267not found. 268The type of the additional parameters passed and returned depend 269on the 270.Em type 271of capability each deals with, be it a simple string, a list, 272a time value, a file or memory size value, a path (consisting of 273a colon-separated list of directories) or a boolean flag. 274The manpage for 275.Xr login.conf 5 276deals in specific tags and their type. 277.Pp 278Note that with all functions in this group, you should not call 279.Xr free 3 280on any pointers returned. 281Memory allocated during retrieval or processing of capability 282tags is automatically reused by subsequent calls to functions 283in this group, or deallocated on calling 284.Fn login_close . 285.Bl -tag -width ".Fn login_setcryptfmt" 286.It Fn login_getcapstr 287This function returns a simple string capability. 288If the string is not found, then the value in 289.Ar def 290is returned as the default value, or if an error 291occurs, the value in the 292.Ar error 293parameter is returned. 294.It Fn login_getcaplist 295This function returns the value corresponding to the named 296capability tag as a list of values in a NULL terminated 297array. 298Within the login class database, some tags are of type 299.Em list , 300which consist of one or more comma- or space separated 301values. 302Usually, this function is not called directly from an 303application, but is used indirectly via 304.Fn login_getstyle . 305.It Fn login_getpath 306This function returns a list of directories separated by colons 307.Ql &: . 308Capability tags for which this function is called consist of a list of 309directories separated by spaces. 310.It Fn login_getcaptime 311This function returns a 312.Em time value 313associated with a particular capability tag with the value expressed 314in seconds (the default), minutes, hours, days, weeks or (365 day) 315years or any combination of these. 316A suffix determines the units used: S for seconds, M for minutes, 317H for hours, D for days, W for weeks and Y for 365 day years. 318Case of the units suffix is ignored. 319.Pp 320Time values are normally used for setting resource, accounting and 321session limits. 322If supported by the operating system and compiler (which is true of 323.Dx ) , 324the value returned is a quad (long long), of type 325.Em rlim_t . 326A value "inf" or "infinity" may be used to express an infinite 327value, in which case RLIM_INFINITY is returned. 328.It Fn login_getcapnum 329This function returns a numeric value for a tag, expressed either as 330tag=<value> or the standard 331.Fn cgetnum 332format tag#<value>. 333The first format should be used in preference to the second, the 334second format is provided for compatibility and consistency with the 335.Xr getcap 3 336database format where numeric types use the 337.Ql \&# 338as the delimiter for numeric values. 339If in the first format, then the value given may be "inf" or 340"infinity" which results in a return value of RLIM_INFINITY. 341If the given capability tag cannot be found, the 342.Ar def 343parameter is returned, and if an error occurs, the 344.Ar error 345parameter is returned. 346.It Fn login_getcapsize 347.Fn login_getcapsize 348returns a value representing a size (typically, file or memory) 349which may be expressed as bytes (the default), 512 byte blocks, 350kilobytes, megabytes, gigabytes, and on systems that support the 351.Ar long long 352type, terabytes. 353The suffix used determines the units, and multiple values and 354units may be used in combination (e.g. 1m500k = 1.5 megabytes). 355A value with no suffix is interpreted as bytes, B as 512-byte 356blocks, K as kilobytes, M as megabytes, G as gigabytes and T as 357terabytes. 358Case is ignored. 359The error value is returned if there is a login capabilities database 360error, if an invalid suffix is used, or if a numeric value cannot be 361interpreted. 362.It Fn login_getcapbool 363This function returns a boolean value tied to a particular flag. 364It returns 0 if the given capability tag is not present or is 365negated by the presence of a "tag@" (See 366.Xr getcap 3 367for more information on boolean flags), and returns 1 if the tag 368is found. 369.It Fn login_getstyle 370This function is used by the login authorisation system to determine 371the style of login available in a particular case. 372The function accepts three parameters, the login_cap entry itself and 373two optional parameters, and authorisation type 'auth' and 'style', and 374applies these to determine the authorisation style that best suites 375these rules. 376.Bl -bullet 377.It 378If 'auth' is neither NULL nor an empty string, look for a tag of type 379"auth-<auth>" in the capability record. 380If not present, then look for the default tag "auth=". 381.It 382If no valid authorisation list was found from the previous step, then 383default to "passwd" as the authorisation list. 384.It 385If 'style' is not NULL or empty, look for it in the list of authorisation 386methods found from the pprevious step. 387If 'style' is NULL or an empty string, then default to "passwd" 388authorisation. 389.It 390If 'style' is found in the chosen list of authorisation methods, then 391return that, otherwise return NULL. 392.El 393.Pp 394This scheme allows the administrator to determine the types of 395authorisation methods accepted by the system, depending on the 396means by which the access occurs. 397For example, the administrator may require skey or kerberos as 398the authentication method used for access to the system via the 399network, and standard methods via direct dialup or console 400logins, significantly reducing the risk of password discovery 401by "snooping" network packets. 402.It Fn login_setcryptfmt 403The 404.Fn login_setcryptfmt 405function is used to set the 406.Xr crypt 3 407format using the 408.Ql passwd_format 409configuration entry. 410If no entry is found, 411.Fa def 412is taken to be used as the fallback. 413If calling 414.Xr crypt_set_format 3 415on the specifier fails, 416.Fa error 417is returned to indicate this. 418.El 419.Sh SEE ALSO 420.Xr crypt 3 , 421.Xr getcap 3 , 422.Xr login_class 3 , 423.Xr login.conf 5 , 424.Xr termcap 5 425