From 31192e1f32dd2a6a2aa637b10d4074545c87cb1c Mon Sep 17 00:00:00 2001 From: yar Date: Thu, 14 Jun 2007 09:33:37 +0000 Subject: Document the quirks of ~/.login_conf and LOGIN_MECLASS. --- lib/libutil/login_cap.3 | 137 ++++++++++++++++++++++++++++-------------------- 1 file changed, 80 insertions(+), 57 deletions(-) (limited to 'lib/libutil') diff --git a/lib/libutil/login_cap.3 b/lib/libutil/login_cap.3 index ae95dc6..7ecefff 100644 --- a/lib/libutil/login_cap.3 +++ b/lib/libutil/login_cap.3 @@ -19,7 +19,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 27, 1996 +.Dd June 14, 2007 .Os .Dt LOGIN_CAP 3 .Sh NAME @@ -152,12 +152,10 @@ retrieved. This may not necessarily be the same as the one requested, either directly via .Fn login_getclassbyname , -indirectly via a user's login record using +or indirectly via a user's login record using .Fn login_getpwclass , by class name using -.Fn login_getclass , -or -.Fn login_getuserclass . +.Fn login_getclass . If the referenced user has no login class specified in .Pa /etc/master.passwd , the class name is @@ -196,68 +194,84 @@ field is set by the function to the authorisation style, according to the requirements of the program handling a login itself. .Pp -As noted above, the -.Fn login_get*class -functions return a -.Vt login_cap_t -object which is used to access -the matching or default record in the capabilities database. The .Fn login_getclassbyname -function accepts two arguments: the first one is the record identifier of the -record to be retrieved, the second is an optional pointer to a +function is the basic means to get a +.Vt login_cap_t +object. +It accepts two arguments: the first one, +.Fa name , +is the record identifier of the +record to be retrieved; the second, +.Fa pwd , +is an optional pointer to a .Vt passwd structure. -If the first +First of all, its arguments are used by the function +to choose between system and user modes of operation. +When in system mode, only the system login class database is used. +When in user mode, the supplemental login class database in the +user's home directory is allowed to override settings from the system +database in a limited way as noted below. +To minimize security implications, user mode is entered by +.Fn login_getclassbyname +if and only if .Fa name -argument is +is +.Dv LOGIN_MECLASS +.Pq Ql me +and +.Fa pwd +is not +.Dv NULL . +Otherwise system mode is chosen. +.Pp +In system mode, any record in the system database +.Pa /etc/login.conf +can be accessed, +and a fallback to the default record is provided as follows. +If +.Fa name +is .Dv NULL , an empty string, or a class that does not exist -in the supplemental or system login class database, then the system +in the login class database, then the +.Dv LOGIN_DEFCLASS +record +.Pq Ql default +is returned instead. +.Pp +In user mode, only the +.Dv LOGIN_MECLASS +record +.Pq Ql me +is accessed and no fallback to the .Ql default -record is returned instead. -If the second -.Fa pwd -parameter is -.Dv NULL , -then only the system login class database is -used. -However, -if the -.Fa pwd -parameter and the value of -.Fa pwd->pw_dir -are both not -.Dv NULL , -then the directory contained in +record is provided. +The directory specified by .Fa pwd->pw_dir is searched for a login database file called .Pa .login_conf , -and capability records -contained within it may override the system defaults. -This scheme allows users to override some login settings from -those in the system login class database by creating class records -for their own private class with a record id of -.Ql me . -In the context of a -.Em login , -it should be noted that some options cannot by overridden by -users for two reasons; many options, such as resource settings -and default process priorities, require root privileges -in order to take effect, and other fields in the user's file are -not be consulted at all during the early phases of login for -security or administrative reasons. -See -.Xr login.conf 5 -for more information on which settings a user is able to override. -Typically, these are limited purely to the user's default login -environment which might otherwise have been overridden in shell -startup scripts in any case. -The user's +and only the +.Ql me +capability record +contained within it may override the system record with the same name +while other records are ignored. +Using this scheme, an application can explicitly +allow users to override a selected subset of login settings. +To do so, the application should obtain two +.Vt login_cap_t +objects, one in user mode and the other in system mode, +and then query the user object before the +system object for login parameters that are allowed to +be overridden by the user. +For example, the user's .Pa .login_conf -merely provides a convenient way for a user to set up their preferred -login environment before the shell is invoked on login. +can provide a convenient way for a user to set up their preferred +login environment before the shell is invoked on login if supported by +.Xr login 1 . +.Pp Note that access to the .Pa /etc/login.conf and @@ -281,8 +295,8 @@ returns .Dv NULL . .Pp The functions -.Fn login_getpwclass , -.Fn login_getclass +.Fn login_getclass , +.Fn login_getpwclass and .Fn login_getuserclass retrieve the applicable login class record for the user's passwd @@ -303,7 +317,7 @@ restrict lookup only to the system login class database in .Pa /etc/login.conf . As explained earlier, .Fn login_getpwclass -only differs from +differs from .Fn login_getclass in that it allows the default class for a super-user as .Ql root @@ -314,6 +328,14 @@ or the user record has no login class, then the system .Ql default entry is retrieved. +Essentially, +.Fn login_getclass name +is equivalent to +.Fn login_getclassbyname name NULL +and +.Fn login_getuserclass pwd +to +.Fn login_getclassbyname LOGIN_MECLASS pwd . .Pp Once a program no longer wishes to use a .Vt login_cap_t @@ -549,6 +571,7 @@ on the specifier fails, is returned to indicate this. .El .Sh SEE ALSO +.Xr login 1 , .Xr crypt 3 , .Xr getcap 3 , .Xr login_class 3 , -- cgit v1.1