glenda.party
term% ls -F
term% cat index.txt
KEYFS(4)                   Kernel Interfaces Manual                   KEYFS(4)



NAME
       keyfs, warning - authentication database files

SYNOPSIS
       auth/keyfs [ -p ] [ -w [np] ] [ -mmntpt ] [ keyfile ]

       auth/warning [ -n ] [ -p ]

DESCRIPTION
       Keyfs  serves a two-level file tree for manipulating authentication in‐
       formation.  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, which is by default read from #r/nvram (see rtc(3)).  With  option
       -p,  keyfs  prompts for a password from which the key is derived.  Key‐
       file 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  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 informa‐
       tion, and one for SecureNet user information.  A user need not  be  in‐
       stalled  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  data‐
       base.   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 re‐
       naming 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.   Writ‐
              ing 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.  This number is not stored in keyfile, and
              is initialized to 0 when keyfs starts.  When the number  reaches
              a  multiple  of  ten, keyfs temporarily disables the account for
              that many seconds.  Reads from the key or  secret  files  during
              this time return the error ``user in purgatory.''

       status The current status of the account, either ok or disabled.  Writ‐
              ing ok enables the account; writing disabled disables it.

       expire The expiration time for the account.  When read, it contains ei‐
              ther  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 ex‐
              piration date is reached, the account is not disabled,  but  key
              cannot be read without an error.

       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; warn‐
       ing'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
       authsrv(6), namespace(6), auth(8)



                                                                      KEYFS(4)