sys/man/4/keyfs

   1 .TH KEYFS 4
   2 .SH NAME
   3 keyfs, warning \- authentication database files
   4 .SH SYNOPSIS
   5 .B auth/keyfs
   6 [
   7 .B -p
   8 ]
   9 [
  10 .B -w
  11 .RB [ np ]
  12 ]
  13 [
  14 .BI -m mntpt
  15 ]
  16 [
  17 .I keyfile
  18 ]
  19 .PP
  20 .B auth/warning
  21 [
  22 .B -n
  23 ]
  24 [
  25 .B -p
  26 ]
  27 .SH DESCRIPTION
  28 .I Keyfs
  29 serves a two-level file tree for manipulating authentication information.
  30 It runs on the machine providing authentication service for the local
  31 Plan 9 network, which may be a dedicated authentication server or
  32 a CPU server.
  33 The programs described in
  34 .IR auth (8)
  35 use
  36 .I keyfs
  37 as their interface to the authentication database.
  38 .PP
  39 .I Keyfs
  40 reads and decrypts file
  41 .I keyfile
  42 (default
  43 .BR /adm/keys )
  44 using the DES key,
  45 which is by default read from
  46 .B #r/nvram
  47 (see
  48 .IR rtc (3)).
  49 With option
  50 .BR -p ,
  51 .I keyfs
  52 prompts for a password from which the key is derived.
  53 .I Keyfile
  54 holds a 41-byte record for each user in the database.
  55 Each record is encrypted separately
  56 and contains the user's name,
  57 DES key,
  58 status,
  59 host status,
  60 and expiration date.
  61 The name is a
  62 null-terminated
  63 .SM UTF
  64 string
  65 .B NAMELEN
  66 bytes long.
  67 The status is a byte containing
  68 binary 0 if the account is enabled,
  69 1 if it is disabled.
  70 Host status is a byte containing
  71 binary 1 if the user is a host,
  72 0 otherwise.
  73 The expiration date is four-byte little-endian integer
  74 which represents the time in seconds since the epoch
  75 (see
  76 .IR date (1))
  77 at which the account will expire.
  78 If any changes are made to the database that affect the information stored in
  79 .IR keyfile ,
  80 a new version of the file is written.
  81 .PP
  82 There are two authentication databases,
  83 one for Plan 9 user information,
  84 and one for SecureNet user information.
  85 A user need not be installed in both databases
  86 but must be installed in the Plan 9 database to connect to a Plan 9 server.
  87 .PP
  88 .I Keyfs
  89 serves an interpretation of the
  90 .I keyfile
  91 in the file tree rooted at
  92 .I mntpt
  93 (default
  94 .BR /mnt/keys ).
  95 Each user
  96 .I user
  97 in
  98 .I keyfile
  99 is represented as the directory
 100 .IR mntpt / user .
 101 .PP
 102 Making a new directory in
 103 .I mntpt
 104 creates a new user entry in the database.
 105 Removing a directory removes the user entry,
 106 and renaming it changes the name in the entry.
 107 Such changes are reflected immediately in
 108 .IR keyfile .
 109 .I Keyfs
 110 does not allow duplicate names when creating or renaming user entries.
 111 .PP
 112 All files in the user directories except for
 113 .B key
 114 contain
 115 .SM UTF
 116 strings with a trailing newline when read,
 117 and should be written as
 118 .SM UTF
 119 strings with or without a trailing newline.
 120 .B Key
 121 contains the
 122 .BR DESKEYLEN -byte
 123 encryption key for the user.
 124 .PP
 125 The following files appear in the user directories.
 126 .TF expire
 127 .TP
 128 .B key
 129 The authentication key for the user.
 130 If the user's account is disabled or expired,
 131 reading this file returns an error.
 132 Writing
 133 .I key
 134 changes the key in the database.
 135 .TP
 136 .B log
 137 The number of consecutive failed authentication attempts for the user.
 138 Writing the string
 139 .B bad
 140 increments this number; writing
 141 .B good
 142 resets it to 0.
 143 This number is not stored in
 144 .IR keyfile ,
 145 and is initialized to 0 when
 146 .I keyfs
 147 starts.
 148 When the number reaches a multiple of ten,
 149 .I keyfs
 150 temporarily disables the account for that many seconds.
 151 Reads from the
 152 .B key
 153 or
 154 .B secret
 155 files during this time return the error
 156 ``user in purgatory.''
 157 .TP
 158 .B status
 159 The current status of the account, either
 160 .B ok
 161 or
 162 .BR disabled .
 163 Writing
 164 .B ok
 165 enables the account;
 166 writing
 167 .B disabled
 168 disables it.
 169 .TP
 170 .B expire
 171 The expiration time for the account.
 172 When read, it contains either the string
 173 .B never
 174 or the time in seconds since the epoch
 175 that the account will expire.
 176 When written with strings of the same form,
 177 it sets the expiration date for the user.
 178 If the expiration date is reached,
 179 the account is not disabled,
 180 but
 181 .I key
 182 cannot be read without an error.
 183 .PD
 184 .PP
 185 If the
 186 .B -w
 187 option is on,
 188 .I keyfs
 189 runs the command
 190 .I warning
 191 once every 24 hours to mail people about expiring keys.
 192 Warnings are sent 14 days and 7 days prior to expiration.
 193 The argument to
 194 .BR -w ,
 195 either
 196 .B p
 197 or
 198 .BR n ,
 199 is passed to
 200 .I warning
 201 to restrict the warnings to
 202 the Plan 9 or SecureNet database.
 203 The default for
 204 .I keyfs
 205 is not to call
 206 .I warning
 207 at all;
 208 .I warning's
 209 own default is to warn about both.
 210 The files
 211 .B /adm/netkeys.who
 212 and
 213 .B /adm/keys.who
 214 are used to find the mail addresses to send to.
 215 The first word on each line identifies
 216 a user.
 217 Any subsequent strings on the line delimited '<' and '>' are considered mail
 218 addresses to send warnings to.
 219 If multiple lines match a user, the last in the file is used.
 220 .B Changeuser
 221 (see
 222 .IR auth (8))
 223 adds lines to these files.
 224 .SH FILES
 225 .TF /adm/netkeys.who
 226 .TP
 227 .B /adm/keys
 228 Encrypted key file for the Plan 9 database.
 229 .TP
 230 .B /adm/netkeys
 231 Encrypted key file for the SecureNet database.
 232 .TP
 233 .B /adm/keys.who
 234 List of users in the Plan 9 database.
 235 .TP
 236 .B /adm/netkeys.who
 237 List of users in  the SecureNet database.
 238 .TP
 239 .B #r/nvram
 240 The non-volatile RAM on the server, which holds the key used
 241 to decrypt key files.
 242 .SH SOURCE
 243 .B /sys/src/cmd/auth/keyfs.c
 244 .br
 245 .B /sys/src/cmd/auth/warning.c
 246 .SH "SEE ALSO"
 247 .IR authsrv (6),
 248 .IR namespace (6),
 249 .IR auth (8)