diff options
Diffstat (limited to 'lib/libutil/login_cap.3')
| -rw-r--r-- | lib/libutil/login_cap.3 | 392 |
1 files changed, 0 insertions, 392 deletions
diff --git a/lib/libutil/login_cap.3 b/lib/libutil/login_cap.3 deleted file mode 100644 index c998d23..0000000 --- a/lib/libutil/login_cap.3 +++ /dev/null @@ -1,392 +0,0 @@ -.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au> -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, is permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice immediately at the beginning of the file, without modification, -.\" this list of conditions, and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. This work was done expressly for inclusion into FreeBSD. Other use -.\" is permitted provided this notation is included. -.\" 4. Absolutely no warranty of function or purpose is made by the author -.\" David Nugent. -.\" 5. Modifications may be freely made to this file providing the above -.\" conditions are met. -.\" -.\" $Id: login_cap.3,v 1.7 1997/05/18 09:14:11 davidn Exp $ -.\" -.Dd December 27, 1996 -.Os FreeBSD -.Dt LOGIN_CAP 3 -.Sh NAME -.Nm login_getclassbyname , -.Nm login_close , -.Nm login_getclass , -.Nm login_getpwclass , -.Nm login_getuserclass , -.Nm login_getcapstr , -.Nm login_getcaplist , -.Nm login_getcaptime , -.Nm login_getcapnum , -.Nm login_getcapsize , -.Nm login_getcapbool , -.Nm login_getstyle -.Nd functions for accessing the login class capabilities database. -.Sh SYNOPSIS -.Fd #include <sys/types.h> -.Fd #include <login_cap.h> -.Ft void -.Fn login_close "login_cap_t * lc" -.Ft login_cap_t * -.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd" -.Ft login_cap_t * -.Fn login_getclass "const char *nam" -.Ft login_cap_t * -.Fn login_getpwclass "const struct passwd *pwd" -.Ft login_cap_t * -.Fn login_getuserclass "const struct passwd *pwd" -.Ft char * -.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *error" -.Ft char ** -.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars" -.Ft char * -.Fn login_getpath "login_cap_t *lc" "const char *cap" "char *error" -.Ft rlim_t -.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" -.Ft rlim_t -.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" -.Ft rlim_t -.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" -.Ft int -.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def" -.Ft char * -.Fn login_getstyle "login_cap_t *lc" "char *style" "const char *auth" -.Pp -.Sh DESCRIPTION -These functions represent a programming interface to the login -classes database provided in -.Xr login.conf 5 . -This database contains capabilities, attributes and default environment -and accounting settings for users and programs running as specific users, -as determined by the login class field within entries in -.Pa /etc/master.passwd . -.Pp -Entries in -.Xr login.conf 5 -consist of colon -.Ql \&: -separated fields, the first field in each record being one or more -identifiers for the record which must be unique for the entire database -each separated by a '|' and may optionally include a description as -the last 'name'. -Remaining fields in the record consist of keyword/data pairs. -Long lines may be continued with a backslash within empty entries -with the second and subsequent lines optionally indented for readability. -This is similar to the format used in -.Xr termcap 5 -except that keywords are not limited to two significant characters, -and are usually longer for improved readability. -As with termcap entries, multiple records can be linked together -(one record including another) using a field containing tc=<recordid>, -the result is that the entire record referenced by <recordid> replaces -the tc= field at the point at which it occurs. -See -.Xr getcap 3 -for further details on the format and use of a capabilities database. -.Pp -The -.Nm login_cap -interface provides a convenient means of retrieving login class -records with all tc= references expanded. -A program will typically call one of -.Fn login_getclass , -.Fn login_getpwclass , -.Fn login_getuserclass -or -.Fn login_getclassbyname -according to its requirements. -Each of these functions returns a login capabilities structure, -.Ft login_cap_t -which may subsequently be used to interrogate the database for -specific values using the rest of the API. -Once the login_cap_t is of no further use, the -.Fn login_close -function should be called to free all resources used. -.Pp -The structure of login_cap_t is defined in login_cap.h, as: -.Bd -literal -offset indent -typedef struct { - char *lc_class; - char *lc_cap; - char *lc_style; -} login_cap_t; -.Ed -.Pp -The -.Ar lc_class -member contains a pointer to the name of the login class -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 -.Fn login_getpwclass , -by class name using -.Fn login_getclass -or -.Fn login_getuserclass . -If the referenced user has no login class specified in -.Pa /etc/master.passwd , -the class name is NULL or an empty string, or if the class -specified does not exist in the database, each of these -functions will search for a record with an id of "default", -with that name returned in the -.Ar lc_class -field. -.Pp -The -.Ar lc_cap -field is used internally by the library to contain the -expanded login capabilities record. -Programs with unusual requirements may wish to use this -with the lower-level -.Fn getcap -style functions to access the record directly. -.Pp -The -.Ar lc_style -field is set by the -.Fn login_getstyle -function to the authorisation style according to the requirements -of the program handling a login itself. -.Pp -As noted above, the -.Fn get*class -functions return a login_cap_t object which is used to access -the matching or default record in the capabilities database. -.Fn getclassbyname -accepts two arguments: the first one is the record identifier of the -record to be retrieved, the second being an optional directory name. -If the first -.Ar name -argument is NULL, an empty string, or a class that does not exist -in the supplimental or system login class database, then the system -.Em default -record is returned instead. -If the second -.Ar dir -parameter is NULL, then only the system login class database is -used, but when not NULL, the named directory is searched for -a login database file called ".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 `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 deafult 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 -.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. -.Pp -If the specified record is NULL, empty or does not exist, and the -system has no "default" record available to fallback, there is a -memory allocation error or for some reason -.Xr cgetent 3 -is unable to access the login capabilities database, this function -returns NULL. -.Pp -The functions -.Fn login_getpwclass , -.Fn login_getclass -and -.Fn login_getuserclass -retrieve the applicable login class record for the user's passwd -entry or class name by calling -.Fn login_getclassbyname . -On failure, NULL is returned. -The difference between these functions is that -.Fn login_getuserclass -includes the user's overriding -.Pa .login_conf -that exists in the user's home directory, -.Fn login_getpwclass, -and -.Fn login_getclass -restricts loookup only to the system login class database in -.Pa /etc/login.conf . -.Fn login_getpwclass -only differs from -.Fn login_getclass -in that it allows the default class for user 'root' as "root" -if none has been specified in the password database. -Otherwise, if the passwd pointer is NULL, or the user record -has no login class, then the system "default" entry is retrieved. -.Pp -Once a program no longer wishes to use a login_cap_t object, -.Fn login_close -may be called to free all resources used by the login class. -.Fn login_close -may be passed a NULL pointer with no harmful side-effects. -.Pp -The remaining functions may be used to retrieve individual -capability records. -Each function takes a login_cap_t object as its first parameter, -a capability tag as the second, and remaining parameters being -default and error values that are returned if the capability is -not found. -The type of the additional parameters passed and returned depend -on the -.Em type -of capability each deals with, be it a simple string, a list, -a time value, a file or memory size value, a path (consisting of -a colon-separated list of directories) or a boolean flag. -The manpage for -.Xr login.conf 5 -deals in specific tags and their type. -.Pp -Note that with all functions in this group, you should not call -.Xr free 3 -on any pointers returned. -Memory allocated during retrieval or processing of capability -tags is automatically reused by subsequent calls to functions -in this group, or deallocated on calling -.Fn login_close . -.Bl -tag -width "login_getcaplist()" -.It Fn login_getcapstr -This function returns a simple string capability. -If the string is not found, then the value in -.Ar def -is returned as the default value, or if an error -occurs, the value in the -.Ar error -parameter is returned. -.It Fn login_getcaplist -This function returns the value corresponding to the named -capability tag as a list of values in a NULL terminated -array. -Within the login class database, some tags are of type -.Em list , -which consist of one or more comma- or space separated -values. -Usually, this function is not called directly from an -application, but is used indirectly via -.Fn login_getstyle . -.It Fn login_getpath -This function returns a list of directories separated by colons -.Ql &: . -Capability tags for which this function is called consist of a list of -directories separated by spaces. -.It Fn login_getcaptime -This function returns a -.Em time value -associated with a particular capability tag with the value expressed -in seconds (the default), minutes, hours, days, weeks or (365 day) -years or any combination of these. -A suffix determines the units used: S for seconds, M for minutes, -H for hours, D for days, W for weeks and Y for 365 day years. -Case of the units suffix is ignored. -.Pp -Time values are normally used for setting resource, accounting and -session limits. -If supported by the operating system and compiler (which is true of -FreeBSD), the value returned is a quad (long long), of type -.Em rlim_t . -A value "inf" or "infinity" may be used to express an infinite -value, in which case RLIM_INFINITY is returned. -.It Fn login_getcapnum -This function returns a numeric value for a tag, expressed either as -tag=<value> or the standard -.Fn cgetnum -format tag#<value>. -The first format should be used in preference to the second, the -second format is provided for compatibility and consistency with the -.Xr getcap 3 -database format where numeric types use the -.Ql \&# -as the delimiter for numeric values. -If in the first format, then the value given may be "inf" or -"infinity" which results in a return value of RLIM_INFINITY. -If the given capability tag cannot be found, the -.Ar def -parameter is returned, and if an error occurs, the -.Ar error -parameter is returned. -.It Fn login_getcapsize -.Fn login_getcapsize -returns a value representing a size (typicially, file or memory) -which may be expressed as bytes (the default), 512 byte blocks, -kilobytes, megabytes, gigabytes, and on systems that support the -.Ar long long -type, terrabytes. -The suffix used determines the units, and multiple values and -units may be used in combination (e.g. 1m500k = 1.5 megabytes). -A value with no suffix is interpreted as bytes, B as 512-byte -blocks, K as kilobytes, M as megabytes, G as gigabytes and T as -terrabytes. -Case is ignored. -The error value is returned if there is a login capabilities database -error, if an invalid suffix is used, or if a numeric value cannot be -interpreted. -.It Fn login_getcapbool -This function returns a boolean value tied to a particular flag. -It returns 0 if the given capability tag is not present or is -negated by the presence of a "tag@" (See -.Xr getcap 3 -for more information on boolean flags), and returns 1 if the tag -is found. -.It Fn login_getstyle -This function is used by the login authorisation system to determine -the style of login available in a particular case. -The function accepts three parameters, the login_cap entry itself and -two optional parameters, and authorisation type 'auth' and 'style', and -applies these to determine the authorisation style that best suites -these rules. -.Bl -bullet -indent offset -.It -If 'auth' is neither NULL nor an empty string, look for a tag of type -"auth-<auth>" in the capability record. -If not present, then look for the default default tag "auth=". -.It -If no valid authorisation list was found from the previous step, then -default to "passwd" as the authorisation list. -.It -If 'style' is not NULL or empty, look for it in the list of authorisation -methods found from the pprevious step. -If 'style' is NULL or an empty string, then default to "passwd" -authorisation. -.It -If 'style' is found in the chosen list of authorisation methods, then -return that, otherwise return NULL. -.El -.Pp -This scheme allows the administrator to determine the types of -authorisation methods accepted by the system, depending on the -means by which the access occurs. -For example, the administrator may require skey or kerberos as -the authentication method used for access to the system via the -network, and standard methods via direct dialup or console -logins, significantly reducing the risk of password discovery -by "snooping" network packets. -.El -.Sh SEE ALSO -.Xr getcap 3 , -.Xr login_class 3 , -.Xr login.conf 5 , -.Xr termcap 5 |
