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