lib/libutil/login_ok.3

   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_ok.3,v 1.7.2.4 2001/12/17 10:08:32 ru Exp $
  21 .\"
  22 .Dd January 2, 1997
  23 .Dt LOGIN_OK 3
  24 .Os
  25 .Sh NAME
  26 .Nm auth_ttyok ,
  27 .Nm auth_hostok ,
  28 .Nm auth_timeok
  29 .Nd functions for checking login class based login restrictions
  30 .Sh LIBRARY
  31 .Lb libutil
  32 .Sh SYNOPSIS
  33 .In sys/types.h
  34 .In time.h
  35 .In login_cap.h
  36 .Ft int
  37 .Fn auth_ttyok "login_cap_t *lc" "const char *tty"
  38 .Ft int
  39 .Fn auth_hostok "login_cap_t *lc" "const char *host" "char const *ip"
  40 .Ft int
  41 .Fn auth_timeok "login_cap_t *lc" "time_t t"
  42 .Sh DESCRIPTION
  43 This set of functions checks to see if login is allowed based on login
  44 class capability entries in the login database,
  45 .Xr login.conf 5 .
  46 .Pp
  47 .Fn auth_ttyok
  48 checks to see if the named tty is available to users of a specific
  49 class, and is either in the
  50 .Em ttys.allow
  51 access list, and not in
  52 the
  53 .Em ttys.deny
  54 access list.
  55 An empty
  56 .Em ttys.allow
  57 list (or if no such capability exists for
  58 the give login class) logins via any tty device are allowed unless
  59 the
  60 .Em ttys.deny
  61 list exists and is non-empty, and the device or its
  62 tty group (see
  63 .Xr ttys 5 )
  64 is not in the list.
  65 Access to ttys may be allowed or restricted specifically by tty device
  66 name, a device name which includes a wildcard (e.g. ttyD* or cuaD*),
  67 or may name a ttygroup, when group=<name> tags have been assigned in
  68 .Pa /etc/ttys .
  69 Matching of ttys and ttygroups is case sensitive.
  70 Passing a
  71 .Dv NULL
  72 or empty string as the
  73 .Ar tty
  74 parameter causes the function to return a non-zero value.
  75 .Pp
  76 .Fn auth_hostok
  77 checks for any host restrictions for remote logins.
  78 The function checks on both a host name and IP address (given in its
  79 text form, typically n.n.n.n) against the
  80 .Em host.allow
  81 and
  82 .Em host.deny
  83 login class capabilities.
  84 As with ttys and their groups, wildcards and character classes may be
  85 used in the host allow and deny capability records.
  86 The
  87 .Xr fnmatch 3
  88 function is used for matching, and the matching on hostnames is case
  89 insensitive.
  90 Note that this function expects that the hostname is fully expanded
  91 (i.e. the local domain name added if necessary) and the IP address
  92 is in its canonical form.
  93 No hostname or address lookups are attempted.
  94 .Pp
  95 It is possible to call this function with either the hostname or
  96 the IP address missing (i.e.\&
  97 .Dv NULL )
  98 and matching will be performed
  99 only on the basis of the parameter given.
 100 Passing
 101 .Dv NULL
 102 or empty strings in both parameters will result in
 103 a non-zero return value.
 104 .Pp
 105 The
 106 .Fn auth_timeok
 107 function checks to see that a given time value is within the
 108 .Em times.allow
 109 login class capability and not within the
 110 .Em times.deny
 111 access lists.
 112 An empty or non-existent
 113 .Em times.allow
 114 list allows access at any
 115 time, except if a given time is falls within a period in the
 116 .Em times.deny
 117 list.
 118 The format of time period records contained in both
 119 .Em times.allow
 120 and
 121 .Em times.deny
 122 capability fields is explained in detail in the
 123 .Xr login_times 3
 124 manual page.
 125 .Sh RETURN VALUES
 126 A non-zero return value from any of these functions indicates that
 127 login access is granted.
 128 A zero return value means either that the item being tested is not
 129 in the
 130 .Em allow
 131 access list, or is within the
 132 .Em deny
 133 access list.
 134 .Sh SEE ALSO
 135 .Xr getcap 3 ,
 136 .Xr login_cap 3 ,
 137 .Xr login_class 3 ,
 138 .Xr login_times 3 ,
 139 .Xr login.conf 5 ,
 140 .Xr termcap 5