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.
25 .Nm login_getcapbool ,
26 .Nm login_getcaplist ,
29 .Nm login_getcapsize ,
30 .Nm login_getcaptime ,
32 .Nm login_getclassbyname ,
33 .Nm login_getpwclass ,
35 .Nm login_getuserclass ,
37 .Nd "functions for accessing the login class capabilities database"
44 .Fn login_close "login_cap_t *lc"
46 .Fn login_getclassbyname "const char *nam" "const struct passwd *pwd"
48 .Fn login_getclass "const char *nam"
50 .Fn login_getpwclass "const struct passwd *pwd"
52 .Fn login_getuserclass "const struct passwd *pwd"
54 .Fn login_getcapstr "login_cap_t *lc" "const char *cap" "const char *def" "const char *error"
56 .Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars"
58 .Fn login_getpath "login_cap_t *lc" "const char *cap" "const char *error"
60 .Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
62 .Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
64 .Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
66 .Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def"
68 .Fn login_getstyle "login_cap_t *lc" "const char *style" "const char *auth"
70 .Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error"
72 These functions represent a programming interface to the login
73 classes database provided in
75 This database contains capabilities, attributes and default environment
76 and accounting settings for users and programs running as specific users,
77 as determined by the login class field within entries in
78 .Pa /etc/master.passwd .
84 separated fields, the first field in each record being one or more
85 identifiers for the record (which must be unique for the entire database),
88 and may optionally include a description as
91 Remaining fields in the record consist of keyword/data pairs.
92 Long lines may be continued with a backslash within empty entries,
93 with the second and subsequent lines optionally indented for readability.
94 This is similar to the format used in
96 except that keywords are not limited to two significant characters,
97 and are usually longer for improved readability.
98 As with termcap entries, multiple records can be linked together
99 (one record including another) using a field containing
100 .Ql tc= Ns Va <recordid> .
101 The result is that the entire record referenced by
105 field at the point at which it occurs.
108 for further details on the format and use of a capabilities database.
112 interface provides a convenient means of retrieving login class
116 A program will typically call one of
118 .Fn login_getpwclass ,
119 .Fn login_getuserclass
121 .Fn login_getclassbyname
122 according to its requirements.
123 Each of these functions returns a login capabilities structure,
125 which may subsequently be used to interrogate the database for
126 specific values using the rest of the API.
129 is of no further use, the
131 function should be called to free all resources used.
138 .Bd -literal -offset indent
148 member contains a pointer to the name of the login class
150 This may not necessarily be the same as the one requested,
152 .Fn login_getclassbyname ,
153 or indirectly via a user's login record using
154 .Fn login_getpwclass ,
157 If the referenced user has no login class specified in
158 .Pa /etc/master.passwd ,
163 specified does not exist in the database, each of these
164 functions will search for a record with an id of
166 with that name returned in the
169 In addition, if the referenced user has a UID of 0 (normally,
171 although the user name is not considered) then
173 will search for a record with an id of
176 for the record with the id of
181 field is used internally by the library to contain the
182 expanded login capabilities record.
183 Programs with unusual requirements may wish to use this
186 style functions to access the record directly.
192 function to the authorisation style, according to the requirements
193 of the program handling a login itself.
196 .Fn login_getclassbyname
197 function is the basic means to get a
200 It accepts two arguments: the first one,
202 is the record identifier of the
203 record to be retrieved; the second,
205 is an optional pointer to a
208 First of all, its arguments are used by the function
209 to choose between system and user modes of operation.
210 When in system mode, only the system login class database is used.
211 When in user mode, the supplemental login class database in the
212 user's home directory is allowed to override settings from the system
213 database in a limited way as noted below.
214 To minimize security implications, user mode is entered by
215 .Fn login_getclassbyname
225 Otherwise system mode is chosen.
227 In system mode, any record in the system database
230 and a fallback to the default record is provided as follows.
235 an empty string, or a class that does not exist
236 in the login class database, then the
242 In user mode, only the
246 is accessed and no fallback to the
249 The directory specified by
252 a login database file called
257 contained within it may override the system record with the same name
258 while other records are ignored.
259 Using this scheme, an application can explicitly
260 allow users to override a selected subset of login settings.
261 To do so, the application should obtain two
263 objects, one in user mode and the other in system mode,
264 and then query the user object before the
265 system object for login parameters that are allowed to
266 be overridden by the user.
267 For example, the user's
269 can provide a convenient way for a user to set up their preferred
270 login environment before the shell is invoked on login if supported by
273 Note that access to the
277 files will only be performed subject to the security checks documented in
283 If the specified record is
285 empty or does not exist, and the
288 record available to fall back to, there is a
289 memory allocation error or for some reason
291 is unable to access the login capabilities database, this function
299 .Fn login_getuserclass
300 retrieve the applicable login class record for the user's passwd
301 entry or class name by calling
302 .Fn login_getclassbyname .
306 The difference between these functions is that
307 .Fn login_getuserclass
308 includes the user's overriding
310 that exists in the user's home directory, and
314 restrict lookup only to the system login class database in
315 .Pa /etc/login.conf .
316 As explained earlier,
320 in that it allows the default class for a super-user as
322 if none has been specified in the password database.
323 Otherwise, if the passwd pointer is
326 has no login class, then the system
330 .Fn login_getclass name
332 .Fn login_getclassbyname name NULL
334 .Fn login_getuserclass pwd
336 .Fn login_getclassbyname LOGIN_MECLASS pwd .
338 Once a program no longer wishes to use a
342 may be called to free all resources used by the login class.
345 function may be passed a
347 pointer with no harmful side-effects.
349 The remaining functions may be used to retrieve individual
351 Each function takes a
353 object as its first parameter,
354 a capability tag as the second, and remaining parameters being
355 default and error values that are returned if the capability is
357 The type of the additional parameters passed and returned depend
360 of capability each deals with, be it a simple string, a list,
361 a time value, a file or memory size value, a path (consisting of
362 a colon-separated list of directories) or a boolean flag.
365 deals in specific tags and their type.
367 Note that with all functions in this group, you should not call
369 on any pointers returned.
370 Memory allocated during retrieval or processing of capability
371 tags is automatically reused by subsequent calls to functions
372 in this group, or deallocated on calling
374 .Bl -tag -width "login_getcaplist()"
375 .It Fn login_getcapstr
376 This function returns a simple string capability.
377 If the string is not found, then the value in
379 is returned as the default value, or if an error
380 occurs, the value in the
382 parameter is returned.
383 .It Fn login_getcaplist
384 This function returns the value corresponding to the named
385 capability tag as a list of values in a
388 Within the login class database, some tags are of type
390 which consist of one or more comma- or space separated
392 Usually, this function is not called directly from an
393 application, but is used indirectly via
396 This function returns a list of directories separated by colons
398 Capability tags for which this function is called consist of a list of
399 directories separated by spaces.
400 .It Fn login_getcaptime
401 This function returns a
403 associated with a particular capability tag with the value expressed
404 in seconds (the default), minutes, hours, days, weeks or (365 day)
405 years or any combination of these.
406 A suffix determines the units used:
419 Case of the units suffix is ignored.
421 Time values are normally used for setting resource, accounting and
423 If supported by the operating system and compiler (which is true of
425 the value returned is a
434 may be used to express an infinite
438 .It Fn login_getcapnum
439 This function returns a numeric value for a tag, expressed either as
445 The first format should be used in preference to the second, the
446 second format is provided for compatibility and consistency with the
448 database format where numeric types use the
450 as the delimiter for numeric values.
451 If in the first format, then the value given may be
455 which results in a return value of
457 If the given capability tag cannot be found, the
459 parameter is returned, and if an error occurs, the
461 parameter is returned.
462 .It Fn login_getcapsize
464 returns a value representing a size (typically, file or memory)
465 which may be expressed as bytes (the default), 512 byte blocks,
466 kilobytes, megabytes, gigabytes, and on systems that support the
469 The suffix used determines the units, and multiple values and
470 units may be used in combination (e.g.\& 1m500k = 1.5 megabytes).
471 A value with no suffix is interpreted as bytes,
483 The error value is returned if there is a login capabilities database
484 error, if an invalid suffix is used, or if a numeric value cannot be
486 .It Fn login_getcapbool
487 This function returns a boolean value tied to a particular flag.
488 It returns 0 if the given capability tag is not present or is
489 negated by the presence of a
493 for more information on boolean flags), and returns 1 if the tag
495 .It Fn login_getstyle
496 This function is used by the login authorisation system to determine
497 the style of login available in a particular case.
498 The function accepts three parameters, the
501 two optional parameters, and authorisation type
506 applies these to determine the authorisation style that best suites
514 nor an empty string, look for a tag of type
515 .Ql auth- Ns Fa <auth>
516 in the capability record.
517 If not present, then look for the default tag
520 If no valid authorisation list was found from the previous step, then
523 as the authorisation list.
529 or empty, look for it in the list of authorisation
530 methods found from the previous step.
535 or an empty string, then default to
541 is found in the chosen list of authorisation methods, then
542 return that, otherwise return
546 This scheme allows the administrator to determine the types of
547 authorisation methods accepted by the system, depending on the
548 means by which the access occurs.
549 For example, the administrator may require skey or kerberos as
550 the authentication method used for access to the system via the
551 network, and standard methods via direct dialup or console
552 logins, significantly reducing the risk of password discovery
553 by "snooping" network packets.
554 .It Fn login_setcryptfmt
556 .Fn login_setcryptfmt
557 function is used to set the
562 If no entry is found,
564 is taken to be used as the fallback.
566 .Xr crypt_set_format 3
567 on the specifier fails,
569 is returned to indicate this.
581 .Fn login_getcapbool ,
582 .Fn login_getcaplist ,
583 .Fn login_getcapnum ,
584 .Fn login_getcapstr ,
585 .Fn login_getcapsize ,
586 .Fn login_getcaptime ,
588 .Fn login_getclassbyname ,
589 .Fn login_getpwclass ,
591 .Fn login_getuserclass
593 .Fn login_setcryptfmt