This is sfs.info, produced by makeinfo version 4.6 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: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

SFS
***

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

   This document applies to version 0.7.2 of the SFS distribution.

* Menu:

* Overview::                    Introduction to SFS
* Installation::                Building and installing the SFS software
* Getting Started::             Play with SFS as quickly as possible
* System overview::             High-level overview of SFS's components
* SFS configuration::           SFS configuration files
* Command reference::           Command usage reference guide
* Security::                    Security implications of running SFS
* Contacts::                    How to contact the authors, report bugs
* Concept Index::               Index of concepts

 --- The Detailed Node Listing ---

Installation

* Requirements::                Requirements for building and running SFS
* Building::                    How to build and install the SFS distribution
* Build Problems::              Common problems compiling the source

Getting Started

* Quick client setup::          How to set up an SFS client
* Quick server setup::          How to set up an SFS server
* Quick user setup::            How to get started as an SFS user

SFS configuration files

* `sfs_config'::           System-wide configuration parameters
* `sfsrwsd_config'::       File server configuration
* `sfsauthd_config'::      User-authentication daemon configuration
* `sfs_users'::            User-authentication database
* `sfssd_config'::         Meta-server configuration
* `sfs_srp_params'::       Default parameters for SRP protocol
* `sfscd_config'::         Meta-client configuration

Command reference guide

* 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

Security considerations

* new vulnerabilities::         Vulnerabilities created by SFS
* exposed vulnerabilities::     Vulnerabilities exploitable because of SFS
* implementation vulnerabilities::  Vulnerabilities in the SFS implementation


File: sfs.info,  Node: Overview,  Next: Installation,  Prev: Top,  Up: Top

Introduction
************

SFS is a network file system that lets you access your files from
anywhere and share them with anyone anywhere.  SFS was designed with
three goals in mind:

   * *Security.*  SFS assumes that malicious parties entirely control
     the network.  It ensures that control of the network only lets them
     delay the file system's operation or conceal the existence of
     servers until reliable network communication is reestablished.

   * *A global namespace.*  SFS mounts all remote file systems under
     the directory `/sfs'.  The contents of that directory is identical
     on every client in the world.  Clients have no notion of
     administrative realm and no site-specific configuration options.
     Servers grant access to users, not to clients.  Thus, users can
     access their files wherever they go, from any machine they trust
     that runs the SFS client software.

   * *Decentralized control.*  SFS does not rely on any privileged
     authority to manage the global namespace.  Anyone with a machine
     on the Internet can set up an SFS file server without needing to
     obtain any kind of certificates.  New servers are instantly
     accessible from all clients in the world.

   SFS achieves these goals by separating key management from file
system security.  It names file systems by the equivalent of their
public keys.  Every remote file server is mounted under a directory of
the form:

     /sfs/@LOCATION,HOSTID

   or:

     /sfs/@LOCATION%PORT,HOSTID

LOCATION is a DNS hostname or an IP address.  HOSTID is a
collision-resistant cryptographic hash of the file server's public key.
PORT is an optional TCP port number (the default is 4).  This naming
scheme lets an SFS client authenticate a server given only a file name,
freeing the client from any reliance on external key management
mechanisms.  SFS calls the directories on which it mounts file servers
"self-certifying pathnames".

   Self-certifying pathnames let users authenticate servers through a
number of different techniques.  As a secure, global file system, SFS
itself provides a convenient key management infrastructure.  Symbolic
links let the file namespace double as a key certification namespace.
Thus, users can realize many key management schemes using only standard
file utilities.  Moreover, self-certifying pathnames let people
bootstrap one key management mechanism using another, making SFS far
more versatile than any file system with built-in key management.

   Through a modular implementation, SFS also pushes user authentication
out of the file system.  Untrusted user processes transparently
authenticate users to remote file servers as needed, using protocols
opaque to the file system itself.

   Finally, SFS separates key revocation from key distribution.  Thus,
the flexibility SFS provides in key management in no way hinders
recovery from compromised keys.

   No caffeine was used in the original production of the SFS software.


File: sfs.info,  Node: Installation,  Next: Getting Started,  Prev: Overview,  Up: Top

Installation
************

This section describes how to build and install the SFS on your system.
If you are too impatient to read the details, be aware of the two most
important points:

   * You must create an `sfs' user and an `sfs' group on your system.
     *Note --with-sfsuser::, to use a name other than `sfs'.

   * You must use gcc version 2.95.2 or later to compile SFS.

* Menu:

* Requirements::                Requirements for building and running SFS
* Building::                    How to build and install the SFS distribution
* Build Problems::              Common problems compiling the source


File: sfs.info,  Node: Requirements,  Next: Building,  Prev: Installation,  Up: Installation

Requirements
============

SFS should run with minimal porting on any system that has solid NFS3
support.  We have run SFS successfully on OpenBSD, FreeBSD, Linux,
OSF/1 4.0, and Solaris 5.7.

   In order to compile SFS, you will need the following:

  1. gcc-2.95.2 or more recent.  You can obtain this from
     `ftp://ftp.gnu.org/pub/gnu/gcc'.  Don't waste your time trying to
     compile SFS with an earlier version of gcc.

  2. gmp-2.0.2 or more recent.  You can obtain this from
     `ftp://ftp.gnu.org/pub/gnu/gmp'.  Many operating systems already
     ship with gmp.  Note, however, that some Linux distributions do
     not include the `gmp.h' header file.  Even if you have libgmp.so,
     if you don't have /usr/include/gmp.h, you need to install gmp on
     your system.  Note that more recent versions (4.0 and above) allow
     SFS to run significantly faster than it did with previous ones.

  3. Header files in `/usr/include' that match the kernel you are
     running.  Particularly on Linux where the kernel and user-land
     utilities are separately maintained, it is easy to patch the
     kernel without installing the correspondingly patched system
     header files in `/usr/include'.  SFS needs to see the patched
     header files to compile properly.

  4. 128 MB of RAM.  The C++ compiler really needs a lot of memory.

  5. 550 MB of free disk space to build SFS.  (Note that on ELF
     targets, you may be able to get away with considerably less.  A
     build tree on FreeBSD only consumes about 200 MB.)


File: sfs.info,  Node: Building,  Next: Build Problems,  Prev: Requirements,  Up: Installation

Building SFS
============

Once you have setup your system as described in *Note Requirements::,
you are ready to build SFS.

  1. Create a user, SFS-USER, and group, SFS-GROUP, for SFS on your
     system.  By default, SFS expects the both SFS-USER and SFS-GROUP
     to be called `sfs'.  For instance, you might add the following
     line to `/etc/passwd':

          sfs:*:71:71:Self-certifying file system:/:/bin/true

     And the following line to `/etc/group':

          sfs:*:71:

     Do not put any users in SFS-GROUP, not even `root'.  Any user in
     SFS-GROUP will not be able to make regular use of the SFS file
     system.  Moreover, having any unprivileged users in SFS-GROUP
     causes a security hole.

  2. Unpack the SFS sources.  For instance, run the commands:

          % gzip -dc sfs-0.7.2.tar.gz | tar xvf -
          % cd sfs-0.7.2

     If you determined that you need gmp (*note Requirements::), you
     should unpack gmp into the top-level of the SFS source tree:

          % gzip -dc ../gmp-2.0.2.tar.gz | tar xvf -

  3. Set your `CC' and `CXX' environment variables to point to the C
     and C++ compilers you wish to use to compile SFS. Some operating
     systems do not come with a recent enough version of gcc *Note
     Requirements::.

  4. Configure the sources for your system with the command
     `./configure'.  You may additionally specify the following options:

    `--with-sfsuser=SFS-USER'
          If the user you created for SFS is not called `sfs'.  Do not
          use an existing account for SFS-USER--even a trusted
          account--as processes running with that user ID will not be
          able to access SFS.  [Note:  If you later change your mind
          about USER-NAME, you do not need to recompile SFS, *Note
          sfs_config::.]

    `--with-sfsgroup=SFS-GROUP'
          If the user you created for SFS does not have the same name as
          SFS-USER.  [Note:  If you later change your mind about
          SFS-GROUP, you do not need to recompile SFS.]

    `--with-gmp=GMP-PATH'
          To specify where `configure' should look for gmp (for example,
          GMP-PATH might be `/usr/local').  Note, if you unpacked gmp
          into a subdirectory of the SFS source code, you do not need
          to specify this option.  `configure' should notice the
          directory and compile gmp automatically.

    `--with-sfsdir=SFSDIR'
          To specify a location for SFS to put its working files.  The
          default is `/var/sfs'.  [You can change this later, *Note
          sfs_config::.]

    `--with-etcdir=ETCDIR'
          To specify where SFS should search for host-specific
          configuration files.  The default is `/etc/sfs'.

    `--datadir=DATADIR'
          Where SFS places its data files.  The default is
          `/usr/local/share'.

     `configure' accepts all the traditional GNU configuration options
     such as `--prefix'.  It also has several options that are only for
     developers.  *Do not use the `--enable-repo' or `--enable-shlib'
     options* (unless you are a gcc maintainer looking for some wicked
     test cases for your compiler).  Also, *Do not use the
     `--with-openssl' option*-it is only for use by the developers in
     compiling some benchmark code that is not part of the release.

  5. Build the sources by running `make'. Note that a GNU-comptabile
     `make' may be required to build SFS.

  6. Install the binaries by running `make install'.  If you are short
     on disk space, you can alternatively install stripped binaries by
     running `make install-strip'.

  7. That's it.  Fire up the client daemon by running `sfscd'.


