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