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