Tahoe.CHK.Capability

Documentation

data CHK

A "Content-Hash-Key" (CHK) capability is small value that can be used to perform some operation on a (usually) larger value that may be stored somewhere else. There are two forms of CHK capabilities: verify and read. See *Verifier* and *Reader* for details.

Constructors

CHKVerifier Verifier

CHKReader Reader

Instances

Eq CHK

Defined in Tahoe.CHK.Capability

Methods

(==) :: CHK -> CHK -> Bool

(/=) :: CHK -> CHK -> Bool

Ord CHK

Defined in Tahoe.CHK.Capability

Methods

compare :: CHK -> CHK -> Ordering

(<) :: CHK -> CHK -> Bool

(<=) :: CHK -> CHK -> Bool

(>) :: CHK -> CHK -> Bool

(>=) :: CHK -> CHK -> Bool

max :: CHK -> CHK -> CHK

min :: CHK -> CHK -> CHK

data Reader

Represent a CHK "read" capability. This capability type can be diminished to a verify capability so it confers all of the abilities of a verify capability. It can also be used to decrypt shares to reconstruct the original plaintext. See makeReader for a safe constructor that correctly derives the verify capability.

Constructors

Reader

Fields

• readKey :: AESKey128

  The read key of a read capability is used as the symmetric encryption key to turn the original plaintext into ciphertext and back again. The read key is also used to derive the verify key for the verify capability. See `storageIndexHash`.

• verifier :: Verifier

  The verify capability for this read capability.

Instances

Eq Reader

Defined in Tahoe.CHK.Capability

Methods

(==) :: Reader -> Reader -> Bool

(/=) :: Reader -> Reader -> Bool

Ord Reader

Defined in Tahoe.CHK.Capability

Methods

compare :: Reader -> Reader -> Ordering

(<) :: Reader -> Reader -> Bool

(<=) :: Reader -> Reader -> Bool

(>) :: Reader -> Reader -> Bool

(>=) :: Reader -> Reader -> Bool

max :: Reader -> Reader -> Reader

min :: Reader -> Reader -> Reader

Show Reader

Give it a Show instance that elides the sensitive material. This makes it easier to compose with other types and we can still learn a lot of useful things about a capability without being able to see the literal secret key.

Defined in Tahoe.CHK.Capability

Methods

showsPrec :: Int -> Reader -> ShowS

show :: Reader -> String

showList :: [Reader] -> ShowS

data Verifier

Represent a CHK "verify" capability. This capability type can be used to verify the existence and validity (bit-level) of shares for the associated piece of plaintext.

It can also be used to repair unhealthy data (I think?)

Constructors

Verifier

Fields

• storageIndex :: ByteString

  The storage index of a verify capability is used as the key into the content-addressable storage system that is a storage server. It can be used to ask storage servers for "shares" (ciphertext plus some metadata) to download.

• fingerprint :: ByteString

  The fingerprint (aka "UEB hash" aka "URI extension block hash") is a cryptographic hash that covers the URI extension block at the end of a CHK share. The URI extension block itself contains various other cryptographic hashes. Altogether this allows for integrity checking so shares downloaded from storage servers can be checked for validity (ie, that they are the same as what was uploaded) before they are processed.

• required :: Word16

  The number of shares required to ZFEC decode the contents of the shares. ZFEC calls this *K*. It must be that 1 <= required <= 256 and required <= total. ZFEC is not defined outside of these bounds.

• total :: Word16

  The total number of shares produced by ZFEC encoding. ZFEC calls this *n*. It must be that 1 <= total <= 256 and required <= total.

• size :: Integer

  The size (in bytes) of the plaintext encoded in the shares. It must be that size >= 0 and in practice it is usually true that size >= 56.

Instances

Eq Verifier

Defined in Tahoe.CHK.Capability

Methods

(==) :: Verifier -> Verifier -> Bool

(/=) :: Verifier -> Verifier -> Bool

Ord Verifier

Defined in Tahoe.CHK.Capability

Methods

compare :: Verifier -> Verifier -> Ordering

(<) :: Verifier -> Verifier -> Bool

(<=) :: Verifier -> Verifier -> Bool

(>) :: Verifier -> Verifier -> Bool

(>=) :: Verifier -> Verifier -> Bool

max :: Verifier -> Verifier -> Verifier

min :: Verifier -> Verifier -> Verifier

Show Verifier

Defined in Tahoe.CHK.Capability

Methods

showsPrec :: Int -> Verifier -> ShowS

show :: Verifier -> String

showList :: [Verifier] -> ShowS

makeReader :: AESKey128 -> ByteString -> Word16 -> Word16 -> Integer -> Reader

Construct a CHK read capability from its components. This includes the correct derivation of the corresponding CHK verify capability.

pCapability :: Parser CHK

A parser combinator for parsing either a verify or read CHK capability from the canonical format. This is the moral inverse of dangerRealShow.

pVerifier :: Parser Verifier

A parser combinator for parsing a CHK verify capability.

pReader :: Parser Reader

A parser combinator for parsing a CHK read capability.

dangerRealShow :: CHK -> Text

Serialize a CHK capability to text. This operation is "dangerous" in that it will serialize the encryption key of a read capability into the text. Since the encryption key is necessary and (practically) sufficient to recover the original plaintext associated with the capability, it must be handled carefully to avoid unintentional disclosure. Serializing the key to a string is a good way to accidentally disclose it! Be warned.

The text is in the canonical form, originally used by the Python implementation of Tahoe-LAFS.