diff options
Diffstat (limited to 'docs/metadata')
| -rw-r--r-- | docs/metadata/blurb | 9 | ||||
| -rw-r--r-- | docs/metadata/build/middle | 33 | ||||
| -rw-r--r-- | docs/metadata/description | 31 | ||||
| -rw-r--r-- | docs/metadata/metadata.json | 246 | ||||
| -rw-r--r-- | docs/metadata/quote | 5 | ||||
| -rw-r--r-- | docs/metadata/requirements | 57 | ||||
| -rw-r--r-- | docs/metadata/sections/configuration | 16 | ||||
| -rw-r--r-- | docs/metadata/test/prefix | 8 | ||||
| -rw-r--r-- | docs/metadata/test/suffix | 23 |
9 files changed, 428 insertions, 0 deletions
diff --git a/docs/metadata/blurb b/docs/metadata/blurb new file mode 100644 index 0000000..bd695b0 --- /dev/null +++ b/docs/metadata/blurb @@ -0,0 +1,9 @@ +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. diff --git a/docs/metadata/build/middle b/docs/metadata/build/middle new file mode 100644 index 0000000..8a15117 --- /dev/null +++ b/docs/metadata/build/middle @@ -0,0 +1,33 @@ +If you are upgrading the wallet server from an earlier installed version, +run `wallet-admin upgrade` after installation to upgrade the database +schema. See the wallet-admin manual page for more information. + +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 uses whatever Perl executable exists in the current +`PATH`. That Perl's path is what the server scripts will use, and that +Perl's configuration will be used to determine where the server Perl +modules will be installed. + +To specify a particular Perl executable to use, either set the `PERL` +environment variable or pass it to configure like: + +``` + ./configure PERL=/path/to/my/perl +``` + +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. + +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, or alternately set the path to the include +files and libraries separately with `--with-remctl-include=DIR` and +`--with-remctl-lib=DIR`. diff --git a/docs/metadata/description b/docs/metadata/description new file mode 100644 index 0000000..190c1db --- /dev/null +++ b/docs/metadata/description @@ -0,0 +1,31 @@ +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. Supported ACL types include Kerberos principal names, +regexes matching Kerberos principal names, and LDAP attribute checks. + +Currently, the object types supported are simple files, passwords, +Kerberos keytabs, WebAuth keyrings, and Duo integrations. 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, a keytab object can also be configured to preserve the +existing keys when retrieved. Included in the wallet distribution is a +script that can be run via remctl on an MIT 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 for MIT Kerberos. (Heimdal doesn't require any +special support.) diff --git a/docs/metadata/metadata.json b/docs/metadata/metadata.json new file mode 100644 index 0000000..5e1ad41 --- /dev/null +++ b/docs/metadata/metadata.json @@ -0,0 +1,246 @@ +{ + "name": "wallet", + "version": "1.4", + "synopsis": "secure data management system", + "maintainer": "Russ Allbery <eagle@eyrie.org>", + "copyrights": [ + { + "holder": "Russ Allbery <eagle@eyrie.org>", + "years": "2014, 2016, 2018", + }, + { + "holder": "The Board of Trustees of the Leland Stanford Junior University", + "years": "2006-2010, 2012-2014", + }, + ], + "license": "Expat", + "build": { + "autotools": true, + "automake": "1.11", + "autoconf": "2.64", + "install": true, + "kerberos": true, + "lancaster": true, + "manpages": true, + "reduced_depends": true, + "type": "Autoconf", + }, + "support": { + "email": "eagle@eyrie.org", + "github": "rra/wallet", + "listname": "kerberos@mit.edu", + "listurl": "https://mailman.mit.edu/mailman/listinfo/kerberos", + "web": "https://www.eyrie.org/~eagle/software/wallet/", + }, + "vcs": { + "type": "Git", + "url": "https://git.eyrie.org/git/kerberos/wallet.git", + "browse": "https://git.eyrie.org/?p=kerberos/wallet.git", + "github": "rra/wallet", + "openhub": "https://www.openhub.net/p/wallet", + "travis": "rra/wallet", + }, + "readme": { + "sections": [ + { "title": "Configuration" }, + ], + }, + "quote": { + "author": "John M. Ford", + "work": "Growing Up Weightless", + }, + "distribution": { + "section": "kerberos", + "tarname": "wallet", + "version": "wallet", + }, + "debian": { + "personal": true, + }, + "docs": { + "user": [ + { + "name": "setup", + "title": "Setup and configuration", + }, + { + "name": "config", + "title": "Configuration options", + }, + { + "name": "objects-and-schemes", + "title": "Objects and ACL schemes", + }, + { + "name": "wallet", + "title": "wallet", + }, + { + "name": "wallet-admin", + "title": "wallet-admin", + }, + { + "name": "wallet-backend", + "title": "wallet-backend", + }, + { + "name": "wallet-report", + "title": "wallet-report", + }, + { + "name": "keytab-backend", + "title": "keytab-backend", + }, + { + "name": "naming", + "title": "Stanford wallet naming policy", + }, + { + "name": "thanks", + "title": "Thanks and credits", + }, + ], + "developer": [ + { + "name": "design", + "title": "Overall design", + }, + { + "name": "design-acl", + "title": "ACL design", + }, + { + "name": "design-api", + "title": "Server module API design", + }, + ], + "contrib": [ + { + "name": "used-principals", + "title": "used-principals", + }, + { + "name": "wallet-contacts", + "title": "wallet-contacts", + }, + { + "name": "wallet-rekey-periodic", + "title": "wallet-rekey-periodic", + }, + { + "name": "wallet-summary", + "title": "wallet-summary", + }, + { + "name": "wallet-unknown-hosts", + "title": "wallet-unknown-hosts", + } + ], + "api": [ + { + "name": "api/acl", + "title": "Wallet::ACL", + }, + { + "name": "api/acl-base", + "title": "Wallet::ACL::Base", + }, + { + "name": "api/acl-external", + "title": "Wallet::ACL::External", + }, + { + "name": "api/acl-krb5", + "title": "Wallet::ACL::Krb5", + }, + { + "name": "api/acl-krb5-regex", + "title": "Wallet::ACL::Krb5::Regex", + }, + { + "name": "api/acl-ldap-attr", + "title": "Wallet::ACL::LDAP::Attribute", + }, + { + "name": "api/acl-ldap-attr-root", + "title": "Wallet::ACL::LDAP::Attribute::Root", + }, + { + "name": "api/acl-nested", + "title": "Wallet::ACL::Nested", + }, + { + "name": "api/acl-netdb", + "title": "Wallet::ACL::NetDB", + }, + { + "name": "api/acl-netdb-root", + "title": "Wallet::ACL::NetDB::Root", + }, + { + "name": "api/admin", + "title": "Wallet::Admin", + }, + { + "name": "api/config", + "title": "Wallet::Config", + }, + { + "name": "api/database", + "title": "Wallet::Database", + }, + { + "name": "api/kadmin", + "title": "Wallet::Kadmin", + }, + { + "name": "api/kadmin-ad", + "title": "Wallet::Kadmin::AD", + }, + { + "name": "api/kadmin-heimdal", + "title": "Wallet::Kadmin::Heimdal", + }, + { + "name": "api/kadmin-mit", + "title": "Wallet::Kadmin::MIT", + }, + { + "name": "api/object-base", + "title": "Wallet::Object::Base", + }, + { + "name": "api/object-duo", + "title": "Wallet::Object::Duo", + }, + { + "name": "api/object-file", + "title": "Wallet::Object::File", + }, + { + "name": "api/object-keytab", + "title": "Wallet::Object::Keytab", + }, + { + "name": "api/object-password", + "title": "Wallet::Object::Password", + }, + { + "name": "api/policy-stanford", + "title": "Wallet::Policy::Stanford", + }, + { + "name": "api/report", + "title": "Wallet::Report", + }, + { + "name": "api/schema", + "title": "Wallet::Schema", + }, + { + "name": "api/server", + "title": "Wallet::Server", + }, + ], + }, +} diff --git a/docs/metadata/quote b/docs/metadata/quote new file mode 100644 index 0000000..eafb546 --- /dev/null +++ b/docs/metadata/quote @@ -0,0 +1,5 @@ +An architect +who does not believe +in privacy +may also lack faith +in keeping out the rain diff --git a/docs/metadata/requirements b/docs/metadata/requirements new file mode 100644 index 0000000..b82a52c --- /dev/null +++ b/docs/metadata/requirements @@ -0,0 +1,57 @@ +The wallet client requires the C +[remctl](https://www.eyrie.org/~eagle/software/remctl/) client library and +a Kerberos library. It will build with either MIT Kerberos or Heimdal. + +The wallet server is written in Perl and requires Perl 5.8.0 or later plus +the following Perl modules: + +* Date::Parse (part of the TimeDate distribution) +* DBI +* DBIx::Class +* Module::Build +* SQL::Translator + +You will also need a DBD Perl module for the database backend that you +intend to use, and the DateTime::Format::* module corresponding to that +DBD module (such as DateTime::Format::SQLite or DateTime::Format::PG). + +Currently, the server has only been tested against SQLite 3, MySQL 5, and +PostgreSQL, and prebuilt SQL files (for database upgrades) are only +provided for those servers. It 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 keytab support in the wallet server supports Heimdal and MIT Kerberos +KDCs and has experimental support for Active Directory. The Heimdal +support requires the Heimdal::Kadm5 Perl module. The MIT Kerberos support +requires the MIT Kerberos `kadmin` client program be installed. The +Active Directory support requires the Net::LDAP, Authen::SASL, and +IPC::Run Perl modules and the `msktutil` client program. + +To support the unchanging flag on keytab objects with an MIT Kerberos KDC, +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 is included in +MIT Kerberos 1.7 and later. + +The WebAuth keyring object support in the wallet server requires the +WebAuth Perl module from WebAuth 4.4.0 or later. + +The Duo integration object support in the wallet server requires the +Net::Duo, JSON, and Perl6::Slurp Perl modules. + +The password object support in the wallet server requires the +Crypt::GeneratePassword Perl module. + +The LDAP attribute ACL verifier requires the Authen::SASL and Net::LDAP +Perl modules. This verifier only works with LDAP servers that support +GSS-API binds. + +The NetDB ACL verifier (only of interest at sites using NetDB to manage +DNS) requires the Net::Remctl Perl module. diff --git a/docs/metadata/sections/configuration b/docs/metadata/sections/configuration new file mode 100644 index 0000000..975516d --- /dev/null +++ b/docs/metadata/sections/configuration @@ -0,0 +1,16 @@ +Before setting up the wallet server, review the Wallet::Config +documentation (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, and set up `keytab-backend` and its `remctld` +configuration on your KDC if you want unchanging flag support. + +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. + +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`). diff --git a/docs/metadata/test/prefix b/docs/metadata/test/prefix new file mode 100644 index 0000000..c92c414 --- /dev/null +++ b/docs/metadata/test/prefix @@ -0,0 +1,8 @@ +The wallet comes with a comprehensive test suite, but it requires some +configuration in order to test anything other than low-level utility +functions. To enable the full test suite, follow the instructions in: + +* `tests/config/README` +* `perl/t/data/README` + +Now, you can run the test suite with: diff --git a/docs/metadata/test/suffix b/docs/metadata/test/suffix new file mode 100644 index 0000000..df44eed --- /dev/null +++ b/docs/metadata/test/suffix @@ -0,0 +1,23 @@ +The test suite requires `remctld` be installed and available in the user's +path or in `/usr/local/sbin` or `/usr/sbin`; and that `sqlite3`, `kinit`, +and either `kvno` or `kgetcred` be installed and available on the user's +path. The test suite will also need to be able to bind to 127.0.0.1 on +ports 11119 and 14373 to test client/server network interactions. + +The test suite uses a SQLite database for server-side and end-to-end +testing and therefore requires the DBD::SQLite and +DateTime::Format::SQLite Perl modules. + +All of the requirements listed above will be required to run the full test +suite of server functionality, but tests will be selectively skipped if +their requirements aren't found. + +The following additional Perl modules will be used if present: + +* Test::MinimumVersion +* Test::Pod +* Test::Spelling +* Test::Strict + +All are available on CPAN. Those tests will be skipped if the modules are +not available. |