diff options
Diffstat (limited to 'perl/Wallet')
| -rw-r--r-- | perl/Wallet/Admin.pm | 193 | ||||
| -rw-r--r-- | perl/Wallet/Server.pm | 55 |
2 files changed, 193 insertions, 55 deletions
diff --git a/perl/Wallet/Admin.pm b/perl/Wallet/Admin.pm new file mode 100644 index 0000000..400068d --- /dev/null +++ b/perl/Wallet/Admin.pm @@ -0,0 +1,193 @@ +# Wallet::Admin -- Wallet system administrative interface. +# $Id$ +# +# Written by Russ Allbery <rra@stanford.edu> +# Copyright 2008 Board of Trustees, Leland Stanford Jr. University +# +# See LICENSE for licensing terms. + +############################################################################## +# Modules and declarations +############################################################################## + +package Wallet::Admin; +require 5.006; + +use strict; +use vars qw($VERSION); + +use Wallet::ACL; +use Wallet::Database; +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'; + +############################################################################## +# Constructor, destructor, and accessors +############################################################################## + +# Create a new wallet administrator object. Opens a connection to the +# database that will be used for all of the wallet configuration information. +# Throw an exception if anything goes wrong. +sub new { + my ($class) = @_; + my $dbh = Wallet::Database->connect; + my $self = { dbh => $dbh }; + 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 unless $self->{dbh}->{InactiveDestroy}; +} + +############################################################################## +# Database initialization +############################################################################## + +# 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. Returns +# true on success and false on failure, setting the object error. +sub initialize { + my ($self, $user) = @_; + my $schema = Wallet::Schema->new; + eval { $schema->create ($self->{dbh}) }; + if ($@) { + $self->error ($@); + return; + } + my $acl = Wallet::ACL->create ('ADMIN', $self->{dbh}, $user, 'localhost'); + unless ($acl->add ('krb5', $user, $user, 'localhost')) { + $self->error ($acl->error); + return; + } + return 1; +} + +# The same as initialize, but also drops any existing tables first before +# creating the schema. Takes the same arguments and throws an exception on +# failure. +sub reinitialize { + my ($self, $user) = @_; + my $schema = Wallet::Schema->new; + eval { $schema->drop ($self->{dbh}) }; + if ($@) { + $self->error ($@); + return; + } + return $self->initialize ($user); +} + +1; +__DATA__ + +############################################################################## +# Documentation +############################################################################## + +=head1 NAME + +Wallet::Admin - Wallet system administrative interface + +=head1 SYNOPSIS + + use Wallet::Admin; + my $admin = Wallet::Admin->new; + unless ($admin->initialize ('user/admin@EXAMPLE.COM')) { + die $admin->error; + } + +=head1 DESCRIPTION + +Wallet::Admin implements the administrative interface to the wallet server +and database. It is normally instantiated and used by B<wallet-admin>, a +thin wrapper around this object that provides a command-line interface to +its actions. + +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). For more information on the normal user +interface to the wallet server, see Wallet::Server(3). + +=head1 CLASS METHODS + +=over 4 + +=item new() + +Creates a new wallet administrative object and connects to the database. +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 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. + +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. + +=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 reinitialize(PRINCIPAL) + +Performs the same actions as initialize(), but first drops any existing +wallet database tables from the database, allowing this function to be +called on a prior wallet database. All data stored in the database will +be deleted and a fresh set of wallet database tables will be created. + +=back + +=head1 SEE ALSO + +wallet-admin(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 diff --git a/perl/Wallet/Server.pm b/perl/Wallet/Server.pm index 68add52..96cff15 100644 --- a/perl/Wallet/Server.pm +++ b/perl/Wallet/Server.pm @@ -30,36 +30,6 @@ $VERSION = '0.06'; # Utility methods ############################################################################## -# 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 = Wallet::Database->connect; - 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'); -} - -# The same as initialize, but also drops any existing tables first before -# creating the schema. Takes the same arguments and throws an exception on -# failure. -sub reinitialize { - my ($class, $user) = @_; - my $dbh = Wallet::Database->connect; - my $schema = Wallet::Schema->new; - $schema->drop ($dbh); - $dbh->disconnect; - return $class->initialize ($user); -} - # 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 @@ -738,22 +708,6 @@ set them, see Wallet::Config(3). =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 @@ -765,15 +719,6 @@ privileged operations. On any error, this method throws an exception. -=item reinitialize(PRINCIPAL) - -Performs the same actions as initialize(), but first drops any existing -wallet database tables from the database, allowing this function to be -called on a prior wallet database. All data stored in the database will be -deleted and a fresh set of wallet database tables will be created. - -On any error, this method throws an exception. - =back =head1 INSTANCE METHODS |