Provided by: krb5-wallet-client_1.7_amd64 
NAME
wallet - Client for retrieving secure data from a central server
SYNOPSIS
wallet [-hv] [-c command] [-f file]
[-k principal] [-p port] [-s server]
[-S srvtab] [-u principal] command [arg ...]
DESCRIPTION
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.
To run the wallet command-line client, you must either already have a Kerberos ticket or
use the -u option. 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.
OPTIONS
-c command
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.
-f file
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.
-k principal
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.
-h Display a brief summary of options and exit. All other valid options and commands are
ignored.
-p port
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.
-S srvtab
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.
The Kerberos v4 principal name will be generated from the Kerberos v5 principal name
using the krb5_524_conv_principal() function of the Kerberos libraries. See its
documentation for more information, but briefly (and in the absence of special
configuration), 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 the
recognized host-based principals (generally "host", "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.
-s server
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.
-u principal
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.
-v Display the version of the wallet client and exit. All other valid options and
commands are ignored.
COMMANDS
As mentioned above, most commands are only available to wallet administrators. The
exceptions are "acl check", "check", "get", "store", "show", "destroy", "flag clear",
"flag set", "getattr", "setattr", and "history". "acl check" and "check" can be run by
anyone. All of the rest of those commands have their own ACLs except "getattr" and
"history", which use the "show" ACL, "setattr", which uses the "store" ACL, and "comment",
which uses the owner or "show" ACL depending on whether one is setting or retrieving the
comment. If the appropriate ACL is set, it alone is checked to see if the user has
access. Otherwise, "destroy", "get", "store", "show", "getattr", "setattr", "history",
and "comment" 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 "store", 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", "expires", or "comment" without an
argument can still be used on that object.
For more information on attributes, see ATTRIBUTES.
acl add <id> <scheme> <identifier>
Add an entry with <scheme> and <identifier> to the ACL <id>. <id> may be either the
name of an ACL or its numeric identifier.
acl check <id>
Check whether an ACL with the ID <id> already exists. If it does, prints "yes"; if
not, prints "no".
acl create <name>
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.
acl destroy <id>
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.
acl history <id>
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 made.
acl remove <id> <scheme> <identifier>
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.
acl rename <id> <name>
Renames the ACL identified by <id> to <name>. This changes the human-readable name,
not the underlying numeric ID, so the ACL's associations with objects will be
unchanged. The "ADMIN" ACL may not be renamed. <id> may be either the current name
or the numeric ID. <name> must not be all-numeric. To rename an ACL, the current
user must be authorized by the "ADMIN" ACL.
acl replace <id> <new-id>
Find any objects owned by <id>, and then change their ownership to <new_id> instead.
<new-id> should already exist, and may already have some objects owned by it. <id> is
not deleted afterwards, though in most cases that is probably your next step. The
"ADMIN" ACL may not be replaced from. <id> and <new-id> may be either the current
name or the numeric ID. To replace an ACL, the current user must be authorized by the
"ADMIN" ACL.
acl show <id>
Display the name, numeric ID, and entries of the ACL <id>.
autocreate <type> <name>
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 <type> <name>
Check whether an object of type <type> and name <name> already exists. If it does,
prints "yes"; if not, prints "no".
comment <type> <name> [<comment>]
If <comment> is not given, displays the current comment for the object identified by
<type> and <name>, or "No comment set" if none is set.
If <comment> is given, sets the comment on the object identified by <type> and <name>
to <comment>. If <comment> is the empty string, clears the comment.
create <type> <name>
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 <type> <name>
Destroy the object identified by <type> and <name>. With some backends, this will
trigger destruction of an object in an external system as well.
expires <type> <name> [<expires>]
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 <expires> is given, sets the expiration on the object identified by <type> and
<name> to that date (and optionally time). <expires> must be in some format that can
be parsed by the Perl Date::Parse module. Most common formats are supported; if in
doubt, use "YYYY-MM-DD HH:MM:SS". If <expires> is the empty string, clears the
expiration of the object.
Currently, the expiration of an object is not used.
flag clear <type> <name> <flag>
Clears the flag <flag> on the object identified by <type> and <name>.
flag set <type> <name> <flag>
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.
get <type> <name>
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).
getacl <type> <name> <acl>
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.
getattr <type> <name> <attr>
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.
history <type> <name>
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.
owner <type> <name> [<owner>]
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.
setacl <type> <name> <acl> <id>
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.
setattr <type> <name> <attr> <value> [<value> ...]
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 ('').
show <type> <name>
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.
store <type> <name> [<data>]
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.
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).
update <type> <name>
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 will generate new
data in the object, and only works for objects that support generating new data
automatically, such as keytabs or passwords. Types that do not support generating new
data will fail and direct you to use get instead.
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).
ATTRIBUTES
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 Attributes
Keytab objects support the following attributes:
enctypes
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-hmac-sha1-96" 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.
CONFIGURATION
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:
wallet_principal
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.
wallet_port
The port to connect to on the wallet server. The default is the default remctl port.
The -p command-line option overrides this setting.
wallet_server
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.
wallet_type
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.
AUTHOR
Russ Allbery <eagle@eyrie.org>
COPYRIGHT AND LICENSE
Copyright 2007-2008, 2010-2013 The Board of Trustees of the Leland Stanford Junior
University
Copying and distribution of this file, with or without modification, are permitted in any
medium without royalty provided the copyright notice and this notice are preserved. This
file is offered as-is, without any warranty.
SPDX-License-Identifier: FSFAP
SEE ALSO
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
<https://www.eyrie.org/~eagle/software/wallet/>.
wallet uses the remctl protocol. For more information about remctl, see
<https://www.eyrie.org/~eagle/software/remctl/>.