| < wallet Configuration | Russ Allbery > Software > wallet | wallet-backend Manual Page > |
(Client for retrieving secure data from a central server)
wallet [-hv] [-c command] [-f file] [-k principal] [-p port] [-s server] [-S srvtab] [-u principal] command [arg ...]
wallet is a client for the wallet system, which stores or creates secure information such as Kerberos keytabs, associates them with ACLs and other metadata, and allows clients to view and download them. This client provides the user interface to the wallet system for both users and wallet administrators.
The wallet command-line client takes a command and optional arguments on the command line, authenticates to the wallet server using Kerberos, and sends that command and arguments to server. It then reads the results and displays them to the user or stores them in a file. The client itself does not know which commands are valid and which aren't; apart from some special handling of particular commands, it sends all commands to the server to respond to appropriately. This allows additional commands to be added to the wallet system without changing all of the clients.
The primary commands of the wallet system are get, which retrieves
some secure data from the wallet, store, which stores some secure
data in the wallet, and show, which stores the metadata about an
object stored in the wallet. Each object in the wallet has a type, which
determines what data the object represents and may determine special
handling when downloading or storing that object, and a name. For
example, a wallet object for the host/example.com Kerberos keytab
would have a type of keytab and a name of host/example.com.
The meaning of the name is specific to each type of object.
Most other wallet commands besides those three are only available to
wallet administrators. The exception is attribute commands; see
ATTRIBUTES. The other commands allow setting ownership and ACLs on
objects, creating and destroying objects, creating and destroying ACLs,
and adding and removing entries from ACLs. An ACL consists of one or more
entries, each of which is a scheme and an identifier. A scheme specifies
a way of checking whether a user is authorized. An identifier is some
data specific to the scheme that specifies which users are authorized.
For example, for the krb5 scheme, the identifier is a principal
name and only that principal is authorized by that ACL entry. For the
pts scheme, the identifier is a PTS group name, and all members of
that PTS group are authorized by that ACL entry.
To run the wallet command-line client, you must already have a Kerberos ticket. You can obtain a Kerberos ticket with kinit and see your current Kerberos tickets with klist. The wallet client uses the remctl protocol to talk to the wallet server.
The command prefix (remctl type) to use. Normally this is an internal
implementation detail and the default (wallet) should be fine. It
may sometimes be useful to use a different prefix for testing a different
version of the wallet code on the server. This option can also be set in
krb5.conf; see CONFIGURATION below.
This flag is only used in combination with the get and store
commands. For get, rather than sending the secure data to standard
output (the default), the secure data will be stored in file.
For store, the data to be stored will be read from file.
With get, if the object being retrieved is not a keytab object, any
current file named output is renamed to
outout.bak before the new file is created.
outout.new is used as a temporary file and any
existing file with that name will be deleted.
If the object being retrieved is a keytab object and the file
output already exists, the downloaded keys will be added to the
existing keytab file output. Old keys are not removed; you may
wish to run kadmin ktremove or an equivalent later to clean up old
keys. output.new is still used as a temporary
file and any existing file with that name will be deleted.
store does not yet support nul bytes in file (or in any
other way of specifying the data to be stored). To store binary files in
the wallet, you will need to encode them with uuencode, base64, or some
similar scheme and then decode them after retrieval.
The service principal of the wallet server. The default is to use the
host principal for the wallet server. The principal chosen must
match one of the keys in the keytab used by remctld on the wallet
server. This option can also be set in krb5.conf; see
CONFIGURATION below.
Display a brief summary of options and exit. All other valid options and commands are ignored.
The port to connect to on the wallet server. The default is the default remctl port. This option can also be set in krb5.conf; see CONFIGURATION below.
This flag is only used in combination with the get command on a
keytab object, and must be used in conjunction with the -f
flag. After the keytab is saved to the file specified by -f, the
DES key for that principal will be extracted and written as a Kerberos v4
srvtab to the file srvtab. Any existing contents of
srvtab will be destroyed. For more information on how the
principal is converted to Kerberos v4, see the description of the
sync attribute under ATTRIBUTES.
The wallet server to connect to. The default may be set when compiling the wallet client. If it isn't, either -s must be given or the server must be set in krb5.conf. See CONFIGURATION below.
Rather than using the user's existing ticket cache for authentication, authenticate as principal first and use those credentials for authentication to the wallet server. wallet will prompt for the password for principal. Non-password authentication methods such as PKINIT aren't supported; to use those, run kinit first and use an existing ticket cache.
Display the version of the wallet client and exit. All other valid options and commands are ignored.
As mentioned above, most commands are only available to wallet
administrators. The exceptions are get, store, show,
destroy, flag clear, flag set, getattr,
setattr, and history. All of those commands have their own
ACLs except getattr and history, which use the show
ACL, and setattr, which uses the store ACL. If the
appropriate ACL is set, it alone is checked to see if the user has access.
Otherwise, get, store, show, getattr,
setattr, and history access is permitted if the user is
authorized by the owner ACL of the object.
Administrators can run any command on any object or ACL except for
get and store. For get and show, they must
still be authorized by either the appropriate specific ACL or the owner
ACL.
If the locked flag is set on an object, no commands can be run on that
object that change data except the flags commands, nor can the
get command be used on that object. show, history,
getacl, getattr, and owner or expires without
an argument can still be used on that object.
For more information on attributes, see ATTRIBUTES.
Adds an entry with <scheme> and <identifier> to the ACL <id>. <id> may be either the name of an ACL or its numeric identifier.
Create a new, empty ACL with name <name>. When setting an ACL on an
object with a set of entries that don't match an existing ACL, first
create a new ACL with acl create, add the appropriate entries to it
with acl add, and then set the ACL on an object with the
owner or setacl commands.
Destroy the ACL <id>. This ACL must no longer be referenced by any object
or the ACL destruction will fail. The special ACL named ADMIN
cannot be destroyed.
Display the history of the ACL <id>. Each change to the ACL (not including changes to the name of the ACL) will be represented by two lines. The first line will have a timestamp of the change followed by a description of the change, and the second line will give the user who made the change and the host from which the change was mde.
Remove the entry with <scheme> and <identifier> from the ACL <id>. <id>
may be either the name of an ACL or its numeric identifier. The last
entry in the special ACL ADMIN cannot be removed to protect against
accidental lockout, but administrators can remove themselves from the
ADMIN ACL and can leave only a non-functioning entry on the ACL.
Use caution when removing entries from the ADMIN ACL.
Display the name, numeric ID, and entries of the ACL <id>.
Create a new object of type <type> with name <name>. The user must be listed in the default ACL for an object with that type and name, and the object will be created with that default ACL set as the object owner.
Normally, there's no need to run this command directly. It's automatically run when trying to get or store an object that doesn't already exist.
Check whether an object of type <type> and name <name> already exists. If
it does, prints yes; if not, prints no.
Create a new object of type <type> with name <name>. With some backends,
this will trigger creation of an entry in an external system as well. The
new object will have no ACLs and no owner set, so usually the
administrator will want to then set an owner with owner so that the
object will be usable.
Destroy the object identified by <type> and <name>. With some backends, this will trigger destruction of an object in an external system as well.
If <expires> is not given, displays the current expiration of the object
identified by <type> and <name>, or No expiration set if none is
set. The expiration will be displayed in seconds since epoch.
If <date> is given, sets the expiration on the object identified by <type>
and <name> to <date> and (if given) <time>. <date> must be in the format
YYYY-MM-DD and <time> in the format HH:MM:SS. If <date> is
the empty string, clears the expiration of the object.
Currently, the expiration of an object is not used.
Clears the flag <flag> on the object identified by <type> and <name>.
Sets the flag <flag> on the object identified by <type> and <name>.
Recognized flags are locked, which prevents all further actions on
that object until the flag is cleared, and unchanging, which tells
the object backend to not generate new data on get but instead return the
same data as previously returned. The unchanging flag is not
meaningful for objects that do not generate new data on the fly.
Prints to standard output the data associated with the object identified by <type> and <name>, or stores it in a file if the -f option was given. This may trigger generation of new data and invalidate old data for that object depending on the object type.
If an object with type <type> and name <name> does not already exist when this command is issued (as checked with the check interface), wallet will attempt to automatically create it (using autocreate).
Prints the ACL <acl>, which must be one of get, store,
show, destroy, or flags, for the object identified by
<type> and <name>. Prints No ACL set if that ACL isn't set on that
object. Remember that if the get, store, or show
ACLs aren't set, authorization falls back to checking the owner ACL. See
the owner command for displaying or setting it.
Prints the object attribute <attr> for the object identified by <type> and <name>. Attributes are used to store backend-specific information for a particular object type, and <attr> must be an attribute type known to the underlying object implementation. The attribute values, if any, are printed one per line. If the attribute is not set on this object, nothing is printed.
Displays the history for the object identified by <type> and <name>. This human-readable output will have two lines for each action that changes the object, plus for any get action. The first line has the timestamp of the action and the action, and the second line gives the user who performed the action and the host from which they performed it.
If <owner> is not given, displays the current owner ACL of the object
identified by <type> and <name>, or No owner set if none is set.
The result will be the name of an ACL.
If <owner> is given, sets the owner of the object identified by <type> and <name> to <owner>. If <owner> is the empty string, clears the owner of the object.
Sets the ACL <acl>, which must be one of get, store,
show, destroy, or flags, to <id> on the object
identified by <type> and <name>. If <id> is the empty string, clears that
ACL on the object.
Sets the object attribute <attr> for the object identified by <type> and
<name>. Attributes are used to store backend-specific information for a
particular object type, and <attr> must be an attribute type known to the
underlying object implementation. To clear the attribute for this object,
pass in a <value> of the empty string ('').
Displays the current object metadata for the object identified by <type> and <name>. This human-readable output will show the object type and name, the owner, any specific ACLs set on the object, the expiration if any, and the user, remote host, and time when the object was created, last stored, and last downloaded.
Stores <data> for the object identified by <type> and <name> for later
retrieval with get. Not all object types support this. If <data>
is not specified on the command line, it will be read from the file
specified with -f (if given) or from standard input.
Currently, the stored data must not contain nul characters and may therefore not be binary data. Its length is also limited by the maximum command line length of the operating system of the wallet server. These restrictions will be lifted in the future.
If an object with type <type> and name <name> does not already exist when this command is issued (as checked with the check interface), wallet will attempt to automatically create it (using autocreate).
Object attributes store additional properties and configuration
information for objects stored in the wallet. They are displayed as part
of the object data with show, retrieved with getattr, and
set with setattr.
Keytab objects support the following attributes:
Restricts the generated keytab to a specific set of encryption types. The
values of this attribute must be enctype strings recognized by Kerberos
(strings like aes256-cts or des-cbc-crc). Note that the
salt should not be included; since the salt is irrelevant for keytab keys,
it will always be set to normal by the wallet.
If this attribute is set, the specified enctype list will be passed to ktadd when get() is called for that keytab. If it is not set, the default set in the KDC will be used.
This attribute is ignored if the unchanging flag is set on a
keytab. Keytabs retrieved with unchanging set will contain all
keys present in the KDC for that Kerberos principal and therefore may
contain different enctypes than those requested by this attribute.
Sets the external systems to which the key of a given principal is
synchronized. The only supported value for this attribute is
kaserver, which says to synchronize the key with an AFS Kerberos v4
kaserver.
If this attribute is set on a keytab, whenever the get command is
run for that keytab, the DES key will be extracted from that keytab and
set in the configured AFS kaserver. If the -S option is given to
the wallet client, the srvtab corresponding to the keytab will be
written to the file specified with that option. The Kerberos v4 principal
name will be the same as the Kerberos v5 principal name except that the
components are separated by . instead of /; the second
component is truncated after the first . if the first component is
one of host, ident, imap, pop, or smtp;
and the first component is rcmd if the Kerberos v5 principal
component is host. The principal name must not contain more than
two components.
If this attribute is set, calling destroy will also destroy the
principal from the AFS kaserver, with a principal mapping determined as
above.
The realm of the srvtab defaults to the same realm as the keytab. You can change this by setting the v4_realm configuration option in the [realms] section of krb5.conf for the local realm. The keytab must be for a principal in the default local realm for the -S option to work correctly.
wallet can optionally be configured in the system
krb5.conf. It will read the default
krb5.conf file for the Kerberos libraries with which it was
compiled. To set an option, put the option in the
[appdefaults] section. wallet will look for
options either at the top level of the [appdefaults]
section or in a subsection named wallet. For example, the
following fragment of a krb5.conf file would set the
default port to 4373 and the default server to wallet.example.org.
[appdefaults]
wallet_port = 4373
wallet = {
wallet_server = wallet.example.org
}
The supported options are:
The service principal of the wallet server. The default is to use the
host principal for the wallet server. The principal chosen must
match one of the keys in the keytab used by remctld on the wallet
server. The -k command-line option overrides this setting.
The port to connect to on the wallet server. The default is the default remctl port. The -p command-line option overrides this setting.
The wallet server to connect to. The -s command-line option overrides this setting. The default may be set when compiling the wallet client. If it isn't, either -s must be given or this parameter must be present in in krb5.conf.
The command prefix (remctl type) to use. Normally this is an internal
implementation detail and the default (wallet) should be fine. It
may sometimes be useful to use a different prefix for testing a different
version of the wallet code on the server. The -c command-line
option overrides this setting.
kadmin(8), kinit(1), krb5.conf(5), remctl(1), remctld(8)
This program is part of the wallet system. The current version is available from <http://www.eyrie.org/~eagle/software/wallet/>.
wallet uses the remctl protocol. For more information about remctl, see <http://www.eyrie.org/~eagle/software/remctl/>.
Russ Allbery <rra@stanford.edu>
| < wallet Configuration | Russ Allbery > Software > wallet | wallet-backend Manual Page > |