.\" Automatically generated by Pod::Man version 1.15
.\" Fri Dec 20 09:52:46 2002
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "sfskey 1"
.TH sfskey 1 "SFS 0.7.2" "2002-12-20" "SFS 0.7.2"
.UC
.SH "NAME"
sfskey \- \s-1SFS\s0 key manager
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
sfskey [\-S \fIsock\fR] [\-p \fIpwfd\fR] 
\&\fIcommand\fR [\fIarg\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBsfskey\fR command performs a variety of key management tasks,
from generating and updating keys to controlling users' \s-1SFS\s0 agents.  The
general usage for \fBsfskey\fR is:
.PP
sfskey [\-S \fIsock\fR] [\-p \fIpwfd\fR] \fIcommand\fR [\fIarg\fR ...]
.PP
\&\fB\-S\fR specifies a \s-1UNIX\s0 domain socket \fBsfskey\fR can use to
communicate with your \fBsfsagent\fR socket.  If \fIsock\fR begins
with \fB-\fR, the remainder is interpreted as a file descriptor number.
The default is to use the environment variable \fB\s-1SFS_AGENTSOCK\s0\fR if
that exists.  If not, \fBsfskey\fR asks the file system for a
connection to the agent.
.PP
The \fB\-p\fR option specifies a file descriptor from which
\&\fBsfskey\fR should read a passphrase, if it needs one, instead of
attempting to read it from the user's terminal.  This option may be
convenient for scripts that invoke \fBsfskey\fR.  For operations
that need multiple passphrases, you must specify the \fB\-p\fR option
multiple times, once for each passphrase.
.PP
In \s-1SFS\s0 0.7, two-party proactive Schnorr signatures (2\-Schnorr for short)
are supported in addition to Rabin signatures.  One half of the  2\-Schnorr
key is stored on the designated signature sever, while the other is stored
locally to file, or remotely via \s-1SRP\s0.  Unlike Rabin keys, 2\-Schnorr keys
can fail to load when a signature server becomes unavailable.  For this 
reason, \fBsfskey\fR supports multiple private-key shares that correspond
to the same public key; this way, a user can maintain a series of backup
signature servers in case his primary server becomes unavailabe.  By
default, \fBsfskey\fR never stores both halves of a 2\-Schnorr key
to the same machine, so as to enforce key sharing.  To this effect,
2\-Schnorr employs special \fBsfskey\fR commands--\fBsfskey 2gen\fR 
and \fBsfskey 2edit\fR. 
.PP
As of \s-1SFS\s0 0.7, there is a new convention for saving and naming private
keys.  By default, keys will be stored locally in \fI$HOME/.sfs/authkeys\fR,
and will be in the following forms:
.PP
.Vb 2
\&    user@host1#n
\&    user@host1#n,p.host2,m
.Ve
The first form is for standard Rabin keys.  The second is for 2\-Schnorr
proactive signature keys.  In the above examples, \fIhost1\fR is the
the full hostname of the generating host, \fIn\fR is the public key
version, \fIp\fR is the priority of the signing host (1 is the highest)
\&\fIhost2\fR is the full hostname of the signing host, and \fIm\fR is the
private key version.  
.PP
In general, these details can remain hidden, in that the symbolic link
\&\fI$HOME/.sfs/identity\fR points to the most recent key generated in
\&\fI$HOME/.sfs/authkeys\fR, and most \fBsfskey\fR commands have
reasonable defaults.  However, there is a command-line system for
accessing and generating specific keys.  A blank keyname and the
special keyname \fI#\fR refer to the default key
\&\fI$HOME/.sfs/identity\fR during key access and the next available
key during key generation.  Keynames containing a \fI#\fR character
but not containing a \fI/\fR character are assumed to refer to keys
in the \fI$HOME/.sfs/authkeys\fR directory.  When given files of the
form \fIprefix\fR\fI#\fR, \fBsfskey\fR looks in the default
directory for the most recent key with the given \fIprefix\fR during key
access, and the next available key with the given \fIprefix\fR during key
generation.  For keys of the form \fIname\fR\fI#\fR\fIsuffix\fR,
\&\fBsfskey\fR will look in the \fI$HOME/.sfs/authkeys\fR directory
for keys that match the given name exactly. \fBsfskey\fR treats
keys with \fI/\fR characters as regular files; it treats keys that
contain \fI@\fR characters but no \fI#\fR characters as keys stored
on remote machines.
.PP
Finally, one should note that \s-1SFS\s0 keys have both a \fIkeyname\fR 
and also a \fIkeylabel\fR.  \fBsfskey\fR uses the former to
retrieve keys from the local file system or from remote servers.  The latter
is less important; the \fIkeylabel\fR is stored internally in the 
private key, and is shown in the output of the \fBsfskey list\fR
command.
.SH "OPTIONS"
.IX Header "OPTIONS"
.Ip "sfskey add [\-t [hrs:]min] [\fIkeyname\fR]" 4
.IX Item "sfskey add [-t [hrs:]min] [keyname]"
.PD 0
.Ip "sfskey add [\-t [hrs:]min] [\fIuser\fR]@\fIhostname\fR" 4
.IX Item "sfskey add [-t [hrs:]min] [user]@hostname"
.PD
The \fBadd\fR command loads and decrypts a private key, and gives
the key to your agent.  Your agent will use it to try to authenticate
you to any file systems you reference.  The \fB\-t\fR option specifies
a timeout after which the agent should forget the private key.
.Sp
In the first form of the command, the key indicated by \fIkeyname\fR
is loaded.  If \fIkeyname\fR is omitted, or \fI#\fR is supplied, then
the default key is \fI$HOME/.sfs/identity\fR. If the
key supplied is a 2\-Schnorr key, then \fBsfskey add\fR will
attempt to load backup keys should the primary key fail due to an
unavailable signature server.
.Sp
The second form of the command fetches a private key over
the network using the
\&\s-1SRP\s0 (\fIhttp://srp.stanford.edu/\fR) protocol.  \s-1SRP\s0
lets users establish a secure connection to a server without remembering
its public key.  Instead, to prove their identities to each other, the
user remembers a secret password and the server stores a one-way
function of the password (also a secret).  \s-1SRP\s0 addresses the fact that
passwords are often poorly chosen; it ensures that an attacker
impersonating one of the two parties cannot learn enough information to
mount an off-line password guessing attack\*(--in other words, the
attacker must interact with the server or user on every attempt to guess
the password.
.Sp
The \fBsfskey update\fR, \fBsfskey register\fR, 
\&\fBsfskey 2gen\fR and \fBsfskey 2edit\fR commands let users
store their private keys on servers, and retrieve them using the
\&\fBadd\fR command.  The private key is stored in encrypted form,
using the same password as the \s-1SRP\s0 protocol (a safe design as the server
never sees any password-equivalent data).
.Sp
Because the second form of \fBsfskey add\fR establishes a secure
connection to a server, it also downloads the servers HostID securely
and creates a symbolic link from \fI/sfs/\fR\fIhostname\fR to the
server's self-certifying pathname.
.Sp
When invoking \fBsfskey add\fR with the \s-1SRP\s0 syntax, \fBsfskey\fR
will ask for the user's password with a prompt of the following form:
.Sp
Passphrase for \fIuser\fR@\fIservername\fR/\fInbits\fR:
.Sp
\&\fIuser\fR is simply the username of the key being fetched from the
server.  \fIservername\fR is the name of the server on which the user
registerd his \s-1SRP\s0 information.  It may not be the same as the
\&\fIhostname\fR argument to \fBsfskey\fR if the user has supplied a
hostname alias (or \s-1CNAME\s0) to \fBsfskey add\fR.  Finally, \fInbits\fR
is the size of the prime number used in the \s-1SRP\s0 protocol.  Higher values
are more secure; 1,024 bits should be adequate.  However, users should
expect always to see the same value for \fInbits\fR (otherwise, someone
may be trying to impersonate the server).
.Ip "sfskey certclear" 4
.IX Item "sfskey certclear"
Clears the list of certification programs the agent runs.
See \fIcertprog\fR, for more details on certification programs.
.Ip "sfskey certlist [\-q]" 4
.IX Item "sfskey certlist [-q]"
Prints the list of certification programs the agent runs.
See \fIcertprog\fR, for more details on certification programs.
.Ip "sfskey certprog [\-p \fIprefix\fR] [\-f \fIfilter\fR] [\-e \fIexclude\fR] \fIprog\fR [\fIarg\fR ...]" 4
.IX Item "sfskey certprog [-p prefix] [-f filter] [-e exclude] prog [arg ...]"
The \fBcertprog\fR command registers a command to be run to lookup
\&\fIHostID\fRs on the fly in the \fI/sfs\fR directory.  This mechanism can be
used for \fBdynamic server authentication\fR\*(--running code to lookup
\&\fIHostID\fRs on-demand.  When you reference the file
\&\fI/sfs/\fR\fIprefix\fR\fI/\fR\fIname\fR, your agent will run the command:
.Sp
\&\fIprog\fR \fIarg\fR ... \fIname\fR
.Sp
If the program succeeds and prints \fIdest\fR to its standard output,
the agent will then create a symbolic link:
.Sp
/sfs/\fIprefix\fR/\fIname\fR \-> \fIdest\fR
.Sp
The \fB\-p\fR flag can be omitted, and the link is
\&\fB/sfs/\fR\fIname\fR\fB -\fR >\fIdest\fR.  \fIprefix\fR can be more than one
directory deep (i.e., a series of path components separated by
\&\fB/\fR).  If so, the first certification program whose prefix matches
at the beginning of \fIprefix\fR is run.  The remaining path components
are passed to \fIprog\fR.  For example:
.Sp
.Vb 1
\&  NEED EXAMPLE
.Ve
\&\fIfilter\fR is a perl-style regular expression.  If it is specified,
then \fIname\fR must contain it for the agent to run \fIprog\fR.
\&\fIexclude\fR is another regular expression, which, if specified,
prevents the agent from running \fIprog\fR on \fIname\fRs that contain
it (regardless of \fIfilter\fR).
.Sp
The program \fBdirsearch\fR can be used with \fBcertprog\fR to
configure \fBcertification paths\fR\*(--lists of directories in which to
look for symbolic links to \fIHostID\fRs.  The usage is:
.Sp
dirsearch [\-clpq] \fIdir1\fR [\fIdir2\fR ...] \fIname\fR
.Sp
\&\fBdirsearch\fR searches through a list of directories \fIdir1\fR,
\&\fIdir2\fR, ... until it finds one containing a file called
\&\fIname\fR, then prints the pathname \fIdir\fR\fB/\fR\fIname\fR.  If it
does not find a file, \fBdirsearch\fR exits with a non-zero exit
code.  The following options affect \fBdirsearch\fR's behavior:
.RS 4
.Ip "\-c" 4
.IX Item "-c"
Print the contents of the file to standard output, instead of its
pathname.
.Ip "\-l" 4
.IX Item "-l"
Require that \fIdir\fR\fB/\fR\fIname\fR be a symbolic link, and print
the path of the link's destination, rather than the path of the link
itself.
.Ip "\-p" 4
.IX Item "-p"
Print the path \fIdir\fR\fB/\fR\fIname\fR.  This is the default
behavior anyway, so the option \fB\-p\fR has no effect.
.Ip "\-q" 4
.IX Item "-q"
Do not print anything.  Exit abnormally if \fIname\fR is not found in
any of the directories.
.RE
.RS 4
.Sp
As an example, to lookup self-certifying pathnames in the directories
\&\fI$HOME/.sfs/known_hosts\fR and \fI/mit\fR, but only accepting links
in \fI/mit\fR with names ending \fI.mit.edu\fR, you might execute the
following commands:
.Sp
.Vb 2
\&  % sfskey certprog dirsearch $HOME/.sfs/known_hosts
\&  % sfskey certprog -f '\e.mit\e.edu$' /mnt/links
.Ve
.RE
.Ip "sfskey delete \fIkeyname\fR" 4
.IX Item "sfskey delete keyname"
Deletes private key \fIkeyname\fR from the agent (reversing the effect
of an \fBadd\fR command).
.Ip "sfskey deleteall" 4
.IX Item "sfskey deleteall"
Deletes all private keys from the agent.
.Ip "sfskey edit [\-LP] [\-o \fIkeyname\fR] [\-c \fIcost\fR] [\-l \fIlabel\fR] [\fIkeyname\fR]" 4
.IX Item "sfskey edit [-LP] [-o keyname] [-c cost] [-l label] [keyname]"
Changes the passphrase, passphrase ``cost'', or name of a public key.
Can also download a key from a remote server via \s-1SRP\s0 and store it in a
file.
.Sp
\&\fIkeyname\fR can be a file name, or it can be of the form
\&\fB[\fR\fIuser\fR\fB]@\fR\fIserver\fR, in which case \fBsfskey\fR will
fetch the key remotely and \fIoutfile\fR must be specified.  If
\&\fIkeyname\fR is unspecified the default is \fI$HOME/.sfs/identity\fR.
If \fIkeyname\fR is \fI#\fR, then \fBsfskey edit\fR will search
for the next appropraite keyname in \fI$HOME/.sfs/authkeys\fR.  In this case,
\&\fBsfskey edit\fR will update \fI$HOME/.sfs/identity\fR to point to
this new key by default.
.Sp
The options are:
.RS 4
.Ip "\-L" 4
.IX Item "-L"
Does not set symlink in the case that \fIkeyname\fR is \fI#\fR.
.Ip "\-P" 4
.IX Item "-P"
Removes any password from the key, so that the password is stored on
disk in unencrypted form.
.Ip "\-o \fIkeyname\fR" 4
.IX Item "-o keyname"
Specifies the file to which the edited key should be written.  A
\&\fIkeyname\fR of \fI#\fR implies that \fBsfskey edit\fR should
generate the next availabe default key in \fI$HOME/.sfs/authkeys\fR.
A \fIkeyname\fR of ther form \fIprefix\fR\fI#\fR implies that
\&\fBsfskey edit\fR should generate the next available key in
\&\fI$HOME/.sfs/authkeys\fR with the prefix \fIprefix\fR.  A \fIkeyname\fR
of the form \fIprefix\fR\fI#\fR\fIsuffix\fR implies that 
\&\fBsfskey edit\fR should make a key named 
\&\fI$HOME/.sfs/authkeys/\fR\fIprefix\fR\fI#\fR\fIsuffix\fR.
.Ip "\-c \fIcost\fR" 4
.IX Item "-c cost"
Override the default computational cost of processing a password, or
\&\fBPwdCost\fR.
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
Specifies the label of the key that shows up in \fBsfskey list\fR.
.RE
.RS 4
.RE
.Ip "sfskey 2edit \-[Smp] [\-l \fIlabel\fR] [\-S | \-s \fIsrpfile\fR] [\fIkeyname1\fR \fIkeyname2\fR ...]" 4
.IX Item "sfskey 2edit -[Smp] [-l label] [-S | -s srpfile] [keyname1 keyname2 ...]"
Refreshes a 2\-Schnorr key by resharing a secret between a server
and a client. In the case of a compromised client or server, it is 
recommended to refresh a 2\-Schnorr key with this command.  If both
the client and the server have been compromised, a refresh will be 
of little use.
.Sp
Use \fBsfskey 2edit\fR by supplying the keys that you wish to have
updated.  Keynames are given in standard \fBsfskey\fR style.  Keynames
must be either remote keynames (i.e., contain a \fI@\fR but no \fI#\fR
character) or stored in the standard keys directory (i.e., contain a \fI#\fR
but no \fI/\fR character).  For remote keys, \s-1SRP\s0 will be used to 
download the key from the server, and the updated, encrypted client private
keyhalf will be written back to the server along with the new server
keyhalf.  No file will be saved locally.  For keys stored in 
\&\fI$HOME/.sfs/authkeys\fR, \fBsfskey 2edit\fR will update the
server private keyhalf, and write the corresponding client private
keyhalf out to \fI$HOME/.sfs/authkeys\fR under a new filename.  By default,
\&\fBsfskey 2edit\fR will also write the new encrypted client private
keyhalf back to the server for later \s-1SRP\s0 retrieval.
.Sp
If no key is specified, the default key, \fI$HOME/.sfs/identity\fR is 
assumed.
.RS 4
.Ip "\-E" 4
.IX Item "-E"
Do not update the encrypted private client key stored on the server.
.Ip "\-S" 4
.IX Item "-S"
Do not update \s-1SRP\s0 information on the server.  This option cannot be used
if some of the keynames specified are for remote keys.
.Ip "\-m" 4
.IX Item "-m"
Refresh multiple keys.  If you have multiple private splits of the same
private key, this flag will automatically update them all, given that
you've specified one of them.  If you run \fBsfskey 2edit \-m\fR,
with no additional arguments or keynames, \fBsfskey\fR will refresh
all current default keys.
.Ip "\-p" 4
.IX Item "-p"
Change password before writing keys out to disk or server.
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
Specifies the label of the key that shows up in \fBsfskey list\fR.
.Ip "\-s \fIsrpfile\fR" 4
.IX Item "-s srpfile"
Get \s-1SRP\s0 parameters from the file \fIsrpfile\fR.
.RE
.RS 4
.RE
.Ip "sfskey gen [\-KP] [\-b \fInbits\fR] [\-c \fIcost\fR] [\-l \fIlabel\fR] [\fIkeyname\fR]" 4
.IX Item "sfskey gen [-KP] [-b nbits] [-c cost] [-l label] [keyname]"
Generates a new Rabin public/private key pair and stores it in \fIkeyname\fR.
It omitted \fIkeyname\fR defaults to the next available Rabin key
in \fI$HOME/.sfs/authkeys\fR.  If \fIkeyname\fR contains a \fI/\fR 
character, it will be treated as a regular Unix file.  If \fIkeyname\fR
is of the form \fIprefix\fR\fI#\fR, \fBsfskey gen\fR will look for
the next avaible Rabin key in \fI$HOME/.sfs/authkeys\fR with the
prefix \fIprefix\fR.  If \fIkeyname\fR contains a non-termainl \fI#\fR
character, it will be treated as a fully-specified keyname to be saved in 
\&\fI$HOME/.sfs/authkeys\fR.
.Sp
Note that \fBsfskey gen\fR is only useful for generating Rabin keys.
Use either \fBsfskey register\fR or \fBsfskey 2gen\fR to
generate 2\-Schnorr keys.
.RS 4
.Ip "\-K" 4
.IX Item "-K"
By default, \fBsfskey gen\fR asks the user to type random text with
which to seed the random number generator.  The \fB\-K\fR option
suppresses that behavior.
.Ip "\-P" 4
.IX Item "-P"
Specifies that \fBsfskey gen\fR should not ask for a passphrase and
the new key should be written to disk in unencrypted form.
.Ip "\-b \fInbits\fR" 4
.IX Item "-b nbits"
Specifies that the public key should be \fInbits\fR long.
.Ip "\-c \fIcost\fR" 4
.IX Item "-c cost"
Override the default computational cost of processing a password, or
\&\fBPwdCost\fR.
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
Specifies the label of the key that shows up in \fBsfskey list\fR.
Otherwise, the user will be prompted for a name.
.RE
.RS 4
.RE
.Ip "sfskey 2gen [\-BEKP] [\-a {\fIhostid\fR | \-}] [\-b \fInbits\fR] [\-c \fIcost\fR] [\-k \fIokeyname\fR] [\-l \fIlabel\fR] [\-S | \-s \fIsrpfile\fR] [\-w \fIwkeyfile\fR] [\fInkeyname\fR]" 4
.IX Item "sfskey 2gen [-BEKP] [-a {hostid | -}] [-b nbits] [-c cost] [-k okeyname] [-l label] [-S | -s srpfile] [-w wkeyfile] [nkeyname]"
Generates a new 2\-Schnorr keypair for each of the servers specified by
the \fB\-a\fR flag.  All keypairs will correspond to the same
public key.  The new keys will be saved locally to the files given
by \fInkeyname\fR in the usual fashion: if \fInkeyname\fR is of the
form \fIprefix\fR#, then \fBsfskey 2gen\fR will look for the next
available 2\-Schnorr key in \fI$HOME/.sfs/authkeys\fR with the prefix
\&\fIprefix\fR.  If no \fInkeyname\fR is given, it will find the next
available keyname in \fI$HOME/.sfs.authkeys\fR with the default
prefix (\fIuser\fR@\fIhost\fR).
.Sp
Note that by default, this operation will update the public key, the
encrypted private key, the \s-1SRP\s0 information, and the server private key
share on all of the servers given.  Specify \fB\-BES\fR to suppress
updates of these fields.
.RS 4
.Ip "\-a \-" 4
.IX Item "-a -"
.PD 0
.Ip "\-a \fIhostid\fR" 4
.IX Item "-a hostid"
.PD
Can be specified arbitrarily many times, once for each server that will
accept the server private half of the 2\-Schnorr key being generated.  Note
that the same public key will be used for all servers.  To specify the local
host, use the first syntax.  If \s-1SRP\s0 is used to download a key from host 
\&\fIhost\fR (e.g., \fB\-k \fR\fIuser\fR\fB@\fR\fIhost\fR), then you can specify
that host by its simple hostname (e.g., \fB\-a \fR\fIhost\fR).  If \s-1SRP\s0 
was not used to connect to a host \fIhost\fR, then \fB\-a\fR requires
a complete \s-1SFS\s0 host identifier (i.e., @\fILocation\fR,\fIHostID\fR).
.Ip "\-B" 4
.IX Item "-B"
Do not update the public key on the given servers.
.Ip "\-E" 4
.IX Item "-E"
Do not update the encrypted private key field on the given servers.
.Ip "\-K" 4
.IX Item "-K"
.PD 0
.Ip "\-P" 4
.IX Item "-P"
.Ip "\-c \fIcost\fR" 4
.IX Item "-c cost"
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
.Ip "\-s \fIsrpfile\fR" 4
.IX Item "-s srpfile"
.PD
See \fBsfskey gen\fR.  These options behave similarly.
.Ip "\-S" 4
.IX Item "-S"
Do not update the \s-1SRP\s0 information on the server.
.Ip "\-b \fInbits\fR" 4
.IX Item "-b nbits"
Speficies the number of bits for the 2\-Schnorr modulus p.  The security of
2\-Schnorr is related to the discrete log problem over Z_p*; values over 1024
are suggested for this parameter, and reasonable defaults are chosen if
this parameter is not specified.
.Ip "\-k \fIkeyname\fR" 4
.IX Item "-k keyname"
Specify this option arbitrarily many times to keys into memory for
\&\fBsfskey\fR.  By default, all keys from \fI$HOME/.sfs/authkeys\fR
are loaded and hashed.  Remote keys and local keys in non-standard 
locations can be loaded into the hash with this option.  The keys
will in turn be used to authenticate you to the servers that you 
intend to update.
.Ip "\-w \fIwkeyfile\fR" 4
.IX Item "-w wkeyfile"
Save the complete Schnorr key (both halves) to the file given.  Note
that it is possible to non-interactively sign with this key, so it is
advised that it not be stored on network-accessible media.  The
intended use for this option is to allow saving of both halves to a 
floppy disk or to a \s-1CD-R\s0, so that in a worst case scenario, the original
key is still recoverable.
.RE
.RS 4
.RE
.Ip "sfskey help" 4
.IX Item "sfskey help"
Lists all of the various \fBsfskey\fR commands and their usage.
.Ip "sfskey hostid \fIhostname\fR" 4
.IX Item "sfskey hostid hostname"
.PD 0
.Ip "sfskey hostid \-" 4
.IX Item "sfskey hostid -"
.PD
Retrieves a self-certifying pathname insecurely over the network and
prints \fB@\fR\fILocation\fR\fB,\fR\fIHostID\fR to standard output.  If
\&\fIhostname\fR is simply \fB-\fR, returns the name of the current
machine, which is not insecure.
.RS 4
.Ip "\-s \fIservice\fR" 4
.IX Item "-s service"
The default service is file service, \fBsfs\fR (except when using
\&\fB-\fR).  This option selects a different \s-1SFS\s0 service.  Possible
values for \fIservice\fR are \fBsfs\fR, \fBauthserv\fR, and
\&\fBrex\fR.
.RE
.RS 4
.RE
.Ip "sfskey kill" 4
.IX Item "sfskey kill"
Kill the agent.
.Ip "sfskey list [\-ql]" 4
.IX Item "sfskey list [-ql]"
List the public keys whose private halves the the agent holds.
.RS 4
.Ip "\-q" 4
.IX Item "-q"
Suppresses the banner line explaining the output.
.Ip "\-l" 4
.IX Item "-l"
Lists the actual value of public keys, in addition the the names of the
keys.
.RE
.RS 4
.RE
.Ip "sfskey norevokeset \fIHostID\fR ..." 4
.IX Item "sfskey norevokeset HostID ..."
.PD 0
.Ip "sfskey norevokelist" 4
.IX Item "sfskey norevokelist"
.Ip "sfskey passwd [\-Kp] [\-S | \-s \fIsrpfile\fR] [\-b \fInbits\fR] [\-c \fIcost\fR] [\-l \fIlabel\fR] [\fIarg1\fR] [\fIarg2\fR] ..." 4
.IX Item "sfskey passwd [-Kp] [-S | -s srpfile] [-b nbits] [-c cost] [-l label] [arg1] [arg2] ..."
.PD
The \fBsfskey passwd\fR command is a high-level command for ``changing
passwords'' in \s-1SFS\s0.  In the case of proactive keys, \fBsfskey passwd\fR
will simply refresh keys via \fBsfskey 2edit\fR functionality.  In
the case of Rabin keys, \fBsfskey passwd\fR generates a new Rabin
key and updates the given servers. By default, \fBsfskey passwd\fR
assumes standard Rabin keys, and thus treats \fIarg-i\fR as 
[\fIuser\fR][@]\fIhost\fR arguments.  If \fIhost\fR is a regular 
hostname, then \s-1SRP\s0 will be required to authenticate the host.  If \fIhost\fR
is a full \s-1SFS\s0 pathname, then \fBsfskey passwd\fR will look for keys
in \fI$HOME/.sfs/authkeys\fR that can authenticate the user to that particular
server.  In the case of proactive 2\-Schnorr keys, \fBsfskey passwd\fR
will treat \fIarg-i\fR as local or remote keynames.
.Sp
If no options or arguments are given, \fBsfskey passwd\fR will look
to the default key given by \fI$HOME/.sfs/identity\fR.  If the default key
is a procative 2\-Schnorr key, then all current 2\-Schnorr keys in 
\&\fI.sfs/authkeys\fR are refreshed.  If the default key is a Rabin key,
then the users key on the local machine is updated.
.RS 4
.Ip "\-p" 4
.IX Item "-p"
Specifies proactive mode.  Will treat arguments \fIarg1\fR through 
\&\fIarg-n\fR as keynames, whether local or remote.  By default,
\&\fBsfskey passwd\fR operates under the assumption that the key to 
update is a Rabin key.
.Ip "\-K" 4
.IX Item "-K"
.PD 0
.Ip "\-S" 4
.IX Item "-S"
.Ip "\-s \fIsrpfile\fR" 4
.IX Item "-s srpfile"
.Ip "\-b \fInbits\fR" 4
.IX Item "-b nbits"
.Ip "\-c \fIcost\fR" 4
.IX Item "-c cost"
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
.PD
These options are the same as for \fBsfskey gen\fR.  Briefly,
\&\fB\-S\fR turns of \s-1SRP\s0, \fB\-K\fR disables keyboard randomness 
query, \fB\-s\fR is used to supply an \s-1SRP\s0 parameters file and is
mutually exclusive with \fB\-S\fR, \fB\-b\fR specifies the 
size of the key in bits, \fB\-c\fR specifies the secret key 
encryption cost, and \fB\-l\fR specifies the label for the key,
as seen in \fBsfskey list\fR.
.RE
.RS 4
.RE
.Ip "sfskey register [\-fgpPK] [\-S | \-s \fIsrpfile\fR] [\-b \fInbits\fR] [\-c \fIcost\fR] [\-u \fIuser\fR] [\-l \fIlabel\fR] [\-w \fIfilename\fR] [\fIkeyname\fR]" 4
.IX Item "sfskey register [-fgpPK] [-S | -s srpfile] [-b nbits] [-c cost] [-u user] [-l label] [-w filename] [keyname]"
The \fBsfskey register\fR command lets users who are logged into an
\&\s-1SFS\s0 file server register their public keys with the file server for the
first time.  Subsequent changes to their public keys can be
authenticated with the old key, and must be performed using
\&\fBsfskey update\fR or \fBsfskey 2gen\fR.  The superuser can also use
\&\fBsfskey register\fR when creating accounts.
.Sp
\&\fIkeyname\fR is the private key to use.  If \fIkeyname\fR does not exist and 
is a pathname, \fBsfskey\fR will create it.  The default \fIkeyname\fR is
\&\fI$HOME/.sfs/identity\fR, unless \fB\-u\fR is used, in which case
the default is to generate a new key in the current directory.  For keys
that contain the special trailing character \fI#\fR, \fBsfskey\fR
will implicitly determine whether the user intends to generate or access
a key.  If the command is invoked as root with the \fB\-u\fR flag, then
generation is assumed.  Similarly, if any of the options \fB\-bcgp\fR
are used, generation is assumed.  Otherwise, \fBsfskey\fR will first
attempt to access the most recent key matching \fIkeyname\fR, and then will 
revert to generation if the access fails.
.Sp
If a user wishes to reuse a public key already registered with another
server, the user can specify \fIuser\fR\fB@\fR\fIserver\fR for
\&\fIkeyname\fR.
.RS 4
.Ip "\-f" 4
.IX Item "-f"
Force reregistration.  Ordinarily, \fBsfskey gen\fR will fail if a 
record for the given user already exists on the server.  
.Ip "\-g" 4
.IX Item "-g"
Force key generation.  When using keynames of the form
\&\fIprefix\fR\fI#\fR, \fBsfskey register\fR will always generate
then next available key with the prefix \fIprefx\fR in the standard
keys direcotry (\fI$HOME/.sfs/authkeys\fR).  If \fBsfskey
register\fR is being run as root with the \fB\-u\fR option, then
access to the standard keys directory \fI$HOME/.sfs/authkeys\fR will
not be allowed.  Hence, the key will simply be generated in the
current directory.
.Ip "\-p" 4
.IX Item "-p"
Generate a new proctive 2\-Schnorr key.  Implies the \fB\-g\fR flag.
.Ip "\-K" 4
.IX Item "-K"
.PD 0
.Ip "\-P" 4
.IX Item "-P"
.Ip "\-l \fIlabel\fR" 4
.IX Item "-l label"
.Ip "\-b \fInbits\fR" 4
.IX Item "-b nbits"
.Ip "\-c \fIcost\fR" 4
.IX Item "-c cost"
.Ip "\-s \fIsrpfile\fR" 4
.IX Item "-s srpfile"
.PD
These options are the same as for \fBsfskey gen\fR.  \fB\-K\fR and
\&\fB\-b\fR have no effect if the key already exists.  They all imply the
\&\fB\-g\fR flag. If \fB\-p\fR is given, then \fI\-b\fR will specify
the size of the modulus \fIp\fR used in 2\-Schnorr.  Without \fB\-p\fR,
\&\fB\-b\fR will specify the size of \fIpq\fR in Rabin.
.Ip "\-S" 4
.IX Item "-S"
Do not register any \s-1SRP\s0 information with the server\*(--this will prevent
the user from using \s-1SRP\s0 to connect to the server, but will also prevent
the server from gaining any information that could be used by an
attacker to mount an off-line guessing attack on the user's password.
.Ip "\-u \fIuser\fR" 4
.IX Item "-u user"
When \fBsfskey register\fR is run as root, specifies a particular
user to register.  
.Ip "\-w \fIfilename\fR" 4
.IX Item "-w filename"
When generating a proactive key, saves the complete key out to 
the given file.  Will raise an error if supplied without the \fB\-p\fR
flag.  For security reasons, this should only be used when saving to
removable media (e.g., \fI/floppy/complete-key-2\fR).  It is a susbstantial
security risk to leave the complete key on a file system that might
be compromised.
.RE
.RS 4
.Sp
\&\fIsfsauthd_config\fR must have a \fBUserfile\fR with the
\&\fB\-update\fR and \fB\-passwd\fR options to enable use of the 
\&\fBsfskey register\fR.
.RE
.Ip "sfskey reset" 4
.IX Item "sfskey reset"
Clear the contents of the \fI/sfs\fR directory, including all symbolic
links created by \fBsfskey certprog\fR and \fBsfskey add\fR, and
log the user out of all file systems.
.Sp
Note that this is not the same as deleting private keys held by the
agent (use \fBdeleteall\fR for that).  In particular, the effect of
logging the user out of all file systems will likely not be
visible\*(--the user will automatically be logged in again on-demand.
.Ip "sfskey revokegen [\-r \fInewkeyfile\fR [\-n \fInewhost\fR]] [\-o \fIoldhost\fR] \fIoldkeyfile\fR" 4
.IX Item "sfskey revokegen [-r newkeyfile [-n newhost]] [-o oldhost] oldkeyfile"
.PD 0
.Ip "sfskey revokelist" 4
.IX Item "sfskey revokelist"
.Ip "sfskey revokeclear" 4
.IX Item "sfskey revokeclear"
.Ip "sfskey revokeprog [\-b [\-f \fIfilter\fR] [\-e \fIexclude\fR]] \fIprog\fR [\fIarg\fR ...]" 4
.IX Item "sfskey revokeprog [-b [-f filter] [-e exclude]] prog [arg ...]"
.Ip "sfskey select [\-f] \fIkeyname\fR" 4
.IX Item "sfskey select [-f] keyname"
.PD
Select the given key as the default key; set \fI$HOME/.sfs/identity\fR
to point to the key given by \fIkeyname\fR.  It cannot be an \s-1SRP\s0 key.
.RS 4
.Ip "\-f" 4
.IX Item "-f"
Force overwrite.  If current \fI$HOME/.sfs/identity\fR is a regular
file, \fBsfskey select\fR will overwrite it.
.RE
.RS 4
.RE
.Ip "sfskey sesskill \fIremotehost\fR" 4
.IX Item "sfskey sesskill remotehost"
Kill the \fBrex\fR session to the server specified by \fIremotehost\fR,
where \fIremotehost\fR is any unique prefix of the remote host's
self-certifying hostname (found under the \*(L"\s-1TO\s0\*(R" column in the output to
\&\fBsfskey sesslist\fR).
.Ip "sfskey sesslist" 4
.IX Item "sfskey sesslist"
List the \fBrex\fR sessions that the agent is maintaining.
.Ip "sfskey srpgen [\-b \fInbits\fR] file" 4
.IX Item "sfskey srpgen [-b nbits] file"
Generate a new \fIsfs_srp_params\fR file.
.Ip "sfskey update [\-fE] [\-S | \-s \fIsrp_params\fR] [\-r \fIsrpkey\fR] [\-a \fIokeyname\fR] [\-k \fInkeyname\fR] \fIserver1\fR \fIserver2\fR ..." 4
.IX Item "sfskey update [-fE] [-S | -s srp_params] [-r srpkey] [-a okeyname] [-k nkeyname] server1 server2 ..."
Change a user's public key and \s-1SRP\s0 information on an \s-1SFS\s0 file server.
To change public keys, typically you should generate a new public key
and store it in \fI$HOME/.sfs/identity\fR.  Then you can run
\&\fBsfskey update [\fR\fIuser\fR\fB]@\fR\fIhost\fR for each server on which
you need to change your public key.
.Sp
To authenticate you to the servers on which updates are requested,
\&\fBsfskey update\fR will first use the keys given via \fB\-a\fR
arguments; it will then search keys in the standard key 
directory--\fI$HOME/.sfs/authkeys\fR.
.Sp
At least one \fIserver\fR argument is required.  As usual, the string 
``\-'' denotes the localhost. The servers specified can be either 
full \s-1SFS\s0 hostnames of the form [\fIuser\fR]@\fILocation\fR,\fIHostId\fR,
or standard hostnames of the form [\fIuser\fR@]\fILocation\fR.  In the
latter case, \s-1SRP\s0 is assumed, and the corresponding private key is 
automatically loaded into \fBsfskey\fR.
.Sp
The new key that is being pushed to the server is given by the
\&\fB\-k\fR flag.  If this is not provided, the default key
\&\fI$HOME/.sfs/identity\fR will be assumed.
.Sp
The \fB\-r\fR provides a shortcut for updating \s-1SRP\s0 information, if, 
for instance, the auth server has changed its realm information.  Invoking
\&\fBsfskey update \fR\fB\-r\fR\fB [\fR\fIuser\fR\fB]@\fR\fIhost\fR is
equivalent to \fBsfskey update \-k [\fR\fIuser\fR\fB]@\fR\fIhost\fR\fB \fR\fIhost\fR.
.Sp
Several options control \fBsfskey update\fR's behavior:
.RS 4
.Ip "\-E" 4
.IX Item "-E"
Do not send encrypted secret key information to the server.
.Ip "\-S" 4
.IX Item "-S"
Do not send \s-1SRP\s0 information to the server\*(--this will prevent the user
from using \s-1SRP\s0 to connect to the server, but will also prevent the
server from gaining any information that could be used by an attacker to
mount an off-line guessing attack on the user's password.  Implies 
\&\fB\-E\fR
.Ip "\-a \fIokeyname\fR" 4
.IX Item "-a okeyname"
This arugment can be supplied arbitrarily many times, once for each
key that should be loaded into \fBsfskey\fR for this session.
Keynames are specified as described above, and can be remote or
local filenames. Usually it will not be necessary to specify keys in the
keys directory (\fI$HOME/.sfs/authkeys\fR) as they are considered
automatically. 
.Ip "\-f" 4
.IX Item "-f"
If there is a change in \s-1SRP\s0 realm information, the \fB\-f\fR flag
will force an update.  Normally, the user is prompted to verify.
.Ip "\-k \fInkeyname\fR" 4
.IX Item "-k nkeyname"
Specifies the new key to push to the server. Can be an \s-1SRP\s0 key,
a local file, or a keyname with a '#' sign, signifyin a key
stored in the keys directory, \fI$HOME/.sfs/authkeys\fR. If this
flag is not specified, \fI$HOME/.sfs/identity\fR is assumed.
Note that the \fB\-k\fR flag can be specified only once.
.Ip "\-r [\fIuser\fR][@]\fIhost\fR" 4
.IX Item "-r [user][@]host"
Update \s-1SRP\s0 information of a key on a remote host. Equivalent to
\&\fBsfskey update \-a \fR\fIhost\fR\fB [\fR\fIuser\fR\fB]@\fR\fIhost\fR.
Cannot be used with the \fB\-akS\fR options.
.Ip "\-s" 4
.IX Item "-s"
\&\fIsrp_params\fR is the path of a file generated by \fBsfskey
srpgen\fR, and specifies the parameters to use in generating \s-1SRP\s0
information for the server.  The default is to get \s-1SRP\s0 parameters from
the server, or look in
\&\fI/usr/local/share/sfs/sfs_srp_params\fR.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdirsearch\fR\|(1), \fInewaid\fR\|(1), \fIrex\fR\|(1), \fIsfsagent\fR\|(1), \fIssu\fR\|(1), \fIsfs_config\fR\|(5), \fIsfs_srp_params\fR\|(5), \fIsfs_users\fR\|(5), \fIsfsauthd_config\fR\|(5), \fIsfscd_config\fR\|(5), \fIsfsrwsd_config\fR\|(5), \fIsfssd_config\fR\|(5), \fIfunmount\fR\|(8), \fIsfsauthd\fR\|(8), \fIsfscd\fR\|(8), \fIsfsrwsd\fR\|(8), \fIsfssd\fR\|(8), \fIvidb\fR\|(8)
.PP
The full documentation for \fB\s-1SFS\s0\fR is maintained as a Texinfo
manual.  If the \fBinfo\fR and \fB\s-1SFS\s0\fR programs are properly installed
at your site, the command \fBinfo \s-1SFS\s0\fR
should give you access to the complete manual.
.PP
For updates, documentation, and software distribution, please
see the \fB\s-1SFS\s0\fR website at \fIhttp://www.fs.net\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
sfsdev@redlab.lcs.mit.edu