on master help sign in
add contextual content in page indexes
commit87cc6d1614b66c59c9fd8c3e16be1668cc218d0c authorJosh Lehman <josh@starcity.com> dateFri 12 Mar 2021, 10:33 (6 years ago) parentdff8b1d
15 files changed+197−28
content/docs+1−1 content/getting-started/planet.md+2−2 content/using/_index.md+28−2 content/using/id/_index.md+27−1 content/using/id/bridge-troubleshooting.md+1−1 content/using/id/creating-an-invite-pool.md+1−1 content/using/id/guide-to-breaches.md+1−1 content/using/id/overview.md+71 content/using/id/using-bridge.md+1−1 content/using/os/_index.md+30−1 content/using/os/stars-and-galaxies.md+1−1 content/using/running/_index.md+16 content/using/os/hosting.md → content/using/running/hosting.md+1−1 sass/_main.scss+15−14 static/_redirects+1−1
content/docs+1−1

Submodule changed.

content/getting-started/planet.md+2−2
@@ -35,7 +35,7 @@ Current hosting providers are:
3535
3636Urbit must run on an existing computer somewhere. Most users run their planet on their personal computer, but we recommend eventually using a cloud service (Digital Ocean, Linode, etc) because it allows your planet to be accessed from anywhere on multiple devices. Hosting your planet in the cloud also allows it to always be online and ready for automatic updates. You are welcome to run from your personal computer and switch to the cloud later...all without losing any data!
3737
38−There is a guide for [hosting your planet on DigitalOcean](@/using/os/hosting.md) and [hosting your planet on Linode](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps), but any cloud hosting service should work.
38+There is a guide for [hosting your planet on DigitalOcean](@/using/running/hosting.md) and [hosting your planet on Linode](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps), but any cloud hosting service should work.
3939
4040### Get your keyfile {#keyfile}
4141
@@ -124,6 +124,6 @@ If for some reason your sponsor (in this case, `~dopzod`) is not responding, rea
124124
125125Now that you’re up and running, take some time to deepen your understanding by checking out some of our other guides:
126126
127−- [Host your Ship in the Cloud](@/using/os/hosting.md): Follow this guide to set your ship up to run as a cloud server, accessible from anywhere.
127+- [Host your Ship in the Cloud](@/using/running/hosting.md): Follow this guide to set your ship up to run as a cloud server, accessible from anywhere.
128128- [Read the Operations Manual](@/using/os/getting-started.md): Become an expert pilot by learning to use your ship.
129129- [Learn to Develop on Urbit](@/docs/development/develop.md): Learn how to contribute to or develop on Urbit.
content/using/_index.md+28−2
@@ -1,7 +1,33 @@
11+++
2−title = "Using"
2+title = "Usage Docs"
33sort_by = "weight"
44template = "sections/docs/chapters.html"
55+++
66
7−TODO
7+Welcome to the usage documentation for the Urbit project. This documentation is
8+maintained by [Tlon](https://tlon.io) and the Urbit community in a public
9+[Github repository](https://github.com/urbit/urbit.org). Issues and
10+contributions are welcome.
11+
12+This documentation provides a series of guides and reference material for
13+assisting you in the usage and operations of your ship. If you're looking for
14+documentation on how to *develop* on Urbit, see our [development docs](@/docs/_index.md).
15+
16+### [Urbit OS](@/using/os/_index.md)
17+
18+This section describes how to interact with your running Urbit ship: this
19+includes working with the filesystem, command line (`dojo`), resolving common
20+issues, and more.
21+
22+### [Urbit ID](@/using/id/_index.md)
23+
24+Urbit ID is our [public-key infrastructure](@/using/id/overview.md), which is
25+what allows you to truly own your identity. Here you'll find guides for
26+interacting with your Urbit ID via our [Bridge](https://bridge.urbit.org)
27+application.
28+
29+### [Running Urbit](@/using/running/_index.md)
30+
31+Urbit can be run in a variety of contexts. Our [Getting Started
32+Guide](@/getting-started.md) covers how to run an Urbit locally on your
33+computer; this section covers alternative ways of running Urbit.
content/using/id/_index.md+27−1
@@ -3,5 +3,31 @@ title = "Urbit ID"
33template = "sections/docs/chapters.html"
44sort_by = "weight"
55description = "How to interact with Urbit ID."
6−weight = 10
6+weight = 20
77+++
8+
9+Urbit ID is our [public-key infrastructure](@/using/id/overview.md), which is
10+what allows you to truly own your identity.
11+
12+### [Overview](@/using/id/overview.md)
13+
14+This document discusses what Urbit ID is, how it's built, and why it's been
15+built that way at a high level.
16+
17+### [Using Bridge](@/using/id/using-bridge.md)
18+
19+A guide to using [Bridge](https://bridge.urbit.org), our tool for managing your
20+Urbit ID.
21+
22+### [Bridge Troubleshooting](@/using/id/bridge-troubleshooting.md)
23+
24+How to resolve common issues in Bridge.
25+
26+### [Creating an Invite Pool](@/using/id/creating-an-invite-pool.md)
27+
28+If you own a star, invite pools allow your friends to invite others onto the
29+network.
30+
31+### [Guide to Breaches](@/using/id/guide-to-breaches.md)
32+
33+What to do when things go very wrong and you need to start over.
content/using/id/bridge-troubleshooting.md+1−1
@@ -2,7 +2,7 @@
22title = "Bridge Troubleshooting"
33template = "doc.html"
44description = "Troubleshooting Bridge if you are running into errors"
5−weight = 5
5+weight = 20
66+++
77
88This page covers common issues encountered with the [Bridge](https://bridge.urbit.org) application.
content/using/id/creating-an-invite-pool.md+1−1
@@ -1,6 +1,6 @@
11+++
22title = "Creating an Invite Pool"
3−weight = 9
3+weight = 30
44template = "doc.html"
55+++
66
content/using/id/guide-to-breaches.md+1−1
@@ -1,6 +1,6 @@
11+++
22title = "Guide to Breaches"
3−weight = 10
3+weight = 40
44template = "doc.html"
55+++
66
content/using/id/overview.mdnew file+71
@@ -0,0 +1,71 @@
1++++
2+title = "Overview"
3+description = "A public key infrastructure (PKI) is a system for binding a set of keys to a name. Sometimes a small amount of metadata is included."
4+weight = 1
5+template = "doc.html"
6++++
7+
8+![](https://media.urbit.org/site/posts/essays/pki-maze.png)
9+
10+A public key infrastructure (PKI) is a system for binding a set of keys to a name. Sometimes a small amount of metadata is included.
11+
12+Existing PKIs include PGP-style ["web of trust"](https://en.wikipedia.org/wiki/Web_of_trust), [SSL certificates](https://en.wikipedia.org/wiki/Certificate_authority), [ZeroTier](https://www.zerotier.com/lf-announcement/), [Keybase](https://keybase.io/), [OpenID](https://openid.net/what-is-openid/), [Mozilla Persona](https://developer.mozilla.org/en-US/docs/Archive/Mozilla/Persona), and [Login with Google](https://developers.google.com/identity). These take unique approaches to the problem and have achieved some degree of success, but none provide globally consistent, permanent, and completely self-owned identities. Exhaustive exploration and categorization is unfortunately out of scope for this post, so we'll just describe Urbit's approach to achieving these properties in our PKI.
13+
14+In Urbit, a "name" is often called a "ship" or an "address" because we use the metadata in the PKI to make names routable. The total data is two 256-bit asymmetric keys, a cryptographic suite number (to allow changing crypto algorithms), the revision number of the key, and the name of a ship that will route for it. This sums to less than 128 bytes of data.
15+
16+Each PKI trades off various properties. We chose a tripartite system so that appropriate choices can be made for different use cases. Here, we explore the various properties we chose by following a series of binary choices -- the idea maze.
17+
18+There are two sorts of PKI: either you can change your keys or not. If you cannot, then your name is impermanent, for no one can keep a set of keys secure forever. Even if your opsec never fails, eventually your crypto algorithms may be compromised.
19+
20+However, if you sacrifice the ability to change your keys, you can have a very nice property: self-attesting keys. If your name is a hash of your public key information, then no other source of information is required to verify you are who you say you are. This is a useful property since it requires no coordination at all. Many things are impermanent, especially during development. It also provides a way to try out the network without obtaining a permanent address.
21+
22+This is our first stop in the idea maze. We call this sort of name a "comet". A comet's name is the 128-bit hash of its public keys.
23+
24+However, Urbit is yours and it's forever. You shouldn't have to change your name every time you change your keys. So, we go back and take the other choice: you must be able to change your keys.
25+
26+To change keys, you must sign a message with the old keys revoking them and supplying the new ones[^0]. The question is what happens if the old keys also sign a second set of new keys. This could happen if an attacker obtained your old keys after the fact. This is important because one of the reasons to be able to change your keys is to invalidate the old ones so that they have no power.
27+
28+We have two options again: the PKI may be globally consistent or not. To be globally consistent means that if you believe a name is bound to a set of keys, then nobody on the network will disagree.
29+
30+If you don't require global consistency, you may sign this message and send it to all your neighbors, and they pass it on, and hopefully it gets to most of the network quickly. However, if one of those ships receives two contradictory versions of this message, the only thing it can do is trust the first one it heard, which may be different than what someone else heard. Thus, this is pairwise consistent but globally inconsistent. This is essentially how the pre-blockchain Ames network worked, though key changes were not actually implemented. Because global consistency is a valuable property, we looked at other options.
31+
32+For a globally consistent PKI that allows you to revoke keys, you need to be able to distinguish between two cryptographically valid messages to determine which was signed first. The dual problem could be solved easily — you can prove a message is signed after another by including the signature of the first in the second. This is equivalent to reading out a newspaper headline to prove a message was recorded after a given day.
33+
34+However, the problem of proving one message was sent before any later ones inverts the problem. You can solve this with newspapers by placing the message in the text of the newspaper. However, while reading a newspaper requires no central party, writing one does. For a long time, this sort of message was always handled by a central party. SSL revocations are managed by a few central parties. When you buy property, it's not sufficient to have the previous owner sign the title — this must be entered into a central land registry. Otherwise, the owner may sell their property to multiple people and there would be no way to determine who is the new owner. With the land registry, all you need to do is ask the registry which sale happened first, and that's the one that counts.
35+
36+However, Urbit is yours and it's forever. Trusting central registries jeopardizes both. The keen reader will notice that the problem of determining which key rotation happened first is exactly the double-spend problem that Satoshi solved with his proof of work algorithm for Bitcoin. His first block famously includes a newspaper headline to prove he didn't mine the block before that date. In a beautiful duality, his own algorithm proves that he didn't mine it after that date.[^1]
37+
38+Some argue that blockchain is only good for money. This is myopic and is generally based on the experience that its most valuable application so far has been money. However, blockchain is a cryptographic primitive to do what was previously impossible: prove that one message was signed before another without a central party. Blockchain was discovered by someone trying to create digital money, and he needed that primitive, but that doesn't mean that's all it's good for.
39+
40+Thus, we store our PKI data on a blockchain for our second kind of name: planets. A planet is a 32-bit address which has key information stored on the blockchain.[^2] The owner of a planet may broadcast new PKI data by adding it to the blockchain. Any later messages by the old keys will be rejected, and everyone on the network will listen to the blockchain for key data. Thus, we have global consistency, permanence, and self sovereignty. We know of no other solution that can provide these properties.
41+
42+However, while small individually, the aggregate PKI data for all nodes on the network may become very large. This is not an issue for comets because nobody needs to store comet keys except for those which they're talking with, and even those can be garbage-collected and re-requested and verified. For planets, there is a canonical set of keys, and somebody must store that. There are about 2<sup>32</sup>, or 4 billion planets. If the PKI data is about 100 bytes for each planet, this is about 400 GB of data. This may be more than most users wish to store, but it's small enough that it would be very cheap for someone to host this data for many users[^3].
43+
44+This information is currently stored directly on the Ethereum 1.0 blockchain, but as is well understood in blockchain circles this approach will not scale beyond a certain point. Many chains are pursing designs that allow the users of the smart contracts to store locally the data associated with the contracts they care about and only commit hashes to the chain. We expect there to be several viable options for this by the time our scaling needs exceed what's provided by Ethereum 1.0. This will free us from the cost of hosting the PKI data on all Ethereum nodes, but the data must still be stored somewhere. Any service that could handle such a large amount of data would inherently centralize the network.
45+
46+However, 4 billion is not enough addresses for every device on the planet today, much less in a few decades. So, we apply our maxim of re-examining our choices at each level for each use case. Examining the idea maze above, we cannot use the blockchain option for everything since the data is too big. However, it's not actually necessary for each of your devices to have its own self-sovereign identity separate from your planet. So we choose the option of using a central registry: your own planet.
47+
48+We allocate 4 billion "moons" to each of those planets. A moon is a 64-bit address whose 32-bit suffix is its planet. Your planet can easily store the keys for its own moons, and anyone who needs to talk to your moons can ask you for the keys.
49+
50+This is the sense in which moons are true ships: they're permanent names and you own them completely, as long as you own the planet. However, they're not independent ships — their keys can always be revoked by their planet.
51+
52+To create a sane network, we require global consistency for all our names. There are three other properties; pick any two:
53+
54+- Comets are impermanent, self sovereign, and plentiful.
55+
56+- Planets are permanent, self sovereign, and not plentiful.
57+
58+- Moons are permanent, not self sovereign, and plentiful.
59+
60+Fancifully, comets are wayward celestial bodies that are great for testing and miscellaneous low-value things that won't last for long. Planets are where you can build a home and shape it into anything you want it to be. People can always find your planet; it's not going anywhere. Moons are useful for special purposes, like storage, heavy industry, and anything else you might want to do off-planet.[^4]
61+
62+
63+[^0]: Or the equivalent with a hierarchical key structure. In practice, you want to have a master key which signs a junior key for everyday use. You use the master key to rotate the junior key.
64+
65+[^1]: More strictly: it proves that he didn't mine it after the other blocks currently on the Bitcoin blockchain. It only gives an ordering within the chain, not a literal timestamp.
66+
67+[^2]: In addition to planets, there are stars and galaxies. From a PKI perspective they're treated exactly like planets, but on the network they provide infrastructure services like routing.
68+
69+[^3]: In practice, this will likely be an included service by your sponsoring star. It could be a separate service, but it will be very cheap because it's a commodity and the "cost of production" is very cheap. At any rate, it should never rise above the capital cost of a 400GB hard drive.
70+
71+[^4]: To extend the metaphor, stars are a neighborhood to live in -- they're easier for other planets to see, so when they want to send you a message they look for your star first. If they don't even know where your star is, they can certainly find your star's galaxy, and that will be enough to locate the star. Of course, if your star is not providing satisfactory service, you can take your planet and move to another star.
content/using/id/using-bridge.md+1−1
@@ -2,7 +2,7 @@
22title = "Using Bridge"
33template = "doc.html"
44description = "How to use Bridge to interact with Azimuth and manage your Urbit ID."
5−weight = 1
5+weight = 10
66aliases = ["/docs/getting-started/using-bridge/"]
77+++
88
content/using/os/_index.md+30−1
@@ -3,5 +3,34 @@ title = "Urbit OS"
33sort_by = "weight"
44description = "How to use Urbit OS"
55template = "sections/docs/chapters.html"
6−weight = 1
6+weight = 10
77+++
8+
9+This section describes how to interact with your running Urbit ship: this
10+includes working with the filesystem, command line (`dojo`), resolving common
11+issues, and more.
12+
13+### [Getting Started](@/using/os/getting-started.md)
14+
15+An overview of common commands and useful general knowledge for operating your
16+ship.
17+
18+### [Messaging](@/using/os/messaging.md)
19+
20+Using chat from its command-line interface.
21+
22+### [Configuring S3 Storage](@/using/os/s3.md)
23+
24+How to set up S3 storage so you can share files in Landscape.
25+
26+### [Shell](@/using/os/shell.md)
27+
28+A comprehensive overview of `dojo` commands.
29+
30+### [Star and Galaxy Operations](@/using/os/stars-and-galaxies.md)
31+
32+How to run an infrastructure node.
33+
34+### [Ship Troubleshooting](@/using/os/ship-troubleshooting.md)
35+
36+How to resolve common problems.
content/using/os/stars-and-galaxies.md+1−1
@@ -14,7 +14,7 @@ If you plan to distribute planets in any capacity, we ask that you keep your sta
1414running. If you fail to do so, those planets will become orphans that are unable
1515to communicate with the network unless they transfer to a new star.
1616
17−See our [cloud hosting instructions](@/using/os/hosting.md) for
17+See our [cloud hosting instructions](@/using/running/hosting.md) for
1818instructions on settings up a Digital Ocean droplet.
1919
2020### Distributing planets
content/using/running/_index.mdnew file+16
@@ -0,0 +1,16 @@
1++++
2+title = "Running Urbit"
3+sort_by = "weight"
4+description = "How to run Urbit in various environments."
5+template = "sections/docs/chapters.html"
6+weight = 30
7++++
8+
9+Urbit can be run in a variety of contexts. Our [Getting Started
10+Guide](@/getting-started.md) covers how to run an Urbit locally on your
11+computer; this section covers alternative ways of running Urbit.
12+
13+### [Cloud Hosting](@/using/running/hosting.md)
14+
15+This guide covers the provisioning and setup of a cloud server in Digital Ocean
16+running your Urbit. This enables your Urbit to be accessed from anywhere.
content/using/os/hosting.md → content/using/running/hosting.mdrenamed+1−1
@@ -1,5 +1,5 @@
11+++
2−title = "Hosting Your Ship In The Cloud"
2+title = "Cloud Hosting"
33description = "How to host your ship in the cloud so you can access it from any device."
44template = "doc.html"
55weight = 2
sass/_main.scss+15−14
@@ -215,20 +215,21 @@ body.essay {
215215 img {
216216 display: block;
217217 }
218− div.footnote-definition {
219− &[id="1"] {
220− margin-top: 4rem;
221− padding-top: 2rem;
222− border-top: 1px solid black;
223− }
224− &:not([id="1"]) {
225− margin: 1rem 0;
226− }
227− p {
228− display: inline;
229− font-size: smaller;
230− }
231− }
218+}
219+
220+div.footnote-definition {
221+ &[id="0"] {
222+ margin-top: 4rem;
223+ padding-top: 2rem;
224+ border-top: 1px solid black;
225+ }
226+ &:not([id="0"]) {
227+ margin: 1rem 0;
228+ }
229+ p {
230+ display: inline;
231+ font-size: smaller;
232+ }
232233}
233234
234235// components
static/_redirects+1−1
@@ -10,7 +10,7 @@
1010/using/integrating-api /docs/arvo/eyre/using-eyre 301!
1111/using/operations /using 301!
1212/using/operations/bridge /using/id/using-bridge 301!
13−/using/operations/hosting /TODO
13+/using/operations/hosting /using/running/hosting 301!
1414/using/operations/using-your-ship /using/os/getting-started 301!
1515/using/operations/stars-and-galaxies /using/os/stars-and-galaxies 301!
1616/using/operations/bridge-troubleshooting /using/os/bridge-troubleshooting 301!