KEYFS(4) KEYFS(4)
NAME
keyfs, warning - authentication database files
SYNOPSIS
auth/keyfs [ -d ] [ -p ] [ -w [np] ] [ -mmntpt ] [ -kkey ] [
keyfile ]
auth/warning [ -n ] [ -p ]
DESCRIPTION
Keyfs serves a two-level file tree for manipulating authen-
tication information. It runs on the machine providing
authentication service for the local Plan 9 network, which
may be a dedicated authentication server or a CPU server.
The programs described in auth(8) use keyfs as their inter-
face to the authentication database.
Keyfs reads and decrypts file keyfile (default /adm/keys)
using the DES key key, which is by default read from
#r/nvram (see rtc(3)). With option -p, keyfs prompts for the
password. Keyfile holds a 41-byte record for each user in
the database. Each record is encrypted separately and con-
tains the user's name, DES key, status, host status, and
expiration date. The name is a null-terminated UTF string
NAMELEN bytes long. The status is a byte containing binary
0 if the account is enabled, 1 if it is disabled. Host sta-
tus is a byte containing binary 1 if the user is a host, 0
otherwise. The expiration date is four-byte little-endian
integer which represents the time in seconds since the epoch
(see date(1)) at which the account will expire. If any
changes are made to the database that affect the information
stored in keyfile, a new version of the file is written.
There are two authentication databases, one for Plan 9 user
information, and one for SecureNet user information. A user
need not be installed in both databases but must be
installed in the Plan 9 database to connect to a Plan 9
server.
Keyfs serves an interpretation of the keyfile in the file
tree rooted at mntpt (default /mnt/keys). Each user user in
keyfile is represented as the directory mntpt/user.
Making a new directory in mntpt creates a new user entry in
the database. Removing a directory removes the user entry,
and renaming it changes the name in the entry. Such changes
are reflected immediately in keyfile. Keyfs does not allow
duplicate names when creating or renaming user entries.
All files in the user directories except for key contain UTF
Page 1 Plan 9 (printed 12/30/24)
KEYFS(4) KEYFS(4)
strings with a trailing newline when read, and should be
written as UTF strings with or without a trailing newline.
Key contains the DESKEYLEN-byte encryption key for the user.
The following files appear in the user directories.
key The authentication key for the user. If the user's
account is disabled or expired, reading this file
returns an error. Writing key changes the key in
the database.
log The number of consecutive failed authentication
attempts for the user. Writing the string bad
increments this number; writing good resets it to 0.
If the number reaches fifty, keyfs disables the
account. Once the account is disabled, the only way
to enable it is to write the string ok to status.
This number is not stored in keyfile, and is ini-
tialized to 0 when keyfs starts.
status The current status of the account, either ok or
disabled. Writing ok enables the account; writing
disabled disables it.
expire The expiration time for the account. When read, it
contains either the string never or the time in sec-
onds since the epoch that the account will expire.
When written with strings of the same form, it sets
the expiration date for the user. If the expiration
date is reached, the account is not disabled, but
key cannot be read without an error.
ishost This file exists only if the user is a host (the
host status for the user is 1). Hosts are the only
users able to receive calls. Creating it makes the
user a host and sets the host status to 1, and
removing it sets the host status to 0.
If the -w option is on, keyfs runs the command warning once
every 24 hours to mail people about expiring keys. Warnings
are sent 14 days and 7 days prior to expiration. The argu-
ment to -w, either p or n, is passed to warning to restrict
the warnings to the Plan 9 or SecureNet database. The
default for keyfs is not to call warning at all; warning's
own default is to warn about both. The files
/adm/netkeys.who and /adm/keys.who are used to find the mail
addresses to send to. The first word on each line identi-
fies a user. Any subsequent strings on the line delimited
'<' and '>' are considered mail addresses to send warnings
to. If multiple lines match a user, the last in the file is
used. Changeuser (see auth(8)) adds lines to these files.
FILES
/adm/keys Encrypted key file for the Plan 9 data-
base.
/adm/netkeys Encrypted key file for the SecureNet
Page 2 Plan 9 (printed 12/30/24)
KEYFS(4) KEYFS(4)
database.
/adm/keys.who List of users in the Plan 9 database.
/adm/netkeys.who List of users in the SecureNet database.
#r/nvram The non-volatile RAM on the server, which
holds the key used to decrypt key files.
SOURCE
/sys/src/cmd/auth/keyfs.c
/sys/src/cmd/auth/warning.c
SEE ALSO
auth(6), namespace(6), auth(8)
Page 3 Plan 9 (printed 12/30/24)