This is sfs.info, produced by makeinfo version 4.2 from sfs.texi.

START-INFO-DIR-ENTRY
* SFS: (sfs).		Self-certifying file system
END-INFO-DIR-ENTRY

   This file documents SFS, the self-certifying file system.

   Copyright 1999-2002 David Mazie`res

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: sfs.info,  Node: `sfs_srp_params',  Next: `sfscd_config',  Prev: `sfssd_config',  Up: SFS configuration

`sfs_srp_params'--Default parameters for SRP protocol
=====================================================

   Specifies a "strong prime" and a generator for use in the SRP
protocol.  SFS ships with a particular set of parameters because
generating new ones can take a considerable amount of CPU time.  You can
replace these parameters with randomly generated ones using the `sfskey
srpgen -b BITS' command.

   Note that SRP parameters can afford to be slightly shorter than Rabin
public keys, both because SRP is based on discrete logs rather than
factoring, and because SRP is used for authentication, not secrecy.
1,024 is a good value for BITS even if `PubKeySize' is slightly larger
in `sfs_config'.


File: sfs.info,  Node: `sfscd_config',  Prev: `sfs_srp_params',  Up: SFS configuration

`sfscd_config'--Meta-client configuration
=========================================

   The `sfscd_config' is really part of the SFS protocol specification.
If you change it, you will no longer be executing the SFS protocol.
Nonetheless, you need to do this to innovate, and SFS was designed to
make implementing new kinds of file systems easy.

   `sfscd_config' takes the following directives:

`Extension STRING'
     Specifies that `sfscd' should send STRING to all servers to
     advertise that it runs an extension of the protocol.  Most servers
     will ignore STRING, but those that support the extension can pass
     off the connection to a new "extended" server daemon.  You can
     specify multiple `Extension' directives.

`Protocol NAME DAEMON [ARG ...]'
     Specifies that pathnames of the form `/sfs/NAME:ANYTHING' should
     be handled by the client daemon DAEMON.  NAME may not contain any
     non-alphanumeric characters.  The `Protocol' directive is useful
     for implementing file systems that are not mounted on
     self-certifying file systems.

`Release {* | SFS-VERSION}'
     Begins a section of the file that applies to servers running SFS
     release SFS-VERSION or older.  `*' signifies arbitrarily large SFS
     release numbers.  The `Release' directive does not do anything on
     its own, but applies to all subsequent `Program' directives until
     the next `Release' directive.

`Libdir PATH'
     Specifies where SFS should look for daemon programs when their
     pathnames do not begin with `/'.  The default is
     `/usr/local/lib/sfs-0.7.2'.  The `Libdir' directive does not do
     anything on its own, but applies to all subsequent `Program'
     directives until the next `Libdir' or `Release' directive.

`Program PROG.VERS DAEMON [ARG ...]'
     Specifies that connections to servers running Sun RPC program
     number PROG and version VERS should be handed off to the the local
     daemon DAEMON.  SFS currently defines two RPC program numbers.
     Ordinary read-write servers use program number 344444, version 3 (a
     protocol very similar to NFS3), while read-only servers use program
     344446, version 1.  The read-only code has not been released yet.
     The `Program' directive must be preceded by a `Release' directive.

The default `sfscd_config' file is:

     Release *
       Program 344444.3 sfsrwcd

To run a different set of daemons when talking to sfs-0.3 or older
servers, you could add the following lines:

     Release 0.3
       Libdir /usr/local/lib/sfs-0.3
       Program 344444.3 sfsrwcd


File: sfs.info,  Node: Command reference,  Next: Security,  Prev: SFS configuration,  Up: Top

Command reference guide
***********************

* Menu:

* sfsagent::                    Run by each user for authentication to servers
* sfskey::                      Controls the agent
* rex::                         Remote execution facility
* dirsearch::                   Search for file name in directories
* newaid::                      Run processes with different sfsagents
* ssu::                         Become root without changing sfsagents
* sfscd::                       Daemon run by root on all client machines
* sfssd::                       Daemon run by root on all server machines
* vidb::                        Manually edit user-authentication database
* funmount::                    Forcibly unmount file systems
* sfsrwsd::                     Daemon implementing read-write file server
* sfsauthd::                    User-authentication server


File: sfs.info,  Node: sfsagent,  Next: sfskey,  Prev: Command reference,  Up: Command reference

`sfsagent' reference guide
==========================

   `sfsagent' is the program users run to authenticate themselves to
remote file servers, to create symbolic links in `/sfs' on the fly, and
to look for revocation certificates.  Many of the features in
`sfsagent' are controlled by the `sfskey' program and described in the
`sfskey' documentation.

   Ordinarily, a user runs `sfsagent' at the start of a session.
`sfsagent' runs `sfskey add' to obtain a private key.  As the user
touches each SFS file server for the first time, the agent
authenticates the user to the file server transparently using the
private key it has.  At the end of the session, the user should run
`sfskey kill' to kill the agent.

   The usage is as follows:

     sfsagent [-dnkF] -S SOCK [-c [PROG [ARG ...]] | KEYNAME]

`-d'
     Stay in the foreground rather than forking and going into the
     background

`-n'
     Do not attempt to communicate with the SFS file system.  This can
     be useful for debugging, or for running an agent on a machine that
     is not running an SFS client.  If you specify `-n', you must also
     use the `-S' option, otherwise your agent will be useless as there
     will be no way to communicate with it.

`-k'
     Atomically kill and replace any existing agent.  Otherwise, if your
     agent is already running, `sfsagent' will refuse to run again.

`-F'
     Turn off forwarding.  By default programs other than the file
     system can ask the agent to authenticate the user.  Specifying
     this option disables this functionality.

`-S SOCK'
     Listen for connections from programs like `sfskey' on the Unix
     domain socket SOCK.  Ordinarily `sfskey' connects to the agent
     through the client file system software, but it can use a named
     Unix domain socket as well.

`-c [PROG [ARG ...]]'
     By default, `sfsagent' on startup runs the command `sfskey add'
     giving it whatever `-t' option and KEYNAME you specified.  This
     allows you to fetch your first key as you start or restart the
     agent.  If you wish to run a different program, you can specify it
     using `-c'.  You might, for instance, wish to run a shell-script
     that executes a `sfskey add' followed by several `sfskey certprog'
     commands.

     `sfsagent' runs the program with the environment variable
     `SFS_AGENTSOCK' set to `-0' and a Unix domain socket on standard
     input.  Thus, when atomically killing and restarting the agent
     using `-k', the commands run by `sfsagent' talk to the new agent
     and not the old.

     If you don't wish to run any program at all when starting
     `sfsagent', simply supply the `-c' option with no PROG.  This will
     start an new agent that has no private keys.


File: sfs.info,  Node: sfskey,  Next: rex,  Prev: sfsagent,  Up: Command reference

`sfskey' reference guide
========================

   The `sfskey' command performs a variety of key management tasks,
from generating and updating keys to controlling users' SFS agents.  The
general usage for `sfskey' is:

     sfskey [-S SOCK] [-p PWFD] COMMAND [ARG ...]

`-S' specifies a UNIX domain socket `sfskey' can use to communicate
with your `sfsagent' socket.  If SOCK begins with `-', the remainder is
interpreted as a file descriptor number.  The default is to use the
environment variable `SFS_AGENTSOCK' if that exists.  If not, `sfskey'
asks the file system for a connection to the agent.

   The `-p' option specifies a file descriptor from which `sfskey'
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 `sfskey'.  For operations that need multiple
passphrases, you must specify the `-p' option multiple times, once for
each passphrase.

   In SFS 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 SRP.  Unlike Rabin
keys, 2-Schnorr keys can fail to load when a signature server becomes
unavailable.  For this reason, `sfskey' 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, `sfskey' 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 `sfskey'
commands--`sfskey 2gen' and `sfskey 2edit'.

   As of SFS 0.7, there is a new convention for saving and naming
private keys.  By default, keys will be stored locally in
`$HOME/.sfs/authkeys', and will be in the following forms:

         USER@HOST1#N
         USER@HOST1#N,P.HOST2,M

   The first form is for standard Rabin keys.  The second is for
2-Schnorr proactive signature keys.  In the above examples, HOST1 is the
the full hostname of the generating host, N is the public key version,
P is the priority of the signing host (1 is the highest) HOST2 is the
full hostname of the signing host, and M is the private key version.

   In general, these details can remain hidden, in that the symbolic
link `$HOME/.sfs/identity' points to the most recent key generated in
`$HOME/.sfs/authkeys', and most `sfskey' commands have reasonable
defaults.  However, there is a command-line system for accessing and
generating specific keys.  A blank keyname and the special keyname `#'
refer to the default key `$HOME/.sfs/identity' during key access and
the next available key during key generation.  Keynames containing a
`#' character but not containing a `/' character are assumed to refer
to keys in the `$HOME/.sfs/authkeys' directory.  When given files of the
form `PREFIX#', `sfskey' looks in the default directory for the most
recent key with the given PREFIX during key access, and the next
available key with the given PREFIX during key generation.  For keys of
the form `NAME#SUFFIX', `sfskey' will look in the `$HOME/.sfs/authkeys'
directory for keys that match the given name exactly. `sfskey' treats
keys with `/' characters as regular files; it treats keys that contain
`@' characters but no `#' characters as keys stored on remote machines.

   Finally, one should note that SFS keys have both a KEYNAME and also
a KEYLABEL.  `sfskey' uses the former to retrieve keys from the local
file system or from remote servers.  The latter is less important; the
KEYLABEL is stored internally in the private key, and is shown in the
output of the `sfskey list' command.

