Rephrase the invirt.authz.locker._authenticate docstring for clarity.

(Based on comments from price)

svn path=/trunk/packages/invirt-base/; revision=2571

diff --git a/python/invirt/authz/locker.py b/python/invirt/authz/locker.py
index a564e10..cf33d5e 100644 (file)
--- a/python/invirt/authz/locker.py
+++ b/python/invirt/authz/locker.py
@@ -69,27 +69,20 @@ def expandAdmin(name, owner):
 
 
 def _authenticate(cell):
-    """Acquire credentials if possible for a particular cell.
-
-    This function returns True if an authenticated connection to the
-    cell should be established; False otherwise.
-
-    If a cell isn't explicitly listed in the configuration file,
-    _authenticate will assume that it /should/ authenticate to the
-    cell.
-
-    The assumption is that choosing to authenticate to a cell will
-    fail in two cases: (a) the cell authenticates against the
-    machine's home realm and there is no PTS ID in the cell, or (b)
-    the cell doesn't authenticate against the machine's home realm and
-    doesn't have cross-realm authentication setup.
-
-    In the former case, it should be possible for the sysadmins to
-    list all cells that authenticate against the home realm (including
-    those where attempting authentication would be problematic). In
-    the latter case, such a cell would be at best distantly connected
-    to the home cell, and we probably don't want to give it quota
-    anyway.
+    """Acquire AFS tokens for a cell if encryption is required by config.
+
+    If the Invirt configuration requires connections to this cell to
+    be encrypted, acquires tokens and returns True. Otherwise, returns
+    False. Consumers of this function must still be sure to encrypt
+    their own connections if necessary.
+
+    Cells not listed in the Invirt configuration default to requiring
+    encryption in order to maintain security by default.
+
+    Due to AFS's cross-realm auto-PTS-creation mechanism, using
+    authenticated connections by default should only fail for cells
+    which authenticate directly against the machine's home realm and
+    cells distantly related to the machine's home realm.
     """
     for c in config.authz.cells:
         if c.cell == cell and not c.auth: