Initial wallet design documentation.

1 files changed, 90 insertions, 0 deletions

diff --git a/doc/design-acl b/doc/design-acl
new file mode 100644
index 0000000..cb07247
--- /dev/null
+++ b/doc/design-acl
@@ -0,0 +1,90 @@
+                     ACL Layer Design for the Wallet
+
+Introduction
+
+    This is a description of the ACL layer of the wallet implementation.
+    This is a specification of the expected behavior of the ACL
+    implementation and includes the syntax and semantics of ACL strings
+    used in the database.  The ACL strings used by the wallet are intended
+    to be an extensible format to which additional ACL backends may be
+    added as needed.  When new ACL backends are added, they should be
+    described here.
+
+Syntax
+
+    An ACL in the wallet consists of two pieces of data, a <scheme> and an
+    <instance>.  <scheme> is one or more characters in the set [a-z0-9-]
+    that identifies the ACL backend to use when interpreting this ACL.
+    <identifier> is zero or more characters including all printable ASCII
+    characters except whitespace.  Only the implementation of <scheme>
+    knows about the meaning of <identifier>.  <identifier> may include
+    zero or more users.
+
+Semantics
+
+    All users are authenticated to the wallet by Kerberos and are
+    therefore represented by a Kerberos principal, which follows the
+    normal Kerberos rules for string representation.
+
+    Whenever there is a question about whether a user is permitted an
+    action by a particular ACL, the following verification algorithm is
+    used:  Iterate through each ACL string on the ACL in question.  If the
+    ACL string is malformatted or the scheme is not recognized, skip it.
+    Otherwise, dispatch the question to the check function of the ACL
+    implementation, passing it the principal identifying the client and
+    the <identifier> portion of the ACL string.  This function returns
+    either authorized or unauthorized.  If authorized, end the search; if
+    unauthorized, continue to the next ACL string.
+
+    There is no support in this scheme for negative ACLs.
+
+    There is one slight complication, namely that some ACL methods need to
+    maintain persistant state for performance reasons (consider, for
+    example, an ACL layer implemented with LDAP queries).  Therefore, each
+    ACL handler should be represented by an object, and when the ACL code
+    discovers it doesn't already have an object on hand for a given ACL
+    scheme, it should construct one before querying it.  If construction
+    fails, it should fail that scheme and any ACL that uses that scheme,
+    but still allow access if an ACL not using that scheme grants access
+    to the user.
+
+ACL Schemes
+
+  krb5
+
+    The <identifier> is a fully-qualified Kerberos principal.  Access is
+    granted if the principal of the client matches <identifier>.
+
+  krb5-group
+
+    <identifier> is the name of a group that contains a list of Kerberos
+    principals.  (Storage of this group is left to the discretion of the
+    backend, but will probably either be a MySQL table or a file on disk.)
+    Access is granted if the principal of the client matches one of the
+    principals contained in the group.
+
+  ldap-entitlement
+
+    <identifier> is an entitlement.  If the entitlement attribute of the
+    LDAP entry corresponding to the given principal contains the
+    entitlement specified in <identifier>, access is granted.
+
+  netdb
+
+    This ACL type is a special case that right now can't be used through
+    the normal ACL mechanism because access depends on the name of the
+    object being accessed through logic peculiar to the backend.  It is
+    included here as a placeholder, but will normally only be used via the
+    backend-specific fallback used when the ACL is not present.
+
+    Access is granted if the action performed is one of the normal owner
+    actions, the object being accessed corresponds to a system key, and
+    the user is an administrator of that system in NetDB (Stanford's
+    system management database).
+
+    For this ACL, <identifier> is empty.
+
+  pts
+
+    <identifier> is the name of an AFS PTS group.  Access is granted if
+    the principal of the user is a member of that AFS PTS group.