first draft at did document

pki/diddocument.md

@@ -0,0 +1,60 @@
+# Decentralized Identity Document (DID Document)
+
+This is the subset of the [DID Document](https://w3c-ccg.github.io/did-spec) spec that we implement as part of the uPort platform.
+
+The Identity document is stored on IPFS and tied to the address using the uport registry as specified in the [PKI document](../index).
+
+## Contents
+
+The Identity document must contain the public key for the identity, everything else is optional. Anything in this document is public, so please be wary of publishing any Private information to it.
+
+This is an example of a minimal identity document:
+
+```js
+{
+  "@context": "https://w3id.org/did/v1",
+  "id": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX",
+  "publicKey": [{
+    "id": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX#keys-1",
+    "type": "EdDsaSAPublicKeySecp256k1",
+    "owner": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX",
+    "publicKeyHex": "04613bb3a4874d27032618f020614c21cbe4c4e4781687525f6674089f9bd3d6c7f6eb13569053d31715a3ba32e0b791b97922af6387f087d6b5548c06944ab062"
+  }, {
+    "id": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX#keys-2",
+    "type": "Ed25519SigningKey",
+    "owner": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX",
+    "publicKeyBase64": "QCFPBLm5pwmuTOu+haxv0+Vpmr6Rrz/DEEvbcjktQnQ="
+  }]
+}
+```
+
+This is a example of a identity document for an app with extra public profile information:
+
+```js
+{
+  "@context": "https://w3id.org/did/v1",
+  "id": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX",
+  "publicKey": [{
+    "id": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX#keys-1",
+    "type": "EdDsaSAPublicKeySecp256k1",
+    "owner": "did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX",
+    "publicKeyHex": "04613bb3a4874d27032618f020614c21cbe4c4e4781687525f6674089f9bd3d6c7f6eb13569053d31715a3ba32e0b791b97922af6387f087d6b5548c06944ab062"
+  }],
+  "owner": {
+    "@context":"http://schema.org",
+    "@type":"Organization",
+    "name":"uPort @ Devcon 3",
+    "description":"Uport Attestations",
+    "image":{"@type":"ImageObject","name":"avatar","contentUrl":"/ipfs/QmSCnmXC91Arz2gj934Ce4DeR7d9fULWRepjzGMX6SSazB"}
+  }
+}
+
+```
+
+### Parameters
+
+Name | Description | Required
+---- | ----------- | --------
+`@context` | `https://w3id.org/did/v1`| yes
+`publicKey` | array of allowed hex encoded [secp256k1 ECDSA curve](https://en.bitcoin.it/wiki/Secp256k1) public keys | yes
+`owner` | Public profile information compatible with [schema.org](https://schema.org) | no

pki/identitydocument.md

@@ -1,5 +1,7 @@
 # Identity Document
 
+Note this format will be deprecated soon and replaced by a standard [DID Document](./diddocument.md).
+
 The Identity document is stored on IPFS and tied to the address using the uport registry as specified in the [PKI document](../index).
 
 The Identity document is a JSON document (strictly speaking a [JSON-LD](https://json-ld.org/)).

pki/index.md

@@ -18,45 +18,10 @@ The following overview shows the basic process for creating and verifying a trus
 
 ## Identity Document
 
-The Identity Document is a [JSON LD](https://json-ld.org) document stored on IPFS. Here is an example:
+We currently support 2 kinds of Identity Documents:
 
-[IPFS Hash QmNVHxsMAXvYktfHLYhRjcL7hGBBojTwY7mnJKsJweCZJK]:https://ipfs.infura.io/ipfs/QmNVHxsMAXvYktfHLYhRjcL7hGBBojTwY7mnJKsJweCZJK
-
-```json
-{
-  "@context":"http://schema.org",
-  "@type":"Person","publicKey":"0x04848b547c6effe251b6e9f69c3bc6845b7997963554703aa41bc1b4c8d8db787ac966938139d5b36f404b89727fbc279153a20ad43ff25da0c30edb8b84d9c836",
-  "publicEncKey":"bpEGZfAtubOkFSsIdZFSlMN30hYlNOjHzS7LJgep82A="
-}
-```
-
-Since it is a JSON LD document, you can include all kinds of data (such as name, location, etc.)
-
-### `publicKey` item
-
-The most important part for the function of the PKI itself is that it contains the `publicKey` of the identity. This is the only required item.
-
-This is a `0x` prefixed hex encoded DER encoded public key for the [secp256k1 ECDSA curve](https://en.bitcoin.it/wiki/Secp256k1).
-
-### `publicEncKey` item
-
-This is an encryption public key created for use with [NACL Box Public Key Encryption](http://nacl.cr.yp.to/box.html).
-
-The public encryption key generated by the NACL library is encoded as a Base64 string.
-
-### `name` item
-
-The uPort app and other apps presenting signed JWTs to their users will use the [`name`](http://schema.org/name) item stored in the Identity Document.
-
-### `image` item
-
-The uPort app and other apps presenting signed JWTs to their users will use the [`image`](http://schema.org/image) item stored in the Identity Document.
-
-The image currently has to be stored in IPFS and the format should look like this:
-
-```json
-{"image":{"contentUrl":"/ipfs/HASH"}}
-```
+- [DID Documents](./diddocument.md)
+- [Legacy Identity Documents](./identitydocument.md)
 
 ## Verifying a signature