wallet release 0.8
(secure data management system)
Written by Russ Allbery <rra@stanford.edu>
Copyright 2006, 2007, 2008 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 beta-quality and should be treated with caution. It is
currently being tested for production deployment at Stanford.
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 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 MySQL 5
and will probably not work fully with other database backends. Porting
is welcome.
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 file object support in the wallet server requires the Digest::MD5
Perl module, which comes with recent versions of Perl and is available
on CPAN for older versions.
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 the NetDB ACL verifier (only of interest at sites using NetDB
to manage DNS), the Net::Remctl Perl module must be installed on the
server.
To support synchronization with an AFS kaserver, the server must have
the Authen::Krb5 Perl module installed. AFS kaserver synchronization
support also requires building kasetkey, which requires AFS and Kerberos
v4 libraries.
To run the test suite, you must have the Perl modules Test::More,
IO::String, and DBI installed. You will also need a DBD module
installed for the database backend you want to use (currently, either
DBD::SQLite or DBD::mysql). Test::More comes with Perl 5.8 or later.
The other modules are available from CPAN and may be available as
part of your OS (many Linux distributions have them as packages, for
example).
To run the full test suite, additionally all of the above software
requirements must be met. Tests requiring some bit of software that's
not installed should be skipped, but not all the permutations have been
checked. The test suite also requires Perl 5.8 or later, the Test::Pod
Perl module (available from CPAN), 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.
You can pass the --with-wallet-server and --with-wallet-port options to
configure to compile in a default wallet server and port. If no port is
set, the remctl default port is used. If no server is set, the server
must be specified either in krb5.conf configuration or on the wallet
command line or the client will exit with an error.
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 GSS-API libraries used by remctl
aren't in a path normally searched by your compiler, you must generally
also specify its installation prefix with the --with-gssapi=DIR option.
Normally, configure will use krb5-config to determine the flags to use
to compile with your Kerberos libraries. If krb5-config isn't found, it
will look for the standard Kerberos libraries in locations already
searched by your compiler. If the the krb5-config script first in your
path is not the one corresponding to the Kerberos libraries you want to
use or if your Kerberos libraries and includes aren't in a location
searched by default by your compiler, you need to specify
--with-krb5=PATH:
./configure --with-krb5=/usr/pubsw
To specify a particular krb5-config script to use, either set the
KRB5_CONFIG environment variable or pass it to configure like:
./configure KRB5_CONFIG=/path/to/krb5-config
To build with AFS kaserver synchronization support, pass --with-afs to
configure. You may need to include the path to the AFS include files
and libraries, such as:
./configure --with-afs=/usr/afsws
The AFS kaserver support also requires Kerberos v4 libraries and tries
to use krb5-config to find such libraries. If your Kerberos v4
libraries aren't somewhere found by your compiler and the krb5-config
script doesn't produce correct results, you need to specify
--with-krb4=PATH giving the root path of the Kerberos v4 installation.
You can pass the --enable-reduced-depends flag to configure to try to
minimize the shared library dependencies encoded in the binaries. This
omits from the link line all the libraries included solely because the
Kerberos libraries depend on them and instead links the programs only
against libraries whose APIs are called directly. This will only work
with shared Kerberos libraries and will only work on platforms where
shared libraries properly encode their own dependencies (such as Linux).
It is intended primarily for building packages for Linux distributions
to avoid encoding unnecessary shared library dependencies that make
shared library migrations more difficult. If none of the above made any
sense to you, don't bother with this flag.
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.
CONFIGURATION
For the basic setup and configuration of the wallet server, see the file
docs/setup in the source distribution. You will need to set up a
database on the server (unless you're using SQLite), initialize the
database, install remctld and the wallet Perl modules, and set up
remctld to run the wallet-backend program.
Before setting up the wallet server, review the Wallet::Config
docuemntation (with man Wallet::Config or perldoc Wallet::Config).
There are many customization options, some of which must be set. You
may also need to create a Kerberos keytab for the keytab object backend
and give it appropriate ACLs, set up keytab-backend and its remctld
configuration on your KDC if you want unchanging flag support, and set
up a srvtab if you want AFS kaserver synchronization support.
The wallet client supports reading configuration settings from the
system krb5.conf file. For more information, see the CONFIGURATION
section of the wallet client man page (man wallet).
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.
