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