oracular (3) Wallet::Object::File.3pm.gz

NAME

       Wallet::Object::File - File object implementation for wallet

SYNOPSIS

           my @name = qw(file mysql-lsdb)
           my @trace = ($user, $host, time);
           my $object = Wallet::Object::File->create (@name, $schema, @trace);
           unless ($object->store ("the-password\n")) {
               die $object->error, "\n";
           }
           my $password = $object->get (@trace);
           $object->destroy (@trace);

DESCRIPTION

       Wallet::Object::File is a representation of simple file objects in the wallet.  It implements the wallet
       object API and provides the necessary glue to store a file on the wallet server, retrieve it later, and
       delete it when the file object is deleted.  A file object must be stored before it can be retrieved with
       get.

       To use this object, the configuration option specifying where on the wallet server to store file objects
       must be set.  See Wallet::Config for details on this configuration parameter and information about how to
       set wallet configuration.

METHODS

       This object mostly inherits from Wallet::Object::Base.  See the documentation for that class for all
       generic methods.  Below are only those methods that are overridden or behave specially for this
       implementation.

       destroy(PRINCIPAL, HOSTNAME [, DATETIME])
           Destroys a file object by removing it from the database and deleting the corresponding file on the
           wallet server.  Returns true on success and false on failure.  The caller should call error() to get
           the error message after a failure.  PRINCIPAL, HOSTNAME, and DATETIME are stored as history
           information.  PRINCIPAL should be the user who is destroying the object.  If DATETIME isn't given,
           the current time is used.

       get(PRINCIPAL, HOSTNAME [, DATETIME])
           Retrieves the current contents of the file object or undef on error.  store() must be called before
           get() will be successful.  The caller should call error() to get the error message if get() returns
           undef.  PRINCIPAL, HOSTNAME, and DATETIME are stored as history information.  PRINCIPAL should be the
           user who is downloading the keytab.  If DATETIME isn't given, the current time is used.

       checksum(PRINCIPAL, HOSTNAME [, DATETIME])
           Retrieves the checksum for contents of the file object or undef on error.  PRINCIPAL, HOSTNAME, and
           DATETIME are stored as history information.  PRINCIPAL should be the user who is downloading the
           keytab.  If DATETIME isn't given, the current time is used.

       store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
           Store DATA as the current contents of the file object.  Any existing data will be overwritten.
           Returns true on success and false on failure.  The caller should call error() to get the error
           message after a failure.  PRINCIPAL, HOSTNAME, and DATETIME are stored as history information.
           PRINCIPAL should be the user who is destroying the object.  If DATETIME isn't given, the current time
           is used.

           If FILE_MAX_SIZE is set in the wallet configuration, a store() of DATA larger than that configuration
           setting will be rejected.

FILES

       FILE_BUCKET/<hash>/<file>
           Files are stored on the wallet server under the directory FILE_BUCKET as set in the wallet
           configuration.  <hash> is the first two characters of the hex-encoded MD5 hash of the wallet file
           object name, used to not put too many files in the same directory.  <file> is the name of the file
           object with all characters other than alphanumerics, underscores, and dashes replaced by "%" and the
           hex code of the character.

LIMITATIONS

       The wallet implementation itself can handle arbitrary file object names.  However, due to limitations in
       the remctld server usually used to run wallet-backend, file object names containing nul characters (ASCII
       0) may not be permitted.  The file system used for storing file objects may impose a length limitation on
       the file object name.

SEE ALSO

       remctld(8), Wallet::Config(3), Wallet::Object::Base(3), wallet-backend(8)

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

AUTHORS

       Russ Allbery <eagle@eyrie.org> Bill MacAllister <bill@ca-zephyr.org>