ref: d5e2fd9028687dfc18c0ac1b249ccec38ab075f6
dir: /sys/man/4/keyfs/
.TH KEYFS 4 .SH NAME keyfs, warning \- authentication database files .SH SYNOPSIS .B auth/keyfs [ .B -p ] [ .B -w .RB [ np ] ] [ .BI -m mntpt ] [ .B -r ] [ .I keyfile ] .PP .B auth/warning [ .B -n ] [ .B -p ] .SH DESCRIPTION .I Keyfs serves a two-level file tree for manipulating authentication 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 .IR auth (8) use .I keyfs as their interface to the authentication database. .PP .I Keyfs reads and decrypts file .I keyfile (default .BR /adm/keys ) using the DES or AES key, which is by default read from .B #r/nvram (see .IR rtc (3)). With option .BR -p , .I keyfs prompts for a password from which the key is derived. .I Keyfile holds a 41-byte (57-byte for AES) record for each user in the database. Each record contains the user's name, DES key, status, warning status, expiration date, secret password and AES key. The name is a null-terminated .SM UTF string .B NAMELEN bytes long. The status is a byte containing binary 0 if the account is enabled, 1 if it is disabled. Warning status is a byte containing the number of user expiration notifications. The expiration date is four-byte little-endian integer which represents the time in seconds since the epoch (see .IR date (1)) at which the account will expire. The secret password is a null-terminated .SM UTF string .B SECRETLEN bytes long. If any changes are made to the database that affect the information stored in .IR keyfile , a new version of the file is written. .PP If the .B -r option is given, the database is mounted `read-only' and no changes are permitted. .PP 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. .PP .I Keyfs serves an interpretation of the .I keyfile in the file tree rooted at .I mntpt (default .BR /mnt/keys ). Each user .I user in .I keyfile is represented as the directory .IR mntpt / user . .PP Making a new directory in .I 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 .IR keyfile . .I Keyfs does not allow duplicate names when creating or renaming user entries. .PP All files in the user directories except for .B key and .B aeskey contain .SM UTF strings with a trailing newline when read, and should be written as .SM UTF strings with or without a trailing newline. .B Key contains the .BR DESKEYLEN -byte encryption key for the user. .B Aeskey contains the .BR AESKEYLEN -byte encryption key. .PP The following files appear in the user directories. .TF expire .TP .B key The authentication key for the user. If the user's account is disabled or expired, reading this file returns an error. Writing .I key changes the key in the database. .TP .B aeskey The AES encryption key for the user. .TP .B secret The secret password. .TP .B log The number of consecutive failed authentication attempts for the user. Writing the string .B bad increments this number; writing .B good resets it to 0. This number is not stored in .IR keyfile , and is initialized to 0 when .I keyfs starts. When the number reaches a multiple of ten, .I keyfs temporarily disables the account for that many seconds. Reads from the .B key or .B secret files during this time return the error ``user in purgatory.'' .TP .B status The current status of the account, either .B ok or .BR disabled . Writing .B ok enables the account; writing .B disabled disables it. .TP .B expire The expiration time for the account. When read, it contains either the string .B never or the time in seconds 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 .I key cannot be read without an error. .PD .PP If the .B -w option is on, .I keyfs runs the command .I warning once every 24 hours to mail people about expiring keys. Warnings are sent 14 days and 7 days prior to expiration. The argument to .BR -w , either .B p or .BR n , is passed to .I warning to restrict the warnings to the Plan 9 or SecureNet database. The default for .I keyfs is not to call .I warning at all; .I warning's own default is to warn about both. The files .B /adm/netkeys.who and .B /adm/keys.who are used to find the mail addresses to send to. The first word on each line identifies 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. .B Changeuser (see .IR auth (8)) adds lines to these files. .SH FILES .TF /adm/netkeys.who .TP .B /adm/keys Encrypted key file for the Plan 9 database. .TP .B /adm/netkeys Encrypted key file for the SecureNet database. .TP .B /adm/keys.who List of users in the Plan 9 database. .TP .B /adm/netkeys.who List of users in the SecureNet database. .TP .B #r/nvram The non-volatile RAM on the server, which holds the key used to decrypt key files. .SH SOURCE .B /sys/src/cmd/auth/keyfs.c .br .B /sys/src/cmd/auth/warning.c .SH "SEE ALSO" .IR authsrv (6), .IR namespace (6), .IR auth (8)