1 .\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, is permitted provided that the following conditions
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
17 .\" 5. Modifications may be freely made to this file providing the above
18 .\" conditions are met.
20 .\" $FreeBSD: src/lib/libutil/login_cap.3,v 1.17.2.8 2002/12/29 16:35:36 schweikh Exp $
27 .Nm login_getcapbool ,
28 .Nm login_getcaplist ,
31 .Nm login_getcapsize ,
32 .Nm login_getcaptime ,
34 .Nm login_getclassbyname ,
35 .Nm login_getpwclass ,
37 .Nm login_getuserclass ,
39 .Nd "functions for accessing the login class capabilities database"
46 .Fn login_close "login_cap_t *lc"
48 .Fn login_getclassbyname "const char *nam" "const struct passwd *pwd"
50 .Fn login_getclass "const char *nam"
52 .Fn login_getpwclass "const struct passwd *pwd"
54 .Fn login_getuserclass "const struct passwd *pwd"
56 .Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *error"
58 .Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars"
60 .Fn login_getpath "login_cap_t *lc" "const char *cap" "char *error"
62 .Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
64 .Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
66 .Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
68 .Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def"
70 .Fn login_getstyle "login_cap_t *lc" "char *style" "const char *auth"
72 .Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error"
74 These functions represent a programming interface to the login
75 classes database provided in
77 This database contains capabilities, attributes and default environment
78 and accounting settings for users and programs running as specific users,
79 as determined by the login class field within entries in
80 .Pa /etc/master.passwd .
86 separated fields, the first field in each record being one or more
87 identifiers for the record (which must be unique for the entire database),
88 each separated by a '|', and may optionally include a description as
90 Remaining fields in the record consist of keyword/data pairs.
91 Long lines may be continued with a backslash within empty entries,
92 with the second and subsequent lines optionally indented for readability.
93 This is similar to the format used in
95 except that keywords are not limited to two significant characters,
96 and are usually longer for improved readability.
97 As with termcap entries, multiple records can be linked together
98 (one record including another) using a field containing tc=<recordid>.
99 The result is that the entire record referenced by <recordid> replaces
100 the tc= field at the point at which it occurs.
103 for further details on the format and use of a capabilities database.
107 interface provides a convenient means of retrieving login class
108 records with all tc= references expanded.
109 A program will typically call one of
111 .Fn login_getpwclass ,
112 .Fn login_getuserclass
114 .Fn login_getclassbyname
115 according to its requirements.
116 Each of these functions returns a login capabilities structure,
118 which may subsequently be used to interrogate the database for
119 specific values using the rest of the API.
120 Once the login_cap_t is of no further use, the
122 function should be called to free all resources used.
124 The structure of login_cap_t is defined in
127 .Bd -literal -offset indent
137 member contains a pointer to the name of the login class
139 This may not necessarily be the same as the one requested,
141 .Fn login_getclassbyname ,
142 indirectly via a user's login record using
143 .Fn login_getpwclass ,
147 .Fn login_getuserclass .
148 If the referenced user has no login class specified in
149 .Pa /etc/master.passwd ,
150 the class name is NULL or an empty string.
152 specified does not exist in the database, each of these
153 functions will search for a record with an id of "default",
154 with that name returned in the
157 In addition, if the referenced user has a UID of 0 (normally,
158 "root", although the user name is not considered) then
160 will search for a record with an id of "root" before it searches
161 for the record with the id of "default".
165 field is used internally by the library to contain the
166 expanded login capabilities record.
167 Programs with unusual requirements may wish to use this
170 style functions to access the record directly.
176 function to the authorisation style, according to the requirements
177 of the program handling a login itself.
181 functions return a login_cap_t object which is used to access
182 the matching or default record in the capabilities database.
183 .Fn login_getclassbyname
184 accepts two arguments: the first one is the record identifier of the
185 record to be retrieved, the second is an optional directory name.
188 argument is NULL, an empty string, or a class that does not exist
189 in the supplemental or system login class database, then the system
191 record is returned instead.
194 parameter is NULL, then only the system login class database is
195 used, but when not NULL, the named directory is searched for
196 a login database file called ".login_conf", and capability records
197 contained within it may override the system defaults.
198 This scheme allows users to override some login settings from
199 those in the system login class database by creating class records
200 for their own private class with a record id of `me'.
203 it should be noted that some options cannot by overridden by
204 users for two reasons; many options, such as resource settings
205 and default process priorities, require root privileges
206 in order to take effect, and other fields in the user's file are
207 not be consulted at all during the early phases of login for
208 security or administrative reasons.
211 for more information on which settings a user is able to override.
212 Typically, these are limited purely to the user's default login
213 environment which might otherwise have been overridden in shell
214 startup scripts in any case.
217 merely provides a convenient way for a user to set up their preferred
218 login environment before the shell is invoked on login.
220 If the specified record is NULL, empty or does not exist, and the
221 system has no "default" record available to fall back to, there is a
222 memory allocation error or for some reason
224 is unable to access the login capabilities database, this function
228 .Fn login_getpwclass ,
231 .Fn login_getuserclass
232 retrieve the applicable login class record for the user's passwd
233 entry or class name by calling
234 .Fn login_getclassbyname .
235 On failure, NULL is returned.
236 The difference between these functions is that
237 .Fn login_getuserclass
238 includes the user's overriding
240 that exists in the user's home directory, and
244 restrict lookup only to the system login class database in
245 .Pa /etc/login.conf .
246 As explained earlier,
250 in that it allows the default class for user 'root' as "root"
251 if none has been specified in the password database.
252 Otherwise, if the passwd pointer is NULL, or the user record
253 has no login class, then the system "default" entry is retrieved.
255 Once a program no longer wishes to use a login_cap_t object,
257 may be called to free all resources used by the login class.
259 may be passed a NULL pointer with no harmful side-effects.
261 The remaining functions may be used to retrieve individual
263 Each function takes a login_cap_t object as its first parameter,
264 a capability tag as the second, and remaining parameters being
265 default and error values that are returned if the capability is
267 The type of the additional parameters passed and returned depend
270 of capability each deals with, be it a simple string, a list,
271 a time value, a file or memory size value, a path (consisting of
272 a colon-separated list of directories) or a boolean flag.
275 deals in specific tags and their type.
277 Note that with all functions in this group, you should not call
279 on any pointers returned.
280 Memory allocated during retrieval or processing of capability
281 tags is automatically reused by subsequent calls to functions
282 in this group, or deallocated on calling
284 .Bl -tag -width ".Fn login_setcryptfmt"
285 .It Fn login_getcapstr
286 This function returns a simple string capability.
287 If the string is not found, then the value in
289 is returned as the default value, or if an error
290 occurs, the value in the
292 parameter is returned.
293 .It Fn login_getcaplist
294 This function returns the value corresponding to the named
295 capability tag as a list of values in a NULL terminated
297 Within the login class database, some tags are of type
299 which consist of one or more comma- or space separated
301 Usually, this function is not called directly from an
302 application, but is used indirectly via
305 This function returns a list of directories separated by colons
307 Capability tags for which this function is called consist of a list of
308 directories separated by spaces.
309 .It Fn login_getcaptime
310 This function returns a
312 associated with a particular capability tag with the value expressed
313 in seconds (the default), minutes, hours, days, weeks or (365 day)
314 years or any combination of these.
315 A suffix determines the units used: S for seconds, M for minutes,
316 H for hours, D for days, W for weeks and Y for 365 day years.
317 Case of the units suffix is ignored.
319 Time values are normally used for setting resource, accounting and
321 If supported by the operating system and compiler (which is true of
323 the value returned is a quad (long long), of type
325 A value "inf" or "infinity" may be used to express an infinite
326 value, in which case RLIM_INFINITY is returned.
327 .It Fn login_getcapnum
328 This function returns a numeric value for a tag, expressed either as
329 tag=<value> or the standard
332 The first format should be used in preference to the second, the
333 second format is provided for compatibility and consistency with the
335 database format where numeric types use the
337 as the delimiter for numeric values.
338 If in the first format, then the value given may be "inf" or
339 "infinity" which results in a return value of RLIM_INFINITY.
340 If the given capability tag cannot be found, the
342 parameter is returned, and if an error occurs, the
344 parameter is returned.
345 .It Fn login_getcapsize
347 returns a value representing a size (typically, file or memory)
348 which may be expressed as bytes (the default), 512 byte blocks,
349 kilobytes, megabytes, gigabytes, and on systems that support the
352 The suffix used determines the units, and multiple values and
353 units may be used in combination (e.g. 1m500k = 1.5 megabytes).
354 A value with no suffix is interpreted as bytes, B as 512-byte
355 blocks, K as kilobytes, M as megabytes, G as gigabytes and T as
358 The error value is returned if there is a login capabilities database
359 error, if an invalid suffix is used, or if a numeric value cannot be
361 .It Fn login_getcapbool
362 This function returns a boolean value tied to a particular flag.
363 It returns 0 if the given capability tag is not present or is
364 negated by the presence of a "tag@" (See
366 for more information on boolean flags), and returns 1 if the tag
368 .It Fn login_getstyle
369 This function is used by the login authorisation system to determine
370 the style of login available in a particular case.
371 The function accepts three parameters, the login_cap entry itself and
372 two optional parameters, and authorisation type 'auth' and 'style', and
373 applies these to determine the authorisation style that best suites
377 If 'auth' is neither NULL nor an empty string, look for a tag of type
378 "auth-<auth>" in the capability record.
379 If not present, then look for the default tag "auth=".
381 If no valid authorisation list was found from the previous step, then
382 default to "passwd" as the authorisation list.
384 If 'style' is not NULL or empty, look for it in the list of authorisation
385 methods found from the pprevious step.
386 If 'style' is NULL or an empty string, then default to "passwd"
389 If 'style' is found in the chosen list of authorisation methods, then
390 return that, otherwise return NULL.
393 This scheme allows the administrator to determine the types of
394 authorisation methods accepted by the system, depending on the
395 means by which the access occurs.
396 For example, the administrator may require skey or kerberos as
397 the authentication method used for access to the system via the
398 network, and standard methods via direct dialup or console
399 logins, significantly reducing the risk of password discovery
400 by "snooping" network packets.
401 .It Fn login_setcryptfmt
403 .Fn login_setcryptfmt
404 function is used to set the
409 If no entry is found,
411 is taken to be used as the fallback.
413 .Xr crypt_set_format 3
414 on the specifier fails,
416 is returned to indicate this.