Add identity and keys docs to simplify grouping.

greglook · Mar 2, 2015 · d794590 · d794590
1 parent 41d5383
commit d794590
Show file tree

Hide file tree

Showing 5 changed files with 106 additions and 170 deletions.
diff --git a/README.md b/README.md
@@ -84,7 +84,7 @@ sha256:<hash-of-D>
 See the [path traversal doc](doc/path-traversal.md) for more details on how this
 is accomplished.
 
-### Identity and State
+### Identity and Mutable State
 
 PGP public keys establish _identity_ in Vault. The hash-id of these _key blobs_
 provides a secure identifier for a mutable reference. Each identity may be bound

diff --git a/doc/data.md b/doc/data.md
@@ -4,12 +4,11 @@ Structured Data
 The blobs stored in Vault are interpreted in the _data layer_. Blob content is
 classified into one of three types:
 - Structured data is represented by _data blobs_.
-- Cryptographic keys are stored as _key blobs_.
+- Cryptographic keys are stored as [_key blobs_](keys.md).
 - All other content is considered _raw blobs_.
 
-Data blobs are stored as EDN text. Key
-blobs follow the OpenPGP standard and are stored as ASCII 'armored' text. Raw
-blobs are not further interpreted.
+Data blobs are stored as EDN text. Key blobs follow the OpenPGP standard and are
+stored as ASCII 'armored' text. Raw blobs are not further interpreted.
 
 ## Data Blobs
 
@@ -28,20 +27,19 @@ An example blob:
 
 ```clojure
 #vault/data
-{:vault/type :filesystem/file
- :name "foo.clj"
+{:name "foo.clj"
+ :content #bytes/seq #vault/blob "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75"
  :posix/permissions 493 ; 0755
  :owner/id 1000
  :owner/name "user"
  :group/id 500
  :group/name "users"
  :time/change #inst "2013-10-23T20:06:13.000-00:00"
- :time/modify #inst "2013-10-25T09:13:24.000-00:00"
- :content/bytes #vault/ref "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75"}
+ :time/modify #inst "2013-10-25T09:13:24.000-00:00"}
 ```
 
-This value has the type `:filesystem/file`. The `:content/bytes` key points to a
-blob which directly contains the byte content of the file.
+The `:content` key points to a blob which directly contains the byte content of
+the file.
 
 ### Supported Tags
 
@@ -50,54 +48,14 @@ Clojure.
 
 | Tag              | Type           | Definition |
 |------------------|----------------|------------|
-| `#bin`           | `byte[]`       | Binary data encoded in Base64.
-| `#uri`           | `URI`          | Uniform Resource Identifier string.
 | `#inst`          | `DateTime`     | An instant in time, rendered as an ISO-8601 string.
-| `#vault/ref`     | `HashID`       | A hash identifier string for a blob of data.
+| `#bytes/bin`     | `byte[]`       | Binary data encoded in Base64.
+| `#vault/blob`    | `HashID`       | A hash identifier string for a blob of data.
 | `#pgp/signature` | `PGPSignature` | A binary-encoded PGP signature packet.
 
 The system _should_ provide a standard mechanism for registering additional tag
 readers in API clients.
 
-## Key Blobs
-
-Vault makes use of the OpenPGP standard for public keys and digital signatures.
-Users of Vault are identified by _public key_ - the key itself is stored
-directly in the system as an ASCII 'armored' blob. The address of the key blob
-serves as an unambiguous identifier of the person controlling the corresponding
-private key.
-
-```
------BEGIN PGP PUBLIC KEY BLOCK-----
-Version: BCPG v1.50
-
-mI0EUr3KFwEEANAfzcKxWqBYhkUGo4xi6d2zZy2RAewFRKVp/BA2bEHLAquDnpn7
-abgrpsCFbBW/LEwiMX6cfYLMxvGzbg5oTfQHMs27OsnKCqFas9UkT6DYS1PM9u4C
-3qlJytK9AFQnSYOrSs8pe6VRdeHZb7FM+PawqH0cuoYfcMZiGAylddXhABEBAAG0
-IVRlc3QgVXNlciA8dGVzdEB2YXVsdC5tdnhjdmkuY29tPoi4BBMBAgAiBQJSvcoX
-AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRCSOxwcQ5IxioerBACBfXLk
-j4ryCBcmJ+jtL1/W5jUQ/E4LWW7gG34tkHBJk00YulXUe4lwY1x9//6zowVV7DvW
-ndmjcb0R6Duw76+xLsnEKomW0aV+ydoTtFZ7bX0kChX/IegPLMB0OnenzOoWKieN
-GLFUpzICH+i7Or5X2bmekHtnbHPfJmQAuvmUnrACAAA=
-=3aKz
------END PGP PUBLIC KEY BLOCK-----
-```
-
-## Data Signatures
-
-Users can sign data in the system with signature structures. Signatures are maps
-which follow the primary value in a data blob, and reference the public key blob
-of the owner.
-
-```clojure
-{:vault/type :vault/signature
- :key #vault/ref "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75"
- :signature #pgp/signature #bin "iQIcBAABAgAGBQJSeHKNAAoJEAadbp3eATs56ckP/2W5QsCPH5SMr..."}
-```
-
-The signature must match the UTF-8 encoded byte sequence of the characters which
-form the primary value in the blob (not including the header).
-
 ## Blob Graph
 
 A data structure should be split into multiple blobs if a part of the data is

