mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2024-12-21 13:57:51 +00:00
42 lines
2.6 KiB
ReStructuredText
42 lines
2.6 KiB
ReStructuredText
|
.. -*- coding: utf-8 -*-
|
||
|
|
|
||
|
|
Share Leases
|
||
|
|
============
|
||
|
|
|
||
|
|
A lease is a marker attached to a share indicating that some client has asked for that share to be retained for some amount of time.
|
||
|
|
The intent is to allow clients and servers to collaborate to determine which data should still be retained and which can be discarded to reclaim storage space.
|
||
|
|
Zero or more leases may be attached to any particular share.
|
||
|
|
|
||
|
|
Renewal Secrets
|
||
|
|
---------------
|
||
|
|
|
||
|
|
Each lease is uniquely identified by its **renewal secret**.
|
||
|
|
This is a 32 byte string which can be used to extend the validity period of that lease.
|
||
|
|
|
||
|
|
To a storage server a renewal secret is an opaque value which is only ever compared to other renewal secrets to determine equality.
|
||
|
|
|
||
|
|
Storage clients will typically want to follow a scheme to deterministically derive the renewal secret for a particular share from information the client already holds about that share.
|
||
|
|
This allows a client to maintain and renew single long-lived lease without maintaining additional local state.
|
||
|
|
|
||
|
|
The scheme in use in Tahoe-LAFS as of 1.16.0 is as follows.
|
||
|
|
|
||
|
|
* The **netstring encoding** of a byte string is the concatenation of:
|
||
|
|
* the base 10 representation of the length of the string
|
||
|
|
* ":"
|
||
|
|
* the string
|
||
|
|
* ","
|
||
|
|
* The **sha256d digest** is the **sha256 digest** of the **sha256 digest** of a string.
|
||
|
|
* The **sha256d tagged digest** is the **sha256d digest** of the concatenation of the **netstring encoding** of one string with one other unmodified string.
|
||
|
|
* The **sha256d tagged pair digest** the **sha256d digest** of the concatenation of the **netstring encodings** of each of three strings.
|
||
|
|
* The **bucket renewal tag** is ``allmydata_bucket_renewal_secret_v1``.
|
||
|
|
* The **file renewal tag** is ``allmydata_file_renewal_secret_v1``.
|
||
|
|
* The **client renewal tag** is ``allmydata_client_renewal_secret_v1``.
|
||
|
|
* The **lease secret** is a 32 byte string, typically randomly generated once and then persisted for all future uses.
|
||
|
|
* The **client renewal secret** is the **sha256d tagged digest** of (**lease secret**, **client renewal tag**).
|
||
|
|
* The **storage index** is constructed using a capability-type-specific scheme.
|
||
|
|
See ``storage_index_hash`` and ``ssk_storage_index_hash`` calls in ``src/allmydata/uri.py``.
|
||
|
|
* The **file renewal secret** is the **sha256d tagged pair digest** of (**file renewal tag**, **client renewal secret**, **storage index**).
|
||
|
|
* The **base32 encoding** is ``base64.b32encode`` lowercased and with trailing ``=`` stripped.
|
||
|
|
* The **peer id** is the **base32 encoding** of the SHA1 digest of the server's x509 certificate.
|
||
|
|
* The **renewal secret** is the **sha256d tagged pair digest** of (**bucket renewal tag**, **file renewal secret**, **peer id**).
|