Subversion Repositories planix.SVN

.HTML "Security in Plan 9

.de SS

.NH 2

..

.EQ

delim $#

.EN

.TL

Security in Plan 9

.AU

Russ Cox, MIT LCS

.br

Eric Grosse, Bell Labs

.br

Rob Pike, Bell Labs

.br

Dave Presotto, Avaya Labs and Bell Labs

.br

Sean Quinlan, Bell Labs

.br

.CW {rsc,ehg,rob,presotto,seanq}@plan9.bell-labs.com

.AB

The security architecture of the Plan 9™

operating system has recently been redesigned

to address some technical shortcomings.

This redesign provided an opportunity also to make the system more

convenient to use securely.

Plan 9 has thus improved in two ways not usually seen together:

it has become more secure

.I and

easier to use.

.LP

The central component of the new architecture is a per-user

self-contained agent called

.CW factotum .

.CW Factotum

securely holds a

copy of the user's keys and negotiates authentication protocols, on

behalf of the user, with secure services around the network.

Concentrating security code in a single program offers several

advantages including: ease of update or repair to broken security

software and protocols; the ability to run secure services at a lower

privilege level; uniform management of keys for all services; and an

opportunity to provide single sign on, even to unchanged legacy

applications.

.CW  Factotum

has an unusual architecture: it is implemented

as a Plan 9 file server.

.FS

Appeared, in a slightly different form, in

.I

Proc. of the 2002 Usenix Security Symposium,

.R

San Francisco.

.FE

.AE

.NH 1

Introduction

.LP

Secure computing systems face two challenges:

first, they must employ sophisticated technology that is difficult to design

and prove correct; and second,

they must be easy for regular people to use.

The question of ease of use is sometimes neglected, but it is essential:

weak but easy-to-use security can be more effective than strong but

difficult-to-use security if it is more likely to be used.

People lock their front doors when they leave the house, knowing

full well that a burglar is capable of picking the lock (or avoiding

the door altogether); yet few would accept the cost and

awkwardness of a bank vault door on the

house even though that might reduce the probability of a robbery.

A related point is that users need a clear model of how the security

operates (if not how it actually provides security) in order to use it

well; for example, the clarity of a lock icon on a web browser

is offset by the confusing and typically insecure

steps for installing X.509 certificates.

.LP

The security architecture of the Plan 9

operating system

[Pike95]

has recently been redesigned to make it both more secure

and easier to use.

By

.I security

we mean three things:

first, the business of authenticating users and services;

second, the safe handling, deployment, and use of keys

and other secret information; and

third, the use of encryption and integrity checks

to safeguard communications

from prying eyes.

.LP

The old security architecture of Plan 9

had several engineering problems in common with other operating systems.

First, it had an inadequate notion of security domain.

Once a user provided a password to connect to a local file store,

the system required that the same password be used to access all the other file

stores.

That is, the system treated all network services as

belonging to the same security domain. 

.LP

Second, the algorithms and protocols used in authentication,

by nature tricky and difficult to get right, were compiled into the

various applications, kernel modules, and file servers.

Changes and fixes to a security protocol

required that all components using that protocol needed to be recompiled,

or at least relinked, and restarted.

.LP

Third, the file transport protocol, 9P

[Pike93],

that forms the core of

the Plan 9 system, had its authentication protocol embedded in its design.

This meant that fixing or changing the authentication used by 9P

required deep changes to the system.

If someone were to find a way to break the protocol, the system would

be wide open and very hard to fix.

.LP

These and a number of lesser problems, combined with a desire

for more widespread use of encryption in the system, spurred us to

rethink the entire security architecture of Plan 9.

.LP

The centerpiece of the new architecture is an agent,

called

.CW factotum ,

that handles the user's keys and negotiates all security

interactions with system services and applications.

Like a trusted assistant with a copy of the owner's keys,

.CW factotum

does all the negotiation for security and authentication.

Programs no longer need to be compiled with cryptographic

code; instead they communicate with

.CW factotum

agents

