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>