# Wallet::Server -- Wallet system server implementation.
# $Id$
#
# Written by Russ Allbery <rra@stanford.edu>
# Copyright 2007 Board of Trustees, Leland Stanford Jr. University
#
# See README for licensing terms.

##############################################################################
# Modules and declarations
##############################################################################

package Wallet::Server;
require 5.006;

use strict;
use vars qw(%MAPPING $VERSION);

use Wallet::ACL;
use Wallet::Config;
use Wallet::Object::Keytab;
use Wallet::Schema;

# This version should be increased on any code change to this module.  Always
# use two digits for the minor version with a leading zero if necessary so
# that it will sort properly.
$VERSION = '0.01';

# This is a mapping of object types to class names, used to determine which
# object implementation should be instantiated for a given object type.
# Currently, there's no dynamic way to recognize new object types, so if you
# extend the wallet system to add new object types, you need to modify this
# list.
%MAPPING = (keytab => 'Wallet::Object::Keytab');

##############################################################################
# Utility methods
##############################################################################

# Opens a database connection.  This is an internal class method used by both
# initialize and new.  Throws an exception if anything goes wrong; otherwise,
# returns the open database handle.
sub _open_db {
    my ($class) = @_;
    unless ($Wallet::Config::DB_DRIVER
            and (defined ($Wallet::Config::DB_INFO)
                 or defined ($Wallet::Config::DB_NAME))) {
        die "database connection information not configured\n";
    }
    my $dsn = "DBI:$Wallet::Config::DB_DRIVER:";
    if (defined $Wallet::Config::DB_INFO) {
        $dsn .= $Wallet::Config::DB_INFO;
    } else {
        $dsn .= "database=$Wallet::Config::DB_NAME";
        $dsn .= ";host=$Wallet::Config::DB_HOST" if $Wallet::Config::DB_HOST;
        $dsn .= ";port=$Wallet::Config::DB_PORT" if $Wallet::Config::DB_PORT;
    }
    my $user = $Wallet::Config::DB_USER;
    my $password = $Wallet::Config::DB_PASSWORD;
    my $dbh = DBI->connect ($dsn, $user, $password, { PrintError => 0 });
    if (not defined $dbh) {
        die "cannot connect to database: $DBI::errstr\n";
    }
    $dbh->{AutoCommit} = 0;
    $dbh->{RaiseError} = 1;
    $dbh->{PrintError} = 0;
    return $dbh;
}

# Initializes the database by populating it with our schema and then creates
# and returns a new wallet server object.  This is used only for initial
# database creation.  Takes the Kerberos principal who will be the default
# administrator so that we can create an initial administrator ACL.  Throws an
# exception on failure.
sub initialize {
    my ($class, $user) = @_;
    my $dbh = $class->_open_db;
    my $schema = Wallet::Schema->new;
    $schema->create ($dbh);
    my $acl = Wallet::ACL->create ('ADMIN', $dbh, $user, 'localhost');
    unless ($acl->add ('krb5', $user, $user, 'localhost')) {
        die "$@\n";
    }
    $dbh->disconnect;
    return $class->new ($user, 'localhost');
}

# Create a new wallet server object.  A new server should be created for each
# user who is making changes to the wallet.  Takes the principal and host who
# are sending wallet requests.  Opens a connection to the database that will
# be used for all of the wallet metadata based on the wallet configuration
# information.  We also instantiate the administrative ACL, which we'll use
# for various things.  Throw an exception if anything goes wrong.
sub new {
    my ($class, $user, $host) = @_;
    my $dbh = $class->_open_db;
    my $acl = Wallet::ACL->new ('ADMIN', $dbh);
    my $self = {
        dbh   => $dbh,
        user  => $user,
        host  => $host,
        admin => $acl,
    };
    bless ($self, $class);
    return $self;
}

# Returns the database handle (used mostly for testing).
sub dbh {
    my ($self) = @_;
    return $self->{dbh};
}

