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

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

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

   Copyright 1999-2002 David Mazie`res

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

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

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


File: sfs.info,  Node: 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 `/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 `/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
`/etc/sfs/sfs_config' exists.  Options in `/etc/sfs/sfs_config' simply
override the defaults in `/usr/local/share/sfs/sfs_config'.  For all
other configuration files, a file in `/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 `/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 `/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
     `/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

