summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/design-schema156
-rw-r--r--perl/Wallet/Schema.pm343
2 files changed, 343 insertions, 156 deletions
diff --git a/docs/design-schema b/docs/design-schema
deleted file mode 100644
index 8e04f49..0000000
--- a/docs/design-schema
+++ /dev/null
@@ -1,156 +0,0 @@
- Database Schema for the Wallet
-
-Introduction
-
- Here should be a comprehensive list of the tables used by the wallet,
- the SQL to create those tables, and a specification of what they're
- for. It's possible that this file will later be written in some other
- format to make extraction of the SQL easier. Please do not copy this
- data into some other file that could get out of sync with this
- documentation; instead, if it's necessary to change the format, please
- move this file elsewhere and keep the documentation with the schema.
-
-Object Metadata
-
- Each object stored in the wallet is represented by an entry in the
- objects table:
-
- create table objects
- (ob_name varchar(255) not null,
- ob_type varchar(16)
- not null references types(ty_name),
- ob_owner integer default null references acls(ac_id),
- ob_acl_get integer default null references acls(ac_id),
- ob_acl_store integer default null references acls(ac_id),
- ob_acl_show integer default null references acls(ac_id),
- ob_acl_destroy integer default null references acls(ac_id),
- ob_acl_flags integer default null references acls(ac_id),
- ob_expires datetime default null,
- ob_created_by varchar(255) not null,
- ob_created_from varchar(255) not null,
- ob_created_on datetime not null,
- ob_stored_by varchar(255) default null,
- ob_stored_from varchar(255) default null,
- ob_stored_on datetime default null,
- ob_downloaded_by varchar(255) default null,
- ob_downloaded_from varchar(255) default null,
- ob_downloaded_on datetime default null,
- primary key (ob_name, ob_type),
- index (ob_owner),
- index (ob_expires));
-
- Object names are not globally unique but only unique within their
- type, so the table has a joint primary key. I haven't yet decided
- what indices the table will need.
-
- Each object has an owner and then up to five more specific ACLs. The
- ob_acl_flags ACL controls who can set flags on this object. Each ACL
- references entries in the following table:
-
- create table acls
- (ac_id integer auto_increment primary key,
- ac_name varchar(255) not null,
- unique index (ac_name));
-
- This just keeps track of unique ACL identifiers. The data is then
- stored in:
-
- create table acl_entries
- (ae_id integer
- not null references acls(ac_id),
- ae_scheme varchar(32)
- not null references acl_schemes(as_name),
- ae_identifier varchar(255)
- not null);
-
- Each object may have zero or more flags associated with it.
-
- create table flags
- (fl_object varchar(255)
- not null references objects(ob_name),
- fl_type varchar(16)
- not null references objects(ob_type),
- fl_flag varchar(32)
- not null references flag_names(fn_name));
-
- Every change made to any object in the wallet database will be
- recorded in this table.
-
- create table object_history
- (oh_id integer auto_increment primary key,
- oh_object varchar(255)
- not null references objects(ob_object),
- oh_type varchar(16)
- not null references objects(ob_type),
- oh_action
- enum('create', 'destroy', 'get', 'store', set') not null,
- oh_field
- enum('owner', 'acl_get', 'acl_store', 'acl_show',
- 'acl_destroy', 'acl_flags', 'expires', 'flags',
- 'type_data'),
- oh_type_field varchar(255),
- oh_from varchar(255),
- oh_to varchar(255),
- oh_by varchar(255) not null,
- oh_from varchar(255) not hull,
- oh_on datetime not null,
- index (oh_object, oh_type));
-
- For a change of type create, get, store, or destroy, only the action
- and the trace records (by, from, and on) are stored. For changes to
- columns or to the flags table, oh_field takes what attribute is
- changed, oh_from takes the previous value converted to a string and
- oh_to takes the next value similarly converted to a string. The
- special field value "type_data" is used when type-specific data is
- changed, and in that case (and only that case) some type-specific name
- for the data being changed is stored in oh_type_field.
-
- Every change made to any ACL in the database will be recorded in this
- table.
-
- create table acl_history
- (ah_id integer auto_increment primary key,
- ah_acl integer not null,
- ah_action enum('create', 'destroy', 'add', 'remove')
- not null,
- ah_scheme varchar(32),
- ah_identifier varchar(255),
- ah_by varchar(255) not null,
- ah_from varchar(255) not null,
- ah_on datetime not null,
- index (ah_acl));
-
- For a change of type create or destroy, only the action and the trace
- records (by, from, and on) are stored. For a change to the lines of
- an ACL, the scheme and identifier of the line that was added or
- removed is included. Note that changes to the ACL name are not
- recorded; ACLs are always tracked by system-generated ID, so name
- changes are purely cosmetic.
-
- The following are normalization tables used to constrain the values
-
- create table types
- (ty_name varchar(16) primary key);
-
- create table acl_schemes
- (as_name varchar(32) primary key);
-
- create table flag_names
- (fn_name varchar(32) primary key);
-
-Storage Backend Data
-
- To support restricting the allowable enctypes for a given keytab, the
- keytab backend will use the following table:
-
- create table keytab_enctypes
- (ke_principal varchar(255)
- not null references objects(ob_name),
- ke_enctype varchar(255)
- not null references enctypes(en_name));
-
- There is a normalization table to ensure that only supported enctypes
- are configured:
-
- create table enctypes
- (en_name varchar(255) primary key);
diff --git a/perl/Wallet/Schema.pm b/perl/Wallet/Schema.pm
new file mode 100644
index 0000000..0e148dd
--- /dev/null
+++ b/perl/Wallet/Schema.pm
@@ -0,0 +1,343 @@
+# Wallet::Schema -- Database schema for the wallet system.
+# $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::Config;
+require 5.006;
+
+use strict;
+use vars qw(@TABLES $VERSION);
+
+use DBI;
+
+# 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';
+
+##############################################################################
+# Implementation
+##############################################################################
+
+# Create a new Wallet::Schema object, parse the SQL out of the documentation,
+# and store it in the object.
+sub new {
+ my ($class) = @_;
+ local $_;
+ my ($found, @sql);
+ $command = '';
+ while (<DATA>) {
+ if (not $found and /^=head1 SCHEMA/) {
+ $found = 1;
+ } elsif ($found and /^=head1 /) {
+ last;
+ } elsif ($found and /^ /) {
+ s/^ //;
+ $command .= $_;
+ if (/;$/) {
+ push (@sql, $command);
+ $command = '';
+ }
+ }
+ }
+ close DATA;
+ my $self = { sql => [ @sql ] };
+ bless ($self, $class);
+ return $self;
+}
+
+# Returns the SQL as a list of commands.
+sub sql {
+ my ($self) = @_;
+ return @{ $self->{sql} };
+}
+
+# Given a database handle, try to create our database by running the SQL. Do
+# this in a transaction regardless of the database settings and throw an
+# exception if this fails.
+sub create {
+ my ($self, $dbh) = @_;
+ eval {
+ $dbh->begin_work;
+ for my $sql (@{ $self->{sql} }) {
+ $dbh->do ($sql, { RaiseError => 1 });
+ }
+ $dbh->commit;
+ };
+ if ($@) {
+ $dbh->rollback;
+ die "$@\n";
+ }
+}
+
+##############################################################################
+# Schema
+##############################################################################
+
+# The following POD is also parsed by the code to extract SQL blocks. Don't
+# add any verbatim blocks to this documentation in the SCHEMA section that
+# aren't intended to be SQL.
+
+1;
+__DATA__
+
+=head1 NAME
+
+Wallet::Schema - Database schema for the wallet system
+
+=head1 SYNOPSIS
+
+ use Wallet::Schema;
+ my $schema = Wallet::Schema->new;
+ my @sql = $schema->sql;
+ $schema->create ($dbh);
+
+=head1 DESCRIPTION
+
+This class encapsulates the database schema for the wallet system. The
+documentation you're reading explains and comments the schema. The Perl
+object extracts the schema from the documentation and can either return it
+as a list of SQL commands to run or run those commands given a connected
+database handle.
+
+This schema attempts to be portable SQL, but it is designed for use with
+MySQL and may require some modifications for other databases.
+
+=head1 METHODS
+
+=over 4
+
+=item new()
+
+Instantiates a new Wallet::Schema object. This parses the documentation and
+extracts the schema, but otherwise doesn't do anything.
+
+=item create(DBH)
+
+Given a connected database handle, runs the SQL commands necessary to create
+the wallet database in an otherwise empty database. This method will not
+drop any existing tables and will therefore fail if a wallet database has
+already been created. On any error, this method will throw a database
+exception.
+
+=item sql()
+
+Returns the schema and the population of the normalization tables as a list
+of SQL commands to run to create the wallet database in an otherwise empty
+database.
+
+=back
+
+=head1 SCHEMA
+
+=head2 Normalization Tables
+
+The following are normalization tables used to constrain the values in other
+tables.
+
+Holds the supported flag names:
+
+ create table flag_names
+ (fn_name varchar(32) primary key);
+ insert into flag_names (fn_name) values ('locked');
+ insert into flag_names (fn_name) values ('unchanging');
+
+Holds the supported object types and their corresponding Perl classes:
+
+ create table types
+ (ty_name varchar(16) primary key,
+ ty_class varchar(64));
+ insert into types (ty_name, ty_class)
+ values ('keytab', 'Wallet::Object::Keytab');
+
+Holds the supported ACL schemes and their corresponding Perl classes:
+
+ create table acl_schemes
+ (as_name varchar(32) primary key,
+ as_class varchar(64));
+ insert into acl_schemes (as_name, as_class)
+ values ('krb5', 'Wallet::ACL::Krb5');
+
+If you have extended the wallet to support additional object types or
+additional ACL schemes, you will want to add additional rows to these tables
+mapping those types or schemes to Perl classes that implement the object or
+ACL verifier APIs.
+
+=head2 ACL Tables
+
+A wallet ACL consists of zero or more ACL entries, each of which is a scheme
+and an identifier. The scheme identifies the check that should be performed
+and the identifier is additional scheme-specific information. Each ACL
+references entries in the following table:
+
+ create table acls
+ (ac_id integer auto_increment primary key,
+ ac_name varchar(255) not null,
+ unique index (ac_name));
+
+This just keeps track of unique ACL identifiers. The data is then stored
+in:
+
+ create table acl_entries
+ (ae_id integer not null references acls(ac_id),
+ ae_scheme varchar(32)
+ not null references acl_schemes(as_name),
+ ae_identifier varchar(255) not null,
+ index (ae_id));
+
+ACLs may be referred to in the API via either the numeric ID or the
+human-readable name, but internally ACLs are always referenced by numeric ID
+so that they can be renamed without requiring complex data modifications.
+
+Currently, the ACL named C<ADMIN> (case-sensitive) is special-cased in the
+Wallet::Server code and granted global access.
+
+Every change made to any ACL in the database will be recorded in this
+table.
+
+ create table acl_history
+ (ah_id integer auto_increment primary key,
+ ah_acl integer not null,
+ ah_action enum('create', 'destroy', 'add', 'remove')
+ not null,
+ ah_scheme varchar(32),
+ ah_identifier varchar(255),
+ ah_by varchar(255) not null,
+ ah_from varchar(255) not null,
+ ah_on datetime not null,
+ index (ah_acl));
+
+For a change of type create or destroy, only the action and the trace
+records (by, from, and on) are stored. For a change to the lines of an ACL,
+the scheme and identifier of the line that was added or removed is included.
+Note that changes to the ACL name are not recorded; ACLs are always tracked
+by system-generated ID, so name changes are purely cosmetic.
+
+ah_by stores the authenticated identity that made the change, ah_from stores
+the host from which they made the change, and ah_on stores the time the
+change was made.
+
+=head2 Object Tables
+
+Each object stored in the wallet is represented by an entry in the objects
+table:
+
+ create table objects
+ (ob_name varchar(255) not null,
+ ob_type varchar(16)
+ not null references types(ty_name),
+ ob_owner integer default null references acls(ac_id),
+ ob_acl_get integer default null references acls(ac_id),
+ ob_acl_store integer default null references acls(ac_id),
+ ob_acl_show integer default null references acls(ac_id),
+ ob_acl_destroy integer default null references acls(ac_id),
+ ob_acl_flags integer default null references acls(ac_id),
+ ob_expires datetime default null,
+ ob_created_by varchar(255) not null,
+ ob_created_from varchar(255) not null,
+ ob_created_on datetime not null,
+ ob_stored_by varchar(255) default null,
+ ob_stored_from varchar(255) default null,
+ ob_stored_on datetime default null,
+ ob_downloaded_by varchar(255) default null,
+ ob_downloaded_from varchar(255) default null,
+ ob_downloaded_on datetime default null,
+ primary key (ob_name, ob_type),
+ index (ob_owner),
+ index (ob_expires));
+
+Object names are not globally unique but only unique within their type, so
+the table has a joint primary key. Each object has an owner and then up to
+five more specific ACLs. The owner provides permission for get, store, and
+show operations if no more specific ACL is set. It does not provide
+permission for destroy or flags.
+
+The ob_acl_flags ACL controls who can set flags on this object. Each object
+may have zero or more flags associated with it:
+
+ create table flags
+ (fl_object varchar(255)
+ not null references objects(ob_name),
+ fl_type varchar(16)
+ not null references objects(ob_type),
+ fl_flag varchar(32)
+ not null references flag_names(fn_name),
+ index (fl_object, fl_type));
+
+Every change made to any object in the wallet database will be recorded in
+this table:
+
+ create table object_history
+ (oh_id integer auto_increment primary key,
+ oh_object varchar(255)
+ not null references objects(ob_object),
+ oh_type varchar(16)
+ not null references objects(ob_type),
+ oh_action
+ enum('create', 'destroy', 'get', 'store', set') not null,
+ oh_field
+ enum('owner', 'acl_get', 'acl_store', 'acl_show',
+ 'acl_destroy', 'acl_flags', 'expires', 'flags',
+ 'type_data'),
+ oh_type_field varchar(255),
+ oh_from varchar(255),
+ oh_to varchar(255),
+ oh_by varchar(255) not null,
+ oh_from varchar(255) not hull,
+ oh_on datetime not null,
+ index (oh_object, oh_type));
+
+For a change of type create, get, store, or destroy, only the action and the
+trace records (by, from, and on) are stored. For changes to columns or to
+the flags table, oh_field takes what attribute is changed, oh_from takes the
+previous value converted to a string and oh_to takes the next value
+similarly converted to a string. The special field value "type_data" is
+used when type-specific data is changed, and in that case (and only that
+case) some type-specific name for the data being changed is stored in
+oh_type_field.
+
+oh_by stores the authenticated identity that made the change, oh_from stores
+the host from which they made the change, and oh_on stores the time the
+change was made.
+
+=head2 Storage Backend Data
+
+The keytab backend supports restricting the allowable enctypes for a given
+keytab. The permitted enctypes are listed in a normalization table:
+
+ create table enctypes
+ (en_name varchar(255) primary key);
+
+and then the restrictions for a given keytab are stored in this table:
+
+ create table keytab_enctypes
+ (ke_principal varchar(255)
+ not null references objects(ob_name),
+ ke_enctype varchar(255)
+ not null references enctypes(en_name),
+ index (ke_principal));
+
+To use this functionality, you will need to populate the enctypes table with
+the enctypes that a keytab may be restricted to. Currently, there is no
+automated mechanism to do this.
+
+=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
generated by cgit v1.2.3 (git 2.39.1) at 2025-11-04 14:05:36 +0000