`sfskey add [-t [hrs:]min] [KEYNAME]'
`sfskey add [-t [hrs:]min] [USER]@HOSTNAME'
     The `add' 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 `-t' option specifies
     a timeout after which the agent should forget the private key.

     In the first form of the command, the key indicated by KEYNAME is
     loaded.  If KEYNAME is omitted, or # is supplied, then the default
     key is `$HOME/.sfs/identity'. If the key supplied is a 2-Schnorr
     key, then `sfskey add' will attempt to load backup keys should the
     primary key fail due to an unavailable signature server.

     The second form of the command fetches a private key over the
     network using the SRP (http://srp.stanford.edu/) protocol.  SRP
     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).  SRP
     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.

     The `sfskey update', `sfskey register', `sfskey 2gen' and `sfskey
     2edit' commands let users store their private keys on servers, and
     retrieve them using the `add' command.  The private key is stored
     in encrypted form, using the same password as the SRP protocol (a
     safe design as the server never sees any password-equivalent data).

     Because the second form of `sfskey add' establishes a secure
     connection to a server, it also downloads the servers HostID
     securely and creates a symbolic link from `/sfs/'HOSTNAME to the
     server's self-certifying pathname.

     When invoking `sfskey add' with the SRP syntax, `sfskey' will ask
     for the user's password with a prompt of the following form:

          Passphrase for USER@SERVERNAME/NBITS:

     USER is simply the username of the key being fetched from the
     server.  SERVERNAME is the name of the server on which the user
     registerd his SRP information.  It may not be the same as the
     HOSTNAME argument to `sfskey' if the user has supplied a hostname
     alias (or CNAME) to `sfskey add'.  Finally, NBITS is the size of
     the prime number used in the SRP protocol.  Higher values are more
     secure; 1,024 bits should be adequate.  However, users should
     expect always to see the same value for NBITS (otherwise, someone
     may be trying to impersonate the server).

`sfskey certclear'
     Clears the list of certification programs the agent runs.  *Note
     certprog::, for more details on certification programs.

`sfskey certlist [-q]'
     Prints the list of certification programs the agent runs.  *Note
     certprog::, for more details on certification programs.

