notes/authz_policy.txt

   1                              -*- text -*-
   2
   3 This file documents what users should expect from path-based authz,
   4 and the responsibilities of the implementor of said feature.
   5
   6
   7 ============================================================================
   8 WHAT USERS SHOULD EXPECT FROM PATH-BASED AUTHZ
   9 ============================================================================
  10
  11 1. CHECKOUTS
  12
  13    Unreadable paths will not be downloaded into a working copy.
  14    However, 'svn update' may cause working paths to disappear or
  15    re-appear based on changing server authorization policies.
  16
  17    (Note: the .svn/entries file may still leak the name of the
  18    unreadable path; see the 'Known Leakage' section below.)
  19
  20
  21 2. LOG MESSAGES
  22
  23    Log information may be restricted, based on readability of
  24    changed-paths.
  25
  26      * If the target of 'svn log' wanders into unreadable territory,
  27        then log output will simply stop at the last readable revision.
  28        If the log is tracing backwards through time, as the plain
  29        "svn log" command does, the target will appear to be added
  30        (without history) in that revision.
  31
  32      * If a revision returned by 'svn log' contains a mixture of
  33        readable/unreadable changed-paths, then the log message is
  34        suppressed, along with the unreadable changed-paths.  Only the
  35        revision number, author, date, and readable paths are
  36        displayed.
  37
  38      * If a revision returned by 'svn log' contains only unreadable
  39        changed-paths, then only the revision number is displayed.
  40
  41    It's an official recommendation ("best practice") to avoid the
  42    "mixed" changed-path situation; users should avoid making a single
  43    commit that includes changes to files in both readable and
  44    unreadable areas.  This scenario is quite annoying for people who
  45    can't read all the changed-paths.
  46
  47
  48 3. COPIES (BRANCHING AND TAGGING)
  49
  50    Subversion does O(1) copies of entire trees, but unfortunately,
  51    this isn't completely compatible with path-based access control.
  52    In order to copy an entire tree, every path in the tree must be
  53    checked for readability: this is an O(N) operation.
  54
  55    Depending on the specific path-based authz module being used,
  56    however, there are sometimes solutions that aren't quite so
  57    expensive as O(N).
  58
  59
  60 4. TRACING PATH CHANGES
  61
  62    If a Subversion 1.1 client attempts to fetch an older version of a
  63    file or directory, e.g.:
  64
  65        svn cat -r5 foo.c
  66        svn diff -r10:28 bar.c
  67
  68    ...then there is a potential for failure, should older versions of
  69    the file exist at unreadable paths.  In other words, the tracing of
  70    copies/renames is subject to readability checks.
  71
  72    If history-tracing wanders into unreadable territory, the process
  73    halts; no further information is retrieved.
  74
  75       Example 1: while 'bar.c' might be perfectly readable in both
  76       revisions 10 and 28, the 'svn diff' command (above) will return
  77       error if the file has an unreadable ancestor somewhere between
  78       those two revisions.
  79
  80       Example 2: 'svn blame bar.c' will not be able to retrieve
  81       unauthorized versions of a file, or any ancestors that precede
  82       it.  So it will appear that 'bar.c' was wholly added -- without
  83       history -- in the first public version *after* the unreadable
  84       version.
  85
  86    So again, an official recommendation ("best practice") is to avoid
  87    renaming or copying files between public and private areas.  For
  88    users without omnipotent read permissions, this will make renames
  89    difficult to follow, and client commands which attempt to trace
  90    history are likely to fail.
  91
  92
  93 5. REVISION PROPERTIES
  94
  95    Users are allowed to attach arbitrary, unversioned properties to
  96    revisions.  Additionally, most revisions also have "standard"
  97    revision props (revprops), such as svn:author, svn:date, and
  98    svn:log.  Access to revprops may be restricted, based on
  99    readability of changed-paths.
 100
 101      * If a revision contains nothing but unreadable changed-paths,
 102        then all revprops are unreadable and unwritable.
 103
 104      * If a revision has a mixture of readable/unreadable
 105        changed-paths, then all revprops are unreadable, except for
 106        svn:author and svn:date.  All revprops are unwritable.
 107
 108    It's an official recommendation ("best practice") to avoid the
 109    latter situation; users should avoid making a single commit that
 110    includes changes to files in both readable and unreadable areas.
 111    This situation is quite annoying for people who can't read all the
 112    changed-paths.
 113
 114
 115 6. KNOWN LEAKAGE OF UNREADABLE PATHS
 116
 117    Subversion may (occasionally) leak knowledge of the existence of an
 118    unreadable path.  However, the *contents* of an unreadable file or
 119    directory will never be leaked.
 120
 121    Here are the known times when this happens:
 122
 123      * 'svn ls directory-URL': an unreadable directory entry is still
 124        listed along with other entries.
 125
 126      * 'svn checkout/update': an unreadable child doesn't appear in
 127        the working copy, but the .svn/entries file still contains an
 128        entry for it (marked 'absent').
 129
 130 7. LOCKING
 131
 132    If a client attempts to lock or unlock an unreadable path, the
 133    command will fail.  If a client attempts to retrieve a lock on one
 134    path, or a list of all locks "below" a directory, only readable
 135    paths will ever be returned; unreadable locked paths remain
 136    unknown.
 137
 138
 139 ============================================================================
 140 HOW TO IMPLEMENT PATH-BASED AUTHZ
 141 ============================================================================
 142
 143 If an RA server implementation wants to implement path-based authz,
 144 here are its responsibilities:
 145
 146    1. Implement a read-authz callback (see svn_repos_authz_read_func_t),
 147       and pass it to the following svn_repos.h functions:
 148
 149            svn_repos_begin_report()
 150            svn_repos_dir_delta()
 151            svn_repos_history2()
 152            svn_repos_get_logs3()
 153            svn_repos_trace_node_locations()
 154            svn_repos_get_file_revs()
 155            svn_repos_fs_get_locks()
 156            svn_repos_fs_change_rev_prop2()
 157            svn_repos_fs_revision_prop()
 158            svn_repos_fs_revision_proplist()
 159            svn_repos_get_commit_editor3()
 160            svn_repos_replay2()
 161
 162    2. Manually implement authz for incoming network requests that
 163       represent calls to:
 164
 165            RA->get_file()
 166            RA->get_dir()
 167            RA->check_path()
 168            RA->stat()
 169            RA->lock()
 170            RA->lock_many()
 171            RA->unlock()
 172            RA->unlock_many()
 173            RA->get_lock()
 174
 175       (These concepts aren't wrapped by libsvn_repos because it's just
 176       as easy to call an authz func directly on a single path, rather
 177       than pass it to a repos wrapper.)
 178
 179    3. Manually implement authz when receiving network requests that
 180       represent calls to a commit editor:
 181
 182           - do write checks for most editor operations
 183           - do read *and* write checks for copy operations.
 184
 185       (Note that doing full-out authz on whole trees fundamentally
 186       contradicts Subversion's O(1) copy philosophy; in practice,
 187       however, specific authz implementations are able to get the same
 188       effect while being less expensive than O(N).)