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"
Page 1 Plan 9 (printed 5/12/25)
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
Page 2 Plan 9 (printed 5/12/25)
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.
Page 3 Plan 9 (printed 5/12/25)