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