diff options
Diffstat (limited to 'static/plan9-4e/man4/keyfs.4')
| -rw-r--r-- | static/plan9-4e/man4/keyfs.4 | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/static/plan9-4e/man4/keyfs.4 b/static/plan9-4e/man4/keyfs.4 new file mode 100644 index 00000000..b88b0330 --- /dev/null +++ b/static/plan9-4e/man4/keyfs.4 @@ -0,0 +1,248 @@ +.TH KEYFS 4 +.SH NAME +keyfs, warning \- authentication database files +.SH SYNOPSIS +.B auth/keyfs +[ +.B -p +] +[ +.B -w +.RB [ np ] +] +[ +.BI -m mntpt +] +[ +.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 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 record for each user in the database. +Each record is encrypted separately +and contains the user's name, +DES key, +status, +host status, +and expiration date. +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. +Host status 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 +.IR date (1)) +at which the account will expire. +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 +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 +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. +.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 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. +If the number reaches fifty, +.I keyfs +disables the account. +Once the account is disabled, +the only way to enable it is to write the string +.B ok +to +.BR status . +This number is not stored in +.IR keyfile , +and is initialized to 0 when +.I keyfs +starts. +.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) |