Capabilities

An overview from the mailing list archives - originally ​Feb 2009 - Brian Warner:

 1: immutable file read-only capability string  URI:CHK:
 2: immutable file verify capability string     URI:CHK-Verifier:

 3: mutable file read-write capability string   URI:SSK:
 4: mutable file read-only capability string    URI:SSK-RO:
 5: mutable file verify capability string       URI:SSK-Verifier:

 6: directory read-write capability string      URI:DIR2:
 7: directory read-only capability string       URI:DIR2-RO:
 8: directory verify capability string          URI:DIR2-Verifier:

In Tahoe, directories are built out of mutable files (a directory is really
just a particular way to interpret the contents of a given mutable file), and
non-directory mutable files aren't used very much. All normal data files are
uploaded into immutable files by default.

Some capabilities can be used to derive others. If you have #1, you can
derive #2 (but not the other way around). The full table is:

     #1->#2
 #3->#4->#5
 #6->#7->#8

Deriving a weaker capability from a strong one is called "diminishing" the stronger one.

So we use "filecap" to talk about #1+#3+#4, but (since most files are
immutable) we're usually talking about #1. We use "dircap" to talk about #6
and #7. We use "readcap" to talk about #1,#4, and #7, but usually we refer to
#7 as a "directory readcap". We use "writecap" to talk about #3 and #6.

A "verifycap" is the weakest capability that still allows every bit of every
share to be validated (hashes checked, signatures verified, etc). That means
#2, #5, and #8.

When we talk about a "repaircap", we mean "the weakest capability that can
still be used to repair the file". Given the current limitations of the
repairer and our webapi, that means we're talking about #1, #3, or #6.
Eventually we'll fix this limitation, and any verifycap should be useable as
a repaircap too. (there's much less work involved to let #2 repair a file..
it's just an incomplete API, rather than a fundamental redesign of the server
protocol).

We then use the somewhat-vague term "rootcap" to refer to a cap (usually a
directory write cap) that is not present inside any directory, so the only
way to ever reach it is to remember it somewhere outside of Tahoe. It might
be remembered in the allmydata.com rootcap database (indexed by account name
plus password), or it might be remembered in a ~/.tahoe/private/aliases file,
or it might just be written down on a piece of paper. The point is that you
have to start from somewhere, and we refer to such a starting point as a
"rootcap".