that represent distinct entities in the cryptographic exchange,

such as a user and server of a secure service.

If a security protocol needs to be added, deleted, or modified,

only

.CW factotum

needs to be updated for all system services

to be kept secure.

.LP

Building on

.CW factotum ,

we modified

secure services in the system to move

user authentication code into

.CW factotum ;

made authentication a separable component of the file server protocol;

deployed new security protocols;

designed a secure file store,

called

.CW secstore ,

to protect our keys but make them easy to get when they are needed;

designed a new kernel module to support transparent use of 

Transport Layer Security (TLS)

[RFC2246];

and began using encryption for all communications within the system.

The overall architecture is illustrated in Figure 1a.

.if h .B1 10 60

.KF

.EQ

gsize 9

.EN

.PS 3i

# Secstore

Sec:  box "Secstore" wid 1.3i ht .5i

# Terminal

Term0: box invis ht .1i with .e at Sec.e + (-1.1i, -.5i)

Term:  box wid 1.1i ht 1i with .nw at Term0.ne

Termlab: "\s-2Terminal\s+2" at Term.s + (0, -.15i)

FT: ellipse "$ F sub  T#" wid .40i ht .30i with .ne at Term.ne + (-.1i, -.1i)

PT: ellipse "$ P sub  T#" wid .6i ht .45i with .sw at Term.sw + (.2i, .2i)

# CPU

Cpu0: box invis ht .1i with .w at Term0.w + (3i, 0)

Cpu:  box wid 1.1i ht 1i with .nw at Cpu0.ne

Cpulab: "\s-2CPU Server\s+2" at Cpu.s + (0, -.15i)

FC: ellipse "$ F sub  C#" wid .40 ht .30i with .nw at Cpu.nw + (.1i, -.1i)

PC: ellipse "$ P sub  C#" wid .6i ht .45i with .se at Cpu.se + (-.2i, .2i)

# Authentication Server

Auth:  box dashed "Auth Server" wid 1.3i ht .5i with .e at Sec.e + (0, -2.3i)

# File Server

File0: box invis ht .1i with .w at Cpu0.w + (0, -1.5i)

File:  box wid 1.1i ht 1i with .nw at File0.ne

Filelab: "\s-2File Server\s+2" at File.s + (0, -.15i)

FF: ellipse "$ F sub  F#" wid .40i ht .30i with .nw at File.nw + (.1i, -.1i)

PF: ellipse "$ P sub  F#" wid .6i ht .45i with .se at File.se + (-.2i, .2i)

# Connections

line from PT.e + (0, +0.05i) to PC.w  + (0, +0.05i)

spline from PT.e + (0, -0.05i) right 1i then down 1.5i right .5i then right to PF.w + (0, -0.05i)

spline from PC.w + (0, -0.05i) left 1.1i then down 1.4i then right to PF.w + (0, 0.05i)

line <-> from FC.se to PC.nw

line <-> from FT.sw to PT.ne

line <-> from FF.se to PF.nw

spline <-> from Sec.e right .5i then down .655i then left to FT.e

#spline from Auth.e + (0, 0.05i) right .5i then up 1i then to FT.se

#spline from Auth.e + (0, 0.00i) right .7i then up 1i then to FC.sw

#spline from Auth.e + (0, -0.05i) right .5i then to FF.w

.PE

.LP

.ps 9

.vs 10

Figure 1a.  Components of the security architecture.

Each box is a (typically) separate machine; each ellipse a process.

The ellipses labeled $F sub X#

are

.CW factotum

processes; those labeled

$P sub X#

are the pieces and proxies of a distributed program.

The authentication server is one of several repositories for users' security information

that

.CW factotum

processes consult as required.

.CW Secstore

is a shared resource for storing private information such as keys;

.CW factotum

consults it for the user during bootstrap.

.sp

.KE

.if h .B2

.EQ

gsize 11

.EN

.LP

Secure protocols and algorithms are well understood

and are usually not the weakest link in a system's security.

In practice, most security problems arise from buggy servers,

