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, separated by blank lines.  A sharp (#) begins a comment to the end of the line.  Lines containing only comments are equivalent 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"

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 written 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 configuration

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 section). 

Protocols

The semantics of interacting with a given file vary according 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 protocol.  The response is the MD5 checksum of the secret catenated with the challenge. 

­netkey
­Netkey (see passwd(1)) challenge-response. A challenges 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 immediately after opening it will yield the public modulus 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 facilitates user confirmation.  A confirmation program loops reading 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 bootstrapping 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 characters. 

The ­raw protocol negates most insulation from outside processes, 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. 

Plan 9  —  March 27, 2001