diff --git a/doc/entities.md b/doc/entities.md
diff --git a/doc/identity.md b/doc/identity.md
@@ -0,0 +1,56 @@
+Identity and State
+==================
+
+Immutable data is great, but to be useful the system needs to be able to
+represent _mutable state_ somehow. Say a user stores a document; that content
+has some address based on its hash digest. If the user updates the document,
+they must keep a different address for the new version. The concept tying the
+different versions of the document together is _identity_.
+
+For motivation, suppose a user wants to store a document in Vault. The first
+version will have a certain hash identifier. When the user wants to make updates
+however, the new version of the document will have a new identifier! Users have
+to juggle remembering the last identifier for their data.
+
+## Mutable Namespaces
+
+To address these problems, a [public key blob](keys.md) establishes a
+_namespace_ which assigns a stable identity to a sequence of blob values. The
+hash of the public key provides a stable identifier to reference the changing
+values by. The 'current root' of the namespace is _bound_ to new values by
+adding _transaction blobs_:
+
+```clojure
+#vault/data
+{:vault/type :vault/tx
+ :time #inst "2013-10-25T09:13:24.000-00:00",
+ :ancestors #{#vault/blob "sha256:00f916cce73e53b5618069817fb451853e0b9f7529fe8e1c6f34615666322037"
+              #vault/blob "sha256:1d5f5e2dcf673e40556b26f4617598cfa26a46f192a18d2f808f6be6b36756cb"},
+ :bindings {#vault/blob "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75"
+            #vault/blob "sha256:e0fb5ab696858a047fd0c8e7f42a98b1649306a159084c9126b6c38a13f6459c",
+            #vault/blob "sha256:dac39f5db1bbbbf88b9a35f9df57eaa4e6248e56a014f54bc2b0792c636aaa5b"
+            #vault/blob "sha256:5667cf1cb367388af4f5827d89d8776d5a6210a7e64a785cd85a20bf8c6d8dcb"}}
+
+#vault/signature
+{:key #vault/blob "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75",
+ :signature #pgp/signature #bytes/bin "iQIcBAABAgAGBQJSeHKNAAoJEAadbp3eATs56ckP/2W5QsCPH5SMr..."}
+
+#vault/signature
+{:key #vault/blob "sha256:dac39f5db1bbbbf88b9a35f9df57eaa4e6248e56a014f54bc2b0792c636aaa5b",
+ :signature #pgp/signature #bytes/bin "AgAGBQJSeAoJEAadbp3eAHKNATs56iQIcBA/2W5QsCPHABckP5SMr..."}
+```
+
+Note that the transaction can bind multiple namespaces at once in an _atomic_
+way. This requires that the blob contain signatures from all affected
+namespaces.
+
+## Causal Ordering
+
+All transaction blobs are timestamped, so modifications to a namespaces can be
+ordered in time. However, transaction blobs _also_ contain an `:ancestors`
+field, giving them version-control semantics. In this way, a _namespace_ in
+Vault is comparable to a _branch_ in a version-control system like Git.
+
+The hash-based reference to past transactions enforces a strict causal ordering
+of updates. Transactions build up a merkle hash chain which provides a secure
+history of the mutations to a namespace.
diff --git a/doc/keys.md b/doc/keys.md
@@ -0,0 +1,39 @@
+Key Blobs
+=========
+
+Vault makes use of the OpenPGP standard for public keys and digital signatures.
+Users of Vault are identified by _public key_ - the key itself is stored
+directly in the system as an ASCII 'armored' blob. The address of the key blob
+serves as an unambiguous identifier of the person controlling the corresponding
+private key.
+
+```
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: BCPG v1.50
+
+mI0EUr3KFwEEANAfzcKxWqBYhkUGo4xi6d2zZy2RAewFRKVp/BA2bEHLAquDnpn7
+abgrpsCFbBW/LEwiMX6cfYLMxvGzbg5oTfQHMs27OsnKCqFas9UkT6DYS1PM9u4C
+3qlJytK9AFQnSYOrSs8pe6VRdeHZb7FM+PawqH0cuoYfcMZiGAylddXhABEBAAG0
+IVRlc3QgVXNlciA8dGVzdEB2YXVsdC5tdnhjdmkuY29tPoi4BBMBAgAiBQJSvcoX
+AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRCSOxwcQ5IxioerBACBfXLk
+j4ryCBcmJ+jtL1/W5jUQ/E4LWW7gG34tkHBJk00YulXUe4lwY1x9//6zowVV7DvW
+ndmjcb0R6Duw76+xLsnEKomW0aV+ydoTtFZ7bX0kChX/IegPLMB0OnenzOoWKieN
+GLFUpzICH+i7Or5X2bmekHtnbHPfJmQAuvmUnrACAAA=
+=3aKz
+-----END PGP PUBLIC KEY BLOCK-----
+```
+
+## Data Signatures
+
+Users can sign data in the system with signature structures. Signatures are maps
+which follow the primary value in a data blob, and reference the public key blob
+of the owner.
+
+```clojure
+#vault/signature
+{:key #vault/ref "sha256:461566632203729fe8e1c6f373e53b5618069817f00f916cceb451853e0b9f75"
+ :signature #pgp/signature #bytes/bin "iQIcBAABAgAGBQJSeHKNAAoJEAadbp3eATs56ckP/2W5QsCPH5SMr..."}
+```
+
+The signature must match the UTF-8 encoded byte sequence of the characters which
+form the primary value in the blob (not including the header).