man(1) Manual page archive


     AGENT(4)                                                 AGENT(4)

     NAME
          agent - authentication management

     SYNOPSIS
          agent [ -m mtpt ]

          aux/rdwr [ -w ] file

     DESCRIPTION
          Agent provides authentication services via a file system
          mounted at mtpt (default /mnt/auth).

          The file system presents config, confirm, and log files in
          addition to those specified by its current configuration.
          Config contains the agent's current configuration and is
          described more fully below, confirm is used for confirmation
          of key usage, and log contains messages from the agent.

        Configuration
          The agent must be initialized by writing to its config file.
          It can be reconfigured by editing config.  Typically, the
          permanent home for configuration files is not the network
          file server but rather NVRAM, local disk, or an encrypted
          file store.

          Configuration files are a series of file descriptions, sepa-
          rated by blank lines.  A sharp (#) begins a comment to the
          end of the line.  Lines containing only comments are equiva-
          lent to blank lines.

          File descriptions are a sequence of key-value pairs, naming
          the file, protocol, authentication data, and any (optional)
          flags to be used:

               file /netkey/plan9.bell-labs.com/rsc
               protocol netkey
               data $plan9password
               flag confirmuse

          Protocols are discussed in the next section.  The confirmuse
          provokes a confirmation each time the key is used;
          confirmopen provokes a confirmation each time the key file
          is opened.  The exact interpretation of these is protocol-
          specific.

          Authentication data may be a quoted string or a variable, as
          in the example.  Variables are introduced by assignment
          lines, which may occur anywhere before their use:

               plan9password = "my secret"

     AGENT(4)                                                 AGENT(4)

          Variables may not be reassigned once created.

          Variable definitions are not included when reading config
          back from the agent, so that changing your configuration
          does not result in having your keys on the screen or in an
          editor's temporary file.  When a new configuration is writ-
          ten to config, any uninitialized variables are searched for
          in the current configuration.  Unnamed quoted strings are
          assigned to fresh variables, so that after writing the con-
          figuration

               file /apop/plan9.bell-labs.com/rsc
               protocol apop
               data "another secret"

          reading config will produce something like

               file /apop/plan9.bell-labs.com/rsc
               protocol apop
               data $xyzzy2

          Thus once a quoted string has been given to the agent, there
          is no way to force it to hand it back via the config file
          (but see the security hole called raw in the protocol sec-
          tion).

        Protocols
          The semantics of interacting with a given file vary accord-
          ing to the protocol it follows.  Agent currently provides
          the following protocols.  Some are challenge-responsed
          based: clients open the file for reading and writing, write
          a challenge to the file, and read back a response.

          apop The POP3 protocol's MD5-based challenge-response proto-
               col.  The response is the MD5 checksum of the secret
               catenated with the challenge.

          netkey
               Netkey (see passwd(1)) challenge-response.  A chal-
               lenges is a decimal number, and the response is the
               hexadecimal for the first four bytes of the challenge
               padded to some length and encrypted using the data as
               password.

          raw  This is not a challenge-response protocol.  Writes are
               not allowed, and reads return the data itself.

          sshrsa
               RSA authentication as used in SSH.  The key data is a
               single (long) line in the format produced by ssh_genkey
               (see ssh(1)). Multiple-precision numbers are read and
               written from the file in base 16.  Reading the file

     AGENT(4)                                                 AGENT(4)

               immediately after opening it will yield the public mod-
               ulus for the key.  After that, a challenge must be
               written to the file.  The challenge will be decrypted
               and the result made available for reading back.  This
               challenge-response cycle may be repeated.

        Confirmation
          The exclusive-use confirm file in the file system facili-
          tates user confirmation.  A confirmation program loops read-
          ing requests and then writing back either yes or no in
          response.  If no program has opened the confirm file, all
          confirmations are successful.  This is useful for bootstrap-
          ping the system.

        Aux/rdwr
          The program aux/rdwr carries on a conversation with any of
          the challenge-response files: you type a challenge at a
          prompt, aux/rdwr writes it to the file and then reads and
          prints the response.

          The -w flag inverts the loop: aux/rdwr reads a challenge
          from the file, writes it to the console, and then relays
          your response.  Thus, aux/rdwr -w /mnt/auth/confirm acts as
          a simple confirmation program.

     SOURCE
          /sys/src/cmd/agent
          /sys/src/cmd/aux/rdwr.c

     SEE ALSO
          /sys/lib/agent.config is a sample configuration file from
          which to build your personal keyring.

     BUGS
          The parsing of quoted strings is simplistic: in particular,
          quoted strings cannot contain double-quotes nor sharp char-
          acters.

          The raw protocol negates most insulation from outside pro-
          cesses, as does the fact that the agent can be debugged via
          the usual channels.  If a rogue process is running as you,
          it can easily access your keys.