Add standard README and NEWS files and organize TODO a bit more by

release targets.

1 files changed, 205 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..3eca879
--- /dev/null
+++ b/README
@@ -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.