--- name: "sfskey" section: "1" platform: "linux" package: "sfs-common" version: "1:0.8-0+pre20060720.1-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/sfskey" --- # sfskey(1) SFS key manager ## 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. 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 unavailable. 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. ## OPTIONS - 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 registered 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. See *certprog*, for more details on certification programs. - sfskey certlist \[-q\] Prints the list of certification programs the agent runs. See *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 *HostID*s on the fly in the */sfs* directory. This mechanism can be used for **dynamic server authentication**--running code to lookup *HostID*s 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 *name*s 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 *HostID*s. 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 confclear Clears the confirmation program that the agent runs. See *confprog*, for more details on confirmation programs. - sfskey conflist \[-q\] Prints the confirmation program that the agent runs. See *confprog*, for more details on confirmation programs. - sfskey confprog *prog* \[*arg* ...\] The **confprog** command registers a command to be run by the agent when it receives an authentication request. The agent provides the program with the following command line arguments: the machine making the request, the machine that the requestor wants to access, the service (e.g., file system, remote execution facility), the current key that the agent will try signing with, and a list of all of the keys that the agent has available. If the confirmation program returns a zero exit status, the agent will sign with the current key; otherwise, it will refuse to sign with that key and will try the next available one. The confirmation program can be very simple (always answer yes, for example), or quite complex. SFS comes with an example confirmation program written in Python/GTK2 (*confirm.py*). When called, the script can pop up a dialog box which asks the user what he wants to do with the request. The user has several options: reject, accept, accept and allow all futures request from the requesting machine to access the named machine, accept and allow access from requestor to any machine in the named machine's domain, or accept and allow access from requestor to any machine. The script saves the user's preferences in a data file which it consults on subsequent invocations. If the user has chosen to accept a particular request automatically, the script returns zero (success) without popping up a dialog box. Confirmation programs allow the user to manage trust policies when working with machines that are trusted to different degrees. For example, a user might trust the machine on his lan but want to manually confirm requests from machines in a shared compute cluster. - 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 appropriate 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 available default key in *$HOME/.sfs/authkeys*. A *keyname* of the 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**. - \-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 re-sharing 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 available Rabin key in *$HOME/.sfs/authkeys* with the prefix *prefix*. If *keyname* contains a non-terminal *#* 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**. - \-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* Specifies 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 gethash \[-6p\] *keyname* Retrieves a public key specified by *keyname*, which can be local (from a local file) or remote (from an authentication server). Remote *keyname*s can contain fully-specified self-certifying hostnames, or simple DNS names. In the latter case, **sfskey** uses SRP to establish a secure connection to the authentication server. - \-6 Display the hash in base-64 encoding. - sfskey group \[-a *key*\] \[-E\] \[-C\] \[-L *version*\] \[-m {+\|-}*membername*\] \[-o {+\|-}*ownername*\] *groupname* Retrieves, creates, and modifies group lists on an authentication server. *groupname* is the name of the group, which can take an optional DNS hostname or self-certifying hostname. Given a simple DNS hostname, the server will attempt SRP to retrieve the server's public key. Using the **-a** is another way to retrieve the key. With no options, **sfskey** will query the authentication server for the group and print out the result. The group owners and members listed will be exactly as they appear in the authentication server's database. The various options are described below. - \-a *key* This option 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 (via SRP) or the path to a local file. Usually it will not be necessary to specify keys in the keys directory (*$HOME/.sfs/authkeys*) as they are considered automatically. - \-E With this option, **sfskey** will ask the authentication server to \`\`expand'' the owners and members lists first by computing the transitive closure of all groups and remote users. The expanded group will contain only public key hashes and user names (local to the remote authentication server). - \-C This option tells **sfskey** to create a new group called *groupname*. If the group already exists, **sfskey** returns an error. - \-L This option tells **sfskey** to retrieve a group's changelog beginning at version *version* up through the most recent version. The changelog contains the updates made to the group's members list, plus the group's current refresh and timeout values. - \-m {+\|-}*membername* - \-o {+\|-}*ownername* This option tells **sfskey** to add (+) or subtract (-) the given member or owner name to or from the given group. *membername*s and *ownername*s must be of the form "u=\", "g=\" or "p=\". The "\" and "\" names can be local or remote, but remote names must contain the fully-qualified self-certifying hostname. Duplicate member names and owner names are removed from the group before it is updated. Removals of names that don't exists on the given list are ignored. This option may be given more than once. - sfskey help Lists all of the various **sfskey** commands and their usage. - sfskey hostid *Location* - sfskey hostid *Location*@t{%}*port* - sfskey hostid - Retrieves a self-certifying pathname insecurely over the network and prints **@***Location***,***HostID* or **@***Location*@t{%}*port***,***HostID* to standard output. If *Location* 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 proactive 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 *prefix* in the standard keys directory (*$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 proactive 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 substantial 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**. - 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. - sfskey srpclear Clears the in-memory cache of server self-certifying hostnames built from SRP results. See *srplist*, for more details on this cache. - sfskey srplist Prints the in-memory cache of server self-certifying hostnames built from SRP results. This cache maps SRP names to self-certifying hostnames. SRP names are of the form *user@host*. Sample output of the **sfskey srplist** command might be ``` % sfskey srplist alice@pdos.lcs.mit.edu @amsterdam.lcs.mit.edu,bkfce6jdbmdbzfbct36qgvmpfwzs8exu alice@redlab.lcs @redlab.lcs.mit.edu,gnze6vwxtwssr8mc5ibae7mtufhphzsk alice@ludlow.scs.cs.nyu.edu @ludlow.scs.cs.nyu.edu,hcbafipmin3eqmsgak2m6heequppitiz ``` Currently, the agent consults this cache and adds new mappings to it when a user invokes REX with a DNS (SRP) name. If the name is in the agent's cache, REX will use the corresponding self-certifying hostname to authenticate the server. If not, REX will use SRP to fetch the server's public key and then add a new mapping to the agent's cache. - sfskey srpcacheprogclear Clears the SRP cache management program that the agent runs. See *srpcacheprog*, for more details on cache management programs. - sfskey srpcacheproglist \[-q\] Prints the SRP cache management program that the agent runs. See *srpcacheprog*, for more details on confirmation programs. - sfskey srpcacheprog *prog* \[*arg* ...\] The **srpcacheprog** command registers a command to be run by the agent in order to manage an on-disk copy of the in-memory SRP name cache (described above; ). The agent will invoke the SRP cache management program with zero arguments when it wants to load the on-disk cache into memory and exactly one argument when it wants to add a new entry to the on-disk cache. If no SRP cache management program is set, the agent will simply maintain an in-memory version which will be lost when the agent is restarted. In the first case (load), the program output must consist of one mapping per line. Each mapping must consist of the SRP name followed by a single space followed by the self-certifying hostname. See *srplist*, for an example of what each of these fields might look like. In the second case (store), the agent's argument to the program will consist of a single mapping, to be added to the on-disk cache. The mapping will have the same format described above: the SRP name followed by a single space followed by the self-certifying hostname (no trailing newline). - 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 authserver 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 option 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 (via SRP) or the path to a local file. 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, signifying 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 -k \[***user***\]@***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*. - sfskey user \[-a *key*\] *username* Retrieves a user record from an authentication server. *username* is the name of the user, which can take an optional DNS hostname or self-certifying hostname. Given a simple DNS hostname, the server will attempt SRP to retrieve the server's public key. Using the **-a** is another way to retrieve the key. **sfskey** will query the authentication server for the user and print out the result. - \-a *key* This option 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 (via SRP) or the path to a local file. Usually it will not be necessary to specify keys in the keys directory (*$HOME/.sfs/authkeys*) as they are considered automatically. ## SEE ALSO [*dirsearch*(1)](/dirsearch/1.md), [*newaid*(1)](/newaid/1.md), [*rex*(1)](/rex/1.md), [*sfsagent*(1)](/sfsagent/1.md), [*ssu*(1)](/ssu/1.md), *sfs\_config*(5), [*sfs\_hosts*(5)](/sfs_hosts/5.md), [*sfs\_srp\_params*(5)](/sfs_srp_params/5.md), [*sfs\_users*(5)](/sfs_users/5.md), [*sfsauthd\_config*(5)](/sfsauthd_config/5.md), [*sfscd\_config*(5)](/sfscd_config/5.md), *sfsrosd\_config*(5), [*sfsrwsd\_config*(5)](/sfsrwsd_config/5.md), [*sfssd\_config*(5)](/sfssd_config/5.md), [*sfs\_environ*(7)](/sfs_environ/7.md), [*funmount*(8)](/funmount/8.md), *nfsmounter*(8), [*sfsauthd*(8)](/sfsauthd/8.md), [*sfscd*(8)](/sfscd/8.md), *sfsrosd*(8), *sfsrwcd*(8), [*sfsrwsd*(8)](/sfsrwsd/8.md), [*sfssd*(8)](/sfssd/8.md), [*vidb*(8)](/vidb/8.md) 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