`sfskey certprog [-p PREFIX] [-f FILTER] [-e EXCLUDE] PROG [ARG ...]'
     The `certprog' command registers a command to be run to lookup
     HOSTIDs on the fly in the `/sfs' directory.  This mechanism can be
     used for "dynamic server authentication"--running code to lookup
     HOSTIDs on-demand.  When you reference the file
     `/sfs/PREFIX/NAME', your agent will run the command:

          PROG ARG ... NAME

     If the program succeeds and prints DEST to its standard output,
     the agent will then create a symbolic link:

          /sfs/PREFIX/NAME -> DEST

     The `-p' flag can be omitted, and the link is `/sfs/NAME -> DEST'.
     PREFIX can be more than one directory deep (i.e., a series of
     path components separated by `/').  If so, the first certification
     program whose prefix matches at the beginning of PREFIX is run.
     The remaining path components are passed to PROG.  For example:

          NEED EXAMPLE

     FILTER is a perl-style regular expression.  If it is specified,
     then NAME must contain it for the agent to run PROG.  EXCLUDE is
     another regular expression, which, if specified, prevents the
     agent from running PROG on NAMEs that contain it (regardless of
     FILTER).

     The program `dirsearch' can be used with `certprog' to configure
     "certification paths"--lists of directories in which to look for
     symbolic links to HOSTIDs.  The usage is:

          dirsearch [-clpq] DIR1 [DIR2 ...] NAME

     `dirsearch' searches through a list of directories DIR1, DIR2, ...
     until it finds one containing a file called NAME, then prints the
     pathname `DIR/NAME'.  If it does not find a file, `dirsearch'
     exits with a non-zero exit code.  The following options affect
     `dirsearch''s behavior:

    `-c'
          Print the contents of the file to standard output, instead of
          its pathname.

    `-l'
          Require that `DIR/NAME' be a symbolic link, and print the
          path of the link's destination, rather than the path of the
          link itself.

    `-p'
          Print the path `DIR/NAME'.  This is the default behavior
          anyway, so the option `-p' has no effect.

    `-q'
          Do not print anything.  Exit abnormally if NAME is not found
          in any of the directories.

     As an example, to lookup self-certifying pathnames in the
     directories `$HOME/.sfs/known_hosts' and `/mit', but only
     accepting links in `/mit' with names ending `.mit.edu', you might
     execute the following commands:

          % sfskey certprog dirsearch $HOME/.sfs/known_hosts
          % sfskey certprog -f '\.mit\.edu$' /mnt/links

`sfskey delete KEYNAME'
     Deletes private key KEYNAME from the agent (reversing the effect
     of an `add' command).

`sfskey deleteall'
     Deletes all private keys from the agent.

`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 SRP and store it
     in a file.

     KEYNAME can be a file name, or it can be of the form
     `[USER]@SERVER', in which case `sfskey' will fetch the key
     remotely and OUTFILE must be specified.  If KEYNAME is unspecified
     the default is `$HOME/.sfs/identity'.  If KEYNAME is `#', then
     `sfskey edit' will search for the next appropraite keyname in
     `$HOME/.sfs/authkeys'.  In this case, `sfskey edit' will update
     `$HOME/.sfs/identity' to point to this new key by default.

     The options are:

    `-L'
          Does not set symlink in the case that KEYNAME is `#'.

    `-P'
          Removes any password from the key, so that the password is
          stored on disk in unencrypted form.

    `-o KEYNAME'
          Specifies the file to which the edited key should be written.
          A KEYNAME of `#' implies that `sfskey edit' should generate
          the next availabe default key in `$HOME/.sfs/authkeys'.  A
          KEYNAME of ther form `PREFIX#' implies that `sfskey edit'
          should generate the next available key in
          `$HOME/.sfs/authkeys' with the prefix PREFIX.  A KEYNAME of
          the form `PREFIX#SUFFIX' implies that `sfskey edit' should
          make a key named `$HOME/.sfs/authkeys/PREFIX#SUFFIX'.

    `-c COST'
          Override the default computational cost of processing a
          password, or `PwdCost', *Note pwdcost::.

    `-l LABEL'
          Specifies the label of the key that shows up in `sfskey list'.

`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.

     Use `sfskey 2edit' by supplying the keys that you wish to have
     updated.  Keynames are given in standard `sfskey' style.  Keynames
     must be either remote keynames (i.e., contain a `@' but no `#'
     character) or stored in the standard keys directory (i.e., contain
     a `#' but no `/' character).  For remote keys, SRP 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 `$HOME/.sfs/authkeys', `sfskey 2edit' will update
     the server private keyhalf, and write the corresponding client
     private keyhalf out to `$HOME/.sfs/authkeys' under a new filename.
     By default, `sfskey 2edit' will also write the new encrypted
     client private keyhalf back to the server for later SRP retrieval.

     If no key is specified, the default key, `$HOME/.sfs/identity' is
     assumed.

    `-E'
          Do not update the encrypted private client key stored on the
          server.

    `-S'
          Do not update SRP information on the server.  This option
          cannot be used if some of the keynames specified are for
          remote keys.

    `-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 `sfskey 2edit -m', with no additional arguments or
          keynames, `sfskey' will refresh all current default keys.

    `-p'
          Change password before writing keys out to disk or server.

    `-l LABEL'
          Specifies the label of the key that shows up in `sfskey list'.

    `-s SRPFILE'
          Get SRP parameters from the file SRPFILE.

`sfskey gen [-KP] [-b NBITS] [-c COST] [-l LABEL] [KEYNAME]'
     Generates a new Rabin public/private key pair and stores it in
     KEYNAME.  It omitted KEYNAME defaults to the next available Rabin
     key in `$HOME/.sfs/authkeys'.  If KEYNAME contains a `/'
     character, it will be treated as a regular Unix file.  If KEYNAME
     is of the form `PREFIX#', `sfskey gen' will look for the next
     avaible Rabin key in `$HOME/.sfs/authkeys' with the prefix PREFIX.
     If KEYNAME contains a non-termainl `#' character, it will be
     treated as a fully-specified keyname to be saved in
     `$HOME/.sfs/authkeys'.

     Note that `sfskey gen' is only useful for generating Rabin keys.
     Use either `sfskey register' or `sfskey 2gen' to generate
     2-Schnorr keys.

    `-K'
          By default, `sfskey gen' asks the user to type random text
          with which to seed the random number generator.  The `-K'
          option suppresses that behavior.

    `-P'
          Specifies that `sfskey gen' should not ask for a passphrase
          and the new key should be written to disk in unencrypted form.

    `-b NBITS'
          Specifies that the public key should be NBITS long.

    `-c COST'
          Override the default computational cost of processing a
          password, or `PwdCost', *Note pwdcost::.

    `-l LABEL'
          Specifies the label of the key that shows up in `sfskey list'.
          Otherwise, the user will be prompted for a name.

`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 `-a' flag.  All keypairs will correspond to the
     same public key.  The new keys will be saved locally to the files
     given by NKEYNAME in the usual fashion: if NKEYNAME is of the form
     PREFIX#, then `sfskey 2gen' will look for the next available
     2-Schnorr key in `$HOME/.sfs/authkeys' with the prefix PREFIX.  If
     no NKEYNAME is given, it will find the next available keyname in
     `$HOME/.sfs.authkeys' with the default prefix (USER@HOST).

     Note that by default, this operation will update the public key,
     the encrypted private key, the SRP information, and the server
     private key share on all of the servers given.  Specify `-BES' to
     suppress updates of these fields.

    `-a -'

    `-a HOSTID'
          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 SRP is used to download a key from host HOST
          (e.g., `-k USER@HOST'), then you can specify that host by its
          simple hostname (e.g., `-a HOST').  If SRP was not used to
          connect to a host HOST, then `-a' requires a complete SFS
          host identifier (i.e., @LOCATION,HOSTID).

    `-B'
          Do not update the public key on the given servers.

    `-E'
          Do not update the encrypted private key field on the given
          servers.

    `-K'
    `-P'
    `-c COST'
    `-l LABEL'
    `-s SRPFILE'
          See `sfskey gen'.  These options behave similarly.

    `-S'
          Do not update the SRP information on the server.

    `-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.

    `-k KEYNAME'
          Specify this option arbitrarily many times to keys into
          memory for `sfskey'.  By default, all keys from
          `$HOME/.sfs/authkeys' 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.

    `-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
          CD-R, so that in a worst case scenario, the original key is
          still recoverable.

`sfskey help'
     Lists all of the various `sfskey' commands and their usage.

`sfskey hostid HOSTNAME'
`sfskey hostid -'
     Retrieves a self-certifying pathname insecurely over the network
     and prints `@LOCATION,HOSTID' to standard output.  If HOSTNAME is
     simply `-', returns the name of the current machine, which is not
     insecure.

    `-s SERVICE'
          The default service is file service, `sfs' (except when using
          `-').  This option selects a different SFS service.  Possible
          values for SERVICE are `sfs', `authserv', and `rex'.

`sfskey kill'
     Kill the agent.

`sfskey list [-ql]'
     List the public keys whose private halves the the agent holds.

    `-q'
          Suppresses the banner line explaining the output.

    `-l'
          Lists the actual value of public keys, in addition the the
          names of the keys.

`sfskey norevokeset HOSTID ...'

`sfskey norevokelist'

`sfskey passwd [-Kp] [-S | -s SRPFILE] [-b NBITS] [-c COST] [-l LABEL] [ARG1] [ARG2] ...'
     The `sfskey passwd' command is a high-level command for "changing
     passwords" in SFS.  In the case of proactive keys, `sfskey passwd'
     will simply refresh keys via `sfskey 2edit' functionality.  In the
     case of Rabin keys, `sfskey passwd' generates a new Rabin key and
     updates the given servers. By default, `sfskey passwd' assumes
     standard Rabin keys, and thus treats ARG-I as [USER][@]HOST
     arguments.  If HOST is a regular hostname, then SRP will be
     required to authenticate the host.  If HOST is a full SFS
     pathname, then `sfskey passwd' will look for keys in
     `$HOME/.sfs/authkeys' that can authenticate the user to that
     particular server.  In the case of proactive 2-Schnorr keys,
     `sfskey passwd' will treat ARG-I as local or remote keynames.

     If no options or arguments are given, `sfskey passwd' will look to
     the default key given by `$HOME/.sfs/identity'.  If the default key
     is a procative 2-Schnorr key, then all current 2-Schnorr keys in
     `.sfs/authkeys' are refreshed.  If the default key is a Rabin key,
     then the users key on the local machine is updated.

    `-p'
          Specifies proactive mode.  Will treat arguments ARG1 through
          ARG-N as keynames, whether local or remote.  By default,
          `sfskey passwd' operates under the assumption that the key to
          update is a Rabin key.

    `-K'
    `-S'
    `-s SRPFILE'
    `-b NBITS'
    `-c COST'
    `-l LABEL'
          These options are the same as for `sfskey gen'.  Briefly,
          `-S' turns of SRP, `-K' disables keyboard randomness query,
          `-s' is used to supply an SRP parameters file and is mutually
          exclusive with `-S', `-b' specifies the size of the key in
          bits, `-c' specifies the secret key encryption cost, and `-l'
          specifies the label for the key, as seen in `sfskey list'.

`sfskey register [-fgpPK] [-S | -s SRPFILE] [-b NBITS] [-c COST] [-u USER] [-l LABEL] [-w FILENAME] [KEYNAME]'
     The `sfskey register' command lets users who are logged into an
     SFS 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
     `sfskey update' or `sfskey 2gen'.  The superuser can also use
     `sfskey register' when creating accounts.

     KEYNAME is the private key to use.  If KEYNAME does not exist and
     is a pathname, `sfskey' will create it.  The default KEYNAME is
     `$HOME/.sfs/identity', unless `-u' 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 `#', `sfskey'
     will implicitly determine whether the user intends to generate or
     access a key.  If the command is invoked as root with the `-u'
     flag, then generation is assumed.  Similarly, if any of the
     options `-bcgp' are used, generation is assumed.  Otherwise,
     `sfskey' will first attempt to access the most recent key matching
     KEYNAME, and then will revert to generation if the access fails.

     If a user wishes to reuse a public key already registered with
     another server, the user can specify `USER@SERVER' for KEYNAME.

    `-f'
          Force reregistration.  Ordinarily, `sfskey gen' will fail if a
          record for the given user already exists on the server.

    `-g'
          Force key generation.  When using keynames of the form
          `PREFIX#', `sfskey register' will always generate then next
          available key with the prefix PREFX in the standard keys
          direcotry (`$HOME/.sfs/authkeys').  If `sfskey register' is
          being run as root with the `-u' option, then access to the
          standard keys directory `$HOME/.sfs/authkeys' will not be
          allowed.  Hence, the key will simply be generated in the
          current directory.

    `-p'
          Generate a new proctive 2-Schnorr key.  Implies the `-g' flag.

    `-K'
    `-P'
    `-l LABEL'
    `-b NBITS'
    `-c COST'
    `-s SRPFILE'
          These options are the same as for `sfskey gen'.  `-K' and
          `-b' have no effect if the key already exists.  They all
          imply the `-g' flag. If `-p' is given, then -B will specify
          the size of the modulus P used in 2-Schnorr.  Without `-p',
          `-b' will specify the size of PQ in Rabin.

    `-S'
          Do not register any SRP information with the server--this
          will prevent the user from using SRP 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.

    `-u USER'
          When `sfskey register' is run as root, specifies a particular
          user to register.

    `-w FILENAME'
          When generating a proactive key, saves the complete key out to
          the given file.  Will raise an error if supplied without the
          `-p' flag.  For security reasons, this should only be used
          when saving to removable media (e.g.,
          `/floppy/complete-key-2').  It is a susbstantial security
          risk to leave the complete key on a file system that might be
          compromised.

     `sfsauthd_config' must have a `Userfile' with the `-update' and
     `-passwd' options to enable use of the `sfskey register', *Note
     sfsauthd_config::.

`sfskey reset'
     Clear the contents of the `/sfs' directory, including all symbolic
     links created by `sfskey certprog' and `sfskey add', and log the
     user out of all file systems.

     Note that this is not the same as deleting private keys held by the
     agent (use `deleteall' 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.

`sfskey revokegen [-r NEWKEYFILE [-n NEWHOST]] [-o OLDHOST] OLDKEYFILE'

`sfskey revokelist'

`sfskey revokeclear'

`sfskey revokeprog [-b [-f FILTER] [-e EXCLUDE]] PROG [ARG ...]'

`sfskey select [-f] KEYNAME'
     Select the given key as the default key; set `$HOME/.sfs/identity'
     to point to the key given by KEYNAME.  It cannot be an SRP key.

    `-f'
          Force overwrite.  If current `$HOME/.sfs/identity' is a
          regular file, `sfskey select' will overwrite it.

`sfskey sesskill REMOTEHOST'
     Kill the `rex' session to the server specified by REMOTEHOST,
     where REMOTEHOST is any unique prefix of the remote host's
     self-certifying hostname (found under the "TO" column in the
     output to `sfskey sesslist').

`sfskey sesslist'
     List the `rex' sessions that the agent is maintaining.

`sfskey srpgen [-b NBITS] file'
     Generate a new `sfs_srp_params' file, *Note sfs_srp_params::.

`sfskey update [-fE] [-S | -s SRP_PARAMS] [-r SRPKEY] [-a OKEYNAME] [-k NKEYNAME] SERVER1 SERVER2 ...'
     Change a user's public key and SRP information on an SFS file
     server.  To change public keys, typically you should generate a
     new public key and store it in `$HOME/.sfs/identity'.  Then you
     can run `sfskey update [USER]@HOST' for each server on which you
     need to change your public key.

     To authenticate you to the servers on which updates are requested,
     `sfskey update' will first use the keys given via `-a' arguments;
     it will then search keys in the standard key
     directory--`$HOME/.sfs/authkeys'.

     At least one SERVER argument is required.  As usual, the string
     "-" denotes the localhost. The servers specified can be either
     full SFS hostnames of the form [USER]@LOCATION,HOSTID, or standard
     hostnames of the form [USER@]LOCATION.  In the latter case, SRP is
     assumed, and the corresponding private key is automatically loaded
     into `sfskey'.

     The new key that is being pushed to the server is given by the
     `-k' flag.  If this is not provided, the default key
     `$HOME/.sfs/identity' will be assumed.

     The `-r' provides a shortcut for updating SRP information, if, for
     instance, the auth server has changed its realm information.
     Invoking `sfskey update `-r' [USER]@HOST' is equivalent to `sfskey
     update -k [USER]@HOST HOST'.

     Several options control `sfskey update''s behavior:

    `-E'
          Do not send encrypted secret key information to the server.

    `-S'
          Do not send SRP information to the server--this will prevent
          the user from using SRP 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 `-E'

    `-a OKEYNAME'
          This arugment can be supplied arbitrarily many times, once
          for each key that should be loaded into `sfskey' 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
          (`$HOME/.sfs/authkeys') as they are considered automatically.

    `-f'
          If there is a change in SRP realm information, the `-f' flag
          will force an update.  Normally, the user is prompted to
          verify.

    `-k NKEYNAME'
          Specifies the new key to push to the server. Can be an SRP
          key, a local file, or a keyname with a '#' sign, signifyin a
          key stored in the keys directory, `$HOME/.sfs/authkeys'. If
          this flag is not specified, `$HOME/.sfs/identity' is assumed.
          Note that the `-k' flag can be specified only once.

    `-r [USER][@]HOST'
          Update SRP information of a key on a remote host. Equivalent
          to `sfskey update -a HOST [USER]@HOST'.  Cannot be used with
          the `-akS' options.

    `-s'
          SRP_PARAMS is the path of a file generated by `sfskey
          srpgen', and specifies the parameters to use in generating SRP
          information for the server.  The default is to get SRP
          parameters from the server, or look in
          `/usr/local/share/sfs/sfs_srp_params'.


File: sfs.info,  Node: rex,  Next: dirsearch,  Prev: sfskey,  Up: Command reference

`rex' reference guide
=====================

   `rex' is a remote execution facility which is integrated with SFS.
The program allows users run to run programs on a remote machine or
obtain a shell.  Like SFS file systems, remote execution servers can be
named by self-certifying path names.

The usage is as follows:

     rex [-TAXpv] [-R PORT:LPORT] DESTINATION [COMMAND]

DESTINATION is one of the following:
   * a self-certifying hostname (location:hostid)

   * a self-certifying pathname (/sfs/... or /symlink-to-sfs/...)

   * any identifier which when processed through certification programs
     will yield a self-certifying pathname

`-T'
     Disable pseudo-tty allocation.

`-A'
     Disable SFS agent forwarding.  By default, if there is no
     `sfsagent' running on the remote machine, `rex' will forward agent
     requests back the `sfsagent' running on the local machine (e.g.,
     when a user accesses an SFS file system or runs `sfskey').

`-X'
     Disable X forwarding.  By default, the `rex' client will set up a
     dummy X server which receives connections from clients on the
     remote machine.  These connections are forwarded over the encrypted
     `rex' channel to the local X server.  `rex' sets the `DISPLAY'
     environment variable appropriately on the remote side.
     Furthermore, X connections are authenticated using a `spoofed'
     MIT-MAGIC-COOKIE-1.

`-p'
     Force `rex' to connect to the DESTINATION even if it cannot be
     resolved into a valid self-certifying path name.

`-v'
     Verbose mode.

`-R PORT:LPORT'
     Forward TCP connections made to PORT on the remote host to LPORT
     on the local machine.

   The `rex' command supports the escape sequences listed below.  Rex
only recognizes the escape character `~' after a newline.
   * . terminate connection

   * ^Z suspend connection

   * ? help message

   * ~ send the escape character


File: sfs.info,  Node: dirsearch,  Next: newaid,  Prev: rex,  Up: Command reference

`dirsearch' command
===================

   `dirsearch' looks for a file name in one or more directories.  The
usage is as follows:

     dirsearch [-c | -l | -p | -q] DIR1 [DIR2 ...] NAME

   Starting with DIR1, the command searches each directory specified
for a file called NAME.  If such a file is found, `dirsearch' exits
with code 0 and, depending on its options, may print the file's
pathname, contents, or expanded symbolic link contents.  If none of the
directories specified contain a file NAME, `dirsearch' exits with code
1 and prints no output.

   `dirsearch' is particularly useful for SFS certificaton *note
certprog:: and revocation programs.  As an example, suppose you have a
directory of symbolic links in your home directory called
`.sfs/bookmarks'.  The directory might contain the following links:
     sfs.fs.net -> /sfs/@sfs.fs.net,uzwadtctbjb3dg596waiyru8cx5kb4an
     sfs.nyu.edu -> /sfs/@sfs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz

If you execute the command:
     sfskey certprog dirsearch -l ~/.sfs/bookmarks

Then the next time you access `/sfs/sfs.fs.net', that pathname will
automaticlaly become a symbolic link to your bookmark.  Moreover, the
same will happen on remote machines to which you log in with the `rex'
command.

   The following mutually exclusive options affect the behavior of
`dirsearch'.  If more than one option is specified, only the last will
have an effect.

`-c'
     This option prints the contents of the file when it is found,
     instead of its pathname.

`-l'
     This option looks for symbolic links.  The file NAME will be
     ignored if it is not a symbolic link.  Furthermore, in its output
     `dirsearch' will expand the symbolic link.

`-p'
     This option says to print the pathname, which is the default
     anyway.  Thus, the only effect of `-p' is to undo any previous
     `-c', `-l', or `-q' option.

`-q'
     This option suppresses any output `dirsearch' would print.  The
     exit code still indicates whether or not the file exists.


File: sfs.info,  Node: newaid,  Next: ssu,  Prev: dirsearch,  Up: Command reference

`newaid' command
================

   The `newaid' command allows root-owned processes to access SFS file
systems using the `sfsagent' of a non-root user.  Additionally, if a
system is configured to allow this, `newaid' permits non-root users to
run multiple `sfsagent' processes, so that different processes owned by
that user access the SFS file system with different agents.  (When used
in The latter mode, `newaid' is similar in function to the AFS program
`pagsh'.)

   SFS maps file system requests to particular `sfsagent' processes
using the notion of agent ID, or "aid".  Every process has a 64-bit aid
associated with it.  Ordinarily, a process's aid is simply its 32-bit
user ID.  Thus, when a user runs `sfsagent', both the agent and all of
the users' processes have the same aid.

   To allow different processes owned by the same user to have different
agents, a system administrator can reserve a range of group IDs for the
purpose of flagging different aids, *Note resvgids::.  (Note that after
changing `ResvGids', you must kill and restart `sfscd' for things to
work properly.)  If the range of reserved group IDs is MIN..MAX, and
the _first_ element of a process's grouplist, G0 is at least MIN and
not more than MAX, then a process's aid is computed as ((G0 - MIN + 1)
<< 32) | UID).  The `newaid' command therefore lets people insert any
of the reserved group IDs at the start of a process's group list.

   For root-owned processes, it is also possible for processes to be
associated with a non-root agent.  In this case, the reserved SFS-GROUP
(as a marker) and target user's uid are actually placed in the
process's grouplist, as well as any reserved group ID to select amongst
multiple agents of the same user.

   The usage is:

     newaid [-l] [-{u|U} UID] [-G | -g GID] [-C DIR] [PROGRAM ARG ...]

   After making appropriate changes to its user ID and/or grouplists,
`newaid' executes the PROGRAM specified on the command line.  If no
PROGRAM is specified, the program specified by the environment variable
`SHELL' is used by default.

`-l'
     Run the command as a login shell.  This argument simply prepends a
     `-' character to `argv[0]' when executing PROGRAM.  Command shells
     interpret this to mean that they are being being run a login
     shells, and usually exhibit slightly different behavior.  (For
     example `csh' will execute the commands in a user's `.login' file.)

`-u UID'
     For root-owned process, specifies that the PROGRAM should be run
     as root, but should be associated with the non-root agent of user
     UID.

`-U UID'
     When `newaid' is invoked by a root-owned processes, this option
     sets the real uid to UID to run PROGRAM, instead of running it
     with uid 0.  This is in itself is not sufficient to "drop
     privileges."  In particular, `newaid' still does not make any
     changes to the process gid or grouplist, beyond manipulating
     aid-specific groups.  Since many root-owned processes also have
     privileged groups in their grouplist, it is in general *insecure*
     to use `-U' unless you set the both the gid and the whole
     grouplist to something sensible (i.e., appropriately unprivileged)
     before invoking `newaid'.

     This option is mostly of use for `login'-like programs that wish
     to create a session with a new aid, and do not wish to make the
     `setuid' system call themselves for fear the the operating
     system's `ptrace' system call is broken and would create s
     security hole.

`-g GID'
`-G'
     By default `newaid' simply picks the first aid under which no
     agent is yet running.  The `-g' option explicitly specifies that
     GID should be added to the start of the process's group list (and
     any previous reserved gid should be removed).  `-G' says to remove
     any reserved gid, so that the aid of the resulting process will
     just be the user's uid.

`-C DIR'
     Changes directory to DIR before running PROGRAM.


File: sfs.info,  Node: ssu,  Next: sfscd,  Prev: newaid,  Up: Command reference

`ssu' command
=============

   The `ssu' command allows an unprivileged user to become root on the
local machine without changing his SFS credentials.  `ssu' invokes the
command `su' to become root.  Thus, the access and password checks
needed to become root are identical to those of the local operating
system's `su' command.  `ssu' also runs
`/usr/local/lib/sfs-0.7.2/newaid' to alter the group list so that SFS
can recognize the root shell as belonging to the original user.

   The usage is as follows:

     ssu [-f | -m | -l | -c COMMAND]

`-f'
`-m'
     These options are passed through to the `su' command.

`-l'
     This option causes the newly spawned root shell to behave like a
     login shell.

`-c COMMAND'
     Tells `ssu' to tell `su' to run COMMAND rather than running a
     shell.

   Note, `ssu' does not work on some versions of Linux because of a bug
in Linux.  To see if this bug is present, run the command `su root -c
ps'.  If this command stops with a signal, your `su' command is broken
and you cannot use `ssu'.


File: sfs.info,  Node: sfscd,  Next: sfssd,  Prev: ssu,  Up: Command reference

`sfscd' command
===============

     sfscd [-d] [-l] [-L] [-f CONFIG-FILE]

   `sfscd' is the program to create and serve the `/sfs' directory on a
client machine.  Ordinarily, you should not need to configure `sfscd'
or give it any command-line options.

`-d'
     Stay in the foreground and print messages to standard error rather
     than redirecting them to the system log.

`-l'
     Ordinarily, `sfscd' will disallow access to a server running on
     the same host.  If the LOCATION in a self-certifying pathname
     resolves to an IP address of the local machine, any accesses to
     that pathname will fail with the error `EDEADLK' ("Resource
     deadlock avoided").

     The reason for this behavior is that SFS is implemented using NFS.
     Many operating systems can deadlock when there is a cycle in the
     mount graph--in other words when two machines NFS mount each
     other, or, more importantly when a machine NFS mounts itself.  To
     allow a machine to mount itself, you can run `sfscd' with the `-l'
     flag.  This may in fact work fine and not cause deadlock on
     non-BSD systems.

`-L'
     On Linux, the `-L' option disables a number of kludges that work
     around bugs in the kernel.  `-L' is useful for people interested
     in improving Linux's NFS support.

`-f CONFIG-FILE'
     Specify an alternate `sfscd' configuration file, *Note
     sfscd_config::.  The default, if `-f' is unspecified, is first to
     look for `/etc/sfs/sfscd_config', then
     `/usr/local/share/sfs/sfscd_config'.


File: sfs.info,  Node: sfssd,  Next: vidb,  Prev: sfscd,  Up: Command reference

`sfssd' command
===============

     sfssd [-d] [-S SFS-CONFIG-FILE] [-f CONFIG-FILE]

   `sfssd' is the main server daemon run on SFS servers.  `sfssd'
itself does not serve any file systems.  Rather, it acts as a
meta-server, accepting connections on TCP port 4 and passing them off
to the appropriate daemon.  Ordinarily, `sfssd' passes all file system
connections to `sfsrwsd', and all user-key management connections to
`sfsauthd'.  However, the `sfssd_config' file (*note sfssd_config::)
allows a great deal of customization, including support for "virtual
servers," multiple versions of the SFS software coexisting, and new
SFS-related services other than the file system and user authentication.

`-d'
     Stay in the foreground and print messages to standard error rather
     than redirecting them to the system log.

`-f CONFIG-FILE'
     Specify an alternate `sfssd' configuration file, *Note
     sfssd_config::.  The default, if `-f' is unspecified, is first to
     look for `/etc/sfs/sfssd_config', then
     `/usr/local/share/sfs/sfssd_config'.

`-S SFS-CONFIG-FILE'
     Specify an alternate name for the `sfs_config' file, *Note
     sfssd_config::.  If SFS-CONFIG-FILE begins with a `/', then only
     this file is parsed.  Otherwise, all the directories
     `/usr/local/share/sfs' and `/etc/sfs' are searched in order, and
     if no file named SFS-CONFIG-FILE is found but a file `sfs_config'
     is found, that file is parsed.  However, the process does not look
     in `/etc/sfs' if SFS-CONFIG-FILE is found in /USR/LOCAL/SHARE/SFS.
     Thus, if you create a file `/etc/sfs/'SFS-CONFIG-FILE, it will
     override `/etc/sfs/sfs_config' while still incorporating the
     defaults from /USR/LOCAL/SHARE/SFS/SFS_CONFIG.

