Ubuntu Manpage: wallet - Client for retrieving secure data from a central server

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