Table of Contents
Capabilities
An overview from the mailing list archives - originally by Feb 2009 - Brian Warner, but updated to take into account literal caps and immutable directories:
1: immutable file read-only capability string URI:CHK:
2: immutable file verify capability string URI:CHK-Verifier:
3: immutable LIT file read-only capability string URI:LIT:
4: mutable file read-write capability string URI:SSK:
5: mutable file read-only capability string URI:SSK-RO:
6: mutable file verify capability string URI:SSK-Verifier:
7: immutable directory read-only capability string URI:DIR2-CHK:
8: immutable directory verify capability string URI:DIR2-CHK-Verifier:
9: immutable LIT directory read-only capability string URI:DIR2-LIT:
10: mutable directory read-write capability string URI:DIR2:
11: mutable directory read-only capability string URI:DIR2-RO:
12: mutable directory verify capability string URI:DIR2-Verifier:
13: unknown/future capability strings <anything else>
In Tahoe-LAFS, mutable directories are built out of mutable files (a mutable 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:
write read verify
--------------------
#1 -> #2 }
#3 } filecaps
#4 -> #5 -> #6 }
#7 -> #8 }
#9 } dircaps
#10 -> #11 -> #12 }
Deriving a weaker capability from a strong one is called "diminishing" the stronger one.
So we use "filecap" to talk about !#1..6, but (since most files are immutable) we're usually talking about !#1. We use "dircap" to talk about !#7..12. We use "readcap" to talk about #{1,3,5,7,9,11}, but usually we refer to #{7,9,11} as a "directory readcap". We use "writecap" to talk about !#4 and !#10.
A "literal cap" or "LIT cap" stores the contents of a small file (!#3) or directory (!#9) in the capability itself.
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,6,8,12}.
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 web-API, that means we're talking about #{1,4,7,10}. Eventually we'll fix this limitation (watch for #568), and any verifycap should be usable as a repaircap too. (There's much less work involved to let !#2 repair a file or !#8 repair a directory... 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 a Tahoe-LAFS
filesystem. 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".