diff options
| -rw-r--r-- | NEWS | 12 | ||||
| -rw-r--r-- | README | 205 | ||||
| -rw-r--r-- | TODO | 104 |
3 files changed, 271 insertions, 50 deletions
@@ -0,0 +1,12 @@ + User-Visible wallet Changes + +wallet 0.2 (unreleased) + + First public alpha release. Only tested with SQLite 3, no history + support, no object list support, and only keytab object and krb5 ACL + support. + +wallet 0.1 (2007-03-08) + + Internal release containing only kasetkey, a stub client, and design + documentation. @@ -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. @@ -1,6 +1,6 @@ wallet To-Do List -Required to replace leland_srvtab: +Minimum required to replace leland_srvtab: * Add support for limiting the enctypes of created keytabs by setting the enctype attribute on the object and include the enctypes in the object @@ -16,24 +16,13 @@ Required to replace leland_srvtab: * Write the remctl configuration and finish Debian packaging of the wallet client and server. -Future work: - -* Add POD testing for the client and server programs. - -* Add POD coverage testing using Test::POD::Coverage for the server - modules. +Release 0.3: * Provide some way of getting at the history tables. Need to get object and ACL history either by object or for all objects, at least. Global history should be by timestamp and possibly limit by timestamp. -* Provide an interface to list all objects in the database by type, by - owner (including null), or by all uses of an ACL. - -* Provide an interface to list all ACLs in the database. Most - interestingly, an interface to list all empty ACLs. - -* Log all actions to syslog. +* Log all server actions to syslog. * Write the NetDB ACL verifier. @@ -41,6 +30,29 @@ Future work: * Write the PTS ACL verifier. +* Add support for a default creation policy and default ACLs. The policy + function needs to return a list of ACLs, and we'll need an ACL function + to check the user against such a list rather than an ACL that already + exists in the database. When we create such an object, we'll also need + to name the ACL, which may require fallback logic if the name was + already taken. + +* Use the class names in the database tables when loading object and + ACL verifier implementations. + +Release 1.0: + +* Add POD testing for the client and server programs. + +* Add POD coverage testing using Test::POD::Coverage for the server + modules. + +* Provide an interface to list all objects in the database by type, by + owner (including null), or by all uses of an ACL. + +* Provide an interface to list all ACLs in the database. Most + interestingly, an interface to list all empty ACLs. + * Add a help function to wallet-backend listing the commands. * The client may not compile against Heimdal due to changes in how the @@ -54,16 +66,8 @@ Future work: * Add a test suite for kasetkey. -* Use standard error handling routines in the wallet client. - -* Write a conventions document for ACL naming, object naming, and similar - issues. - -* Write a future design and roadmap document to collect notes about how - unimplemented features should be handled. - -* Support displaying and possibly specifying dates in some format more - normal than seconds since epoch. +* Compiling kasetkey should be optional and probably not enabled by + default. * Log failures in the wallet-backend properly, which also requires catching all exceptions. @@ -80,27 +84,9 @@ Future work: * The wallet client should read configuration information from krb5.conf, and possibly from some other configuration as well. -* Add support for a default creation policy and default ACLs. The policy - function needs to return a list of ACLs, and we'll need an ACL function - to check the user against such a list rather than an ACL that already - exists in the database. When we create such an object, we'll also need - to name the ACL, which may require fallback logic if the name was - already taken. - -* Use the class names in the database tables when loading object and - ACL verifier implementations. - * Error messages from ACL operations should refer to the ACLs by name instead of by ID. -* There is a lot of duplicate code in wallet-backend. Convert that to - use some sort of data-driven model with argument count and flags so - that the method calls can be written only once. - -* There's a lot of code duplication in the dispatch functions in the - Wallet::Server class. Find a way to rewrite that so that the dispatch - doesn't duplicate the same code patterns. - * Add the database schema version to a global table so that we can use it to support schema upgrades in the future. @@ -110,14 +96,6 @@ Future work: * Write a wallet-admin program to provide an interface to things like database initialization and, eventually, upgrades. -* Add a function to wallet-admin to purge expired entries. Possibly also - check expiration before allowing anyone to get or store objects. - -* Compiling kasetkey should be optional and probably not enabled by - default. - -* Add a comment field for objects that can be set by the owner. - * Implement store support in the wallet client. Add an option to read the data from a file. The initial implementation, depending on the underlying remctl support, may have to ban nul characters in the @@ -126,6 +104,30 @@ Future work: * Implement a simple file wallet object. Document a naming convention for those files (group-service, perhaps). +Future work: + +* Write a conventions document for ACL naming, object naming, and similar + issues. + +* Write a future design and roadmap document to collect notes about how + unimplemented features should be handled. + +* Support displaying and possibly specifying dates in some format more + normal than seconds since epoch. + +* There is a lot of duplicate code in wallet-backend. Convert that to + use some sort of data-driven model with argument count and flags so + that the method calls can be written only once. + +* There's a lot of code duplication in the dispatch functions in the + Wallet::Server class. Find a way to rewrite that so that the dispatch + doesn't duplicate the same code patterns. + +* Add a function to wallet-admin to purge expired entries. Possibly also + check expiration before allowing anyone to get or store objects. + +* Add a comment field for objects that can be set by the owner. + * Implement an ssh keypair wallet object. The server can run ssh-keygen to generate a public/private key pair and return both to the client, which would split them apart. Used primarily for host keys. May need a @@ -167,6 +169,8 @@ Future work: * Provide a REST implementation of the wallet server. +* Provide a CGI implementation of the wallet server. + * Document all diagnostics for all wallet APIs. * Write a test suite to scan all wallet code looking for diagnostics that |