# Set or return the error stashed in the object.
sub error {
    my ($self, @error) = @_;
    if (@error) {
        my $error = join ('', @error);
        chomp $error;
        1 while ($error =~ s/ at \S+ line \d+\.?\z//);
        $self->{error} = $error;
    }
    return $self->{error};
}

# Disconnect the database handle on object destruction to avoid warnings.
sub DESTROY {
    my ($self) = @_;
    $self->{dbh}->disconnect;
}

##############################################################################
# Object methods
##############################################################################

# Create a new object and returns that object.  On error, returns undef and
# sets the internal error.
#
# For the time being, we hard-code an ACL named ADMIN to use to authorize
# object creation.  This needs more work later.
sub create {
    my ($self, $type, $name) = @_;
    unless ($MAPPING{$type}) {
        $self->error ("unknown object type $type");
        return undef;
    }
    my $class = $MAPPING{$type};
    my $dbh = $self->{dbh};
    my $user = $self->{user};
    my $host = $self->{host};
    unless ($self->{admin}->check ($user)) {
        $self->error ("$user not authorized to create ${type}:${name}");
        return undef;
    }
    my $object = eval { $class->create ($type, $name, $dbh, $user, $host) };
    if ($@) {
        $self->error ($@);
        return undef;
    } else {
        return 1;
    }
}

# Given the name and type of an object, returns a Perl object representing it
# or returns undef and sets the internal error.
sub retrieve {
    my ($self, $type, $name) = @_;
    unless ($MAPPING{$type}) {
        $self->error ("unknown object type $type");
        return undef;
    }
    my $class = $MAPPING{$type};
    my $object = eval { $class->new ($type, $name, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    } else {
        return $object;
    }
}

# Sets the internal error variable to the correct message for permission
# denied on an object.
sub object_error {
    my ($self, $object, $action) = @_;
    my $user = $self->{user};
    my $id = $object->type . ':' . $object->name;
    if ($action eq 'getattr') {
        $action = "get attributes for";
    } elsif ($action eq 'setattr') {
        $action = "set attributes for";
    } elsif ($action !~ /^(create|get|store|show|destroy)\z/) {
        $action = "set $action for";
    }
    $self->error ("$self->{user} not authorized to $action $id");
}

# Given an object and an action, checks if the current user has access to
# perform that object.  If so, returns true.  If not, returns undef and sets
# the internal error message.  Note that we do not allow any special access to
# admins for get and store; if they want to do that with objects, they need to
# set the ACL accordingly.
sub acl_check {
    my ($self, $object, $action) = @_;
    unless ($action =~ /^(get|store|show|destroy|flags|setattr|getattr)\z/) {
        $self->error ("unknown action $action");
        return undef;
    }
    if ($action ne 'get' and $action ne 'store') {
        return 1 if $self->{admin}->check ($self->{user});
    }
    my $id;
    if ($action eq 'getattr') {
        $id = $object->acl ('show');
    } elsif ($action eq 'setattr') {
        $id = $object->acl ('store');
    } else {
        $id = $object->acl ($action);
    }
    if (! defined ($id) and $action =~ /^(get|(get|set)attr|store|show)\z/) {
        $id = $object->owner;
    }
    unless (defined $id) {
        $self->object_error ($object, $action);
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    my $status = $acl->check ($self->{user});
    if ($status == 1) {
        return 1;
    } elsif (not defined $status) {
        $self->error ($acl->error);
        return undef;
    } else {
        $self->object_error ($object, $action);
        return undef;
    }
}

# Retrieves or sets an ACL on an object.
sub acl {
    my ($self, $type, $name, $acl, $id) = @_;
    undef $self->{error};
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    unless ($self->{admin}->check ($self->{user})) {
        $self->object_error ($object, 'ACL');
        return undef;
    }
    my $result;
    if (defined $id) {
        $result = $object->acl ($acl, $id, $self->{user}, $self->{host});
    } else {
        $result = $object->acl ($acl);
    }
    if (not defined ($result) and $object->error) {
        $self->error ($object->error);
    }
    return $result;
}

# Retrieves or sets an attribute on an object.
sub attr {
    my ($self, $type, $name, $attr, @values) = @_;
    undef $self->{error};
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    my $user = $self->{user};
    my $host = $self->{host};
    if (@values) {
        return unless $self->acl_check ($object, 'setattr');
        my $result = $object->attr ($attr, [ @values ], $user, $host);
        $self->error ($object->error) unless $result;
        return $result;
    } else {
        return unless $self->acl_check ($object, 'getattr');
        my @result = $object->attr ($attr);
        if (not @result and $object->error) {
            $self->error ($object->error);
            return;
        } else {
            return @result;
        }
    }
}

# Retrieves or sets the expiration of an object.
sub expires {
    my ($self, $type, $name, $expires) = @_;
    undef $self->{error};
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    unless ($self->{admin}->check ($self->{user})) {
        $self->object_error ($object, 'expires');
        return undef;
    }
    my $result;
    if (defined $expires) {
        $result = $object->expires ($expires, $self->{user}, $self->{host});
    } else {
        $result = $object->expires;
    }
    if (not defined ($result) and $object->error) {
        $self->error ($object->error);
    }
    return $result;
}

# Retrieves or sets the owner of an object.
sub owner {
    my ($self, $type, $name, $owner) = @_;
    undef $self->{error};
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    unless ($self->{admin}->check ($self->{user})) {
        $self->object_error ($object, 'owner');
        return undef;
    }
    my $result;
    if (defined $owner) {
        $result = $object->owner ($owner, $self->{user}, $self->{host});
    } else {
        $result = $object->owner;
    }
    if (not defined ($result) and $object->error) {
        $self->error ($object->error);
    }
    return $result;
}

# Retrieve the information associated with an object, or returns undef and
# sets the internal error if the retrieval fails or if the user isn't
# authorized.
sub get {
    my ($self, $type, $name) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'get');
    my $result = $object->get ($self->{user}, $self->{host});
    $self->error ($object->error) unless defined $result;
    return $result;
}

# Store new data in an object, or returns undef and sets the internal error if
# the object can't be found or if the user isn't authorized.  Also don't
# permit storing undef, although storing the empty string is fine.
sub store {
    my ($self, $type, $name, $data) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'store');
    if (not defined ($data)) {
        $self->{error} = "no data supplied to store";
        return undef;
    }
    my $result = $object->store ($data, $self->{user}, $self->{host});
    $self->error ($object->error) unless defined $result;
    return $result;
}

# Return a human-readable description of the object's metadata, or returns
# undef and sets the internal error if the object can't be found or if the
# user isn't authorized.
sub show {
    my ($self, $type, $name) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'show');
    my $result = $object->show;
    $self->error ($object->error) unless defined $result;
    return $result;
}

