oracular (8) wallet-backend.8.gz

Provided by: krb5-wallet-server_1.5-1.1_all bug

NAME

       wallet-backend - Wallet server for storing and retrieving secure data

SYNOPSIS

       wallet-backend [-q] command [args ...]

DESCRIPTION

       wallet-backend implements the interface between remctld and the wallet system.  It is
       written to run under remctld and expects the authenticated identity of the remote user in
       the REMOTE_USER environment variable.  It uses REMOTE_HOST or REMOTE_ADDR if REMOTE_HOST
       isn't set for additional trace information.  It accepts the command from remctld on the
       command line, creates a Wallet::Server object, and calls the appropriate methods.

       This program is a fairly thin wrapper around Wallet::Server that translates command
       strings into method calls and returns the results.  It does check all arguments except for
       the <data> argument to the store command and rejects any argument not matching
       "^[\w_/.-]+\z"; in other words, only alphanumerics, underscore ("_"), slash ("/"), period
       ("."), and hyphen ("-") are permitted in arguments.  This provides some additional
       security over and above the checking already done by the rest of the wallet code.

OPTIONS

       --quiet, -q
           If this option is given, wallet-backend will not log its actions to syslog.

COMMANDS

       Most commands are only available to wallet administrators (users on the "ADMIN" ACL).  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", "comment", or "expires" 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.

       check <type> <name>
           Check whether an object of type <type> and name <name> already exists.  If it does,
           prints "yes"; if not, prints "no".

       checksum file|password <name>
           Return the checksum for a file or password object.  By default a file objects checksum
           some will be calculated using the perl function md5_hex of the Digest::MD5 module.
           This behavior can be overriden in the wallet configuration file.  See perldoc
           Wallet::Config for complete details.

       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> [<date> [<time>]]
           If <date> 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> and <time> 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 <date> 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>.  This may trigger generation of new data and invalidate old data for that
           object depending on the object type.

       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.

       rename <type> <name> <new-name>
           Renames an existing object.  This currently only supports file objects, where it
           renames the object itself, then the name and location of the object in the file store.

       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 given as an argument, it
           will be read from standard input.

       update <type> <name>
           Prints to standard output the data associated with the object identified by <type> and
           <name>.  If the object is one that can have changing information, such as a keytab or
           password, then we generate new data for that object regardless of whether there is
           current data or the unchanging flag is set.

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.

AUTHOR

       Russ Allbery <eagle@eyrie.org>

       Copyright 2019 Dropbox, Inc.

       Copyright 2007-2008, 2010-2013 The Board of Trustees of the Leland Stanford Junior
       University

       Permission is hereby granted, free of charge, to any person obtaining a copy of this
       software and associated documentation files (the "Software"), to deal in the Software
       without restriction, including without limitation the rights to use, copy, modify, merge,
       publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
       to whom the Software is furnished to do so, subject to the following conditions:

       The above copyright notice and this permission notice shall be included in all copies or
       substantial portions of the Software.

       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
       INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
       PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
       FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
       OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
       DEALINGS IN THE SOFTWARE.

       SPDX-License-Identifier: MIT

SEE ALSO

       Wallet::Server(3), remctld(8)

       This program is part of the wallet system.  The current version is available from
       <https://www.eyrie.org/~eagle/software/wallet/>.