sfskey(1)

NAME
sfskey - SFS key manager

SYNOPSIS
sfskey [-S sock] [-p pwfd] command [arg ...]

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

OPTIONS
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 is loaded from file keyfile. The default for keyfile, if omitted, is $HOME/.sfs/identity.

The second form of the command fetches a private key over the network using the http://srp.stanford.edu/srp/,SRP 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 and register 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). Clears the list of certification programs the agent runs. See certprog, for more details on certification programs. Prints the list of certification programs the agent runs. See certprog, for more details on certification programs. 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 ---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 ---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:
    Print the contents of the file to standard output, instead of its pathname. 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. Print the path dir/name. This is the default behavior anyway, so the option -p has no effect. 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
Deletes private key keyname from the agent (reversing the effect of an add command). Deletes all private keys from the agent. 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.

The options are:
    Removes any password from the key, so that the password is stored on disk in unencrypted form. Specifies the file two which the edited key should be written. Override the default computational cost of processing a password, or PwdCost. Specifies the name of the key that shows up in sfskey list.
Generates a new public/private key pair and stores it in keyfile. It omitted keyfile defaults to $HOME/.sfs/identity.
    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. Specifies that sfskey gen should not ask for a passphrase and the new key should be written to disk in unencrypted form. Specifies that the public key should be nbits long. Override the default computational cost of processing a password, or PwdCost. Specifies the name of the key that shows up in sfskey list. Otherwise, the user will be prompted for a name.
Lists all of the various sfskey commands and their usage. 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. Kill the agent. List the public keys whose private halves the the agent holds.
    Suppresses the banner line explaining the output. Lists the actual value of public keys, in addition the the names of the keys.
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. The superuser can also use sfskey register when creating accounts.

key is the private key to use. If key does not exist and is a pathname, sfskey will create it. The default key is $HOME/.sfs/identity, unless -u is used, in which case the default is to generate a new key but not store it anywhere. If a user wishes to reuse a public key already registered with another server, the user can specify user@server for key.
    These options are the same as for sfskey gen. -K and -b have no effect if the key already exists. 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. When sfskey register is run as root, specifies a particular user to register. This can be useful when creating accounts for people.

    sfsauthd_config must have a Userfile with the -reg option to enable use of the sfskey register.
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. 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). List the rex sessions that the agent is maintaining. Generate a new sfs_srp_params file. Change a user's public key and SRP information on an SFS file server. The default value for newkey is $HOME/.sfs/identity.

To change public keys, typically a user should generate a new public key and store it in $HOME/.sfs/identity. Then he can run sfskey update [user]@host for each server on which he needs to change his public key.

Several options control sfskey update's behavior:
    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. 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/etc/sfs/sfs_srp_params. Specify the server on which to change the users key. The server must be specified as Location:HostID. A server of - means to use the local host. You can specify the -a option multiple times, in which case sfskey will attempt to change oldkey to newkey on multiple servers in parallel.

    If oldkey is the name of a remote key---i.e. of the form [user]@host---then the default value of server is to use whatever server successfully completes the SRP authentication protocol while fetching oldkey. Otherwise, if oldkey is a file, the -a option is mandatory.

SEE ALSO
rex(1), sfsagent(1), ssu(1), sfs_config(5), sfs_srp_params(5), sfs_users(5), sfsauthd_config(5), sfscd_config(5), sfsrwsd_config(5), sfssd_config(5), sfsauthd(8), sfscd(8), sfsrwsd(8), sfssd(8)

The full documentation for SFS is maintained as a Texinfo manual. If the info and SFS programs are properly installed at your site, the command info SFS should give you access to the complete manual.

For updates, documentation and software distribution, please see the SFS website at http://www.fs.net.

AUTHOR
sfsdev@redlab.lcs.mit.edu