confusing software, or administrative oversights.

It is these practical problems that we are addressing.

Although this paper describes the algorithms and protocols we are using,

they are included mainly for concreteness.

Our main intent is to present a simple security architecture built

upon a small trusted code base that is easy to verify (whether by manual or

automatic means), easy to understand, and easy to use.

.LP

Although it is a subjective assessment,

we believe we have achieved our goal of ease of use.

That we have achieved

our goal of improved security is supported by our plan to

move our currently private computing environment onto the Internet

outside the corporate firewall.

The rest of this paper explains the architecture and how it is used,

to explain why a system that is easy to use securely is also safe

enough to run in the open network.

.NH 1

An Agent for Security

.LP

One of the primary reasons for the redesign of the Plan 9

security infrastructure was to remove the authentication

method both from the applications and from the kernel.

Cryptographic code

is large and intricate, so it should

be packaged as a separate component that can be repaired or

modified without altering or even relinking applications

and services that depend on it.

If a security protocol is broken, it should be trivial to repair,

disable, or replace it on the fly.

Similarly, it should be possible for multiple programs to use

a common security protocol without embedding it in each program.

.LP

Some systems use dynamically linked libraries (DLLs) to address these configuration issues.

The problem with this approach is that it leaves

security code in the same address space as the program using it.

The interactions between the program and the DLL

can therefore accidentally or deliberately violate the interface,

weakening security.

Also, a program using a library to implement secure services

must run at a privilege level necessary to provide the service;

separating the security to a different program makes it possible

to run the services at a weaker privilege level, isolating the

privileged code to a single, more trustworthy component.

.LP

Following the lead of the SSH agent

[Ylon96],

we give each user

an agent process responsible

for holding and using the user's keys.

The agent program is called

.CW factotum

because of its similarity to the proverbial servant with the

power to act on behalf of his master because he holds the

keys to all the master's possessions.  It is essential that

.CW factotum

keep the keys secret and use them only in the owner's interest.

Later we'll discuss some changes to the kernel to reduce the possibility of

.CW factotum

leaking information inadvertently.

.LP

.CW Factotum

is implemented, like most Plan 9 services, as a file server.

It is conventionally mounted upon the directory

.CW /mnt/factotum ,

and the files it serves there are analogous to virtual devices that provide access to,

and control of, the services of the

.CW factotum .

The next few sections describe the design of

.CW factotum

and how it operates with the other pieces of Plan 9 to provide

security services.

.SS

Logging in

.LP

To make the discussions that follow more concrete,

we begin with a couple of examples showing how the

Plan 9 security architecture appears to the user.

These examples both involve a user

.CW gre

logging in after booting a local machine.

The user may or may not have a secure store in which

all his keys are kept.

If he does,

.CW factotum

will prompt him for the password to the secure store

and obtain keys from it, prompting only when a key

isn't found in the store.

Otherwise,

.CW factotum

must prompt for each key.

.LP

In the typescripts, \f6\s9\en\s0\fP

represents a literal newline

character typed to force a default response.

User input is in italics, and

long lines are folded and indented to fit.

.LP

This first example shows a user logging in without

help from the secure store.

First,

.CW factotum

prompts for a user name that the local kernel

will use:

.P1

user[none]: \f6\s9gre\s0\fP

.P2

(Default responses appear in square brackets.)

The kernel then starts accessing local resources

and requests, through

.CW factotum ,

a user/password pair to do so:

.P1

!Adding key: dom=cs.bell-labs.com

    proto=p9sk1

user[gre]: \f6\s9\en\s0\fP

password: \f6****\fP

.P2

Now the user is logged in to the local system, and

the mail client starts up:

.P1

!Adding key: proto=apop

    server=plan9.bell-labs.com

user[gre]: \f6\s9\en\s0\fP

password: \f6****\fP

.P2

.CW Factotum

is doing all the prompting and the applications

being started are not even touching the keys.

Note that it's always clear which key is being requested.

.LP

Now consider the same login sequence, but in the case where

