man(1) Manual page archive


     KEYFS(4)                                                 KEYFS(4)

     NAME
          keyfs - authentication database files

     SYNOPSIS
          keyfs [ -mmntpt ] [ -kkey ] [ -rnsfile ] [ keyfile ]

     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 key key, which is by default read from
          #r/nvram (see rtc(3)). 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 con-
          taining binary 0 if the account is enabled, 1 if it is dis-
          abled.  Host status is a byte containing binary 1 if the
          user is a host, and 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.  If given option -r, keyfs rebuilds its
          name space from nsfile before writing any changes to its
          database.

          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,
          and renaming it changes the name in the entry.  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

     KEYFS(4)                                                 KEYFS(4)

          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 incre-
               ments 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.

     FILES
          /adm/keys
                Encrypted key file for the Plan 9 database.
          /adm/netkeys
                Encrypted key file for the SecureNet database.
          #r/nvram
                The non-volatile RAM on the server, which holds the
                key used to decrypt key files.

     SEE ALSO
          auth(6), namespace(6), auth(8)