ref: 2459e34d77e2e21ef829c0dfaafd99433899494f
dir: /man/2/factotum/
.TH FACTOTUM 2
.SH NAME
Factotum: attrtext, challenge, copyattrs, delattr, findattr, findattrval, getuserpassd, mount, open, parseattrs, proxy,
publicattrs, takeattrs, respond, response, rpc, rpcattrs \- client interface to factotum
.SH SYNOPSIS
.EX
include "factotum.m";
auth := load Factotum Factotum->PATH;
Authinfo: adt{
cuid: string; # ID on caller
suid: string; # ID on server
cap: string; # capability (only valid on server side)
secret: array of byte; # key for encryption
};
AuthRpcMax: con \fR...\fP;
init: fn();
mount: fn(fd: ref Sys->FD, mnt: string, flags: int,
aname: string, keyspec: string): (int, ref Authinfo);
getuserpasswd: fn(keyspec: string): (string, string);
Challenge: adt {
user: string; # user (some protocols)
chal: string; # challenge string
};
challenge: fn(keyspec: string): ref Challenge;
response: fn(c: ref Challenge, resp: string): ref Authinfo;
respond: fn(chal: string, keyspec: string): (string, string);
open: fn(): ref Sys->FD;
rpc: fn(facfd: ref Sys->FD, verb: string, a: array of byte):
(string, array of byte);
proxy: fn(afd: ref Sys->FD, facfd: ref Sys->FD, arg: string):
ref Authinfo;
rpcattrs: fn(facfd: ref Sys->FD): list of ref Attr;
Attr: adt {
tag: int; # Aattr, Aval, or Aquery
name: string;
val: string;
text: fn(a: self ref Attr): string;
};
parseattrs: fn(s: string): list of ref Attr;
copyattrs: fn(l: list of ref Attr): list of ref Attr;
delattr: fn(l: list of ref Attr, n: string): list of ref Attr;
takeattrs: fn(l: list of ref Attr, names: list of string): list of ref Attr;
findattr: fn(l: list of ref Attr, n: string): ref Attr;
findattrval: fn(l: list of ref Attr, n: string): string;
publicattrs: fn(l: list of ref Attr): list of ref Attr;
attrtext: fn(l: list of ref Attr): string;
.EE
.SH DESCRIPTION
.B Factotum
interacts with an instance of the authentication agent
.IR factotum (4)
to authenticate a client to a server.
It can also interact with Plan 9's
.I factotum
if that is in the name space (as well as or instead of
.IR factotum (4)).
.PP
.B Factotum
supports both the basic RPC interface to
.I factotum
and various high-level operations built on that.
The high-level functions will be described first.
.PP
.B Init
must be called before any other function.
.PP
.B Mount
is similar to
.B Sys->mount
(see
.IR sys-bind (2)),
but uses
.I factotum
to authenticate,
if the server requires it.
.B Factotum->mount
should be used instead of
.B Sys->mount
when mounting file servers that use
.IR attach (5)
to authenticate.
(If the server on
.I fd
does not require authentication,
.B Factotum->mount
simply calls
.BR Sys->mount .)
.B Mount
returns
.RI ( v , ai ).
If the integer
.I v
is non-negative, the mount succeeded;
on error,
.I v
is negative, either the authentication or the mount failed,
.I ai
is nil, and the system error string contains a diagnostic.
If the server required authentication and that was successful,
.I ai
is a non-nil reference to an
.B Authinfo
value containing the agreed user IDs, a capability for
.IR cap (3)
that is valid only on the server, and an array of bytes
containing a shared secret that can be used by client
and server to create encryption and hashing keys for the conversation.
.PP
.B Getuserpasswd
returns a tuple
.RI ( user , password )
containing the values for the
.B user
and
.B !password
attributes of a factotum entry that has
.B proto=pass
and matches the given
.IR keyspec .
The tuple values are nil if no entry matches or the caller lacks permission to see them.
.PP
The pair of functions
.B challenge
and
.B response
give servers access to challenge/response protocols provided by
.IR factotum .
All such authentication protocols are embedded in an application-level protocol
such as FTP, IMAP, POP3 and so on, in a way specific to that protocol.
These functions calculate parameters for application-specific messages.
.PP
A server calls
.B challenge
to get a challenge value to present to the user who will answer the challenge.
The server verifies the user's response by calling
.BR response ,
which returns an
.B Authinfo
value (as described above) if the response is correct.
The specific challenge/response protocol is selected by the
.B proto
attribute in the
.I keyspec
for
.BR challenge ,
which opens a connection to
.IR factotum ,
obtains a string representing a challenge value,
and returns a reference to a
.B Challenge
adt that gives the challenge and a user name.
Some protocols take the user name from a
.B user
attribute in the
.IR keyspec ,
and others negotiate it within the authentication protocol.
In the latter case, the
.B user
field of the resulting
.B Challenge
gives the name negotiated.
.PP
In the other direction, a process uses
.B respond
to calculate the correct response to a given challenge.
.I Chal
is the challenge presented by a server, and
.I keyspec
gives the attributes of the relevant key in the local
.IR factotum .
.B Respond
interacts with
.I factotum
and returns a tuple
.RI ( response,\ user )
that gives the
.I response
string to return to the server, and an optional
.I user
name, depending on the protocol.
On error, the
.I response
is nil, and the system error string contains a diagnostic.
.PP
.IR Factotum (4)
represents keys as attribute value pairs in textual form, with space-separated fields.
A field can be a value-less
.IR attribute ,
an
.IB attribute = value
pair, or
.IB attribute ?
to mark a required attribute with unknown value.
An
.I attribute
name that begins with an exclamation mark
.RB ( ! )
is to be considered hidden or secret.
Values containing white space or special characters can be quoted using the conventions of
.IR sh (1).
.PP
.B Parseattrs
parses a string
.I s
of that form into a list of
.B Attr
references.
Each
.B Attr
has a
.B tag
that identifies the value as
.B Aattr
(a value-less attribute), a
.B Aval
(an attribute-value pair), or
.B Aquery
(an attribute for which a value is needed).
Other operations include:
.TP 15n
.B copyattrs
Return a copy of attribute list
.IR l .
.TP
.B delattr
Return a copy of
.I l
removing all attributes with name
.IR n .
.TP
.B takeattrs
Return the subset of list
.I l
that contains only the attributes listed in
.IR names .
.TP
.B findattr
Return a reference to the first
.B Attr
in
.I l
with the name
.IR n .
.TP
.B findattrval
Return the value of the first attribute in
.I l
with name
.IR n ;
return nil if the attribute is not found or has no value.
.TP
.B publicattrs
Return a copy of
.I l
in which all secret attributes have been removed.
.TP
.B attrtext
Return the textual representation of attribute list
.IR l ,
acceptable to
.BR parseattrs .
.PP
The low-level interfaces to
.I factotum
are as follows.
.PP
.B Proxy
links an authenticating server on
.I afd
with the
.I factotum
agent on
.IR facfd .
Typically
.I facfd
is the result of calling
.BR Factotum->open ,
which is equivalent to
.IP
.EX
sys->open("/mnt/factotum/rpc", Sys->ORDWR)
.EE
.PP
.I Afd
is a file descriptor that represents a connection to the service that requires authentication.
It is typically the result of
.IR sys-open (2),
.IR dial (2),
or
.IR sys-fauth (2).
.I Params
gives any parameters for
.IR factotum ,
as a string containing space-separated
.IB attr = value
pairs.
.B Proxy
ferries messages between the server and
.I factotum
until the end of the selected authentication protocol.
If authentication failed,
.B proxy
returns nil; otherwise on success it always returns a non-nil reference to an
.B Authinfo
value with contents as above, but if the protocol does not
supply that authentication data, all the values are nil.
.PP
.B Rpcattrs
returns the initial attributes provided in the
.B start
request, and any others added later by the protocol.
.PP
.B Rpc
does one message exchange with the
.I factotum
on
.IR facfd .
It writes a message containing the given
.I verb
and optional binary parameter
.IR a ,
and returns
.RI ( v , a )
where
.I v
is the response string from
.I factotum
and
.I a
is an optional binary parameter for that response.
Exceptionally,
.I v
is the string
\f5"rpc failure"\fP
if communication fails or a message is garbled, or
\f5"no key"\fP
if
.B rpc
cannot find a suitable key.
See
.IR factotum (4)
for details of the protocol.
.PP
.B AuthRpcMax
is an integer constant giving the maximum size of a message in an
.B rpc
exchange.
.SH SOURCE
.B /appl/lib/factotum.b
.SH SEE ALSO
.IR sys-bind (2),
.IR sys-fauth (2),
.IR factotum (4),
.IR attach (5)
.SH DIAGNOSTICS
Functions that return nil references on error also set the system error string.