docs/nodekeys.rst

   1 =======================
   2 Node Keys in Tahoe-LAFS
   3 =======================
   4
   5 "Node Keys" are cryptographic signing/verifying keypairs used to
   6 identify Tahoe-LAFS nodes (client-only and client+server). The private
   7 signing key is stored in NODEDIR/private/node.privkey , and is used to
   8 sign the announcements that are distributed to all nodes by the
   9 Introducer. The public verifying key is used to identify the sending
  10 node from those other systems: it is displayed as a "Node ID" that looks
  11 like "v0-abc234xyz567..", which ends with a long base32-encoded string.
  12
  13 These node keys were introduced in the 1.10 release (April 2013), as
  14 part of ticket #466. In previous releases, announcements were unsigned,
  15 and nodes were identified by their Foolscap "Tub ID" (a somewhat shorter
  16 base32 string, with no "v0-" prefix).
  17
  18 Why Announcements Are Signed
  19 ----------------------------
  20
  21 All nodes (both client-only and client+server) publish announcements to
  22 the Introducer, which then relays them to all other nodes. These
  23 announcements contain information about the publishing node's nickname,
  24 how to reach the node, what services it offers, and what version of code
  25 it is running.
  26
  27 The new private node key is used to sign these announcements, preventing
  28 the Introducer from modifying their contents en-route. This will enable
  29 future versions of Tahoe-LAFS to use other forms of introduction
  30 (gossip, multiple introducers) without weakening the security model.
  31
  32 The Node ID is useful as a handle with which to talk about a node. For
  33 example, when clients eventually gain the ability to control which
  34 storage servers they are willing to use (#467), the configuration file
  35 might simply include a list of Node IDs for the approved servers.
  36
  37 TubIDs are currently also suitable for this job, but they depend upon
  38 having a Foolscap connection to the server. Since our goal is to move
  39 away from Foolscap towards a simpler (faster and more portable)
  40 protocol, we want to reduce our dependence upon TubIDs. Node IDs and
  41 Ed25519 signatures can be used for non-Foolscap non-SSL based protocols.
  42
  43 How The Node ID Is Computed
  44 ---------------------------
  45
  46 The long-form Node ID is the Ed25519 public verifying key, 256 bits (32
  47 bytes) long, base32-encoded, with a "v0-" prefix appended, and the
  48 trailing "=" padding removed, like so:
  49
  50   v0-rlj3jnxqv4ee5rtpyngvzbhmhuikjfenjve7j5mzmfcxytwmyf6q
  51
  52 The Node ID is displayed in this long form on the node's front Welcome
  53 page, and on the Introducer's status page. In most other places
  54 (share-placement lists, file health displays), the "short form" is used
  55 instead. This is simply the first 8 characters of the base32 portion,
  56 frequently enclosed in square brackets, like this:
  57
  58   [rlj3jnxq]
  59
  60 In contrast, old-style TubIDs are usually displayed with just 6 base32
  61 characters.
  62
  63 Version Compatibility, Fallbacks For Old Versions
  64 -------------------------------------------------
  65
  66 Since Tahoe-LAFS 1.9 does not know about signed announcements, 1.10
  67 includes backwards-compatibility code to allow old and new versions to
  68 interoperate. There are three relevant participants: the node publishing
  69 an announcement, the Introducer which relays them, and the node
  70 receiving the (possibly signed) announcement.
  71
  72 When a 1.10 node connects to an old Introducer (version 1.9 or earlier),
  73 it sends downgraded non-signed announcements. It likewise accepts
  74 non-signed announcements from the Introducer. The non-signed
  75 announcements use TubIDs to identify the sending node. The new 1.10
  76 Introducer, when it connects to an old node, downgrades any signed
  77 announcements to non-signed ones before delivery.
  78
  79 As a result, the only way to receive signed announcements is for all
  80 three systems to be running the new 1.10 code. In a grid with a mixture
  81 of old and new nodes, if the Introducer is old, then all nodes will see
  82 unsigned TubIDs. If the Introducer is new, then nodes will see signed
  83 Node IDs whenever possible.
  84
  85 Share Placement
  86 ---------------
  87
  88 Tahoe-LAFS uses a "permuted ring" algorithm to decide where to place
  89 shares for any given file. For each potential server, it uses that
  90 server's "permutation seed" to compute a pseudo-random but deterministic
  91 location on a ring, then walks the ring in clockwise order, asking each
  92 server in turn to hold a share until all are placed. When downloading a
  93 file, the servers are accessed in the same order. This minimizes the
  94 number of queries that must be done to download a file, and tolerates
  95 "churn" (nodes being added and removed from the grid) fairly well.
  96
  97 This property depends upon server nodes having a stable permutation
  98 seed. If a server's permutation seed were to change, it would
  99 effectively wind up at a randomly selected place on the permuted ring.
 100 Downloads would still complete, but clients would spend more time asking
 101 other servers before querying the correct one.
 102
 103 In the old 1.9 code, the permutation-seed was always equal to the TubID.
 104 In 1.10, servers include their permutation-seed as part of their
 105 announcement. To improve stability for existing grids, if an old server
 106 (one with existing shares) is upgraded to run the 1.10 codebase, it will
 107 use its old TubID as its permutation-seed. When a new empty server runs
 108 the 1.10 code, it will use its Node ID instead. In both cases, once the
 109 node has picked a permutation-seed, it will continue using that value
 110 forever.
 111
 112 To be specific, when a node wakes up running the 1.10 code, it will look
 113 for a recorded NODEDIR/permutation-seed file, and use its contents if
 114 present. If that file does not exist, it creates it (with the TubID if
 115 it has any shares, otherwise with the Node ID), and uses the contents as
 116 the permutation-seed.
 117
 118 There is one unfortunate consequence of this pattern. If new 1.10 server
 119 is created in a grid that has an old client, or has a new client but an
 120 old Introducer, then that client will see downgraded non-signed
 121 announcements, and thus will first upload shares with the TubID-based
 122 permutation-seed. Later, when the client and/or Introducer is upgraded,
 123 the client will start seeing signed announcements with the NodeID-based
 124 permutation-seed, and will then look for shares in the wrong place. This
 125 will hurt performance in a large grid, but should not affect
 126 reliability. This effect shouldn't even be noticeable in grids for which
 127 the number of servers is close to the "N" shares.total number (e.g.
 128 where num-servers < 3*N). And the as-yet-unimplemented "share
 129 rebalancing" feature should repair the misplacement.
 130
 131 If you wish to avoid this effect, try to upgrade both Introducers and
 132 clients at about the same time. (Upgrading servers does not matter: they
 133 will continue to use the old permutation-seed).