KEYFS(4)                                                 KEYFS(4)

     NAME
          keyfs, warning - authentication database files

     SYNOPSIS
          auth/keyfs [ -p ] [ -w [np] ] [ -mmntpt ] [ -r ] [ 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 or AES 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.  Keyfile holds a
          41-byte (57-byte for AES) record for each user in the data-
          base.  Each record contains the user's name, DES key, sta-
          tus, warning status, expiration date, secret password and
          AES key.  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.  Warning status is
          a byte containing the number of user expiration notifica-
          tions.  The expiration date is four-byte little-endian inte-
          ger which represents the time in seconds since the epoch
          (see date(1)) at which the account will expire.  The secret
          password is a null-terminated UTF string SECRETLEN bytes
          long.  If any changes are made to the database that affect
          the information stored in keyfile, a new version of the file
          is written.

          If the -r option is given, the database is mounted `read-
          only' and no changes are permitted.

          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,

     KEYFS(4)                                                 KEYFS(4)

          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 and aeskey
          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.  Aeskey contains the AESKEYLEN-byte encryption
          key.

          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.
          aeskey  The AES encryption key for the user.
          secret  The secret password.
          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 ini-
                  tialized to 0 when keyfs starts.  When the number
                  reaches a multiple of ten, keyfs temporarily dis-
                  ables 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.  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.

          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.

     KEYFS(4)                                                 KEYFS(4)

     FILES
          /adm/keys         Encrypted key file for the Plan 9 data-
                            base.
          /adm/netkeys      Encrypted key file for the SecureNet data-
                            base.
          /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)