diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 205 |
1 files changed, 205 insertions, 0 deletions
@@ -0,0 +1,205 @@ + wallet release 0.2 + (secure data management system) + + Written by Russ Allbery <rra@stanford.edu> + + Copyright 2006, 2007 Board of Trustees, Leland Stanford Jr. University. + This software is distributed under a BSD-style license. Please see the + file LICENSE in the distribution for more information. + + This software is alpha-quality, and this release is intended as a + technology preview and API preview. This code has never been deployed + in a production environment and considerable work remains before it will + be ready. See the file TODO in the distribution for the list of work + that remains. + +BLURB + + The wallet is a system for managing secure data, authorization rules to + retrieve or change that data, and audit rules for documenting actions + taken on that data. Objects of various types may be stored in the + wallet or generated on request and retrieved by authorized users. The + wallet tracks ACLs, metadata, and trace information. It is built on top + of the remctl protocol and uses Kerberos GSS-API authentication. One of + the object types it supports is Kerberos keytabs, making it suitable as + a user-accessible front-end to Kerberos kadmind with richer ACL and + metadata operations. + +DESCRIPTION + + The wallet is a client/server system using a central server with a + supporting database and a stand-alone client that can be widely + distributed to users. The server runs on a secure host with access to a + local database; tracks object metadata such as ACLs, attributes, + history, expiration, and ownership; and has the necessary access + privileges to create wallet-managed objects in external systems (such as + Kerberos service principals). The client uses the remctl protocol to + send commands to the server, store and retrieve objects, and query + object metadata. The same client can be used for both regular user + operations and wallet administrative actions. + + All wallet actions are controlled by a fine-grained set of ACLs. Each + object has an owner ACL and optional get, store, show, destroy, and + flags ACLs that control more specific actions. A global administrative + ACL controls access to administrative actions. An ACL consists of zero + or more entries, each of which is a generic scheme and identifier pair, + allowing the ACL system to be extended to use any existing authorization + infrastructure. Currently, the only ACL type supported matches a single + Kerberos principal name, but this will be extended in future releases. + + Currently, the only object type supported is a Kerberos keytab. By + default, whenever a Kerberos keytab object is retrieved from the wallet, + the key is changed in the Kerberos KDC and the wallet returns a keytab + for the new key. However, also included in the wallet distribution is a + script that can be run via remctl on the Kerberos KDC to extract the + existing key for a principal, and the wallet system will use that + interface to retrieve the current key if the unchanging flag is set on a + Kerberos keytab object. + + The Kerberos keytab object implementation also optionally supports + synchronization of keys with an AFS kaserver to aid in migration from + Kerberos v4 to Kerberos v5. Included in the wallet distribution is the + kasetkey client, which can create, change the keys of, and delete + principals from an AFS kaserver, authenticating from a srvtab. It is a + partial replacement for kas or a Kerberos v4 kadmin. + +REQUIREMENTS + + The wallet client is written in C and builds against the C remctl + libraries. You will have to install the remctl client libraries in + order to build it. remctl can be obtained from: + + http://www.eyrie.org/~eagle/software/remctl/ + + The wallet client currently requires MIT Kerberos and will need some + minor portability modifications to build with Heimdal. + + The kasetkey program requires AFS libraries and MIT Kerberos and its + Kerberos v4 compatibility libraries. Currently, kasetkey is built + unconditionally. It will become optional and disabled by default in a + future release. + + The wallet server is written in Perl and requires Perl 5.6.0 or later. + It uses the Perl DBI layer to talk to a database, and therefore the DBI + module and a DBD module for the database it will use must be installed. + Currently, the server has only been tested against SQLite 3 and will + probably not work fully with other database backends. It will be ported + to and tested with MySQL for a later release. + + The wallet server is intended to be run under remctld and use remctld to + do authentication. It can be ported to any other front-end, but doing + so will require writing a new version of server/wallet-backend that + translates the actions in that protocol into calls to the Wallet::Server + Perl object. + + The keytab support in the wallet server requires the kadmin client + program be installed and currently assumes that it follows the syntax of + the MIT Kerberos kadmin client. It also requires that the wallet server + have a keytab for a principal with appropriate access to create, modify, + and delete principals from the KDC (as configured in kadm5.acl on an MIT + Kerberos KDC). + + To support the unchanging flag on keytab objects, the Net::Remctl Perl + module (shipped with remctl) must be installed on the server and the + keytab-backend script must be runnable via remctl on the KDC. This + script also requires an MIT Kerberos kadmin.local binary that supports + the -norandkey option to ktadd. This option will be included in MIT + Kerberos 1.7 and later. + + To support synchronization with an AFS kaserver, the server must have + the Authen::Krb5 Perl module installed. + + To run the full test suite, all of the above software requirements must + be met. Tests requiring some bit of software that's not installed will + be skipped, but all the permutations have not yet been checked. The + test suite also requires the Perl modules Test::More and Test::Pod. + Test::More comes with Perl 5.8 or later and is available separately from + CPAN. Test::Pod is available from CPAN. The test suite also requires + that remctld be installed and available on the user's path or in + /usr/local/sbin or /usr/sbin, that test cases can run services on and + connect to ports 14373 and 14444 on 127.0.0.1, and that kinit and kvno + (which come with Kerberos) be installed and available on the user's + path. The full test suite also requires a local keytab, a srvtab with + ADMIN access to a test AFS kaserver, and some additional configuration. + + If you change the Automake files and need to regenerate Makefile.in, you + will need Automake 1.10 or later. If you change configure.ac or any of + the m4 files it includes and need to regenerate configure or + config.h.in, you will need Autoconf 2.61 or later. + +BUILD AND INSTALLATION + + You can build and install wallet with the standard commands: + + ./configure + make + make install + + The last step will probably have to be done as root. Currently, this + always installs both the client and the server. By default, wallet + installs itself under /usr/local except for the server Perl modules, + which are installed into whatever default site module path is used by + your Perl installation. To change the installation location of the + files other than the Perl modules, pass the --prefix=DIR argument to + configure. To change the Perl module installation location, you will + need to run perl on Makefile.PL in the perl subdirectory of the build + tree with appropriate options and rebuild the module after running make + and before running make install. + + If remctl was installed in a path not normally searched by your + compiler, you must specify its installation prefix to configure with the + --with-remctl=DIR option. If the AFS library headers are not found by + your compiler, specify their location with --with-afs-headers=DIR; + similarly, if the AFS libraries are not found by your compiler, specify + their location with --with-afs-libs=DIR. + + Currently, building in a different directory from the source directory + is not supported due to the complexity of integration with the Perl + build process. This will be corrected in a later release. + +TESTING + + The wallet system comes with an extensive test suite which you can run + with: + + make check + + In order to test the client in a meaningful way and test the keytab + support in the server, however, you will need to do some preparatory + work before running the test suite. Review the files: + + tests/data/README + perl/t/data/README + + and follow the instructions in those files to enable the full test + suite. Note that testing the AFS kaserver requires creating a srvtab + with ADMIN access to a running AFS kaserver; if you don't care about AFS + kaserver synchronization, you may want to skip that part of the test + suite configuration. + + The test suite also requires some additional software be installed that + isn't otherwise used by the wallet. See REQUIREMENTS above for the full + list of requirements for the test suite. The test driver attempts to + selectively skip those tests for which the necessary configuration is + not available, but this has not yet been fully tested in all of its + possible permutations. + + If a test case fails, please run that individual test program directly + and send me the output when reporting the problem. + +THANKS + + To Roland Schemers for the original idea that kicked off this project + and for the original implementation of the leland_srvtab system, which + was its primary inspiration. + + To Anton Ushakov for his prior work on Kerberos v5 synchronization and + his enhancements to kasetkey to read a key from an existing srvtab. + + To Jeffrey Hutzelman for his review of the original wallet design and + multiple useful discussions about what actions and configurations the + wallet would need to support to be useful outside of Stanford. + + To Huaqing Zheng, Paul Pavelko, David Hoffman, and Paul Keser for their + reviews of the wallet system design and comments on design decisions and + security models. |