Node:sfskey, Next:rex, Previous:sfsagent, Up:Command reference
sfskey
reference guideThe 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.
sfskey add [-t [hrs:]min] [keyfile]
sfskey add [-t [hrs:]min] [user]@hostname
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 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).
sfskey certclear
sfskey certlist [-q]
sfskey certprog [-p prefix] [-f filter] [-e exclude] prog [arg ...]
certprog
command registers a command to be run to lookup
HostIDs on the fly in the /sfs
directory. This mechanism can be
used for dynamic server authentication--running code to lookup
HostIDs on-demand. When you reference the file
/sfs/prefix/name
, your agent will run the command:
prog arg ... name
If the program succeeds and prints dest to its standard output,
the agent will then create a symbolic link:
/sfs/prefix/name -> dest
The -p
flag can be omitted, and the link is
/sfs/name -> dest
. prefix can be more than one
directory deep (i.e., a series of path components separated by
/
). If so, the first certification program whose prefix matches
at the beginning of prefix is run. The remaining path components
are passed to prog. For example:
NEED EXAMPLE
filter is a perl-style regular expression. If it is specified, then name must contain it for the agent to run prog. exclude is another regular expression, which, if specified, prevents the agent from running prog on names that contain it (regardless of filter).
The program dirsearch
can be used with certprog
to
configure certification paths--lists of directories in which to
look for symbolic links to HostIDs. The usage is:
dirsearch [-clpq] dir1 [dir2 ...] name
dirsearch
searches through a list of directories dir1,
dir2, ... until it finds one containing a file called
name, then prints the pathname dir/name
. If it
does not find a file, dirsearch
exits with a non-zero exit
code. The following options affect dirsearch
's behavior:
-c
-l
dir/name
be a symbolic link, and print
the path of the link's destination, rather than the path of the link
itself.
-p
dir/name
. This is the default
behavior anyway, so the option -p
has no effect.
-q
As an example, to lookup self-certifying pathnames in the directories
$HOME/.sfs/known_hosts
and /mit
, but only accepting links
in /mit
with names ending .mit.edu
, you might execute the
following commands:
% sfskey certprog dirsearch $HOME/.sfs/known_hosts % sfskey certprog -f '\.mit\.edu$' /mnt/links
sfskey delete keyname
add
command).
sfskey deleteall
sfskey edit [-P] [-o outfile] [-c cost] [-n name] [keyname]
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:
-P
-o outfile
-c cost
PwdCost
, pwdcost.
-n name
sfskey list
.
sfskey gen [-KP] [-b nbits] [-c cost] [-n name] [keyfile]
$HOME/.sfs/identity
.
-K
sfskey gen
asks the user to type random text with
which to seed the random number generator. The -K
option
suppresses that behavior.
-P
sfskey gen
should not ask for a passphrase and
the new key should be written to disk in unencrypted form.
-b nbits
-c cost
PwdCost
, pwdcost.
-n name
sfskey list
.
Otherwise, the user will be prompted for a name.
sfskey help
sfskey
commands and their usage.
sfskey hostid hostname
sfskey hostid -
Location:HostID
to standard output. If
hostname is simply -
, returns the name of the current
machine, which is not insecure.
sfskey kill
sfskey list [-ql]
-q
-l
sfskey norevokeset HostID ...
sfskey norevokelist
sfskey register [-KS] [-b nbits] [-c cost] [-u user] [key]
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.
-K
-b nbits
-c cost
sfskey gen
. -K
and
-b
have no effect if the key already exists.
-S
-u user
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
,
sfsauthd_config.
sfskey reset
/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 sesskill remotehost
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
rex
sessions that the agent is maintaining.
sfskey srpgen [-b nbits] file
sfs_srp_params
file, sfs_srp_params.
sfskey update [-S | -s srp_params] [-a {server | -}] oldkey [newkey]
$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:
-S
-s
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
.
-a server
-a -
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.