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