Update the design documentation to reflect the current protocol and

implementation.

1 files changed, 49 insertions, 39 deletions

diff --git a/docs/design b/docs/design
index 0b10a25..f7faa55 100644
--- a/docs/design
+++ b/docs/design
@@ -66,6 +66,8 @@ Server Design
     The wallet server supports the following protocol operations on an
     object:
 
+        autocreate      Create an object with default ACLs
+        check           Determine whether an object exists
         create          Create a new wallet entry for an object
         destroy         Delete the wallet entry for a given object
         owner           Set the owner of an object
@@ -77,25 +79,25 @@ Server Design
         get             Retrieve the named object from the wallet
         store           Store the named object in the wallet
 
-    The first seven operations manipulate or display the metadata of the
+    The first nine operations manipulate or display the metadata of the
     object.  The next two operations store or retrieve the object itself.
 
-    The owner, acl, and expires operations are only available to wallet
-    administrators.  Even if one is the listed owner of an object, one may
-    not change the owner, ACL, or expiration date on that object.  (This
-    may be reconsidered later to permit the owner to set the ACLs on an
-    object.  This design mirrors the existing Stanford University srvtab
-    distribution system and is maximally conservative.)
-
-    Objects are created with a store command, a get command on a object
-    type that supports data generation, or a create command (which creates
-    the metadata without storing any data).  Administrators can create
-    objects with the create command.  Object creation via get or store
-    only happens via local policy.  When someone attempts to get or store
-    an object that doesn't already exist, the type and name of the object
-    and the operation is passed to a policy function, which returns an
-    ACL.  If the user is authorized by that ACL, the object is created and
-    that ACL becomes the object's new owner.
+    The create, owner, acl, and expires operations are only available to
+    wallet administrators.  Even if one is the listed owner of an object,
+    one may not change the owner, ACL, or expiration date on that object.
+    (This may be reconsidered later to permit the owner to set the ACLs on
+    an object.  This design mirrors the existing Stanford University
+    srvtab distribution system and is maximally conservative.)
+
+    Objects are created with an autocreate or a create command (which
+    creates the metadata without storing any data).  Administrators can
+    create objects with the create command.  Object creation via
+    autocreate.  When someone attempts to get or store an object that
+    doesn't already exist, as determined by the check call, the wallet
+    client attempts autocreate.  On the server, the type and name of the
+    object and the operation is passed to a policy function, which returns
+    an ACL.  If the user is authorized by that ACL, the object is created
+    and that ACL becomes the object's new owner.
 
   ACLs
 
@@ -153,14 +155,23 @@ Server Design
     * Trace fields storing the user, remote host, and timestamp for when
       this object was last created, stored, and downloaded.
 
-  Keytab-Specific Metadata
+  Type-Specific Attributes
 
-    Objects of type keytab have one additional piece of metadata: an
-    optional list of enctypes for which keys should be generated for that
-    principal.  This list can be used to restrict the Kerberos enctypes
-    for a particular keytab to only those supported by that application.
-    In the absence of a list associated with a keytab, the default enctype
-    list in the KDC will be used.
+    Object types may support additional attributes, which are keys and
+    lists of values.  The acceptable keys and values are determined by the
+    individual object implementations.  For many object types, no
+    attributes are supported.
+
+    Objects of type keytab support two attributes: an optional list of
+    enctypes for which keys should be generated for that principal, and an
+    optional list of external systems with which the keytab is
+    synchronized.  The enctype list list can be used to restrict the
+    Kerberos enctypes for a particular keytab to only those supported by
+    that application.  In the absence of a list associated with a keytab,
+    the default enctype list in the KDC will be used.  The sync attribute
+    currently only supports a value of kaserver, which means that the DES
+    key in the keytab is set as the key for a corresponding principal in
+    an AFS kaserver.
 
   Flags
 
@@ -202,24 +213,20 @@ Keytab Server Backend
 
   NetDB Default ACLs
 
-    If a user attempts to get a keytab for which no entry had previously
-    been created with create and that keytab is one of a specific set of
-    host-bound principals as configured by the local wallet server
-    deployment (generally things like host/*), we will check the principal
-    against an ACL of scheme netdb and identifier equal to the host name
-    for the principal (after chasing CNAMEs).  If that ACL authorizes the
+    For Stanford's purposes, if a user attempts to autocreate keytab for
+    which no entry had previously been created with create and that keytab
+    is one of a specific set of host-bound principals as configured by the
+    local wallet server deployment (generally things like host/*), we will
+    check the principal against an ACL of scheme netdb and identifier
+    equal to the host name for the principal.  If that ACL authorizes the
     user, we will automatically create a wallet entry for this host, owned
     by an ACL of scheme netdb and identifier equal to the fully qualified
     name of the system.  This will allow anyone with NetDB ownership of
     the system to manage the keytabs.
 
-    Note that this does leave the system open to a potential attack via
-    DNS by spoofing a CNAME return and hence fooling the wallet into
-    thinking that a particular host is an alias for a host that the user
-    has NetDB roles to manage when it actually isn't.  This attack can
-    only allow the user to create a keytab that doesn't already exist,
-    however, so the impact seems slight given the difficulty of the
-    attack.
+    This is implemented via a Stanford-specific wallet configuration file
+    that uses the server autocreate support.  See examples/stanford.conf
+    to see how this is implemented.
 
   Retrieving Existing Keytabs
 
@@ -254,7 +261,9 @@ Client Design
     operations (although we will skip store for the initial implementation
     since it's not required for keytabs), and in general should pass any
     command on to the server so that we can add new commands later without
-    modifying the client code.
+    modifying the client code.  When called with a get or store command,
+    it should check whether the object already exists with the check
+    command and, if not, attempt autocreation with the autocreate command.
 
     When retrieving a keytab, the client should support either creating a
     new keytab file or adding the keys from the downloaded keytab to an
@@ -274,7 +283,8 @@ Client Design
     ticket.
 
     Similarly, whenever a keytab is created or changed, the server needs
-    to synchronize the key with Kerberos v4.
+    to synchronize the key with Kerberos v4 (using the sync attribute on
+    keytab objects).
 
 Security Considerations