# Destroys the object, or returns undef and sets the internal error if the
# object can't be found or if the user isn't authorized.
sub destroy {
    my ($self, $type, $name) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'destroy');
    my $result = $object->destroy ($self->{user}, $self->{host});
    $self->error ($object->error) unless defined $result;
    return $result;
}

##############################################################################
# Object flag methods
##############################################################################

# Clear a flag on an object.  Takes the object and the flag.  Returns true on
# success or undef and sets the internal error on failure.
sub flag_clear {
    my ($self, $type, $name, $flag) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'flags');
    my $result = $object->flag_clear ($flag, $self->{user}, $self->{host});
    $self->error ($object->error) unless defined $result;
    return $result;
}

# Set a flag on an object.  Takes the object and the flag.  Returns true on
# success or undef and sets the internal error on failure.
sub flag_set {
    my ($self, $type, $name, $flag) = @_;
    my $object = $self->retrieve ($type, $name);
    return undef unless defined $object;
    return undef unless $self->acl_check ($object, 'flags');
    my $result = $object->flag_set ($flag, $self->{user}, $self->{host});
    $self->error ($object->error) unless defined $result;
    return $result;
}

##############################################################################
# ACL methods
##############################################################################

# Create a new empty ACL in the database.  Returns true on success and undef
# on failure, setting the internal error.
sub acl_create {
    my ($self, $name) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->error ("$self->{user} not authorized to create ACL");
        return undef;
    }
    my $dbh = $self->{dbh};
    my $user = $self->{user};
    my $host = $self->{host};
    my $acl = eval { Wallet::ACL->create ($name, $dbh, $user, $host) };
    if ($@) {
        $self->error ($@);
        return undef;
    } else {
        return 1;
    }
}

# Sets the internal error variable to the correct message for permission
# denied on an ACL.
sub acl_error {
    my ($self, $acl, $action) = @_;
    my $user = $self->{user};
    if ($action eq 'add') {
        $action = 'add to';
    } elsif ($action eq 'remove') {
        $action = 'remove from';
    }
    $self->error ("$self->{user} not authorized to $action ACL $acl");
}