.CW gre

has a secure store account:

.P1

user[none]: \f6\s9gre\s0\fP

secstore password: \f6*********\fP

STA PIN+SecurID: \f6*********\fP

.P2

That's the last

.CW gre

will hear from

.CW factotum

unless an attempt is made to contact

a system for which no key is kept in the secure store.

.SS

The factotum

.LP

Each computer running Plan 9 has one user id that owns all the

resources on that system \(em the scheduler, local disks,

network interfaces, etc.

That user, the

.I "host owner" ,

is the closest analogue in Plan 9 to a Unix

.CW root

account (although it is far weaker;

rather than having special powers, as its name implies the host owner

is just a regular user that happens to own the

resources of the local machine).

On a single-user system, which we call a terminal,

the host owner is the id of the terminal's user.

Shared servers such as CPU servers normally have a pseudo-user

that initially owns all resources.

At boot time, the Plan 9 kernel starts a

.CW factotum

executing as, and therefore with the privileges of,

the host owner.

.LP

New processes run as

the same user as the process which created them.

When a process must take on the identity of a new user,

such as to provide a login shell

on a shared CPU server,

it does so by proving to the host owner's

.CW factotum

that it is

authorized to do so.

This is done by running an

authentication protocol with

.CW factotum

to

prove that the process has access to secret information

which only the new user should possess.

For example, consider the setup in Figure 1a.

If a user on the terminal

wants to log in to the CPU server using the

Plan 9

.CW cpu

service

[Pike93],

then

$P sub T#

might be the

.CW cpu

client program and

$P sub C#

the

.CW cpu

server.

Neither $P sub C# nor $P sub T#

knows the details of the authentication.

They

do need to be able to shuttle messages back and

forth between the two

.CW factotums ,

but this is

a generic function easily performed without

knowing, or being able to extract, secrets in

the messages.

$P sub T#

will make a network connection to $P sub C#.

$P sub T#

and

$P sub C#

will then relay messages between

the

.CW factotum

owned by the user, $F sub T#,

and the one owned by the CPU server, $F sub C#,

until mutual authentication has been established.

Later

sections describe the RPC between

.CW factotum

and

applications and the library functions to support proxy operations.

.LP

The kernel always uses a single local instance of

.CW factotum ,

running as the

host owner, for

its authentication purposes, but

a regular user may start other

.CW factotum

agents.

In fact, the

.CW factotum

representing the user need not be

running on the same machine as its client.

For instance, it is easy for a user on a CPU server,

through standard Plan 9 operations,

to replace the

.CW /mnt/factotum

in the user's private file name space on the server

with a connection to the

.CW factotum

running on the terminal.

(The usual file system permissions prevent interlopers

from doing so maliciously.)

This permits secure operations on the CPU server to be

transparently validated by the user's own

.CW factotum ,

so

secrets need never leave the user's terminal.

The SSH agent

[Ylon96]

does much the

same with special SSH protocol messages, but

an advantage to making our agent a file system

is that we need no new mechanism to access our remote

agent; remote file access is sufficient.

.LP

Within

.CW factotum ,

each protocol is implemented as a state

machine with a generic interface, so protocols are in

essence pluggable modules, easy to add, modify, or drop.

Writing a message to and reading a message from

.CW factotum

each require a separate RPC and result in

a single state transition.

Therefore

.CW factotum

always runs to completion on every RPC and never blocks

waiting for input during any authentication.

Moreover, the number of simultaneous

authentications is limited only by the amount of memory we're

willing to dedicate to representing the state machines.

.LP

Authentication protocols are implemented only

within

.CW factotum ,

but adding and removing

protocols does require relinking the binary, so

.CW factotum

processes (but no others)

need to be restarted in order to take advantage of

new or repaired protocols.

.LP

At the time of writing, 

.CW factotum

contains authentication

modules for the Plan 9 shared key protocol (p9sk1),

SSH's RSA authentication, passwords in the clear, APOP, CRAM, PPP's CHAP,

Microsoft PPP's MSCHAP, and VNC's challenge/response.

.SS

Local capabilities

.LP

A capability system, managed by the kernel, is used to empower

.CW factotum

to grant permission to another process to change its user id.

A

kernel device driver

implements two files,

.CW /dev/caphash

and

.CW /dev/capuse .

The write-only file

.CW /dev/caphash

can be opened only by the host owner, and only once.

.CW Factotum

opens this file immediately after booting.

.LP

To use the files,

.CW factotum

creates a string of the form

.I userid1\f(CW@\fPuserid2\f(CW@\fPrandom-string ,

uses SHA1 HMAC to hash

.I userid1\f(CW@\fPuserid2

with key

.I random-string ,

and writes that hash to

.CW /dev/caphash .

.CW Factotum

then passes the original string to another

process on the same machine, running

as user

.I userid1 ,

which

writes the string to

.CW /dev/capuse .

The kernel hashes the string and looks for

a matching hash in its list.

If it finds one,

the writing process's user id changes from

.I userid1

to

.I userid2 .

Once used, or if a timeout expires,

the capability is discarded by the kernel.

.LP

The capabilities are local to the machine on which they are created.

Hence a

.CW factotum

running on one machine cannot pass capabilities

to processes on another and expect them to work.

.SS

Keys

.LP

We define the word

.I key

to mean not only a secret, but also a description of the

context in which that secret is to be used: the protocol,

server, user, etc. to which it applies.

That is,

a key is a combination of secret and descriptive information

used to authenticate the identities of parties

transmitting or receiving information.

The set of keys used

in any authentication depends both on the protocol and on

parameters passed by the program requesting the authentication.

.LP

Taking a tip from SDSI

[RiLa],

which represents security information as textual S-expressions,

keys in Plan 9 are represented as plain UTF-8 text.

Text is easily

understood and manipulated by users.

By contrast,

a binary or other cryptic format

can actually reduce overall security.

Binary formats are difficult for users to examine and can only be

cracked by special tools, themselves poorly understood by most users.

For example, very few people know or understand what's inside

their X.509 certificates.

Most don't even know where in the system to

find them.

Therefore, they have no idea what they are trusting, and why, and

are powerless to change their trust relationships.

Textual, centrally stored and managed keys are easier to use and safer.

.LP

Plan 9 has historically represented databases as attribute/value pairs,

since they are a good foundation for selection and projection operations.

.CW Factotum

therefore represents

the keys in the format

.I attribute\f(CW=\fPvalue ,

where

.I attribute

is an identifier, possibly with a single-character prefix, and

.I value

is an arbitrary quoted string.

The pairs themselves are separated by white space.

For example, a Plan 9 key and an APOP key

might be represented like this:

.P1

dom=bell-labs.com proto=p9sk1 user=gre

	!password='don''t tell'

proto=apop server=x.y.com user=gre

	!password='open sesame'

.P2

If a value is empty or contains white space or single quotes, it must be quoted;

quotes are represented by doubled single quotes.

Attributes that begin with an exclamation mark

.CW ! ) (

are considered

.I secret .

.CW Factotum

will never let a secret value escape its address space

and will suppress keyboard echo when asking the user to type one.

.LP

A program requesting authentication selects a key

by providing a

.I query ,

a list of elements to be matched by the key.

Each element in the list is either an

.I attribute\f(CW=\fPvalue

pair, which is satisfied by keys with

exactly that pair;

or an attribute followed by a question mark,

.I attribute\f(CW? ,

which is satisfied by keys with some pair specifying

the attribute.

A key matches a query if every element in the list

is satisfied.

For instance, to select the APOP key in the previous example,

an APOP client process might specify the query

.P1

server=x.y.com proto=apop

.P2

Internally,

.CW factotum 's

APOP module would add the requirements of

having

.CW user

and

.CW !password

attributes, forming the query

.P1

server=x.y.com proto=apop user? !password?

.P2

when searching for an appropriate key.

.LP

.CW Factotum

modules expect keys to have some well-known attributes.

For instance, the

.CW proto

attribute specifies the protocol module

responsible for using a particular key,

and protocol modules may expect other well-known attributes

(many expect keys to have

.CW !password

attributes, for example).

Additional attributes can be used as comments or for

further discrimination without intervention by 

.CW factotum ; 

for example, the APOP and IMAP mail clients conventionally

include a

.CW server

attribute to select an appropriate key for authentication.

.LP

Unlike in SDSI,

keys in Plan 9 have no nested structure.  This design

keeps the representation simple and straightforward.

If necessary, we could add a nested attribute

or, in the manner of relational databases, an attribute that

selects another tuple, but so far the simple design has been sufficient.

.LP

A simple common structure for all keys makes them easy for users

to administer,

but the set of attributes and their interpretation is still

protocol-specific and can be subtle.

Users may still

need to consult a manual to understand all details.

Many attributes

.CW proto , (

.CW user ,

.CW password ,

.CW server )

are self-explanatory and our short experience

has not uncovered any particular difficulty in handling keys.

Things

will likely get messier, however,

when we grapple with public

keys and their myriad components.

.SS

Protecting keys

.LP

Secrets must be prevented from escaping

.CW factotum .

There are a number of ways they could leak:

another process might be able to debug the agent process, the

agent might swap out to disk, or the process might willingly

disclose the key.

The last is the easiest to avoid:

secret information in a key is marked

as such, and

whenever

.CW factotum

prints keys or queries for new

ones, it is careful to avoid displaying secret information.

(The only exception to this is the

``plaintext password'' protocol, which consists

of sending the values of the

.CW user

and

.CW !password

attributes.

Only keys tagged with

.CW proto=pass

can have their passwords disclosed by this mechanism.)

.LP

Preventing the first two forms of leakage

requires help from the kernel.

In Plan 9, every process is

represented by a directory in the

.CW /proc

file system.

Using the files in this directory,

other processes could (with appropriate access permission) examine

.CW factotum 's

memory and registers.

.CW Factotum

is protected from processes of other users

by the default access bits of its

.CW /proc

directory.

However, we'd also like to protect the

agent from other processes owned by the same user,

both to avoid honest mistakes and to prevent

an unattended terminal being

exploited to discover secret passwords.

To do this, we added a control message to

.CW /proc

called

.CW private .

Once the

.CW factotum

process has written

.CW private

to its

.CW /proc/\f2pid\fP/ctl

file, no process can access

.CW factotum 's

memory

through

.CW /proc .

(Plan 9 has no other mechanism, such as

.CW /dev/kmem ,

for accessing a process's memory.)

.LP

Similarly, the agent's address space should not be

swapped out, to prevent discovering unencrypted

keys on the swapping media.

The

.CW noswap

control message in

.CW /proc

prevents this scenario.

Neither

.CW private

nor

.CW noswap

is specific to

.CW factotum .

User-level file servers such as

.CW dossrv ,

which interprets FAT file systems,

could use

.CW noswap

to keep their buffer caches from being

swapped to disk.

.LP

Despite our precautions, attackers might still

find a way to gain access to a process running as the host

owner on a machine.

Although they could not directly

access the keys, attackers could use the local

.CW factotum

to perform authentications for them.

In the case

of some keys, for example those locking bank

accounts, we want a way to disable or at least

detect such access.

That is the role of the

.CW confirm

attribute in a key.

Whenever a key with a

.CW confirm

attribute is accessed, the local user must

confirm use of the key via a local GUI.

The next section describes the actual mechanism.

.LP

We have not addressed leaks possible as a result of

someone rebooting or resetting a machine running

.CW factotum .

For example, someone could reset a machine

and reboot it with a debugger instead of a kernel,

allowing them to examine the contents of memory

and find keys.  We have not found a satisfactory

solution to this problem.

.SS

Factotum transactions

.LP

External programs manage

.CW factotum 's

internal key state

through its file interface,

writing textual

.CW key

and

.CW delkey

commands to the

.CW /mnt/factotum/ctl

file.

Both commands take a list of attributes as an argument.

.CW Key

creates a key with the given attributes, replacing any

extant key with an identical set of public attributes.

.CW Delkey

deletes all keys that match the given set of attributes.

Reading the 

.CW ctl

file returns a list of keys, one per line, displaying only public attributes.

The following example illustrates these interactions.

.P1

% cd /mnt/factotum

% ls -l

-lrw------- gre gre 0 Jan 30 22:17 confirm

--rw------- gre gre 0 Jan 30 22:17 ctl

-lr-------- gre gre 0 Jan 30 22:17 log

-lrw------- gre gre 0 Jan 30 22:17 needkey

--r--r--r-- gre gre 0 Jan 30 22:17 proto

--rw-rw-rw- gre gre 0 Jan 30 22:17 rpc

% cat >ctl

key dom=bell-labs.com proto=p9sk1 user=gre

    !password='don''t tell'

key proto=apop server=x.y.com user=gre

    !password='bite me'

^D

% cat ctl

key dom=bell-labs.com proto=p9sk1 user=gre

key proto=apop server=x.y.com user=gre

% echo 'delkey proto=apop' >ctl

% cat ctl

key dom=bell-labs.com proto=p9sk1 user=gre

% 

.P2

(A file with the

.CW l

bit set can be opened by only one process at a time.)

.LP

The heart of the interface is the

.CW rpc

file.

Programs authenticate with

.CW factotum

by writing a request to the

.CW rpc

file

and reading back the reply; this sequence is called an RPC

.I transaction .

Requests and replies have the same format:

a textual verb possibly followed by arguments,

which may be textual or binary.

The most common reply verb is

.CW ok ,

indicating success.

An RPC session begins with a

.CW start

transaction; the argument is a key query as described

earlier.

Once started, an RPC conversation usually consists of 

a sequence of

.CW read

and

.CW write

transactions.

If the conversation is successful, an

.CW authinfo

transaction will return information about

the identities learned during the transaction.

The

.CW attr

transaction returns a list of attributes for the current

conversation; the list includes any attributes given in

the 

.CW start

query as well as any public attributes from keys being used.

.LP

As an example of the

.CW rpc

file in action, consider a mail client

connecting to a mail server and authenticating using

the POP3 protocol's APOP challenge-response command.

There are four programs involved: the mail client $P sub C#, the client

.CW factotum

$F sub C#, the mail server $P sub S#, and the server

.CW factotum

$F sub S#.

All authentication computations are handled by the

.CW factotum

processes.

The mail programs' role is just to relay messages.

.LP

At startup, the mail server at

.CW x.y.com

begins an APOP conversation

with its

.CW factotum

to obtain the banner greeting, which

includes a challenge:

.P1

$P sub S -> F sub S#: start proto=apop role=server

$F sub S -> P sub S#: ok

$P sub S -> F sub S#: read

$F sub S -> P sub S#: ok +OK POP3 \f2challenge\fP

.P2

Having obtained the challenge, the server greets the client:

.P1

$P sub S -> P sub C#: +OK POP3 \f2challenge\fP

.P2

The client then uses an APOP conversation with its

.CW factotum

to obtain a response:

.P1

$P sub C -> F sub C#: start proto=apop role=client

            server=x.y.com

$F sub C -> P sub C#: ok

$P sub C -> F sub C#: write +OK POP3 \f2challenge\fP

$F sub C -> P sub C#: ok

$P sub C -> F sub C#: read

$F sub C -> P sub C#: ok APOP gre \f2response\fP

.P2

.CW Factotum

requires that

.CW start

requests include a 

.CW proto

attribute, and the APOP module requires an additional

.CW role

attribute, but the other attributes are optional and only

restrict the key space.

Before responding to the

.CW start

transaction, the client

.CW factotum

looks for a key to

use for the rest of the conversation.

Because of the arguments in the

.CW start

request, the key must have public attributes

.CW proto=apop

and

.CW server=x.y.com ;

as mentioned earlier,