KEYFS(4)						     Kernel Interfaces Manual							  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 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 auth(8) use  keyfs
       as their interface 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  sepa-
       rately  and  contains 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 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 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  repre-
       sented 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 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 initialized 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 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 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  argument  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 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.  Changeuser (see auth(8)) adds lines to these files.

FILES

       /adm/keys
	      Encrypted key file for the Plan 9 database.

       /adm/netkeys
	      Encrypted key file for the SecureNet 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)

																	  KEYFS(4)