# Display the membership of an ACL or return undef and set the internal error.
sub acl_show {
    my ($self, $id) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->acl_error ($id, 'show');
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    my $result = $acl->show;
    if (not defined $result) {
        $self->error ($acl->error);
        return undef;
    }
    return $result;
}

# Change the human-readable name of an ACL or return undef and set the
# internal error.
sub acl_rename {
    my ($self, $id, $name) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->acl_error ($id, 'rename');
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    if ($acl->name eq 'ADMIN') {
        $self->error ('cannot rename the ADMIN ACL');
        return undef;
    }
    unless ($acl->rename ($name)) {
        $self->error ($acl->error);
        return undef;
    }
    return 1;
}

# Destroy an ACL, deleting it out of the database.  Returns true on success.
# On failure, returns undef, setting the internal error.
sub acl_destroy {
    my ($self, $id) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->acl_error ($id, 'destroy');
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    if ($acl->name eq 'ADMIN') {
        $self->error ('cannot destroy the ADMIN ACL');
        return undef;
    }
    unless ($acl->destroy ($self->{user}, $self->{host})) {
        $self->error ($acl->error);
        return undef;
    }
    return 1;
}

# Add an ACL entry to an ACL.  Returns true on success.  On failure, returns
# undef, setting the internal error.
sub acl_add {
    my ($self, $id, $scheme, $identifier) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->acl_error ($id, 'add');
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    unless ($acl->add ($scheme, $identifier, $self->{user}, $self->{host})) {
        $self->error ($acl->error);
        return undef;
    }
    return 1;
}

# Remove an ACL entry to an ACL.  Returns true on success.  On failure,
# returns undef, setting the internal error.
sub acl_remove {
    my ($self, $id, $scheme, $identifier) = @_;
    unless ($self->{admin}->check ($self->{user})) {
        $self->acl_error ($id, 'remove');
        return undef;
    }
    my $acl = eval { Wallet::ACL->new ($id, $self->{dbh}) };
    if ($@) {
        $self->error ($@);
        return undef;
    }
    if ($acl->name eq 'ADMIN') {
        my @e = $acl->list;
        if (not @e and $acl->error) {
            $self->error ($acl->error);
            return undef;
        } elsif (@e == 1 && $e[0][0] eq $scheme && $e[0][1] eq $identifier) {
            $self->error ('cannot remove last ADMIN ACL entry');
            return undef;
        }
    }
    my $user = $self->{user};
    my $host = $self->{host};
    unless ($acl->remove ($scheme, $identifier, $user, $host)) {
        $self->error ($acl->error);
        return undef;
    }
    return 1;
}

1;
__END__

##############################################################################
# Documentation
##############################################################################

=head1 NAME

Wallet::Server - Wallet system server implementation

=head1 SYNOPSIS

    use Wallet::Server;
    my $server = Wallet::Server->new ($user, $host);
    $server->create ('keytab', 'host/example.com@EXAMPLE.COM');

=head1 DESCRIPTION

Wallet::Server is the top-level class that implements the wallet server.
The wallet is a system for storing, generating, and retrieving secure
information such as Kerberos keytabs.  The server maintains metadata about
the objects, checks access against ACLs, and dispatches requests for objects
to backend implementations for that object type.

Wallet::Server is normally instantiated and used by B<wallet-backend>, a
thin wrapper around this object that determines the authenticated remote
user and gets user input and then calls the appropriate method of this
object.

To use this object, several configuration variables must be set (at least
the database configuration).  For information on those variables and how to
set them, see Wallet::Config(3).

=head1 CLASS METHODS

=over 4

=item initialize(PRINCIPAL)

Initializes the database as configured in Wallet::Config and loads the
wallet database schema.  Then, creates an ACL with the name ADMIN and adds
an ACL entry of scheme C<krb5> and instance PRINCIPAL to that ACL.  This
bootstraps the authorization system and lets that Kerberos identity make
further changes to the ADMIN ACL and the rest of the wallet database.
Returns a new Wallet::Server object, although that object should only be
used to do other administrative functions.  Before performing normal
operations, that object should be destroyed and the database reopened with
new().  initialize() uses C<localhost> as the hostname and PRINCIPAL as the
user when logging the history of the ADMIN ACL creation and for any
subsequent actions on the object it returns.

On any error, this method throws an exception.

=item new(PRINCIPAL, HOSTNAME)

