1 files changed, 31 insertions, 0 deletions
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.)