git ssb

1
var page = require('../../page.part')
2
var com = require('../../com.part')
3
4
module.exports = () => page({
5
  section: 'docs',
6
  tab: 'guides-concepts',
7
  path: '/protocols/secure-scuttlebutt.html',
8
  content: `
9
    <h2>Secure Scuttlebutt</h2>
10
    <p>Secure Scuttlebutt is a database protocol for unforgeable append-only message feeds.</p>
11
    <p>
12
      &quot;Unforgeable&quot; means that only the owner of a feed can update that feed, as enforced by digital signing (see <a href="#security-properties">Security properties</a>).
13
      This property makes Secure Scuttlebutt useful for peer-to-peer applications.
14
      Secure Scuttlebutt also makes it easy to encrypt messages.
15
    </p>
16
17
    <hr>
18
19
    <h2 id="concepts">Concepts</h2>
20
    <p>Building upon Secure Scuttlebutt requires understanding a few concepts that it uses to ensure the unforgeability of message feeds.</p>
21
    
22
    <h3 id="identities">Identities</h3>
23
    <p>
24
      An identity is simply a <a href="http://ed25519.cr.yp.to/">ed25519 key pair</a>.
25
      The public key is used as the identifier.
26
    </p>
27
    <p>
28
      There is no worldwide store of identities.
29
      Users must exchange pubkeys, either by publishing them on their feeds, or out-of-band.
30
    </p>
31
32
    <h3 id="feeds">Feeds</h3>
33
    <p>
34
      A feed is a signed append-only sequence of messages.
35
      Each identity has exactly one feed.
36
    </p>
37
    <p>
38
      Note that append-only means you cannot delete an existing message, or change your history.
39
      This is enforced by a per-feed blockchain.
40
      This is to ensure the entire network converges on the same state.
41
    </p>
42
43
    <h3 id="messages">Messages</h3>
44
    <p>Each message contains:</p>
45
    <ul>
46
      <li>A signature</li>
47
      <li>The signing public key</li>
48
      <li>A content-hash of the previous message</li>
49
      <li>A sequence number</li>
50
      <li>A timestamp</li>
51
      <li>An identifier of the hashing algorithm in use (currently only &quot;sha256&quot; is supported)</li>
52
      <li>A content object</li>
53
    </ul>
54
    <p>Here&#39;s an example message:</p>
55
    ${ com.code({ js: `{
56
  "previous": "%26AC+gU0t74jRGVeDY01...MnutGGHM=.sha256",
57
  "author": "@hxGxqPrplLjRG2vtjQL87...0nNwE=.ed25519",
58
  "sequence": 216,
59
  "timestamp": 1442590513298,
60
  "hash": "sha256",
61
  "content": {
62
    "type": "vote",
63
    "vote": {
64
      "link": "%WbQ4dq0m/zu5jxll9zUb...KjZ80JvI=.sha256",
65
      "value": 1
66
    }
67
  },
68
  "signature": "Sjq1C3yiKdmi1TWvNqxI...gmAQ==.sig.ed25519"
69
}` }) }
70
71
    <h3 id="entity-references-links-">Entity References (Links)</h3>
72
    <p>
73
      Messages can reference three types of Secure Scuttlebutt entities: messages, feeds, and blobs (i.e. files).
74
      Messages and blobs are referred to by their hashes, but a feed is referred to by its signing public key.
75
    </p>
76
77
    <h3 id="confidentiality">Confidentiality</h3>
78
    <p>
79
      For private sharing, Scuttlebot uses <a href="http://doc.libsodium.org/">libsodium</a> to encrypt confidential log-entries.
80
      Feed IDs are public keys, and so once two feeds are mutually following each other, they can exchange confidential data freely.
81
    </p>
82
83
    <h3 id="following">Following</h3>
84
    <p>
85
      Users choose which feeds to synchronize by following them.
86
      Presently, <a href="/modules/scuttlebot-replicate.html">Scuttlebot&#39;s replicate plugin</a>, which is enabled by default, looks on the master user&#39;s feed for <code>type:contact</code> messages to know which users are currently followed.
87
    </p>
88
89
    <h3 id="replication">Replication</h3>
90
    <p>
91
      Since feeds are append-only, replication is simple: request all messages in the feed that are newer than the latest message you know about.
92
      Scuttlebot maintains a table of known peers, which it cycles through, asking for updates for all followed feeds.
93
    </p>
94
95
    <h3 id="gossip">Gossip</h3>
96
    <p>
97
      The protocol creates a <a href="https://en.wikipedia.org/wiki/Gossip_protocol">global gossip network</a>.
98
      This means that information is able to distribute across multiple machines, without requiring direct connections between them.
99
    </p>
100
    <p><img src="/img/gossip-graph1.png" alt="Gossip graph"></p>
101
    <p>Even though Alice and Dan lack a direct connection, they can still exchange feeds:</p>
102
    <p><img src="/img/gossip-graph2.png" alt="Gossip graph 2"></p>
103
    <p>
104
      This is because gossip creates &quot;transitive&quot; connections between computers.
105
      Dan&#39;s messages travel through Carla and the Pub to reach Alice, and visa-versa.
106
    </p>
107
108
    <h3 id="lan-connectivity">LAN connectivity</h3>
109
    <p>
110
      SSB is hostless: each computer installs the same copy of software and has equal rights in the network.
111
      Devices discover each other over the LAN with multicast UDP and sync automatically.
112
    </p>
113
114
    <h3 id="pub-servers">Pub Servers</h3>
115
    <p>
116
      To sync across the Internet, &quot;Pub&quot; nodes run at public IPs and follow users.
117
      They are essentially mail-bots which improve uptime and availability.
118
      Users generate invite-codes to command Pubs to follow their friends.
119
      The Scuttlebot community runs some Pubs, and anybody can create and introduce their own.
120
    </p>
121
122
    <h2 id="security-properties">Security properties</h2>
123
    <p>
124
      Secure Scuttlebutt maintains useful security properties even when it is connected to a malicious Secure Scuttlebutt database.
125
      This makes it ideal as a store for peer-to-peer applications.
126
    </p>
127
    <p>
128
      Imagine that we want to read from a feed for which we know the identity, but we&#39;re connected to a malicious Secure Scuttlebutt instance.
129
      As long as the malicious database does not have the private key:
130
    </p>
131
    <ul>
132
      <li>The malicious database cannot create a new feed with the same identifier</li>
133
      <li>The malicious database cannot write new fake messages to the feed</li>
134
      <li>The malicious database cannot reorder the messages in the feed</li>
135
      <li>The malicious database cannot send us a new copy of the feed that omits messages from the middle</li>
136
      <li>The malicious database <em>can</em> refuse to send us the feed, or only send us the first <em>N</em> messages in the feed</li>
137
      <li>Messages may optionally be encrypted</li>
138
    </ul>
139
    <p>
140
      Additionally there is a protection from the feed owner, through the blockchain.
141
      The <code>previous</code> content-hash them from changing the feed history after publishing, as a newly-created message wouldn&#39;t match the hash of later messages which were already replicated.
142
      This ensures the append-only constraint, and thus safe network convergence.
143
    </p>
144
145
    <p class="next"><a href="/protocols/secret-handshake.html">Secret Handshake</a></p>
146
    <ul class="see-also">
147
      <li><a href="/docs/social/social-network.html">Social Network</a></li>
148
    </ul>
149
  `
150
})