= Capabilities = An overview from the mailing list archives - originally by [http://allmydata.org/pipermail/tahoe-dev/2009-February/001110.html 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 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: write read verify -------------------- #1 -> #2 #4 -> #5 -> #6 #7 -> #8 #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 webapi, that means we're talking about #{1,4,7,10}. 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 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 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". }}}