Creates a new wallet server object for actions from the user PRINCIPAL
connecting from HOSTNAME.  PRINCIPAL and HOSTNAME will be used for logging
history information for all subsequent operations.  new() opens the
database, using the database configuration as set by Wallet::Config and
ensures that the C<ADMIN> ACL exists.  That ACL will be used to authorize
privileged operations.

On any error, this method throws an exception.

=back

=head1 INSTANCE METHODS

For all methods that can fail, the caller should call error() after a
failure to get the error message.

=over 4

=item acl(TYPE, NAME, ACL [, ID])

Gets or sets the ACL type ACL to ID for the object identified by TYPE and
NAME.  ACL should be one of C<get>, C<store>, C<show>, C<destroy>, or
C<flags>.  If ID is not given, returns the current setting of that ACL as a
numeric ACL ID or undef if that ACL isn't set or on failure.  To distinguish
between an ACL that isn't set and a failure to retrieve the ACL, the caller
should call error() after an undef return.  If error() also returns undef,
that ACL wasn't set; otherwise, error() will return the error message.

If ID is given, sets the specified ACL to ID, which can be either the name
of an ACL or a numeric ACL ID.  To set an ACL, the current user must be
authorized by the ADMIN ACL.  Returns true for success and false for
failure.

ACL settings are checked before the owner and override the owner setting.

=item acl_add(ID, SCHEME, IDENTIFIER)

Adds an ACL entry with scheme SCHEME and identifier IDENTIFIER to the ACL
identified by ID.  ID may be either the ACL name or the numeric ACL ID.
SCHEME must be a valid ACL scheme for which the wallet system has an ACL
verifier implementation.  To add an entry to an ACL, the current user must
be authorized by the ADMIN ACL.  Returns true for success and false for
failure.

=item acl_create(NAME)

Create a new ACL with the specified NAME, which must not be all-numeric.
The newly created ACL will be empty.  To create an ACL, the current user
must be authorized by the ADMIN ACL.  Returns true on success and false on
failure.

=item acl_destroy(ID)

Destroys the ACL identified by ID, which may be either the ACL name or its
numeric ID.  This call will fail if the ACL is still referenced by any
object.  The ADMIN ACL may not be destroyed.  To destroy an ACL, the current
user must be authorized by the ADMIN ACL.  Returns true on success and false
on failure.

=item acl_remove(ID, SCHEME, IDENTIFIER)

Removes from the ACL identified by ID the entry matching SCHEME and
IDENTIFIER.  ID may be either the name of the ACL or its numeric ID.  The
last entry in the ADMIN ACL cannot be removed.  To remove an entry from an
ACL, the current user must be authorized by the ADMIN ACL.  Returns true on
success and false on failure.

=item acl_rename(OLD, NEW)

Renames the ACL identified by OLD to NEW.  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.  OLD may be either the
current name or the numeric ID.  NEW must not be all-numeric.  To rename an
ACL, the current user must be authorized by the ADMIN ACL.  Returns true on
success and false on failure.

=item acl_show(ID)

Returns a human-readable description, including membership, of the ACL
identified by ID, which may be either the ACL name or its numeric ID.  To
show an ACL, the current user must be authorized by the ADMIN ACL (although
be aware that anyone with show access to an object can see the membership of
ACLs associated with that object through the show() method).  Returns the
human-readable description on success and undef on failure.

=item attr(TYPE, NAME, ATTRIBUTE [, VALUE ...])

Sets or retrieves a given object attribute.  Attributes are used to store
backend-specific information for a particular object type and ATTRIBUTE must
be an attribute type known to the underlying object implementation.

If VALUE is not given, returns the values of that attribute, if any, as a
list.  On error, returns the empty list.  To distinguish between an error
and an empty return, call error() afterwards.  It is guaranteed to return
undef unless there was an error.  To retrieve an attribute setting, the user
must be authorized by the ADMIN ACL, the show ACL if set, or the owner ACL
if the show ACL is not set.

If VALUE is given, sets the given ATTRIBUTE values to VALUE, which is one or
more attribute values.  Pass the empty string as the only VALUE to clear the
attribute values.  Returns true on success and false on failure.  To set an
attribute value, the user must be authorized by the ADMIN ACL, the store ACL
if set, or the owner ACL if the store ACL is not set.

=item create(TYPE, NAME)