File: sfs.info,  Node: Build Problems,  Prev: Building,  Up: Installation

Problems building SFS
=====================

The most common problem you will encounter is an internal compiler error
from gcc.  If you are not running gcc-2.95.2 or later, you will very
likely experience internal compiler errors when building SFS and need to
upgrade the compiler.  You must `make clean' after upgrading the
compiler.  You cannot link object files together if they have been
created by different versions of the C++ compiler.

   On OSF/1 for the alpha, certain functions using a gcc extension
called `__attribute__((noreturn))' tend to cause internal compiler
errors.  If you experience internal compiler errors when compiling SFS
for the alpha, try building with the command `make
ECXXFLAGS='-D__attribute__\(x\)='' instead of simply `make'.

   Sometimes, a particular source file will give particularly stubborn
internal compiler errors on some architectures.  These can be very hard
to work around by just modifying the SFS source code.  If you get an
internal compiler error you cannot obviously fix, try compiling the
particular source file with a different level of debugging.  (For
example, using a command like `make sfsagent.o CXXDEBUG=-g' in the
appropriate subdirectory.)

   If your `/tmp' file system is too small, you may also end up running
out of temporary disk space while compiling SFS.  Set your `TMPDIR'
environment variable to point to a directory on a file system with more
free space (e.g., `/var/tmp').

   You may need to increase your heap size for the compiler to work.  If
you use a csh-derived shell, run the command `unlimit datasize'.  If
you use a Bourne-like shell, run `ulimit -d `ulimit -H -d`'.

   On some operating systems, some versions of GMP do not install the
library properly.  If you get linker errors about symbols with names
like `___gmp_default_allocate', try running the command `ranlib
/usr/local/lib/libgmp.a' (substituting wherever your GMP library is
installed for `/usr/local').


File: sfs.info,  Node: Getting Started,  Next: System overview,  Prev: Installation,  Up: Top

Getting Started
***************

This chapter gives a brief overview of how to set up an SFS client and
server once you have compiled and installed the software.

* Menu:

* Quick client setup::          How to set up an SFS client
* Quick server setup::          How to set up an SFS server
* Quick user setup::            How to get started as an SFS user


File: sfs.info,  Node: Quick client setup,  Next: Quick server setup,  Prev: Getting Started,  Up: Getting Started

Quick client setup
==================

SFS clients require no configuration.  Simply run the program `sfscd',
and a directory `/sfs' should appear on your system.  To test your
client, access our SFS test server.  Type the following commands:

     % cd /sfs/@sfs.fs.net,uzwadtctbjb3dg596waiyru8cx5kb4an
     % cat CONGRATULATIONS
     You have set up a working SFS client.
     %

Note that the `/sfs/@sfs.fs.net,...' directory does not need to exist
before you run the `cd' command.  SFS transparently mounts new servers
as you access them.


File: sfs.info,  Node: Quick server setup,  Next: Quick user setup,  Prev: Quick client setup,  Up: Getting Started

Quick server setup
==================

Setting up an SFS server is a slightly more complicated process.  You
must perform at least three steps:

  1. Create a public/private key pair for your server.

  2. Create an `/etc/sfs/sfsrwsd_config' configuration file.

  3. Configure your machine as an NFS server and export all necessary
     directories to `localhost'.

   To create a public/private key pair for your server, run the
commands:
     mkdir /etc/sfs
     sfskey gen -P /etc/sfs/sfs_host_key

   Then you must create an `/etc/sfs/sfsrwsd_config' file based on
which local directories you wish to export and what names those
directories should have on clients.  This information takes the form of
one or more `Export' directives in the configuration file.  Each export
directive is a line of the form:

     Export LOCAL-DIRECTORY SFS-NAME

   LOCAL-DIRECTORY is the name of a local directory on your system you
wish to export.  SFS-NAME is the name you wish that directory to have
in SFS, relative to the previous `Export' directives.  The SFS-NAME of
the first `Export' directive must be `/'.  Subsequent SFS-NAMEs must
correspond to pathnames that already exist in the previously exported
directories.

   Suppose, for instance, that you wish to export two directories,
`/disk/u1' and `/disk/u2' as `/usr1' and `/usr2', respectively.  You
should create a directory to be the root of the exported namespace, say
`/var/sfs/root', create the necessary SFS-NAME subdirectories, and
create a corresponding `sfsrwsd_config' file.  You might run the
following commands to do this:

     % mkdir /var/sfs/root
     % mkdir /var/sfs/root/usr1
     % mkdir /var/sfs/root/usr2

and create the following `sfsrwsd_config' file:

     Export /var/sfs/root /
     Export /disk/u1 /usr1
     Export /disk/u2 /usr2

   Finally, you must export all the LOCAL-DIRECTORYs in your
`sfsrwsd_config' to `localhost' via NFS version 3.  The details of
doing this depend heavily on your operating system.  For instance, in
OpenBSD you must add the following lines to the file `/etc/exports' and
run the command `kill -HUP `cat /var/run/mountd.pid`':

     /var/sfs/root localhost
     /disk/u1 localhost
     /disk/u2 localhost

   On Linux, the syntax for the exports file is:

     /var/sfs/root localhost(rw)
     /disk/u1 localhost(rw)
     /disk/u2 localhost(rw)

   On Solaris, add the following lines to the file `/etc/dfs/dfstab'
and run `exportfs -a':

     share -F nfs -o -rw=localhost /var/sfs/root
     share -F nfs -o -rw=localhost /disk/u1
     share -F nfs -o -rw=localhost /disk/u2

   In general, the procedure for exporting NFS file systems varies
greatly between operating systems.  Check your operating system's NFS
documentation for details.  (The manual page for `mountd' is a good
place to start.)

   Once you have generated a host key, created an `sfsrwsd_config'
file, and reconfigured your NFS server, you can start the SFS server by
running `sfssd'.  Note that a lot can go wrong in setting up an SFS
server.  Thus, we recommend that you first run `sfssd -d'.  The `-d'
switch will leave `sfssd' in the foreground and send error messages to
your terminal.  If there are problems, you can then easily kill `sfssd'
from your terminal, fix the problems, and start again.  Once things are
working, omit the `-d' flag; `sfssd' will run in the background and
send its output to the system log.

   Note: *You will not be able to access an SFS server running on the
same machine as the client* unless you run `sfscd' with the `-l' flag,
*Note sfscd::.  Attempts to SFS mount a machine on itself will return
the error `EDEADLK' (Resource deadlock avoided).


File: sfs.info,  Node: Quick user setup,  Prev: Quick server setup,  Up: Getting Started

Getting started as an SFS user
==============================

To access an SFS server, you must first register a public key with the
server, then run the program `sfsagent' on your SFS client to
authenticate you.

   To register a public key, log into the file server and run the
command:

     sfskey register

   This should produce something similar to the following output:

     % sfskey register
     sfskey: /home/user/.sfs/random_seed: No such file or directory
     sfskey: creating directory /home/user/.sfs
     sfskey: creating directory /home/user/.sfs/authkeys
     Creating new key: user@server.com#1 (Rabin)
            Key Label: user@server.com#1

   Press <RET> to accept the default key label.  You will then see:

     Enter passphrase:
                Again:
     
     sfskey needs secret bits with which to seed the random number generator.
     Please type some random or unguessable text until you hear a beep:
       64

   At this point, type 64 random characters to seed the random number
generator, until you hear a bell.  You will then be prompted for your
UNIX password.  If all goes well you should see a message line:

       UNIX password:
     wrote key: /home/user/.sfs/authkeys/user@server.com#1
     %

The above procedure creates a public/private key pair for you and
registers it with the server.  (Note that if you already have a public
key on another server, you can reuse that public key by giving `sfskey'
your address at that server, e.g., `sfskey register
user@other.server.com'.)

   After registering your public key with an SFS server, you can use the
`sfskey login' command to access the server.  Get a shell on a
different client machine from the server, and run the command:

     sfskey login USR@SERVER

SERVER is the name of the server on which you registered, and USER is
your logname on that server.  You should be prompted for a password,
and see something like the following:

     Passphrase for dm@server.com/1024:
     SFS Login as dm@server.com

The `sfskey login' command does three things:  It starts the `sfsagent'
program, which persists in the background to authenticate you to file
servers as needed.  It fetches your private key from SERVER and
decrypts it using your passphrase.  Finally, it fetches the server's
public key, and creates a symbolic link from `/sfs/SERVER' to
`/sfs/@SERVER,HOSTID'.  (The passphrase you type is also used to
authenticate the server to the client, so that `sfskey' can fetch the
server's public key securely.)

   If, after your agent is already running, you wish to fetch a private
key from another server or download another server's public key, you
can run `sfskey login' multiple times.  You will be able to access all
the servers you have logged into simultaneously.

   While `sfskey' provides a convenient way of authenticating oneself
to servers and obtaining their self-certifying pathnames, it is by no
means the only way.  If you use the same public key on all servers, you
will only need to type your password once to download your private key;
`sfsagent' will automatically authenticate you to whatever file servers
you touch.  Moreover, once you have access to one SFS file server, you
can store on it symbolic links pointing to other servers'
self-certifying pathnames.

   When you are done using SFS, you should run the command

     sfskey kill

before logging out.  This will kill your `sfsagent' process running in
the background and get rid of the private keys it was holding for you
in memory.


File: sfs.info,  Node: System overview,  Next: SFS configuration,  Prev: Getting Started,  Up: Top

System overview
***************

        sfskey--+---------------- - - - -----------+
                |                                  |
              agent--+                             |
          agent------+                             |
                     |                             |
        +---------------+                       +-------------+
        |         sfscd |-------- - - - --------| sfssd       |
        |            |  |                       |  |          |
        |    sfsrwcd-+  |                       |  +-sfsrwsd--+-+
        | nfsmounter-+  |                       |  +-sfsauthd | |
        +---------------+                       +-------------+ |
                     |                                          V
     +--------+      |                                   +--------+
     | kernel |      |                                   | kernel |
     |  NFS3  |<-----+                                   |  NFS3  |
     | client |                                          | server |
     +--------+                                          +--------+
     
               CLIENT                               SERVER
SFS consists of a number interacting programs on both the client and the
server side.

On the client side, SFS implements a file system by pretending to be an
NFS server and talking to the local operating system's NFS3 client.  The
program `sfscd' gets run by root (typically at boot time).  `sfscd'
spawns two other daemons--`nfsmounter' and `sfsrwcd'.

   `nfsmounter' handles the mounting and unmounting of NFS file
systems.  In the event that `sfscd' dies, `nfsmounter' takes over being
the NFS server to prevent file system operations from blocking as it
tries to unmount all file systems.  *Never send `nfsmounter' a
`SIGKILL' signal (i.e., `kill -9').* `nfsmounter''s main purpose is to
clean up the mess if any other part of the SFS client software fails.
Whatever bad situation SFS has gotten your machine into, killing
`nfsmounter' will likely only make matters worse.

   `sfsrwcd' implements the ordinary read-write file system protocol.
As other dialects of the SFS protocol become available, they will be
implemented as daemons running alongside `sfsrwcd'.

   Each user of an SFS client machine must run an instance of the
`sfsagent' command.  `sfsagent' serves several purposes.  It handles
user authentication as the user touches new file systems.  It can fetch
HOSTIDs on the fly, a mechanism called "Dynamic server authentication".
Finally, it can perform revocation checks on the HOSTIDs of servers
the user accesses, to ensure the user does not access HOSTIDs
corresponding to compromised private keys.

   The `sfskey' utility manages both user and server keys.  It lets
users control and configure their agents.  Users can hand new private
keys to their agents using `sfskey', list keys the agent holds, and
delete keys.  `sfskey' will fetch keys from remote servers using SRP,
*Note SRP::.  It lets users change their public keys on remote servers.
Finally, `sfskey' can configure the agent for dynamic server
authentication and revocation checking.

   On the server side, the program `sfssd' spawns two subsidiary
daemons, `sfsrwsd' and `sfsauthd'.  If virtual hosts or multiple
versions of the software are running, `sfssd' may spawn multiple
instances of each daemon.  `sfssd' listens for TCP connections on port
4.  It then hands each connection off to one of the subsidiary daemons,
depending on the self-certifying pathname and service requested by the
client.

   `sfsrwsd' is the server-side counterpart to `sfsrwcd'.  It
communicates with client side `sfsrwcd' processes using the SFS file
system protocol, and accesses the local disk by acting as a client of
the local operating system's NFS server.  `sfsrwsd' is the one program
in sfs that _must be configured_ before you run it, *Note
sfsrwsd_config::.

   `sfsauthd' handles user authentication.  It communicates directly
with `sfsrwsd' to authenticate users of the file system.  It also
accepts connections over the network from `sfskey' to let users
download their private keys or change their public keys.


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

SFS configuration files
***********************

SFS comprises a number of programs, many of which have configuration
files.  All programs look for configuration files in two
directories--first `/usr/local/etc/sfs', then, if they don't find the
file there, in `/usr/local/share/sfs'.  You can change these locations
using the `--with-etcdir' and `--datadir' options to the `configure'
command, *Note configure::.

   The SFS software distribution installs reasonable defaults in
`/usr/local/share/sfs' for all configuration files except
`sfsrwsd_config'.  On particular hosts where you wish to change the
default behavior, you can override the default configuration file by
creating a new file of the same name in `/usr/local/etc/sfs'.

   The `sfs_config' file contains system-wide configuration parameters
for most of the programs comprising SFS.  Note that
`/usr/local/share/sfs/sfs_config' is always parsed, even if
`/usr/local/etc/sfs/sfs_config' exists.  Options in
`/usr/local/etc/sfs/sfs_config' simply override the defaults in
`/usr/local/share/sfs/sfs_config'.  For all other configuration files,
a file in `/usr/local/etc/sfs' entirely overrides the version in
``PKGDATADIR''.

   If you are running a server, you will need to create an
`sfsrwsd_config' file to tell SFS what directories to export, and
possibly an `sfsauthd_config' if you wish to share the database of user
public keys across several file servers.

   The `sfssd_config' file contains information about which protocols
and services to route to which daemons on an SFS server, including
support for backwards compatibility across several versions of SFS.  You
probably don't need to change this file.

   `sfs_srp_params' contains some cryptographic parameters for
retrieving keys securely over the network with a passphrase (as with the
`sfskey add USR@SERVER' command).

   `sfscd_config' Contains information about extensions to the SFS
protocol and which kinds of file servers to route to which daemons.  You
almost certainly should not touch this file unless you are developing
new versions of the SFS software.

   Note that configuration command names are case-insensitive in all
configuration files (though the arguments are not).

* Menu:

* `sfs_config'::           System-wide configuration parameters
* `sfsrwsd_config'::       File server configuration
* `sfsauthd_config'::      User-authentication daemon configuration
* `sfs_users'::            User-authentication database
* `sfssd_config'::         Meta-server configuration
* `sfs_srp_params'::       Default parameters for SRP protocol
* `sfscd_config'::         Meta-client configuration


File: sfs.info,  Node: `sfs_config',  Next: `sfsrwsd_config',  Prev: SFS configuration,  Up: SFS configuration

`sfs_config'--system-wide configuration parameters
==================================================

The `sfs_config' file lets you set the following system-wide parameters:

`sfsdir DIRECTORY'
     The directory in which SFS stores its working files.  The default
     is `/var/sfs', unless you changed this with the `--with-sfsdir'
     option to `configure'.

`sfsuser SFS-USER [SFS-GROUP]'
     As described in *Note Building::, SFS needs its own user and group
     to run.  This configuration directive lets you set the user and
     group IDs SFS should use. By default, SFS-USER is `sfs' and
     SFS-GROUP is the same as SFS-USER.  The `sfsuser' directive lets
     you supply either a user and group name, or numeric IDs to change
     the default.  Note:  *If you change SFS-GROUP, you must make sure
     the the program `/usr/local/lib/sfs-0.7.2/suidconnect' is setgid
     to the new SFS-GROUP.*

`anonuser {USER | UID GID}'
     Specifies an unprivileged user id to be used for anonymous file
     access.  If specified as USER, the name USER will be looked up in
     the password file, and the login group of that user used as the
     group id.  Can alternatively be specified as a numeric UID and GID.
     The default is to use -1 for both the UID and GID, though the
     default `sfs_config' file specifies the user name nobody.

`ResvGids LOW-GID HIGH-GID'
     SFS lets users run multiple instances of the `sfsagent' program.
     However, it needs to modify processes' group lists so as to know
     which file system requests correspond to which agents.  The
     `ResvGids' directive gives SFS a range of group IDs it can use to
     tag processes corresponding to a particular agent.  (Typically, a
     range of 16 gids should be plenty.)  Note that the range is
     inclusive--both LOW-GID and HIGH-GID are considered reserved gids.

     The setuid root program `newaid' lets users take on any of these
     group IDs, *Note newaid::.  Thus, make sure these groups are not
     used for anything else, or you will create a security hole.  There
     is no default for `ResvGids'.

     Note that after changing `ResvGids', you must kill and restart
     `sfscd' for things to work properly.

`RSASize BITS'
     Sets the default size of public keys for cryptosystems that are
     based on the diffculty of factoring integers.  The Rabin public
     keys used in self-certifying pathnames are affected by this
     paremeter.  The default value of BITS is 1280.

`DlogSize BITS'
     Sets the default size of public keys for cryptosystems that are
     based on the diffculty of taking discrete logs in subgroups of
     *Z*_p_*.  This parameter affects SRP paremeter and 2-Schnorr key
     generation.  The default value of BITS is 1024.

`PwdCost COST'
     Sets the computational cost of processing a user-chosen password.
     SFS uses passwords to encrypt users' private keys.  Unfortunately,
     users tend to choose poor passwords.  As computers get faster,
     guessing passwords gets easier.  By increasing the COST parameter,
     you can maintain the cost of guessing passwords as hardware
     improves.  The change will apply to new keys, and to old keys
     after people run `sfskey edit'.

     The default value is 11.  COST is an exponential parameter.  Thus,
     you probably don't want anything too much larger.  The maximum
     value is 32--at which point password hashing will not terminate in
     any tractable amount of time and the `sfskey' command will be
     unusable.

`LogPriority FACILITY.LEVEL'
     Sets the syslog facility and level at which SFS should log
     activity.  The default is `daemon.notice'.


File: sfs.info,  Node: `sfsrwsd_config',  Next: `sfsauthd_config',  Prev: `sfs_config',  Up: SFS configuration

`sfsrwsd_config'--File server configuration
===========================================

`Hostname NAME'
     Set the LOCATION part of the server's self-certifying pathname.
     The default is the current host's fully-qualified hostname.

`Keyfile PATH'
     Tells `sfsrwsd' to look for its private key in file PATH.  The
     default is `sfs_host_key'.  SFS looks for file names that do not
     start with `/' in `/usr/local/etc/sfs', or whatever directory you
     specified if you used the `--with-etcdir' option to `configure'
     (*note configure::).

`Export LOCAL-DIRECTORY SFS-NAME [R|W]'
     Tells `sfsrwsd' to export LOCAL-DIRECTORY, giving it the name
     SFS-NAME with respect to the server's self-certifying pathname.
     Appending `R' to an export directive gives anonymous users
     read-only access to the file system (under user ID -2 and group ID
     -2).  Appending `W' gives anonymous users both read and write
     access.  *Note Quick server setup::, for an example of the `Export'
     directive.

     There is almost no reason to use the `W' flag.  The `R' flag lets
     anyone on the Internet issue NFS calls to your kernel as user -2.
     SFS filters these calls; it makes sure that they operate on files
     covered by the export directive, and it blocks any calls that would
     modify the file system.  This approach is safe given a perfect NFS3
     implementation.  If, however, there are bugs in your NFS code,
     attackers may exploit them if you have the `R' option--probably
     just crashing your server but possibly doing worse.

`LeaseTime SECONDS'


File: sfs.info,  Node: `sfsauthd_config',  Next: `sfs_users',  Prev: `sfsrwsd_config',  Up: SFS configuration

`sfsauthd_config'--User-authentication daemon configuration
===========================================================

`Hostname NAME'
     Set the LOCATION part of the server's self-certifying pathname.
     The default is the current host's fully-qualified hostname.

`Keyfile PATH'
     Tells `sfsrwsd' to look for its private key in file PATH.  The
     default is `sfs_host_key'.  SFS looks for file names that do not
     start with `/' in `/usr/local/etc/sfs', or whatever directory you
     specified if you used the `--with-etcdir' option to `configure'
     (*note configure::).

`Userfile [-update] [-create] [-passwd] [-admin] [-prefix=PREFIX] [-uid=UID | -uidmap=U1-U2+U3] [-gid=GID | -gidmap=G1-G2+G3] [-pub=PUBPATH] PATH'
     This specifies a file in which `sfsauthd' should look for user
     public keys when authenticating users.  You can specify multiple
     `Userfile' directives to use multiple files.  This can be useful in
     an environment where most user accounts are centrally maintained,
     but a particular server has a few locally-maintained guest (or
     root) accounts.

     Userfile has the following options:

    `-update'
          Specifies a user database as updatable.  Users can register
          new public keys, update their public keys, and change their
          server key information on writable databases.  If this
          command is not given, the database is assumed to read-only
          and possibly on a remote machine.  Thus, `sfsauthd' maintains
          local copies of read-only databases in `/var/sfs/authdb'.
          This process ensures that temporarily unavailable file
          servers never disrupt `sfsauthd''s operation.

    `-create'
          Create an empty `sfs_users' file if no such file exists.

    `-passwd'
          Treat the Unix passwd file (`/etc/passwd' on most machines) as
          part of this userfile.  Use password, shell and home directory
          information.  Allows users who do not exist in the database
          to log into `sfsauthd' with their UNIX password, so that they
          might register an SFS key (note this allso requires the
          `-update' flag).  *Note sfskey register::, for details on
          this. Also important for proper functioning of `rexd'.

    `-admin'
          Allow an SFS administrator to make changes to user records
          that have the admin flag set in their `privs' field.

    `-prefix=PREFIX'
          Prepend the prefix PREFIX to usernames in the given userfile.

    `-uid=UID'
    `-uidmap=U1-U2+U3'
          These options are mutually exclusive.  The first maps every
          user's credentials in the given file to the given UID, UID.
          The second maps users in the UID range (U1 to U2) to the
          offset U3.  For example, if you wanted to map users to
          1000-2520 to 61000-62520, you would supply
          -uidmap=1000-2520+60000.

    `-gid=GID'
    `-gidmap=G1-G2+G3'
          See above.  Functions the same as `gid' and `gidmap', but
          applies to group IDs, rather than user IDs.  Again, these
          options are mutually exclusive.

    `-pub=PUBPATH'
          `sfsauthd' supports the secure remote password protocol, or
          SRP.  SRP lets users connect securely to `sfsauthd' with their
          passwords, without needing to remember the server's public
          key.  To prove its identity through SRP, the server must
          store secret data derived from a user's password.  The file
          PATH specified in `Userfile' contains these secrets for users
          opting to use SRP.  The `-pub' option tells `sfsauthd' to
          maintain in PUBPATH a separate copy of the database without
          secret information.  PUBPATH might reside on an anonymously
          readable SFS file system--other machines can then import the
          file as a read-only database using a `Userfile' line with the
          `-update' flag.

     If no `Userfile' directive is specified, `sfsauthd' uses the
     following default (again, unqualified names are assumed to be in
     `/usr/local/etc/sfs'):

          Userfile -update -passwd -pub=sfs_users.pub sfs_users

`Logfile PATH'
     Use the logfile given by PATH to output the signature log
     generated by `sfsauthd'.  The default logfile is
     `/var/sfs/sign_log'.

`SRPfile PATH'
     Where to find default parameters for the SRP protocol.  Generate
     such a file using the "sfskey gensrp" command. The default is
     `sfs_srp_params'.  If the default file does not exist, serving
     pre-generated SRP parameters is disabled.

`Denyfile PATH'
     Specify a file containing a list of users that are to be explicitly
     denied the ability to register and update keys on the authserver.
     The default is `sfs_deny'.  If the default file does not exist, we
     assume an empty list.

`Realm NAME'
     Define the realm to which this authserver will belong.
     Authentication information (including SRP) can be shared amongst
     authservers that are in the same realm.  Thus, a user that wants
     to authenticate to a realm, can contact any authserver in that
     realm.

     If the realm directive does NOT appear in this file, the
     authserver will not join any realm.  This behavior is the default.
     If the realm directive does appear, NAME cannot be empty.

     NOTE: Changing an authserver's realm after users have already
     registered using SRP requires all users to update their
     authentication data because the realm is bound into the stored SRP
     information.  Specifically, each user will need to run

          sfskey update -r username@authserver

     A user logged on to the authserver can use the hostname - to
     signify the local host:

          sfskey update -r -

`Certpath DIR [DIR ...]'
     Specify a certification path to return to the client as a result
     of an "sfskey login" command; this list of directories will become
     the arguments to a dirsearch certprog.  That is, for a certpath
     "DIR1 DIR2" the client will add a certprog "dirsearch DIR1 DIR2"
     to the user's agent.  The certification path will be tagged with a
     prefix equal to the authserver's realm (see above).

     NOTE: The certpath directive only makes sense if the authserver is
     part of a realm.  The certpath will be ignored if the realm
     directive isn't specified.

     There are three ways to specify a certpath directory:

          certpath //dir1 /dir2 @sfs.host.domain,HOSTID/dir2

     which can also be written

          certpath //dir1
          certpath /dir2
          certpath @sfs.host.domain,HOSTID/dir2

     A directory starting with two slashes ("//") is considered relative
     to the client machine's root ("/").  A directory starting with one
     slash ("/") is relative to the authserver's self-certifying
     pathname (the authserver performs the substitution before is sends
     the dir).  The third form is a fully specified directory on SFS.

     The default certpath is empty.


File: sfs.info,  Node: `sfs_users',  Next: `sfssd_config',  Prev: `sfsauthd_config',  Up: SFS configuration

`sfs_users'--User-authentication database
=========================================

The `sfs_users' file, maintained and used by the `sfsauthd' program,
maps public keys to local users and groups. It is roughly analogous to
the Unix `/etc/passwd' file.  Each line of `sfs_users' has the
following format (split into two lines here only for clarity of
presentation):

     [USER|GROUP]:USER:UID:VERSION:GID:OWNER:PUBKEY:PRIVS
                               :SRP:PRIVKEY:SRVPRIVKEY:AUDIT

USER
     USER is the unique name of a public key in the database.
     Ordinarily it is the same as a username in the local password file.
     However, in certain cases it may be useful to map multiple public
     keys to the same local account (for instance if several people
     have an account with root privileges).  In such cases, each key
     should be given a unique name (e.g., `dm/root', `kaminsky/root',
     etc.).

UID
     UID is the user's user ID on the given server.

VERSION
     VERSION is the version number of this record in the users database.
     Upon registration, this value is set to 1.  Upon every subsequent
     update, this value is incremented by 1.

GID
     GID is the users's group ID on the given server.

OWNER
     This field is ignored as of SFS 0.7.

PUBKEY
     PUBKEY is an ASCII, human-readable representation of the user's
     public key.  Can be either a Rabin or 2-Schnorr public key as of
     SFS 0.7.

PRIVS
     The PRIVS field indicates whether a field can be updated by the
     SFS admin--given of course that a Userfile is included with the
     `-admin' option.

SRP
     SRP is the server-side information for the SRP protocol, *Note
     SRP::.  Unlike the previous fields, this information must be kept
     secret.  If the information is disclosed, an attacker may be able
     to impersonate the server by causing the `sfskey add' command to
     fetch the wrong HOSTID.  Note also that SRP-INFO is specific to a
     particular hostname.  If you change the LOCATION of a file server,
     users will need to register new SRP-INFO.

PRIVKEY
     PRIVKEY is actually opaque to `sfsauthd'.  It is private, per-user
     data that `sfsauthd' will return to users who successfully
     complete the SRP protocol.  Currently, `sfskey' users this field
     to store an encrypted copy of a user's private key, allowing the
     user to retrieve the private key over the network.

SRVPRIVKEY
     If a user has chosen 2-Schnorr proactive signatures, the server's
     half of the private key is kept in this field.

AUDIT
     AUDIT contains the time, source IP address, and description of the
     last update to this field.  Useful in recovering from a
     compromised key.


Note if you edit `sfs_users' files by hand, you risk overwriting
concurrent updates by `sfsauthd'.  Use the `vidb' *note vidb:: command
to lock `sfs_users' files while you edit them.


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

`sfssd_config'--Meta-server configuration
=========================================

`sfssd_config' configures `sfssd', the server that accepts connections
for `sfsrwsd' and `sfsauthd'.  `sfssd_config' can be used to run
multiple "virtual servers", or to run several versions of the server
software for compatibility with old clients.

   Directives are:

`BindAddr IP-ADDR [PORT]'
     Specifies the IP address and port on which `sfssd' should listen
     for TCP connections.  The default is `INADDR_ANY' for the address
     and port 4.

`RevocationDir PATH'
     Specifies the directory in which `sfssd' should search for
     revocation/redirection certificates when clients connect to unknown
     (potentially revoked) self-certifying pathnames.  The default
     value is `/var/sfs/srvrevoke'.  Use the command `sfskey revokegen'
     to generate revocation certificates.

`HashCost BITS'
     Specifies that clients must pay for connections by burning CPU
     time.  This can help reduce the effectiveness of denial-of-service
     attacks.  The default value is 0.  The maximum value is 22.

`Server {* | @LOCATION[,HOSTID]}'
     Specifies a section of the file that applies connection requests
     for the self-certifying pathname @LOCATION`,'HOSTID.  If `,'HOSTID
     is omitted, then the following lines apply to any connection that
     does not match an explicit HOSTID in another `Server'.  The
     argument `*' applies to all clients who do not have a better match
     for either LOCATION or HOSTID.

`Release {* | SFS-VERSION}'
     Begins a section of the file that applies to clients 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 `Service' directives until
     the next `Release' or `Server' directive.

`Extensions EXT1 [EXT2 ...]'
     Specifies that subsequent `Service' directives apply only to
     clients that supply all of the listed extension strings (EXT1,
     ...).  `Extensions' applies until the next `Extensions', `Release'
     or `Server' directive

`Service SRVNO DAEMON [ARG ...]'
     Specifies the daemon that should handle clients seeking service
     number SRVNO.  SFS defines the following values of SRVNO:

          1. File server
          2. Authentication server
          3. Remote execution
          4. SFS/HTTP (not yet released)

`Service SRVNO -u PATH'
     Operates as the above syntax of `Service', only instead of
     spawning a daemon, connects to the unix-domain socket specified by
     `path' to communicate with an already running daemon.  This option
     may be useful when debugging SFS servers, as the server for a
     particular service on a particular self-certifying pathname can be
     run under the debugger and receive connections on the usual SFS
     port without interfering with other servers on the same machine.

`Service SRVNO -t HOST [PORT]'
     Specifies that `sfssd' should act as a "TCP proxy" for this
     particular service, relaying any incoming connections to TCP port
     PORT on HOST.  If unspecified, PORT is the default SFS TCP port 4.

     This syntax is useful in a NATted environment.  For instance,
     suppose you have two SFS servers with addresses 10.0.0.2 and
     10.0.0.3 on a private network, and one machine 10.0.0.1 with an
     externally visible interface 4.3.2.1.  You can use this proxy
     syntax to export the internal file systems.  The easiest way is to
     pick two DNS names for the new servers, but point them at your
     outside server.  For example:

          server-a.mydomain.com.  IN A    4.3.2.1
          server-b.mydomain.com.  IN A    4.3.2.1

     Then, on your outside machine, you might have the following
     `sfssd_config' file:

          Server server-a.mydomain.com
            Release *
                Service 1 -t 10.0.0.2
                Service 2 -t 10.0.0.2
                Service 3 -t 10.0.0.2
          Server server-b.mydomain.com
            Release *
                Service 1 -t 10.0.0.3
                Service 2 -t 10.0.0.3
                Service 3 -t 10.0.0.3

     Then on each of the internal machines, be sure to specify
     `Hostname server-A.mydomain.com' and `Hostname
     server-B.mydomain.com' in `sfsrwsd_config'.


The default contents of `sfssd_config' is:

     Server *
       Release *
           Service 1 sfsrwsd
           Service 2 sfsauthd
           Service 3 rexd

To disable the file server, you can copy this file to
`/etc/sfs/sfssd_config' and comment out the line `Service 1 sfsrwsd'.
To disable the remote login server, comment out the line for `rexd'.

To run a different server for sfs-0.6 and older clients, you could add
the lines:

       Release 0.6
         Service 1 /usr/local/lib/sfs-0.6/sfsrwsd


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 `/usr/local/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 `/usr/local/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 `/usr/local/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 `/usr/local/etc/sfs' if SFS-CONFIG-FILE is found
     in /USR/LOCAL/SHARE/SFS.  Thus, if you create a file
     `/usr/local/etc/sfs/'SFS-CONFIG-FILE, it will override
     `/usr/local/etc/sfs/sfs_config' while still incorporating the
     defaults from /USR/LOCAL/SHARE/SFS/SFS_CONFIG.



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

`vidb' command
==============

`vidb' manually edits an SFS user-authentication file *note
sfs_users::, acquiring locks to prevent concurrent updates from
overwriting each other.  The usage is:

     vidb [-r] [-w] [-e EDITOR] SFS-USERS-FILE

   `vidb' has the following options:

`-r'
     Recovers from a previous edit session.  `vidb' makes a copy of of
     SFS-USERS-FILE to be edited, named by appending `.tmp' to the file
     name.  If an editing session crashes, vidb will refuse to run, as
     the old temporarly file may contain useful data that should not be
     deleted.  With `-r', however, `vidb' removes any old temporary
     file.

`-w'
     The point of `vidb' is to avoid concurrent edits to the database
     and the corresponding inconsistencies that might result.
     Ordinarily, if the database is already being edited, `vidb' will
     just exit with an error message.  The `-w' flag tells `vidb' to
     wait until it can acquire the lock on the database, and then run.

`-e EDITOR'
     Specifies the editor to use for editing the file.  The default is
     to use the command specified by the enviornment variable `EDITOR'.
     If there is no environment variable and `-e' is not specified,
     `vidb' uses `vi'.

Note: `vidb' should really recreate any publicly-readable versions of
user authentication databases (either by parsing `sfsauthd_config' for
`-pub=...' options to `Userfile' directives or signaling `sfsauthd').
Currently you must manually kill `sfssd' or `sfsauthd' for this to
happen.


File: sfs.info,  Node: funmount,  Next: sfsrwsd,  Prev: vidb,  Up: Command reference

`funmount' command
==================

The `funmount' command is executed as follows:

     funmount PATH

   `funmount' forcibly attempts to unmount the file system mounted on
PATH.  It is roughly equivalent to running `umount -f PATH'.  However,
on most operating systems the `umount' command does a great deal more
than simply execute the `unmount' system call--for instance it may
attempt to read the attributes of the file system being unmounted
and/or contact a remote NFS server to notify it of the unmount
operation.  These extra actions make `umount' hang when a remote NFS
server is unavailable or a loopback server has crashed, which in turn
causes the client to become ever more wedged.  `funmount' can avoid such
situations when you are trying to salvage a machine with bad NFS mounts
without rebooting it.

   SFS will get very confused if you ever unmount file systems from
beneath it.  SFS's `nfsmounter' program tries to clean up the mess if
the client software ever crashes.  Running `funmount' will generally
only make things worse by confusing `nfsmounter'.

   If `/a' is a mount point, and `/a/b' is another mount point,
unmounting `/a' before `/a/b' will cause the latter file system to
become "lost."  Once a file system is lost, there is no way to unmount
it without rebooting.  Worse yet, on some operating systems, commands
such as `df' may hang because of a lost file system.

   Many operating systems will not let you unmount a file system (even
forcibly) if a process is using the file system's root directory (for
instance as a current working directory).  Under such circumstances,
`funmount' may fail.  To unmount the file system you must find and kill
whatever process is using the directory.  Utilities such as `fstat' and
`lsof' may be helpful for identifying processes with a particular file
system open.


File: sfs.info,  Node: sfsrwsd,  Next: sfsauthd,  Prev: funmount,  Up: Command reference

`sfsrwsd' daemon
================

     /usr/local/lib/sfs-0.7.2/sfsrwsd [-f CONFIG-FILE]

   `sfsrwsd' is the program implementing the SFS read-write server.
Ordinarily, you should never run `sfsrwsd' directly, but rather have
`sfssd' do so.  Nonetheless, you must create a configuration file for
`sfsrwsd' before running an SFS server.  *Note sfsrwsd_config::, for
what to put in your `sfsrwsd_config' file.

`-f CONFIG-FILE'
     Specify an alternate `sfsrwsd' configuration file, *Note
     sfsrwsd_config::.  The default, if `-f' is unspecified, is
     `/usr/local/etc/sfs/sfsrwsd_config'.


File: sfs.info,  Node: sfsauthd,  Prev: sfsrwsd,  Up: Command reference

`sfsauthd' daemon
=================

     /usr/local/lib/sfs-0.7.2/sfsauthd [-u SOCKFILE] [-f CONFIG-FILE]

   `sfsauthd' is the program responsible for authenticating users.
`sfsrwsd' and other daemons communicate with `sfsauthd', forwarding it
authentication requests from `sfsagent' processes on remote client
machines.  `sfsauthd' informs requesting daemons of whether
authentication requests are valid, and if so what local credentials to
associate with the remote user agent.  The `sfskey' program also
communicates directly with remote `sfsauthd' processes when retrieving
and updating users keys (with `sfskey add', `update', `register', and
more).

`-f CONFIG-FILE'
     Specify an alternate `sfssauthd_config' configuration file, *Note
     sfsauthd_config::.  The default, if `-f' is unspecified, is
     `/usr/local/etc/sfs/sfsauthd_config'.

`-u PATH'
     Bind unix domain socket PATH, and accept TCP connections passed
     over connections to that socket.  This option allows `sfssd' to
     communicate with already running `sfsauthd' commands using a
     directive like `Service 2 -u PATH' in `sfssd_config' *Note
     sfssd_config::.


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

Security considerations
***********************

SFS shares files between machines using cryptographically protected
communication.  As such, SFS can help eliminate security holes
associated with insecure network file systems and let users share files
where they could not do so before.

   That said, there will very likely be security holes attackers can
exploit because of SFS, that they could not have exploited otherwise.
This chapter enumerates some of the security consequences of running
SFS.  The first section describes vulnerabilities that may result from
the very existence of a global file system.  The next section lists bugs
potentially present in your operating system that may be much easier for
attackers to exploit if you run SFS.  Finally the last section attempts
to point out weak points of the SFS implementation that may lead to
vulnerabilities in the SFS software itself.

* Menu:

* new vulnerabilities::         Vulnerabilities created by SFS
* exposed vulnerabilities::     Vulnerabilities exploitable because of SFS
* implementation vulnerabilities::  Vulnerabilities in the SFS implementation


File: sfs.info,  Node: new vulnerabilities,  Next: exposed vulnerabilities,  Prev: Security,  Up: Security

Vulnerabilities created by SFS
==============================

Facilitating exploits
---------------------

Many security holes can be exploited much more easily if the attacker
can create an arbitrary file on your system.  As a simple example, if a
bug allows attackers to run any program on your machine, SFS allows them
to supply the program somewhere under `/sfs'.  Moreover, the file can
have any numeric user and group (though of course, SFS disables setuid
and devices).

`.' in `path'
-------------

Another potential problem users putting the current working directory
`.' in their PATH environment variables.  If you are browsing a file
system whose owner you do not trust, that owner can run arbitrary code
as you by creating programs named things like `ls' in the directories
you are browsing.  Putting `.' in the PATH has always been a bad idea
for security, but a global file system like SFS makes it much worse.

symbolic links from untrusted servers
-------------------------------------

Users need to be careful about using untrusted file systems as if they
were trusted file systems.  Any file system can name files in any other
file system by symbolic links.  Thus, when randomly overwriting files in
a file system you do not trust, you can be tricked, by symbolic links,
into overwriting files on the local disk or another SFS file system.

   As an example of a seemingly appealing use of SFS that can cause
problems, consider doing a `cvs' checkout from an untrusted CVS
repository, so as to peruse someone else's source code.  If you run
`cvs' on a repository you do not trust, the person hosting the
repository could replace the `CVSROOT/history' with a symbolic link to
a file on some other file system, and cause you to append garbage to
that file.

   This `cvs' example may or may not be a problem.  For instance, if
you are about to compile and run the software anyway, you are placing
quite a bit of trust in the person running the CVS repository anyway.
The important thing to keep in mind is that for most uses of a file
system, you are placing some amount of trust in in the file server.

   *Note resvgids::, to see how users can run multiple agents with the
`newaid' command.  One way to cut down on trust is to access untrusted
file servers under a different agent with different private keys.
Nonetheless, this still allows the remote file servers to serve
symbolic links to the local file system in unexpected places.

Leaking information
-------------------

Any user on the Internet can get the attributes of a LOCAL-DIRECTORY
listed in an `Export' directive (*note export::).  This is so users can
run commands like `ls -ld' on a self-certifying pathname in `/sfs',
even if they cannot change directory to that pathname or list files
under it.  If you wish to keep attribute information secret on a
LOCAL-DIRECTORY, you will need to export a higher directory.  We may
later reevaluate this design decision, though allowing such anonymous
users to get attributes currently simplifies the client implementation.


File: sfs.info,  Node: exposed vulnerabilities,  Next: implementation vulnerabilities,  Prev: new vulnerabilities,  Up: Security

Vulnerabilities exploitable because of SFS
==========================================

NFS server security
-------------------

The SFS read-write server software requires each SFS server to run an
NFS server.  Running an NFS server at all can constitute a security
hole.  In order to understand the full implications of running an SFS
server, you must also understand NFS security.

   NFS security relies on the secrecy of file handles.  Each file on an
exported file system has associated with it an NFS file handle
(typically 24 to 32 bytes long).  When mounting an NFS file system, the
`mount' command on the client machine connects to a program called
`mountd' on the server and asks for the file handle of the root of the
exported file system.  `mountd' enforces access control by refusing to
return this file handle to clients not authorized to mount the file
system.

   Once a client has the file handle of a directory on the server, it
sends NFS requests directly to the NFS server's kernel.  The kernel
performs no access control on the request (other than checking that the
user the client claims to speak for has permission to perform the
requested operation).  The expectation is that all clients are trusted
to speak for all users, and no machine can obtain a valid NFS file
handle without being an authorized NFS client.

   To prevent attackers from learning NFS file handles when using SFS,
SFS encrypts all NFS file handles with a 20-byte key using the Blowfish
encryption algorithm.  Unfortunately, not all operating systems choose
particularly good NFS file handles in the first place.  Thus, attackers
may be able to guess your file handles anyway.  In general, NFS file
handles contain the following 32-bit words:

   * A file system ID (containing the device number)

   * The inode number (i-number) of the file

   * A generation number that changes when the i-number is recycled

In addition NFS file handles can contain the following words:

   * A second file system ID word (for a 64-bit fsid)

   * The length of the file handle data

   * The i-number of the exported directory

   * The generation number of the exported directory

   * Another copy of the file system ID (for the exported directory?)

   * One or more unused 0 words

Many of these words can be guessed outright by attackers without their
needing to interact with any piece of software on the NFS server.  For
instance, the file system ID is often just the device number on which
the physical file system resides.  The i-number of the root directory in
a file system is always 2.  The i-number and generation number of the
root directory can also be used as the i-number and generation number of
the "exported directory".

   On some operating systems, then, the only hard thing for an attacker
to guess is the 32-bit generation number of some directory on the
system.  Worse yet, the generation numbers are sometimes not chosen
with a good random number generator.

   To minimize the risks of running an NFS server, you might consider
taking the following precautions:

   * Many operating systems ship with a program called `fsirand' that
     re-randomizes all generation numbers in a file system.  Running
     `fsirand' may result in much better generation numbers than, say,
     a factory install of an operating system.

   * In general, you should try to block all external NFS traffic from
     reaching your machine.  If you have a firewall, consider filtering
     ports 111 and 2049 for both TCP and UDP.  If your server's
     operating system comes with some sort of IP filtering, you might
     filter any traffic to port 2049 that does not come from the
     loopback interface (though on some OSes, this could prevent you
     from acting as an NFS client if you are still using NFS on your
     local network--try it to see).

   * Most operating systems allow you to export NFS file systems
     "read-mostly"--i.e. read-write to a small number of servers and
     read-only to everyone else.  The read-only requirement typically is
     enforced by the kernel.  Thus, if you can export file systems
     read-write to `localhost' for SFS, but read-only to any client on
     which an attacker may have learned an NFS file handle, you may be
     able to protect the integrity of your file system under attack.
     (Note, however, that unless you filter forged packets at your
     firewall, the attacker can put whatever source address he wants on
     an NFS UDP packet.)  See the `mountd' or `exports' manual page for
     more detail.  *Note:  under no circumstances should you make your
     file system "read-only to the world," as this will let anyone find
     out NFS file handles.  You want the kernel to think of the file
     system as read-only for the world, but `mountd' to refuse to give
     out file handles to anybody but `localhost'.*

`mountd -n'.
------------

The `mountd' command takes a flag `-n' meaning "allow mount requests
from unprivileged ports."  *Do not ever run use this flag*.  Worse yet,
some operating systems (notably HP-UX 9) always exhibit this behavior
regardless of whether they `-n' flag has been specified.

   The `-n' option to `mountd' allows any user on an NFS client to
learn file handles and thus act as any other user.  The situation gets
considerably worse when exporting file systems to `localhost', however,
as SFS requires.  Then everybody on the Internet can learn your NFS
file handles.  The reason is that the `portmap' command will forward
mount requests and make them appear to come from `localhost'.

`portmap' forwarding
--------------------

In order to support broadcast RPCs, the `portmap' program will relay
RPC requests to the machine it is running on, making them appear to
come from `localhost'.  That can have disastrous consequences in
conjunction with `mountd -n' as described previously.  It can also be
used to work around "read-mostly" export options by forwarding NFS
requests to the kernel from `localhost'.

   Operating systems are starting to ship with `portmap' programs that
refuse to forward certain RPC calls including mount and NFS requests.
Wietse Venema has also written a `portmap' replacement that has these
properties, available from
`ftp://ftp.porcupine.org/pub/security/index.html'.  It is also a good
idea to filter TCP and UDP ports 111 (`portmap') at your firewall, if
you have one.

Bugs in the NFS implementation
------------------------------

Many NFS implementations have bugs.  Many of those bugs rarely surface
when clients and servers with similar implementation talk to each other.
Examples of bugs we've found include servers crashing when the receive a
write request for an odd number of bytes, clients crashing when they
receive the error `NFS3ERR_JUKEBOX', and clients using uninitialized
memory when the server returns a `lookup3resok' data structure with
`obj_attributes' having `attributes_follow' set to false.

   SFS allows potentially untrusted users to formulate NFS requests
(though of course SFS requires file handles to decrypt correctly and
stamps the request with the appropriate Unix uid/gid credentials).
This may let bad users crash your server's kernel (or worse).
Similarly, bad servers may be able to crash a client.

   As a precaution, you may want to be careful about exporting any
portion of a file system to anonymous users with the `R' or `W' options
to `Export' (*note export::).  When analyzing your NFS code for
security, you should know that even anonymous users can make the
following NFS RPC's on a LOCAL-DIRECTORY in your `sfsrwsd_config' file:
`NFSPROC3_GETATTR', `NFSPROC3_ACCESS', `NFSPROC3_FSINFO', and
`NFSPROC3_PATHCONF'.

   On the client side, a bad, non-root user in collusion with a bad file
server can possibly crash or deadlock the machine.  Many NFS client
implementations have inadequate locking that could lead to race
conditions.  Other implementations make assumptions about the
hierarchical nature of a file system served by the server.  By violating
these assumptions (for example having two directories on a server each
contain the other), a user may be able to deadlock the client and create
unkillable processes.

`logger' buffer overrun
-----------------------

SFS pipes log messages through the `logger' program to get them into
the system log.  SFS can generate arbitrarily long lines.  If your
`logger' does something stupid like call `gets', it may suffer a buffer
overrun.  We assume no one does this, but feel the point is worth
mentioning, since not all logger programs come with source.

   To avoid using `logger', you can run `sfscd' and `sfssd' with the
`-d' flag and redirect standard error wherever you wish manually.


File: sfs.info,  Node: implementation vulnerabilities,  Prev: exposed vulnerabilities,  Up: Security

Vulnerabilities in the SFS implementation
=========================================

Resource exhaustion
-------------------

The best way to attack the SFS software is probably to cause resource
exhaustion.  You can try to run SFS out of file descriptors, memory, CPU
time, or mount points.

   An attacker can run a server out of file descriptors by opening many
parallel TCP connections.  Such attacks can be detected using the
`netstat' command to see who is connecting to SFS (which accepts
connections on port 4).  Users can run the client (also `sfsauthd') out
of descriptors by connecting many times using the setgid program
`/usr/local/lib/sfs-0.7.2/suidconnect'.  These attacks can be traced
using a tool like lsof, available from
`ftp://vic.cc.purdue.edu/pub/tools/unix/lsof'.

   SFS enforces a maximum size of just over 64 K on all RPC requests.
Nonetheless, a client could connect 1000 times, on each connection send
the first 64 K of a slightly larger message, and just sit there.  That
would obviously consume about 64 Megabytes of memory, as SFS will wait
patiently for the rest of the request.

   A worse problem is that SFS servers do not currently flow-control
clients.  Thus, an attacker could make many RPCs but not read the
replies, causing the SFS server to buffer arbitrarily much data and run
out of memory.  (Obviously the server eventually flushes any buffered
data when the TCP connection closes.)

   Connecting to an SFS server costs the server tens of milliseconds of
CPU time.  An attacker can try to burn a huge amount of the server's CPU
time by connecting to the server many times.  The effects of such
attacks can be mitigated using hashcash, *Note HashCost::.

   Finally, a user on a client can cause a large number of file systems
to be mounted.  If the operating system has a limit on the number of
mount points, a user could run the client out of mount points.

Non-idempotent operations
-------------------------

If a TCP connection is reset, the SFS client will attempt to reconnect
to the server and retransmit whatever RPCs were pending at the time the
connection dropped.  Not all NFS RPCs are idempotent however.  Thus, an
attacker who caused a connection to reset at just the right time could,
for instance, cause a `mkdir' command to return `EEXIST' when in fact
it did just create the directory.

Injecting packets on the loopback interface
-------------------------------------------

SFS exchanges NFS traffic with the local operating system using the
loopback interface.  An attacker with physical access to the local
ethernet may be able to inject arbitrary packets into a machine,
including packets to 127.0.0.1.  Without packet filtering in place, an
attacker can also send packets from anywhere making them appear to come
from 127.0.0.1.

   On the client, an attacker can forge NFS requests from the kernel to
SFS, or forge replies from SFS to the kernel.  The SFS client encrypts
file handles before giving them to the operating system.  Thus, the
attacker is unlikely to be able to forge a request from the kernel to
SFS that contain a valid file handle.  In the other direction however,
the reply does not need to contain a file handle.  The attacker may well
be able to convince the kernel of a forged reply from SFS.  The attacker
only needs to guess a (possibly quite predictable) 32-bit RPC XID
number.  Such an attack could result, for example, in a user getting the
wrong data when reading a file.

   On the server side, you also must assume the attacker cannot guess a
valid NFS file handle (otherwise, you already have no security--*note
NFS security::).  However, the attacker might again forge NFS replies,
this time from the kernel to the SFS server software.

   To prevent such attacks, if your operating system has IP filtering,
it would be a good idea to block any packets either from or to
127.0.0.1 if those packets do not come from the loopback interface.
Blocking traffic "from" 127.0.0.1 at your firewall is also a good idea.

Causing deadlock
----------------

On BSD-based systems (and possibly others) the buffer reclaiming policy
can cause deadlock.  When an operation needs a buffer and there are no
clean buffers available, the kernel picks some particular dirty buffer
and won't let the operation complete until it can get that buffer.  This
can lead to deadlock in the case that two machines mount each other.

Getting private file data from public workstations
--------------------------------------------------

An attacker may be able to read the contents of a private file shortly
after you log out of a public workstation if the he can then become root
on the workstation.  There are two attacks possible.

   First, the attacker may be able to read data out of physical memory
or from the swap partition of the local disk.  File data may still be in
memory if the kernel's NFS3 code has cached it in the buffer cache.
There may also be fragments of file data in the memory of the `sfsrwcd'
process, or out on disk in the swap partition (though `sfsrwcd' does
its best to avoid getting paged out).  The attacker can read any
remaining file contents once he gains control of the machine.

   Alternatively, the attacker may have recorded encrypted session
traffic between the client and server.  Once he gains control of the
client machine, he can attach to the `sfsrwcd' process with the
debugger and learn the session key if the session is still open.  This
will let him read the session he recorded in encrypted form.

   To minimize the risks of these attacks, you must kill and restart
`sfscd' before turning control of a public workstation over to another
user.  Even this is not guaranteed to fix the problem.  It will flush
file blocks from the buffer cache by unmounting all file systems, for
example, but the contents of those blocks may persist as uninitialized
data in buffers sitting on the free list.  Similarly, any programs you
ran that manipulated private file data may have gotten paged out to
disk, and the information may live on after the processes exit.

   In conclusion, if you are paranoid, it is best not to use public
workstations.

Setuid programs and devices on remote file systems
--------------------------------------------------

SFS does its best to disable setuid programs and devices on remote file
servers it mounts.  However, we have only tested this on operating
systems we have access to.  When porting SFS to new platforms, It is
worth testing that both setuid programs and devices do not work over
SFS.  Otherwise, any user of an SFS client can become root.


File: sfs.info,  Node: Contacts,  Next: Concept Index,  Prev: Security,  Up: Top

How to contact people involved with SFS
***************************************

Please report any bugs you find in SFS to <sfsbug@redlab.lcs.mit.edu>.

   You can send mail to the authors of SFS at
<sfs-dev@pdos.lcs.mit.edu>.

   There is also a mailing list of SFS users and developers at
<sfs@sfs.fs.net>.  To subscribe to the list, send mail to
<sfs-subscribe@sfs.fs.net>.


File: sfs.info,  Node: Concept Index,  Prev: Contacts,  Up: Top

Concept Index
*************

* Menu:

* /etc/exports:                          Quick server setup.
* ___gmp_default_allocate:               Build Problems.
* aid:                                   newaid.
* Caffeine:                              Overview.
* Certification paths:                   sfskey.
* configure:                             Building.
* dirsearch <1>:                         sfskey.
* dirsearch:                             dirsearch.
* Disk Full:                             Build Problems.
* Dynamic server authentication:         sfskey.
* EDEADLK:                               sfscd.
* HOSTID:                                Overview.
* Internal compiler error:               Build Problems.
* NFS security:                          exposed vulnerabilities.
* nfsmounter <1>:                        System overview.
* nfsmounter:                            funmount.
* Resource deadlock avoided:             sfscd.
* Self-certifying pathname:              Overview.
* sfs_config:                            sfs_config.
* sfs_srp_params:                        sfs_srp_params.
* sfs_users:                             sfs_users.
* sfsauthd_config:                       sfsauthd_config.
* sfscd_config:                          sfscd_config.
* sfsrwsd_config:                        sfsrwsd_config.
* sfssd_config:                          sfssd_config.
* SRP:                                   sfskey.
* Virtual memory exhausted:              Build Problems.



Tag Table:
Node: Top927
Node: Overview3718
Node: Installation6788
Node: Requirements7493
Node: Building9130
Ref: configure10511
Ref: --with-sfsuser10645
Ref: --with-sfsgroup11073
Node: Build Problems12916
Node: Getting Started14945
Node: Quick client setup15401
Node: Quick server setup16063
Node: Quick user setup19847
Node: System overview23460
Node: SFS configuration27720
Node: `sfs_config'30462
Ref: sfs_config30679
Ref: resvgids31958
Ref: pwdcost33365
Node: `sfsrwsd_config'34255
Ref: sfsrwsd_config34458
Ref: export34969
Node: `sfsauthd_config'35973
Ref: sfsauthd_config36207
Ref: Realm40977
Node: `sfs_users'43141
Ref: sfs_users43337
Node: `sfssd_config'46160
Ref: sfssd_config46355
Ref: HashCost47167
Node: `sfs_srp_params'51129
Ref: sfs_srp_params51351
Node: `sfscd_config'51946
Ref: sfscd_config52121
Node: Command reference54613
Node: sfsagent55586
Node: sfskey58434
Ref: SRP63012
Ref: certprog65457
Ref: sfskey passwd77862
Ref: sfskey register79876
Node: rex88153
Node: dirsearch90147
Node: newaid92252
Node: ssu96314
Node: sfscd97439
Node: sfssd99072
Node: vidb100962
Node: funmount102582
Node: sfsrwsd104514
Node: sfsauthd105203
Node: Security106433
Node: new vulnerabilities107645
Node: exposed vulnerabilities110808
Ref: NFS security111068
Node: implementation vulnerabilities119660
Node: Contacts126362
Node: Concept Index126824

End Tag Table
