Imported Upstream version 1.1

1 files changed, 1096 insertions, 0 deletions

diff --git a/perl/lib/Wallet/Server.pm b/perl/lib/Wallet/Server.pm
new file mode 100644
index 0000000..95fd4e6
--- /dev/null
+++ b/perl/lib/Wallet/Server.pm
@@ -0,0 +1,1096 @@
+# Wallet::Server -- Wallet system server implementation.
+#
+# Written by Russ Allbery <eagle@eyrie.org>
+# Copyright 2007, 2008, 2010, 2011, 2013, 2014
+#     The Board of Trustees of the Leland Stanford Junior University
+#
+# See LICENSE for licensing terms.
+
+##############################################################################
+# Modules and declarations
+##############################################################################
+
+package Wallet::Server;
+require 5.006;
+
+use strict;
+use warnings;
+use vars qw(%MAPPING $VERSION);
+
+use Wallet::ACL;
+use Wallet::Config;
+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.11';
+
+##############################################################################
+# Utility methods
+##############################################################################
+
+# 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 $schema = Wallet::Schema->connect;
+    my $acl = Wallet::ACL->new ('ADMIN', $schema);
+    my $self = {
+        schema => $schema,
+        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->{schema}->storage->dbh;
+}
+
+# Returns the DBIx::Class-based database schema object.
+sub schema {
+    my ($self) = @_;
+    return $self->{schema};
+}
+
+# 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) = @_;
+
+    if ($self->{schema}) {
+        $self->{schema}->storage->dbh->disconnect;
+    }
+}
+
+##############################################################################
+# Object methods
+##############################################################################
+
+# Given an object type, return the mapping to a class by querying the
+# database, or undef if no mapping exists.  Also load the relevant module.
+sub type_mapping {
+    my ($self, $type) = @_;
+    my $class;
+    eval {
+        my $guard = $self->{schema}->txn_scope_guard;
+        my %search = (ty_name => $type);
+        my $type_rec = $self->{schema}->resultset('Type')->find (\%search);
+        $class = $type_rec->ty_class;
+        $guard->commit;
+    };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    if (defined $class) {
+        eval "require $class";
+        if ($@) {
+            $self->error ($@);
+            return;
+        }
+    }
+    return $class;
+}
+
+# Given an object which doesn't currently exist, check whether a default_owner
+# function is defined and, if so, if it returns an ACL for that object.  If
+# so, create the ACL and check if the current user is authorized by that ACL.
+# Returns true if so, false if not, setting the internal error as appropriate.
+#
+# This leaves those new ACLs in the database, which may not be the best
+# behavior, but it's the simplest given the current Wallet::ACL API.  This
+# should probably be revisited later.
+sub create_check {
+    my ($self, $type, $name) = @_;
+    my $user = $self->{user};
+    my $host = $self->{host};
+    my $schema = $self->{schema};
+    unless (defined (&Wallet::Config::default_owner)) {
+        $self->error ("$user not authorized to create ${type}:${name}");
+        return;
+    }
+    my ($aname, @acl) = Wallet::Config::default_owner ($type, $name);
+    unless (defined $aname) {
+        $self->error ("$user not authorized to create ${type}:${name}");
+        return;
+    }
+    my $acl = eval { Wallet::ACL->new ($aname, $schema) };
+    if ($@) {
+        $acl = eval { Wallet::ACL->create ($aname, $schema, $user, $host) };
+        if ($@) {
+            $self->error ($@);
+            return;
+        }
+        for my $entry (@acl) {
+            unless ($acl->add ($entry->[0], $entry->[1], $user, $host)) {
+                $self->error ($acl->error);
+                return;
+            }
+        }
+    } else {
+        my @entries = $acl->list;
+        if (not @entries and $acl->error) {
+            $self->error ($acl->error);
+            return;
+        }
+        @entries = sort { $$a[0] cmp $$b[0] && $$a[1] cmp $$b[1] } @entries;
+        @acl     = sort { $$a[0] cmp $$b[0] && $$a[1] cmp $$b[1] } @acl;
+        my $okay = 1;
+        if (@entries != @acl) {
+            $okay = 0;
+        } else {
+            for my $i (0 .. $#entries) {
+                $okay = 0 unless ($entries[$i][0] eq $acl[$i][0]);
+                $okay = 0 unless ($entries[$i][1] eq $acl[$i][1]);
+            }
+        }
+        unless ($okay) {
+            $self->error ("ACL $aname exists and doesn't match default");
+            return;
+        }
+    }
+    if ($acl->check ($user)) {
+        return $aname;
+    } else {
+        $self->error ("$user not authorized to create ${type}:${name}");
+        return;
+    }
+}
+
+# Create an object and returns it.  This function is called by both create and
+# autocreate and assumes that permissions and names have already been checked.
+# On error, returns undef and sets the internal error.
+sub create_object {
+    my ($self, $type, $name) = @_;
+    my $class = $self->type_mapping ($type);
+    unless ($class) {
+        $self->error ("unknown object type $type");
+        return;
+    }
+    my $schema = $self->{schema};
+    my $user = $self->{user};
+    my $host = $self->{host};
+    my $object = eval { $class->create ($type, $name, $schema, $user, $host) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    return $object;
+}
+
+# Create a new object and returns that object.  This method can only be called
+# by wallet administrators.  autocreate should be used by regular users who
+# may benefit from default ACLs.  On error, returns undef and sets the
+# internal error.
+sub create {
+    my ($self, $type, $name) = @_;
+    unless ($self->{admin}->check ($self->{user})) {
+        my $id = $type . ':' . $name;
+        $self->error ("$self->{user} not authorized to create $id");
+        return;
+    }
+    if (defined (&Wallet::Config::verify_name)) {
+        my $error = Wallet::Config::verify_name ($type, $name, $self->{user});
+        if ($error) {
+            $self->error ("${type}:${name} rejected: $error");
+            return;
+        }
+    }
+    return unless $self->create_object ($type, $name);
+    return 1;
+}
+
+# Attempt to auto-create an object based on default ACLs.  This method is
+# called by the wallet client when trying to get an object that doesn't
+# already exist.  On error, returns undef and sets the internal error.
+sub autocreate {
+    my ($self, $type, $name) = @_;
+    if (defined (&Wallet::Config::verify_name)) {
+        my $error = Wallet::Config::verify_name ($type, $name, $self->{user});
+        if ($error) {
+            $self->error ("${type}:${name} rejected: $error");
+            return;
+        }
+    }
+    my $acl = $self->create_check ($type, $name);
+    return unless $acl;
+    my $object = $self->create_object ($type, $name);
+    return unless $object;
+    unless ($object->owner ($acl, $self->{user}, $self->{host})) {
+        $self->error ($object->error);
+        return;
+    }
+    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) = @_;
+    my $class = $self->type_mapping ($type);
+    unless ($class) {
+        $self->error ("unknown object type $type");
+        return;
+    }
+    my $object = eval { $class->new ($type, $name, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    } 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_verify {
+    my ($self, $object, $action) = @_;
+    my %actions = map { $_ => 1 }
+        qw(get store show destroy flags setattr getattr comment);
+    unless ($actions{$action}) {
+        $self->error ("unknown action $action");
+        return;
+    }
+    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');
+    } elsif ($action ne 'comment') {
+        $id = $object->acl ($action);
+    }
+    if (! defined ($id) and $action ne 'flags') {
+        $id = $object->owner;
+    }
+    unless (defined $id) {
+        $self->object_error ($object, $action);
+        return;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    my $status = $acl->check ($self->{user});
+    if ($status == 1) {
+        return 1;
+    } elsif (not defined $status) {
+        $self->error ($acl->error);
+        return;
+    } else {
+        $self->object_error ($object, $action);
+        return;
+    }
+}
+
+# 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 unless defined $object;
+    unless ($self->{admin}->check ($self->{user})) {
+        $self->object_error ($object, 'ACL');
+        return;
+    }
+    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 unless defined $object;
+    my $user = $self->{user};
+    my $host = $self->{host};
+    if (@values) {
+        return unless $self->acl_verify ($object, 'setattr');
+        if (@values == 1 and $values[0] eq '') {
+            @values = ();
+        }
+        my $result = $object->attr ($attr, [ @values ], $user, $host);
+        $self->error ($object->error) unless $result;
+        return $result;
+    } else {
+        return unless $self->acl_verify ($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 comment of an object.
+sub comment {
+    my ($self, $type, $name, $comment) = @_;
+    undef $self->{error};
+    my $object = $self->retrieve ($type, $name);
+    return unless defined $object;
+    my $result;
+    if (defined $comment) {
+        return unless $self->acl_verify ($object, 'comment');
+        $result = $object->comment ($comment, $self->{user}, $self->{host});
+    } else {
+        return unless $self->acl_verify ($object, 'show');
+        $result = $object->comment;
+    }
+    if (not defined ($result) and $object->error) {
+        $self->error ($object->error);
+    }
+    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 unless defined $object;
+    unless ($self->{admin}->check ($self->{user})) {
+        $self->object_error ($object, 'expires');
+        return;
+    }
+    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 unless defined $object;
+    unless ($self->{admin}->check ($self->{user})) {
+        $self->object_error ($object, 'owner');
+        return;
+    }
+    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;
+}
+
+# Checks for the existence of an object.  Returns 1 if it does, 0 if it
+# doesn't, and undef if there was an error in checking the existence of the
+# object.
+sub check {
+    my ($self, $type, $name) = @_;
+    my $object = $self->retrieve ($type, $name);
+    if (not defined $object) {
+        if ($self->error =~ /^cannot find/) {
+            return 0;
+        } else {
+            return;
+        }
+    }
+    return 1;
+}
+
+# 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.  If the object doesn't exist, attempts dynamic creation of the
+# object using the default ACL mappings (if any).
+sub get {
+    my ($self, $type, $name) = @_;
+    my $object = $self->retrieve ($type, $name);
+    return unless defined $object;
+    return unless $self->acl_verify ($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.  If the
+# object doesn't exist, attempts dynamic creation of the object using the
+# default ACL mappings (if any).
+sub store {
+    my ($self, $type, $name, $data) = @_;
+    my $object = $self->retrieve ($type, $name);
+    return unless defined $object;
+    return unless $self->acl_verify ($object, 'store');
+    if (not defined ($data)) {
+        $self->{error} = "no data supplied to store";
+        return;
+    }
+    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 unless defined $object;
+    return unless $self->acl_verify ($object, 'show');
+    my $result = $object->show;
+    $self->error ($object->error) unless defined $result;
+    return $result;
+}
+
+# Return a human-readable description of the object history, or returns undef
+# and sets the internal error if the object can't be found or if the user
+# isn't authorized.
+sub history {
+    my ($self, $type, $name) = @_;
+    my $object = $self->retrieve ($type, $name);
+    return unless defined $object;
+    return unless $self->acl_verify ($object, 'show');
+    my $result = $object->history;
+    $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 unless defined $object;
+    return unless $self->acl_verify ($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 unless defined $object;
+    return unless $self->acl_verify ($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 unless defined $object;
+    return unless $self->acl_verify ($object, 'flags');
+    my $result = $object->flag_set ($flag, $self->{user}, $self->{host});
+    $self->error ($object->error) unless defined $result;
+    return $result;
+}
+
+##############################################################################
+# ACL methods
+##############################################################################
+
+# Checks for the existence of an ACL.  Returns 1 if it does, 0 if it doesn't,
+# and undef if there was an error in checking the existence of the object.
+sub acl_check {
+    my ($self, $id) = @_;
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        if ($@ =~ /^ACL .* not found/) {
+            return 0;
+        } else {
+            $self->error ($@);
+            return;
+        }
+    }
+    return 1;
+}
+
+# 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;
+    }
+    my $user = $self->{user};
+    my $host = $self->{host};
+    if (defined (&Wallet::Config::verify_acl_name)) {
+        my $error = Wallet::Config::verify_acl_name ($name, $user);
+        if ($error) {
+            $self->error ("$name rejected: $error");
+            return;
+        }
+    }
+    my $schema = $self->{schema};
+    my $acl = eval { Wallet::ACL->create ($name, $schema, $user, $host) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    } 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';
+    } elsif ($action eq 'history') {
+        $action = 'see history of';
+    }
+    $self->error ("$self->{user} not authorized to $action ACL $acl");
+}
+
+# Display the history of an ACL or return undef and set the internal error.
+sub acl_history {
+    my ($self, $id) = @_;
+    unless ($self->{admin}->check ($self->{user})) {
+        $self->acl_error ($id, 'history');
+        return;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    my $result = $acl->history;
+    if (not defined $result) {
+        $self->error ($acl->error);
+        return;
+    }
+    return $result;
+}
+
+# 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;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    my $result = $acl->show;
+    if (not defined $result) {
+        $self->error ($acl->error);
+        return;
+    }
+    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;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    if ($acl->name eq 'ADMIN') {
+        $self->error ('cannot rename the ADMIN ACL');
+        return;
+    }
+    if (defined (&Wallet::Config::verify_acl_name)) {
+        my $error = Wallet::Config::verify_acl_name ($name, $self->{user});
+        if ($error) {
+            $self->error ("$name rejected: $error");
+            return;
+        }
+    }
+    unless ($acl->rename ($name, $self->{user}, $self->{host})) {
+        $self->error ($acl->error);
+        return;
+    }
+    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;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    if ($acl->name eq 'ADMIN') {
+        $self->error ('cannot destroy the ADMIN ACL');
+        return;
+    }
+    unless ($acl->destroy ($self->{user}, $self->{host})) {
+        $self->error ($acl->error);
+        return;
+    }
+    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;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    unless ($acl->add ($scheme, $identifier, $self->{user}, $self->{host})) {
+        $self->error ($acl->error);
+        return;
+    }
+    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;
+    }
+    my $acl = eval { Wallet::ACL->new ($id, $self->{schema}) };
+    if ($@) {
+        $self->error ($@);
+        return;
+    }
+    if ($acl->name eq 'ADMIN') {
+        my @e = $acl->list;
+        if (not @e and $acl->error) {
+            $self->error ($acl->error);
+            return;
+        } elsif (@e == 1 && $e[0][0] eq $scheme && $e[0][1] eq $identifier) {
+            $self->error ('cannot remove last ADMIN ACL entry');
+            return;
+        }
+    }
+    my $user = $self->{user};
+    my $host = $self->{host};
+    unless ($acl->remove ($scheme, $identifier, $user, $host)) {
+        $self->error ($acl->error);
+        return;
+    }
+    return 1;
+}
+
+1;
+__END__
+
+##############################################################################
+# Documentation
+##############################################################################
+
+=head1 NAME
+
+Wallet::Server - Wallet system server implementation
+
+=for stopwords
+keytabs metadata backend HOSTNAME ACL timestamp ACL's nul Allbery
+backend-specific wallet-backend verifier
+
+=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 L<Wallet::Config>.
+
+=head1 CLASS METHODS
+
+=over 4
+
+=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
+the name of the ACL 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 clear the ACL, pass in an empty string
+as the ID.  To set or clear 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_history(ID)
+
+Returns the history of the ACL identified by ID, which may be either the
+ACL name or its numeric ID.  To see the history of an ACL, the current
+user must be authorized by the ADMIN ACL.  Each change that modifies the
+ACL (not counting changes in 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.  Returns
+undef 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() afterward.  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 autocreate(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.
+Returns true on success and false on failure.
+
+To create an object using this method, the current user must be authorized
+by the default owner as determined by the wallet configuration.  For more
+information on how to map new objects to default owners, see
+Wallet::Config(3).  Wallet administrators should use the create() method
+to create objects.
+
+=item check(TYPE, NAME)
+
+Check whether an object of type TYPE and name NAME exists.  Returns 1 if
+it does, 0 if it doesn't, and undef if some error occurred while checking
+for the existence of the object.
+
+=item comment(TYPE, NAME, [COMMENT])
+
+Gets or sets the comment for the object identified by TYPE and NAME.  If
+COMMENT is not given, returns the current comment or undef if no comment
+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, no comment
+was set; otherwise, error() will return the error message.
+
+If COMMENT is given, sets the comment to COMMENT.  Pass in the empty
+string for COMMENT to clear the comment.  To set a comment, the current
+user must be the object owner or be on the ADMIN ACL.  Returns true for
+success and false for failure.
+
+=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.
+Returns true on success and false on failure.
+
+To create an object using this method, the current user must be authorized
+by the ADMIN ACL.  Use autocreate() to create objects based on the default
+owner as determined by the wallet configuration.
+
+=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 a member
+of the ADMIN ACL, authorized by the destroy ACL, or authorized by the
+owner ACL; however, if the destroy ACL is set, the owner ACL will not be
+checked.  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, the
+expiration wasn't set; otherwise, error() will return the error message.
+
+If EXPIRES is given, sets the expiration to EXPIRES.  EXPIRES must be in
+the format C<YYYY-MM-DD +HH:MM:SS>, although the time portion may be
+omitted.  Pass in the empty string for EXPIRES to clear the expiration
+date.  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 history(TYPE, NAME)
+
+Returns (as a string) the human-readable history of the object identified
+by TYPE and NAME, or undef on error.  To see the object history, 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 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 the name of the ACL 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 schema()
+
+Returns the DBIx::Class schema object.
+
+=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 <eagle@eyrie.org>
+
+=cut