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.
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 () 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).
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 EXAMPLEfilter 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:
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
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:
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.
Note that sfskey gen is only useful for generating Rabin keys. Use either sfskey register or sfskey 2gen to generate 2-Schnorr keys.
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.
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.
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.
sfsauthd_config must have a Userfile with the -update and -passwd options to enable use of the sfskey register.
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.
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:
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 .
AUTHOR
sfsdev@redlab.lcs.mit.edu