Creates a new object of type TYPE and name NAME.  TYPE must be a recognized
type for which the wallet system has a backend implementation.  To create an
object, the current user must be authorized by the ADMIN ACL.  Returns true
on success and false on failure.

=item destroy(TYPE, NAME)

Destroys the object identified by TYPE and NAME.  This destroys any data
that the wallet had saved about the object, may remove the underlying object
from other external systems, and destroys the wallet database entry for the
object.  To destroy an object, the current user must be authorized by the
ADMIN ACL or the destroy ACL on the object; the owner ACL is not sufficient.
Returns true on success and false on failure.

=item dbh()

Returns the database handle of a Wallet::Server object.  This is used mostly
for testing; normally, clients should perform all actions through the
Wallet::Server object to ensure that authorization and history logging is
done properly.

=item error()

Returns the error of the last failing operation or undef if no operations
have failed.  Callers should call this function to get the error message
after an undef return from any other instance method.

=item expires(TYPE, NAME [, EXPIRES])

Gets or sets the expiration for the object identified by TYPE and NAME.  If
EXPIRES is not given, returns the current expiration or undef if no
expiration is set or on an error.  To distinguish between an expiration that
isn't set and a failure to retrieve the expiration, the caller should call
error() after an undef return.  If error() also returns undef, that ACL
wasn't set; otherwise, error() will return the error message.

If EXPIRES is given, sets the expiration to EXPIRES, which should be in
seconds since epoch.  To set an expiration, the current user must be
authorized by the ADMIN ACL.  Returns true for success and false for
failure.

=item flag_clear(TYPE, NAME, FLAG)

Clears the flag FLAG on the object identified by TYPE and NAME.  To clear a
flag, the current user must be authorized by the ADMIN ACL or the flags ACL
on the object.

=item flag_set(TYPE, NAME, FLAG)

Sets the flag FLAG on the object identified by TYPE and NAME.  To set a
flag, the current user must be authorized by the ADMIN ACL or the flags ACL
on the object.

=item get(TYPE, NAME)

Returns the data associated with the object identified by TYPE and NAME.
Depending on the object TYPE, this may generate new data and invalidate any
existing data or it may return data previously stored or generated.  Note
that this data may be binary and may contain nul characters.  To get an
object, the current user must either be authorized by the owner ACL or
authorized by the get ACL; however, if the get ACL is set, the owner ACL
will not be checked.  Being a member of the ADMIN ACL does not provide any
special privileges to get objects.

Returns undef on failure.  The caller should be careful to distinguish
between undef and the empty string, which is valid object data.

=item owner(TYPE, NAME [, OWNER])

Gets or sets the owner for the object identified by TYPE and NAME.  If OWNER
is not given, returns the current owner as a numeric ACL ID or undef if no
owner is set or on an error.  To distinguish between an owner that isn't set
and a failure to retrieve the owner, the caller should call error() after an
undef return.  If error() also returns undef, that ACL wasn't set;
otherwise, error() will return the error message.

If OWNER is given, sets the owner to OWNER, which may be either the name of
an ACL or a numeric ACL ID.  To set an owner, the current user must be
authorized by the ADMIN ACL.  Returns true for success and false for
failure.

The owner of an object is permitted to get, store, and show that object, but
cannot destroy or set flags on that object without being listed on those
ACLs as well.

=item show(TYPE, NAME)

Returns (as a string) a human-readable representation of the metadata stored
for the object identified by TYPE and NAME, or undef on error.  Included is
the metadata and entries of any ACLs associated with the object.  To show an
object, the current user must be a member of the ADMIN ACL, authorized by
the show ACL, or authorized by the owner ACL; however, if the show ACL is
set, the owner ACL will not be checked.

=item store(TYPE, NAME, DATA)

Stores DATA for the object identified with TYPE and NAME for later retrieval
with get.  Not all object types support this.  Note that DATA may be binary
and may contain nul characters.  To store an object, the current user must
either be authorized by the owner ACL or authorized by the store ACL;
however, if the store ACL is set, the owner ACL is not checked.  Being a
member of the ADMIN ACL does not provide any special privileges to store
objects.  Returns true on success and false on failure.

=back

=head1 SEE ALSO

wallet-backend(8)

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

=head1 AUTHOR

Russ Allbery <rra@stanford.edu>

=cut