From 034c8940cfd1fa80efb35d06b1103f0dd6d1094b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Fri, 8 Jun 2018 12:25:06 +0100 Subject: [PATCH 01/23] docs: add identity RFC --- docs/rfc-identity.md | 196 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 docs/rfc-identity.md diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md new file mode 100644 index 0000000..b8055fc --- /dev/null +++ b/docs/rfc-identity.md @@ -0,0 +1,196 @@ +# RFC Peer-Star-Identity + +This is a proposal for an identity management system for Peer-Star, named Peer-Star-Identity. It's built upon standards to provide a good foundation for Peer-Star applications to authenticate and identify users. + +*Authors*: André Cruz, João Santos, Pedro Teixeira + +1. [Standards & foundations](#standards--foundations) + 1. [Decentralized Identifiers](#decentralized-identifiers-dids) + 1. [Self-signed Verifiable Claims](#self-signed-verifiable-claims) + 1. [Self-signed Key-chain](#self-signed-key-chain) + 1. [Trusting an entity](#trusting-an-entity) +1. [Proposal: The IdentityManager](#proposal-the-identitymanager) + 1. [What is it?](#what-is-it) + 1. [Managing identities](#managing-identities) + 1. [Managing Verifiable Claims](#managing-verifiable-claims) + 1. [Authenticating on applications](#authentication-on-applications) + 1. [Signing artifacts on applications](#signing-artifacts-on-applications) + 1. [Managing application sessions](#managing-application-sessions) + 1. [Revoking a device](#revoking-a-device) +1. [Diagrams & mockups](#diagrams--mockups) +1. [Glossary](#glossary) + +## Standards & foundations + +### Decentralized Identifiers (DIDs) + +A Decentralized Identifier (DID) is a string that uniquely maps to an identiy, e.g. `did:btcr:123-445-333`. This standard is fully described in the [W3C DID spec](https://w3c-ccg.github.io/did-spec/) and is being widely adopted to create digital identities. + +There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a Public Key that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. + +The owner of a DID can use the DID's private key to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public key listed in the DID-Document. + +### Self-signed Verifiable Claims + +A Verifiable Claim is a qualification, achievement, quality, or piece of information about an entity's background such as a name, government ID, payment provider, home address, or university degree. This standard is described in detail in the [W3C Verifiable Claims spec](https://www.w3.org/TR/verifiable-claims-data-model). + +By linking one or more Verifiable Claims to an identity, we are strengthening the credibility of the identity itself. Those claims may be self-signed or made by other entities. + +We will start off by leveraging self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. + +### Self-signed Key-chain + +In a simple configuration, the DID key (the one used to prove control of the DID) could be used to sign artifacts and to cypher communication. However, that solution is sub-optimal for the following reasons: + +- Does not offer Perfect Forward Secrecy: If an attacker manages to gain access to the private key, he/she is able to decypher all previous communications made to, and from, that entity's DID. +- Over exposes the private key: A private key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to the key. +- If the key is compromised, the attacker is able to completely impersonate the real DID owner. + +For those reasons, we propose a mechanism where a master key pair is used to sign (authorize) other key pairs. The master key pair can then be used to sign others. This process can continue through many layers. The advantage of this mechanism is that if a key is compromised, only the keys that it signed need to be changed. All the other ones above it, remain safe. + +In the first version of this proposal we envision three layers of keys, as shown in the figure below. The first, *layer 1* is the DID key, called the *Root Key*. The Root Key is the one used to create the DID and authorize *layer 2* keys. Each entity will use Peer-Star applications from different devices (laptop, smart-phone and others). For each device, an entity will have one key pair whose public key is signed by the _Root Key_. Those keys are called Device Keys and are _layer 2_ keys. Finally, Device Keys can be used to sign (authorize) new temporary keys, Ephemeral Keys, to be used by specific applications. These are _layer 3_ keys. + +``` +(layer 1) rootKey +(layer 2) |-- deviceKey1 {signed by rootKey} +(layer 3) |---- applicationKey1 {signed by deviceKey1} +(layer 3) |---- applicationKey2 {signed by deviceKey1} +(layer 2) |-- deviceKey_n_ {signed by rootKey} +``` + +#### Revocation + +It's important for the entity in control of the DID to revoke a Device Key in case of theft or other circumstances. Similarly to how public keys are made available in DID-Documents, revoked Public Device Keys of a DID should also be public. The way a revoked Device Public Key gets published and the way a relying party query the list of revoked devices depends on the DID method as well. + +#### Verifying the chain + +A relying party must always verify the signatures of the Key-Chain to be sure that the entity controlling the DID authorized a specific public key. This is a three step process: + +- Verify the Public Key signature of each layer, starting from the Leaf Key up to the Root Key. +- Check if the Root Public Key of the chain matches the DID Public Key. +- Check if the Device Public Key is not flagged as revoked. + +At this point, a relying party just needs to prove that the entity owns the private key of the layer 3 key. This can easily be done by asking him to sign or decrypt a challenge. + +### Trusting an entity + +Typical DApps flows require a relying party to trust another. We can leverage DIDs, self-Signed Verifiable Claims and self-signed Key-chains in an "handshake" ceremony. + +Consider the following example: Alice wants to share something secret with Bob. + +After agreeing on a transport, Alice presents herself with her DID, her self-Signed Verifiable Claims and a self-signed Key-chain (linked list of public keys and signatures) to Bob. Alice does this by encrypting all this material, along with a nounce, with Bob's public key and signing it with her leaf private key (the last key on the chain). To trust Alice, Bob must: + +1. Decrypt Alice's message and check its signature against the Leaf Public Key. +2. Resolve Alice's DID to a DID-Document which includes the Root Public Key. +3. Verify the Self-signed Key-chain as described in [Verifying the chain](#Verifying-the-chain) +4. Check the signatures of the self-signed Verifiable Claims against the Root Public Key. +5. Manually verify Alice's Verifiable Claims to see if they credible. +6. If Alice uses different keys for encrypting and signing, send her a challenge encrypted with her Public Key for encryption and ask her to send back the decrypted challenge. + +Please note that certain aspects of point `5.` can be done automatically by crawling the proofs and verifying the signatures against Alice's Root Public Key. Still, Bob must explicitly verify the proofs as an attacker might be trying to impersonate the real Alice with fake social profiles. + +If all went good, Bob is pretty confident that Alice is the real Alice. For future "handshake" ceremonies to be faster, Bob can store Alice's DID and Device Public Key somewhere, like a contacts list. + +## Proposal: The IdentityManager + +Usability is a crucial aspect on this proposal as it played a very important role on its concept. + +On one hand, the experience for end-users should be intuitive, simple and familiar. Ideally, users should have little contact with private keys and most of the cryptographic operations should happen behind the scenes. On the other hand, developers building DApps should have an easy way to authenticate users. + +### What is it? + +The IdentityManager is a web-page hosted on IPFS and reachable via a specific URL, e.g.: https://peer-identity.io. The application will work completely offline thanks to the installation of a ServiceWorker. + +Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. + +Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with a intuitive API. + +Moreover, any meaningful event on the IdentityManager, such as the removal of an identity, will be broadcasted to interested parties. This allows applications to immediately react to certain events by subscribing to them on the IdentityManager. + +Among others, the most important advantages of this solution are: + +- Doesn't require the Root Keys that control the DID to be used often, making them less vulnerable to theft as they can be kept safe. +- Embraces several DID methods instead of being tied to a specific method. +- Doesn't require any extensions, scanning of QRCodes, or any other unfriendly processes for daily use. +- Requires little updates to data stored in blockchains, hence incurring less costs. +- Acts like a "server" in the sense that sensitive information may be safely stored in it. Many DID methods require a secret for certain actions, e.g.: uPort requires an app secret to request normal and verified credentials. +- Has a wide support among devices. If we make it a PWA, users may install the application in the OS itself, further enhancing the user experience. +- Allows the user to choose between several identities when authenticating, useful for people that manage companies, organizations or similar. + +### Managing identities + +Users will be able to associate one or more identities using their preferred DID method. They will be guided throughout the process according to the chosen DID method. Once they complete it, they will have successfully created a Device Key associated with the identity Root Key (via signing). + +All the Device Private Keys will be encrypted with a passphrase to improve security. Even if a device gets stolen, the robber won't be able to use most features without the passphrase as all the information stored locally will be encrypted with the Device Public Key. This gives time for the owner of the Identity to revoke the compromised device in the IdentityManager of another device. + +Because the identity was linked to this device at setup time, and depending on the DID method, profile information and verifiable claims might become stale. For this reason, users will be able to sync up with their Root Identity to update any stale data. + +### Managing Verifiable Claims + +Users will be able to add claims to their identities. Initially, we will focus on adding self-signed claims linked to some of the most popular social networks. The process of adding those claims (and proofs) will work similarly to [Keybase](https://keybase.io/) in the sense that users will be guided throughout the process. + +The exact way in how the claims will be stored is dependent on the DID method. For instance, uPort already provides a way to store these claims via attestations. + +### Authentication on applications + +Peer-Star applications will use the IdentityManagerClient to manage the user's session. + +When bootstrapped, the IdentityManagerClient will read a pair of public and private keys, called the Session Keys, from the local storage. Alternatively, the Session Keys will be generated and stored in case they do not exist yet. Note that the Session Keys are considered layer 3 keys. +The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If that's not the case, the application can request the user to authenticate via the IdentityManagerClient. + +When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data (including the signed Session Public Key) is sent back to the application. If the user denied the disclosure of the information, the operation will fail. +In both scenarios, the popup is closed and the outcome is made available to the application. + +Applications might choose the TTL of a session depending on the degree of security they want to have. + +### Signing artifacts on applications + +Applications may want to sign artifacts, such as regular data or Ephemeral Keys. This will be possible in two different ways: + +1. Sign with the Session Private Key +2. Sign with the Device Private Key + +The first method is less intrusive and happens transparently to the user, but is less secure. More specifically, a robber who stoled a device may still sign Ephemeral Keys with the Session Private Key as long as a session is valid (not expired). Relying parties will still see those signatures as valid until the DID owner revokes the stolen device. + +The second method provides more security as the user is prompted for the Device Private Key passphrase, but it's more intrusive. The interaction is similar to the Authentication process, where a popup pointing to the sign screen gets open. The user either allows or denies the signing and the result gets back into the application. Please note that the passphrase might be stored in memory in the IdentityManager during a certain amount of time, which in turn makes this process less intrusive for subsequent signings. + +Ultimately, the application may choose between both methods for different situations depending on the security degree they want to have. + +### Managing application sessions + +Users will be able to revoke any application session listed on the identity's Authenticated Session list. Revoking a session will essentially delete the application session from the IdentityManager local storage. + +Even if a malicious application persists the session data for future use, it will be unable to sign artifacts, such as Ephemeral Keys, with the Device Private Key, rendering the application useless in those scenarios. + +### Revoking a device + +Users must be able to revoke a device associated with an identity. To do so, users may see the list of devices associated with an identity and revoke any device of that list, including the device from which they are interacting. This will require interacting with the DID method (Root Private Key) to publish the device being revoked. + +If a device becomes aware that it was revoked, it will trigger a wipe-out process where all the identity data stored locally will be deleted, including the Device Key and Authenticated Sessions. + +### Diagrams & mockups + +**IdentityManager authentication flow diagram** + +![Authentication flow](https://user-images.githubusercontent.com/1017236/41130726-db9125b4-6aaf-11e8-9ec1-bd55c16a7ff2.png) + +**IdentityManager authenticate screen diagram** + +![Authenticate screen](https://i.imgur.com/kyvkrZE.png) + +**IdentityManager application mockups** + +![IdentityManager authenticate screen mockup](https://i.imgur.com/fZ7VYfi.png) + +## Glossary + +- **Entity:** A person, company, organization or equivalent that controls an identity. +- **DID:** An identity identifier, which resolves to a DID-Document. +- **DID-Document:** A JSON-LD document which contains information about an identity, such as public keys to be used to communicate with entity that controls the identity. +- **Root Keys:** A pair of public and private keys that control the DID. +- **Device Keys:** A pair of public and private keys of a device, signed by the Root Public Key that controls the DID. +- **Ephemeral Keys:** A temporary pair of public and private keys, signed by the Device Private Key. +- **Session**: A unique pair of public and private keys stored locally by the IdentityManagerClient that identifies a visitor. +- **Authenticated Session:** A session that was signed by the entity controlling the Device Key. +- **IdentityManager**: An application that provides identification and authentication to the Peer-Star ecosystem. +- **IdentityManagerClient**: A library used by Peer-Star applications that makes it easier to interact with the IdentityManager. From 9cecc0fbc04fe8c3c533a749978782234012d1fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 13 Jun 2018 11:12:42 +0100 Subject: [PATCH 02/23] docs: fix session private being owned by the application --- docs/rfc-identity.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index b8055fc..a31140a 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -34,9 +34,9 @@ The owner of a DID can use the DID's private key to digitally sign artifacts. An A Verifiable Claim is a qualification, achievement, quality, or piece of information about an entity's background such as a name, government ID, payment provider, home address, or university degree. This standard is described in detail in the [W3C Verifiable Claims spec](https://www.w3.org/TR/verifiable-claims-data-model). -By linking one or more Verifiable Claims to an identity, we are strengthening the credibility of the identity itself. Those claims may be self-signed or made by other entities. +By issuing Verifiable Claims about an entity's identity, we are strengthening the credibility of the identity itself. Those claims may be issued by the owners themselves or by other identities. -We will start off by leveraging self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. +We will start off by leveraging self-issued and self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. ### Self-signed Key-chain @@ -135,10 +135,9 @@ The exact way in how the claims will be stored is dependent on the DID method. F Peer-Star applications will use the IdentityManagerClient to manage the user's session. -When bootstrapped, the IdentityManagerClient will read a pair of public and private keys, called the Session Keys, from the local storage. Alternatively, the Session Keys will be generated and stored in case they do not exist yet. Note that the Session Keys are considered layer 3 keys. -The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If that's not the case, the application can request the user to authenticate via the IdentityManagerClient. +When bootstrapped, the IdentityManagerClient will attempt to read the a Session Public Key from the local storage of the applications' origin. The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If the IdentityManager doesn't recognize that Session Public Key or if there's no Session Public Key in first place, there's no Authenticated Session, meaning that no user is authenticated. In such cases, the application may request the Identity Manager to authenticate the user, typically via a login button. -When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data (including the signed Session Public Key) is sent back to the application. If the user denied the disclosure of the information, the operation will fail. +When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data (including the Session Public Key and its signature signed by the Device Private Key) is sent back to the application. If the user denied the disclosure of the information, the operation will fail. In both scenarios, the popup is closed and the outcome is made available to the application. Applications might choose the TTL of a session depending on the degree of security they want to have. @@ -150,7 +149,7 @@ Applications may want to sign artifacts, such as regular data or Ephemeral Keys. 1. Sign with the Session Private Key 2. Sign with the Device Private Key -The first method is less intrusive and happens transparently to the user, but is less secure. More specifically, a robber who stoled a device may still sign Ephemeral Keys with the Session Private Key as long as a session is valid (not expired). Relying parties will still see those signatures as valid until the DID owner revokes the stolen device. +The first method is less intrusive and happens transparently to the user, but is less secure. More specifically, a robber who stoled a device may still sign Ephemeral Keys with the Session Private Key as long as a session is valid (not expired). Relying parties will still see those signatures as valid until the DID owner revokes the stolen device. The second method provides more security as the user is prompted for the Device Private Key passphrase, but it's more intrusive. The interaction is similar to the Authentication process, where a popup pointing to the sign screen gets open. The user either allows or denies the signing and the result gets back into the application. Please note that the passphrase might be stored in memory in the IdentityManager during a certain amount of time, which in turn makes this process less intrusive for subsequent signings. @@ -172,12 +171,13 @@ If a device becomes aware that it was revoked, it will trigger a wipe-out proces **IdentityManager authentication flow diagram** -![Authentication flow](https://user-images.githubusercontent.com/1017236/41130726-db9125b4-6aaf-11e8-9ec1-bd55c16a7ff2.png) +![Authentication flow](https://i.imgur.com/uMAi2be.png) **IdentityManager authenticate screen diagram** ![Authenticate screen](https://i.imgur.com/kyvkrZE.png) + **IdentityManager application mockups** ![IdentityManager authenticate screen mockup](https://i.imgur.com/fZ7VYfi.png) @@ -186,11 +186,11 @@ If a device becomes aware that it was revoked, it will trigger a wipe-out proces - **Entity:** A person, company, organization or equivalent that controls an identity. - **DID:** An identity identifier, which resolves to a DID-Document. -- **DID-Document:** A JSON-LD document which contains information about an identity, such as public keys to be used to communicate with entity that controls the identity. +- **DID-Document:** A JSON-LD document which contains information about an identity, such as public keys to be used to communicate with the entity that controls the identity. - **Root Keys:** A pair of public and private keys that control the DID. - **Device Keys:** A pair of public and private keys of a device, signed by the Root Public Key that controls the DID. - **Ephemeral Keys:** A temporary pair of public and private keys, signed by the Device Private Key. -- **Session**: A unique pair of public and private keys stored locally by the IdentityManagerClient that identifies a visitor. -- **Authenticated Session:** A session that was signed by the entity controlling the Device Key. +- **Session**: A unique public key stored locally by the IdentityManagerClient that identifies a visitor. +- **Authenticated Session:** A session that was signed by the entity controlling the Device Key. The Session Private Key lives securely on the IdentityManager origin. - **IdentityManager**: An application that provides identification and authentication to the Peer-Star ecosystem. - **IdentityManagerClient**: A library used by Peer-Star applications that makes it easier to interact with the IdentityManager. From cfc52244e13b17151078427572d4df3f361d2976 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 13 Jun 2018 11:43:19 +0100 Subject: [PATCH 03/23] docs: small phrase improvement --- docs/rfc-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index a31140a..b40777e 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -191,6 +191,6 @@ If a device becomes aware that it was revoked, it will trigger a wipe-out proces - **Device Keys:** A pair of public and private keys of a device, signed by the Root Public Key that controls the DID. - **Ephemeral Keys:** A temporary pair of public and private keys, signed by the Device Private Key. - **Session**: A unique public key stored locally by the IdentityManagerClient that identifies a visitor. -- **Authenticated Session:** A session that was signed by the entity controlling the Device Key. The Session Private Key lives securely on the IdentityManager origin. +- **Authenticated Session:** A Session that was signed by the entity controlling the Device Key. The Session Private Key lives securely on the IdentityManager local storage. - **IdentityManager**: An application that provides identification and authentication to the Peer-Star ecosystem. - **IdentityManagerClient**: A library used by Peer-Star applications that makes it easier to interact with the IdentityManager. From d60ff8eb3564e6a197e7bc5b24e6448f06de5786 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Thu, 14 Jun 2018 10:03:54 +0100 Subject: [PATCH 04/23] docs: very minor tweaks --- docs/rfc-identity.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index b40777e..1af2f9b 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -46,7 +46,7 @@ In a simple configuration, the DID key (the one used to prove control of the DID - Over exposes the private key: A private key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to the key. - If the key is compromised, the attacker is able to completely impersonate the real DID owner. -For those reasons, we propose a mechanism where a master key pair is used to sign (authorize) other key pairs. The master key pair can then be used to sign others. This process can continue through many layers. The advantage of this mechanism is that if a key is compromised, only the keys that it signed need to be changed. All the other ones above it, remain safe. +Alternatively, we propose a mechanism where a master key pair is used to sign (authorize) other key pairs. The master key pair can then be used to sign others. This process can continue through many layers. The advantage of this mechanism is that if a key is compromised, only the keys that it signed need to be changed. All the other ones above it, remain safe. In the first version of this proposal we envision three layers of keys, as shown in the figure below. The first, *layer 1* is the DID key, called the *Root Key*. The Root Key is the one used to create the DID and authorize *layer 2* keys. Each entity will use Peer-Star applications from different devices (laptop, smart-phone and others). For each device, an entity will have one key pair whose public key is signed by the _Root Key_. Those keys are called Device Keys and are _layer 2_ keys. Finally, Device Keys can be used to sign (authorize) new temporary keys, Ephemeral Keys, to be used by specific applications. These are _layer 3_ keys. @@ -70,7 +70,7 @@ A relying party must always verify the signatures of the Key-Chain to be sure th - Check if the Root Public Key of the chain matches the DID Public Key. - Check if the Device Public Key is not flagged as revoked. -At this point, a relying party just needs to prove that the entity owns the private key of the layer 3 key. This can easily be done by asking him to sign or decrypt a challenge. +Still, more steps are necessary for a relying party to fully trust the entity. This is explained in the next section. ### Trusting an entity @@ -85,7 +85,7 @@ After agreeing on a transport, Alice presents herself with her DID, her self-Sig 3. Verify the Self-signed Key-chain as described in [Verifying the chain](#Verifying-the-chain) 4. Check the signatures of the self-signed Verifiable Claims against the Root Public Key. 5. Manually verify Alice's Verifiable Claims to see if they credible. -6. If Alice uses different keys for encrypting and signing, send her a challenge encrypted with her Public Key for encryption and ask her to send back the decrypted challenge. +6. If Alice uses different keys for encrypting, send her a challenge encrypted with her Public Key for encryption and ask her to send back the decrypted challenge. Please note that certain aspects of point `5.` can be done automatically by crawling the proofs and verifying the signatures against Alice's Root Public Key. Still, Bob must explicitly verify the proofs as an attacker might be trying to impersonate the real Alice with fake social profiles. @@ -137,7 +137,7 @@ Peer-Star applications will use the IdentityManagerClient to manage the user's s When bootstrapped, the IdentityManagerClient will attempt to read the a Session Public Key from the local storage of the applications' origin. The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If the IdentityManager doesn't recognize that Session Public Key or if there's no Session Public Key in first place, there's no Authenticated Session, meaning that no user is authenticated. In such cases, the application may request the Identity Manager to authenticate the user, typically via a login button. -When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data (including the Session Public Key and its signature signed by the Device Private Key) is sent back to the application. If the user denied the disclosure of the information, the operation will fail. +When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data, including the Session Public Key and its signature signed by the Device Private Key, is sent back to the application. If the user denied the disclosure of the information, the operation will fail. In both scenarios, the popup is closed and the outcome is made available to the application. Applications might choose the TTL of a session depending on the degree of security they want to have. @@ -177,7 +177,6 @@ If a device becomes aware that it was revoked, it will trigger a wipe-out proces ![Authenticate screen](https://i.imgur.com/kyvkrZE.png) - **IdentityManager application mockups** ![IdentityManager authenticate screen mockup](https://i.imgur.com/fZ7VYfi.png) From d38de04974f49056076ee23b221a23ecddc46949 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Thu, 21 Jun 2018 13:13:47 +0100 Subject: [PATCH 05/23] docs: use did method delegates and did-auth --- docs/rfc-identity.md | 99 ++++++++++++++++++++------------------------ 1 file changed, 45 insertions(+), 54 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 1af2f9b..19edf5c 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -5,10 +5,10 @@ This is a proposal for an identity management system for Peer-Star, named Peer-S *Authors*: André Cruz, João Santos, Pedro Teixeira 1. [Standards & foundations](#standards--foundations) - 1. [Decentralized Identifiers](#decentralized-identifiers-dids) + 1. [Decentralized identifiers](#decentralized-identifiers-dids) 1. [Self-signed Verifiable Claims](#self-signed-verifiable-claims) - 1. [Self-signed Key-chain](#self-signed-key-chain) - 1. [Trusting an entity](#trusting-an-entity) + 1. [DID Delegates & devices](#did-delegates--devices) + 1. [Using DID-Auth to prove control of the DID](#using-did-auth-to-prove-control-of-the-did) 1. [Proposal: The IdentityManager](#proposal-the-identitymanager) 1. [What is it?](#what-is-it) 1. [Managing identities](#managing-identities) @@ -22,13 +22,13 @@ This is a proposal for an identity management system for Peer-Star, named Peer-S ## Standards & foundations -### Decentralized Identifiers (DIDs) +### Decentralized identifiers (DIDs) -A Decentralized Identifier (DID) is a string that uniquely maps to an identiy, e.g. `did:btcr:123-445-333`. This standard is fully described in the [W3C DID spec](https://w3c-ccg.github.io/did-spec/) and is being widely adopted to create digital identities. +A Decentralized Identifier (DID) is a string that uniquely maps to an identity, e.g. `did:btcr:123-445-333`. This standard is fully described in the [W3C DID spec](https://w3c-ccg.github.io/did-spec/) and is being widely adopted to create digital identities. -There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a Public Key that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. +There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a set of public key that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. -The owner of a DID can use the DID's private key to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public key listed in the DID-Document. +The owner of a DID can use the DID's private keys to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public keys listed in the DID-Document. ### Self-signed Verifiable Claims @@ -38,56 +38,43 @@ By issuing Verifiable Claims about an entity's identity, we are strengthening th We will start off by leveraging self-issued and self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. -### Self-signed Key-chain +### DID Delegates & devices -In a simple configuration, the DID key (the one used to prove control of the DID) could be used to sign artifacts and to cypher communication. However, that solution is sub-optimal for the following reasons: +In a simple configuration, there's only a key that owns the DID, called the Master Key. That key could be used to sign artifacts and to cypher communication. However, that solution is sub-optimal for the following reasons: -- Does not offer Perfect Forward Secrecy: If an attacker manages to gain access to the private key, he/she is able to decypher all previous communications made to, and from, that entity's DID. -- Over exposes the private key: A private key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to the key. -- If the key is compromised, the attacker is able to completely impersonate the real DID owner. +1. Does not offer Perfect Forward Secrecy: If an attacker manages to gain access to the Master Key, he/she is able to decypher all previous communications made to, and from, that entity's DID. +2. Over exposes the private key: A Master Key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to it. +3. If the Master Key is compromised, the attacker is able to completely impersonate the real DID owner. -Alternatively, we propose a mechanism where a master key pair is used to sign (authorize) other key pairs. The master key pair can then be used to sign others. This process can continue through many layers. The advantage of this mechanism is that if a key is compromised, only the keys that it signed need to be changed. All the other ones above it, remain safe. +The DID spec states that DID methods must provide a way for the owner to rotate keys, which solve `1` and `2`. The DID spec also states that DID methods must provide a way to recover the DID (e.g.: in case of theft), which solves `3`. -In the first version of this proposal we envision three layers of keys, as shown in the figure below. The first, *layer 1* is the DID key, called the *Root Key*. The Root Key is the one used to create the DID and authorize *layer 2* keys. Each entity will use Peer-Star applications from different devices (laptop, smart-phone and others). For each device, an entity will have one key pair whose public key is signed by the _Root Key_. Those keys are called Device Keys and are _layer 2_ keys. Finally, Device Keys can be used to sign (authorize) new temporary keys, Ephemeral Keys, to be used by specific applications. These are _layer 3_ keys. +Nevertheless, the DID spec advises DID methods to support adding delegate keys that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. +delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). -``` -(layer 1) rootKey -(layer 2) |-- deviceKey1 {signed by rootKey} -(layer 3) |---- applicationKey1 {signed by deviceKey1} -(layer 3) |---- applicationKey2 {signed by deviceKey1} -(layer 2) |-- deviceKey_n_ {signed by rootKey} -``` +It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the owner key is used instead. In both cases, from now on, we will call these keys Device Keys. #### Revocation -It's important for the entity in control of the DID to revoke a Device Key in case of theft or other circumstances. Similarly to how public keys are made available in DID-Documents, revoked Public Device Keys of a DID should also be public. The way a revoked Device Public Key gets published and the way a relying party query the list of revoked devices depends on the DID method as well. +As said earlier in this document, the entity in control of the DID may revoke a Device Key. Similarly to how non-revoked Public Device Keys keys are publicly listed in DID-Documents, revoked Public Device Keys should also be public. The reasoning is that a relying party must be able to verify signatures made the past and, as such, must be able to assert that the public key is associated to the DID, even if it's revoked. -#### Verifying the chain +As of now, the DID spec does not specifies how and where the revoked keys can be obtained. There's an [open issue](https://github.com/w3c-ccg/did-spec/issues/63) on the DID spec that brings this topic into discussion and, apparently, the W3C CCG working group is keen in listing revoked keys in the DID-Document. -A relying party must always verify the signatures of the Key-Chain to be sure that the entity controlling the DID authorized a specific public key. This is a three step process: +### Using DID-Auth to prove control of the DID -- Verify the Public Key signature of each layer, starting from the Leaf Key up to the Root Key. -- Check if the Root Public Key of the chain matches the DID Public Key. -- Check if the Device Public Key is not flagged as revoked. +Typical DApps flows require a relying party to trust another. We can leverage DIDs and self-Signed Verifiable Claims in an "handshake" ceremony. The ceremony should follow the [DID-Auth spec](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md). -Still, more steps are necessary for a relying party to fully trust the entity. This is explained in the next section. +To exemplify how [DID-Auth] works, consider the following example: Alice wants to share something secret with Bob. -### Trusting an entity +After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-Signed Verifiable Claims. Alice does this by encrypting all this material, along with a nounce, with Bob's public key and signing her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: -Typical DApps flows require a relying party to trust another. We can leverage DIDs, self-Signed Verifiable Claims and self-signed Key-chains in an "handshake" ceremony. +1. Decrypt Alice's message +2. Resolve Alice's DID to a DID-Document +3. Check if Alice's Device Public Key is listed in `authentication` property of the DID-Document +4. Verify the message signature against her Device Public Key using the correct algorithm +5. Verify the signatures of the self-signed Verifiable Claims against the public keys listed in the `publicKey` property of the DID-Document. +6. Manually verify Alice's Verifiable Claims to see if they credible. -Consider the following example: Alice wants to share something secret with Bob. - -After agreeing on a transport, Alice presents herself with her DID, her self-Signed Verifiable Claims and a self-signed Key-chain (linked list of public keys and signatures) to Bob. Alice does this by encrypting all this material, along with a nounce, with Bob's public key and signing it with her leaf private key (the last key on the chain). To trust Alice, Bob must: - -1. Decrypt Alice's message and check its signature against the Leaf Public Key. -2. Resolve Alice's DID to a DID-Document which includes the Root Public Key. -3. Verify the Self-signed Key-chain as described in [Verifying the chain](#Verifying-the-chain) -4. Check the signatures of the self-signed Verifiable Claims against the Root Public Key. -5. Manually verify Alice's Verifiable Claims to see if they credible. -6. If Alice uses different keys for encrypting, send her a challenge encrypted with her Public Key for encryption and ask her to send back the decrypted challenge. - -Please note that certain aspects of point `5.` can be done automatically by crawling the proofs and verifying the signatures against Alice's Root Public Key. Still, Bob must explicitly verify the proofs as an attacker might be trying to impersonate the real Alice with fake social profiles. +Please note that certain aspects of point `6.` can be done automatically by crawling the proofs and verifying the signatures against Alice's Public Keys. Still, Bob must explicitly verify the proofs as an attacker might be trying to impersonate the real Alice with fake social profiles. If all went good, Bob is pretty confident that Alice is the real Alice. For future "handshake" ceremonies to be faster, Bob can store Alice's DID and Device Public Key somewhere, like a contacts list. @@ -97,33 +84,37 @@ Usability is a crucial aspect on this proposal as it played a very important rol On one hand, the experience for end-users should be intuitive, simple and familiar. Ideally, users should have little contact with private keys and most of the cryptographic operations should happen behind the scenes. On the other hand, developers building DApps should have an easy way to authenticate users. +The IdentityManager packages emerging [Standards & foundations](#standards--foundations) into a intuitive and easy to use interface for end-users. + ### What is it? -The IdentityManager is a web-page hosted on IPFS and reachable via a specific URL, e.g.: https://peer-identity.io. The application will work completely offline thanks to the installation of a ServiceWorker. +The IdentityManager is a web-page hosted on IPFS and reachable via a specific URL, e.g.: https://peer-identity.io. The application will work completely offline thanks to the installation of a ServiceWorker. By using the application, users will be able to: -Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. +- Create identities on several DID methods +- Import identities created on other devices +- Manage Verifiable Claims of identities +- Authenticate to dApps -Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with a intuitive API. +Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with a intuitive API. Moreover, any meaningful event on the IdentityManager, such as the removal of an identity, will be broadcasted to interested parties. This allows applications to immediately react to certain events by subscribing to them on the IdentityManager. Among others, the most important advantages of this solution are: -- Doesn't require the Root Keys that control the DID to be used often, making them less vulnerable to theft as they can be kept safe. - Embraces several DID methods instead of being tied to a specific method. +- Uses DID best practices, such as using delegate keys to associate devices. - Doesn't require any extensions, scanning of QRCodes, or any other unfriendly processes for daily use. -- Requires little updates to data stored in blockchains, hence incurring less costs. - Acts like a "server" in the sense that sensitive information may be safely stored in it. Many DID methods require a secret for certain actions, e.g.: uPort requires an app secret to request normal and verified credentials. -- Has a wide support among devices. If we make it a PWA, users may install the application in the OS itself, further enhancing the user experience. +- Has a wide support among devices. If we make it a PWA, users may install the application in the OS itself, further enhancing the user experience. Later on, we can develop native mobile apps to support OS's that don't yet allow PWA to be installed natively. - Allows the user to choose between several identities when authenticating, useful for people that manage companies, organizations or similar. ### Managing identities -Users will be able to associate one or more identities using their preferred DID method. They will be guided throughout the process according to the chosen DID method. Once they complete it, they will have successfully created a Device Key associated with the identity Root Key (via signing). +Users will be able to create identities using their preferred DID method or associate existing ones. They will be guided throughout the process according to the chosen DID method. Once they complete it, they will have successfully created a Device Key. All the Device Private Keys will be encrypted with a passphrase to improve security. Even if a device gets stolen, the robber won't be able to use most features without the passphrase as all the information stored locally will be encrypted with the Device Public Key. This gives time for the owner of the Identity to revoke the compromised device in the IdentityManager of another device. -Because the identity was linked to this device at setup time, and depending on the DID method, profile information and verifiable claims might become stale. For this reason, users will be able to sync up with their Root Identity to update any stale data. +Because the identity was linked to this device at setup time, and depending on the DID method, profile information and verifiable claims might become stale. For this reason, users will be able to sync up with their identity to update any stale data. ### Managing Verifiable Claims @@ -163,7 +154,7 @@ Even if a malicious application persists the session data for future use, it wil ### Revoking a device -Users must be able to revoke a device associated with an identity. To do so, users may see the list of devices associated with an identity and revoke any device of that list, including the device from which they are interacting. This will require interacting with the DID method (Root Private Key) to publish the device being revoked. +Users must be able to revoke a device associated with an identity. To do so, users may see the list of devices associated with an identity and revoke any device of that list, including the device from which they are interacting. This will require interacting with the DID method (Master Private Key) to publish the device being revoked. If a device becomes aware that it was revoked, it will trigger a wipe-out process where all the identity data stored locally will be deleted, including the Device Key and Authenticated Sessions. @@ -186,9 +177,9 @@ If a device becomes aware that it was revoked, it will trigger a wipe-out proces - **Entity:** A person, company, organization or equivalent that controls an identity. - **DID:** An identity identifier, which resolves to a DID-Document. - **DID-Document:** A JSON-LD document which contains information about an identity, such as public keys to be used to communicate with the entity that controls the identity. -- **Root Keys:** A pair of public and private keys that control the DID. -- **Device Keys:** A pair of public and private keys of a device, signed by the Root Public Key that controls the DID. -- **Ephemeral Keys:** A temporary pair of public and private keys, signed by the Device Private Key. +- **Master Keys:** A pair of public and private keys that owns the identity (owns the DID). +- **Device Keys:** A pair of public and private keys of a device that can act on behalf of the identity owner. +- **Ephemeral Keys:** A temporary pair of public and private keys, signed by the Device Private Key or the Session Private Key. - **Session**: A unique public key stored locally by the IdentityManagerClient that identifies a visitor. - **Authenticated Session:** A Session that was signed by the entity controlling the Device Key. The Session Private Key lives securely on the IdentityManager local storage. - **IdentityManager**: An application that provides identification and authentication to the Peer-Star ecosystem. From 38c4225f61b037314d75b9208574165ab4eeeb9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Thu, 21 Jun 2018 14:03:25 +0100 Subject: [PATCH 06/23] docs: fix small typo --- docs/rfc-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 19edf5c..6d6aab9 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -51,7 +51,7 @@ The DID spec states that DID methods must provide a way for the owner to rotate Nevertheless, the DID spec advises DID methods to support adding delegate keys that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). -It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the owner key is used instead. In both cases, from now on, we will call these keys Device Keys. +It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the Master Key is used instead. In both cases, from now on, we will call these keys Device Keys. #### Revocation From 4298dc4c5f6039e16aca493928dccc6d3d3a3a17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Santos?= Date: Thu, 21 Jun 2018 14:39:42 +0100 Subject: [PATCH 07/23] Updated perfect-forward-secrecy paragraph Updated perfect-forward-secrecy paragraph and minor typos fixes --- docs/rfc-identity.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 6d6aab9..d61f9e7 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -26,7 +26,7 @@ This is a proposal for an identity management system for Peer-Star, named Peer-S A Decentralized Identifier (DID) is a string that uniquely maps to an identity, e.g. `did:btcr:123-445-333`. This standard is fully described in the [W3C DID spec](https://w3c-ccg.github.io/did-spec/) and is being widely adopted to create digital identities. -There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a set of public key that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. +There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a set of public keys that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. The owner of a DID can use the DID's private keys to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public keys listed in the DID-Document. @@ -36,36 +36,36 @@ A Verifiable Claim is a qualification, achievement, quality, or piece of informa By issuing Verifiable Claims about an entity's identity, we are strengthening the credibility of the identity itself. Those claims may be issued by the owners themselves or by other identities. -We will start off by leveraging self-issued and self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. +We will start off by leveraging self-issued and self-signed Verifiable Claims based on social networks, similar to [Keybase](https://keybase.io/) claims. They are easy to setup and they deliver a good base for trusting identities. Later on, we can expand to other types of Verifiable Claims as well, like claims emitted by third-parties. ### DID Delegates & devices -In a simple configuration, there's only a key that owns the DID, called the Master Key. That key could be used to sign artifacts and to cypher communication. However, that solution is sub-optimal for the following reasons: +In a simple configuration, there's only a key that owns the DID, called the Master Key. That key could be used to sign artifacts and to cipher communication. However, that solution is sub-optimal for the following reasons: -1. Does not offer Perfect Forward Secrecy: If an attacker manages to gain access to the Master Key, he/she is able to decypher all previous communications made to, and from, that entity's DID. +1. Does not offer Perfect Forward Secrecy: If an attacker manages to gain access to the Master Key, he/she is able to decipher all previous communications made to, and from, that entity's DID. This happens because no session keys are generated, the Master key, acts as the session key. 2. Over exposes the private key: A Master Key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to it. 3. If the Master Key is compromised, the attacker is able to completely impersonate the real DID owner. -The DID spec states that DID methods must provide a way for the owner to rotate keys, which solve `1` and `2`. The DID spec also states that DID methods must provide a way to recover the DID (e.g.: in case of theft), which solves `3`. +The DID spec states that DID methods must provide a way for the owner to rotate keys, which solves `2`. The DID spec also states that DID methods must provide a way to recover the DID (e.g.: in case of theft), which solves `3`. -Nevertheless, the DID spec advises DID methods to support adding delegate keys that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. +Nevertheless, the [DID specification](https://w3c-ccg.github.io/did-spec/) advises DID methods to support adding delegate keys that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). -It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the Master Key is used instead. In both cases, from now on, we will call these keys Device Keys. +It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone, or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the Master Key is used instead. In both cases, from now on, we will call these keys _Device Keys_. #### Revocation -As said earlier in this document, the entity in control of the DID may revoke a Device Key. Similarly to how non-revoked Public Device Keys keys are publicly listed in DID-Documents, revoked Public Device Keys should also be public. The reasoning is that a relying party must be able to verify signatures made the past and, as such, must be able to assert that the public key is associated to the DID, even if it's revoked. +As previously stated, the entity in control of the DID may revoke a Device Key. Similarly to how non-revoked Public Device Keys keys are publicly listed in DID-Documents, revoked Public Device Keys should also be public. This is because a relying party must be able to verify signatures made in the past and, as such, must be able to assert that the public key is associated to the DID, even if it's revoked. -As of now, the DID spec does not specifies how and where the revoked keys can be obtained. There's an [open issue](https://github.com/w3c-ccg/did-spec/issues/63) on the DID spec that brings this topic into discussion and, apparently, the W3C CCG working group is keen in listing revoked keys in the DID-Document. +As of now, the DID spec does not specify how and where the revoked keys can be obtained. There's an [open issue](https://github.com/w3c-ccg/did-spec/issues/63) on the DID spec that brings this topic into the discussion and the W3C CCG working group is keen in listing revoked keys in the DID-Document. ### Using DID-Auth to prove control of the DID -Typical DApps flows require a relying party to trust another. We can leverage DIDs and self-Signed Verifiable Claims in an "handshake" ceremony. The ceremony should follow the [DID-Auth spec](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md). +Typical DApps flows require a relying party to trust another. We can leverage DIDs and self-signed Verifiable Claims in a "handshake" ceremony. The ceremony should follow the [DID-Auth spec](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md). -To exemplify how [DID-Auth] works, consider the following example: Alice wants to share something secret with Bob. +To illustrate how [DID-Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) works, consider the following example: Alice wants to share a secret with Bob. -After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-Signed Verifiable Claims. Alice does this by encrypting all this material, along with a nounce, with Bob's public key and signing her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: +After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: 1. Decrypt Alice's message 2. Resolve Alice's DID to a DID-Document @@ -80,11 +80,11 @@ If all went good, Bob is pretty confident that Alice is the real Alice. For futu ## Proposal: The IdentityManager -Usability is a crucial aspect on this proposal as it played a very important role on its concept. +Usability is a crucial aspect of this proposal as it played a very important role in its concept. On one hand, the experience for end-users should be intuitive, simple and familiar. Ideally, users should have little contact with private keys and most of the cryptographic operations should happen behind the scenes. On the other hand, developers building DApps should have an easy way to authenticate users. -The IdentityManager packages emerging [Standards & foundations](#standards--foundations) into a intuitive and easy to use interface for end-users. +The IdentityManager packages emerging [Standards & foundations](#standards--foundations) into an intuitive and easy to use interface for end-users. ### What is it? @@ -95,7 +95,7 @@ The IdentityManager is a web-page hosted on IPFS and reachable via a specific UR - Manage Verifiable Claims of identities - Authenticate to dApps -Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with a intuitive API. +Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with an intuitive API. Moreover, any meaningful event on the IdentityManager, such as the removal of an identity, will be broadcasted to interested parties. This allows applications to immediately react to certain events by subscribing to them on the IdentityManager. @@ -126,9 +126,9 @@ The exact way in how the claims will be stored is dependent on the DID method. F Peer-Star applications will use the IdentityManagerClient to manage the user's session. -When bootstrapped, the IdentityManagerClient will attempt to read the a Session Public Key from the local storage of the applications' origin. The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If the IdentityManager doesn't recognize that Session Public Key or if there's no Session Public Key in first place, there's no Authenticated Session, meaning that no user is authenticated. In such cases, the application may request the Identity Manager to authenticate the user, typically via a login button. +When bootstrapped, the IdentityManagerClient will attempt to read the Session Public Key from the local storage of the applications' origin. The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If the IdentityManager doesn't recognize that Session Public Key or if there's no Session Public Key in the first place, there's no Authenticated Session, meaning that no user is authenticated. In such cases, the application may request the Identity Manager to authenticate the user, typically via a login button. -When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data, including the Session Public Key and its signature signed by the Device Private Key, is sent back to the application. If the user denied the disclosure of the information, the operation will fail. +When the application requests the IdentityManagerClient to authenticate the user, a popup pointing to the IdentityManager authenticate screen is open (via `window.open`). In this screen, the user is asked to choose an identity and to disclose some information, such as its name, its photo and a set of claims & proofs. If the user consented to the disclosure of this information and entered the Device Private Key passphrase correctly, a new session for this application will be created and stored. The session data, including the Session Public Key and its signature signed by the Device Private Key, is sent back to the application. If the user denied the disclosure of the information, the operation will fail. In both scenarios, the popup is closed and the outcome is made available to the application. Applications might choose the TTL of a session depending on the degree of security they want to have. @@ -140,7 +140,7 @@ Applications may want to sign artifacts, such as regular data or Ephemeral Keys. 1. Sign with the Session Private Key 2. Sign with the Device Private Key -The first method is less intrusive and happens transparently to the user, but is less secure. More specifically, a robber who stoled a device may still sign Ephemeral Keys with the Session Private Key as long as a session is valid (not expired). Relying parties will still see those signatures as valid until the DID owner revokes the stolen device. +The first method is less intrusive and happens transparently to the user, but is less secure. More specifically, a robber who stole a device may still sign Ephemeral Keys with the Session Private Key as long as a session is valid (not expired). Relying parties will still see those signatures as valid until the DID owner revokes the stolen device. The second method provides more security as the user is prompted for the Device Private Key passphrase, but it's more intrusive. The interaction is similar to the Authentication process, where a popup pointing to the sign screen gets open. The user either allows or denies the signing and the result gets back into the application. Please note that the passphrase might be stored in memory in the IdentityManager during a certain amount of time, which in turn makes this process less intrusive for subsequent signings. From f0c71e71639044873a67a8e05f8bbf7c8e8de7a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Thu, 21 Jun 2018 16:55:29 +0100 Subject: [PATCH 08/23] docs: small clarification in signing --- docs/rfc-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index d61f9e7..ef3d79b 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -150,7 +150,7 @@ Ultimately, the application may choose between both methods for different situat Users will be able to revoke any application session listed on the identity's Authenticated Session list. Revoking a session will essentially delete the application session from the IdentityManager local storage. -Even if a malicious application persists the session data for future use, it will be unable to sign artifacts, such as Ephemeral Keys, with the Device Private Key, rendering the application useless in those scenarios. +Even if a malicious application persists the session data for future use, it will be unable to sign artifacts, such as Ephemeral Keys, with both the Session Key and the Device Key, rendering the application useless in those scenarios. ### Revoking a device From 236604e59b5120e110d9ff7d31b89dcf0e2a2385 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Fri, 22 Jun 2018 11:58:15 +0100 Subject: [PATCH 09/23] docs: apply suggestions --- docs/rfc-identity.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index ef3d79b..99825aa 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -48,8 +48,8 @@ In a simple configuration, there's only a key that owns the DID, called the Mast The DID spec states that DID methods must provide a way for the owner to rotate keys, which solves `2`. The DID spec also states that DID methods must provide a way to recover the DID (e.g.: in case of theft), which solves `3`. -Nevertheless, the [DID specification](https://w3c-ccg.github.io/did-spec/) advises DID methods to support adding delegate keys that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. -delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). +Nevertheless, the [DID specification](https://w3c-ccg.github.io/did-spec/) advises DID methods to support adding [delegate keys](https://w3c-ccg.github.io/did-spec/#authorization-and-delegation) that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. +Delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone, or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the Master Key is used instead. In both cases, from now on, we will call these keys _Device Keys_. @@ -65,14 +65,14 @@ Typical DApps flows require a relying party to trust another. We can leverage DI To illustrate how [DID-Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) works, consider the following example: Alice wants to share a secret with Bob. -After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: +After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing with her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: 1. Decrypt Alice's message 2. Resolve Alice's DID to a DID-Document 3. Check if Alice's Device Public Key is listed in `authentication` property of the DID-Document 4. Verify the message signature against her Device Public Key using the correct algorithm 5. Verify the signatures of the self-signed Verifiable Claims against the public keys listed in the `publicKey` property of the DID-Document. -6. Manually verify Alice's Verifiable Claims to see if they credible. +6. Manually verify Alice's Verifiable Claims to see if they are credible. Please note that certain aspects of point `6.` can be done automatically by crawling the proofs and verifying the signatures against Alice's Public Keys. Still, Bob must explicitly verify the proofs as an attacker might be trying to impersonate the real Alice with fake social profiles. @@ -93,9 +93,13 @@ The IdentityManager is a web-page hosted on IPFS and reachable via a specific UR - Create identities on several DID methods - Import identities created on other devices - Manage Verifiable Claims of identities -- Authenticate to dApps +- Authenticate to dApps (sessions) -Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with an intuitive API. +Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. + +All private keys, such as Device Private Keys and Session Private Keys, will be safely stored in the IdentityManager local storage. Applications must interact with the IdentityManager to sign or decypher payload that uses such keys. + +Using the `postMessage` API to directly communicate with the IdentityManager is a bit clunky. Instead, developers will use a library called IdentityManagerClient that abstracts all the communication layer with an intuitive API. Moreover, any meaningful event on the IdentityManager, such as the removal of an identity, will be broadcasted to interested parties. This allows applications to immediately react to certain events by subscribing to them on the IdentityManager. @@ -105,14 +109,16 @@ Among others, the most important advantages of this solution are: - Uses DID best practices, such as using delegate keys to associate devices. - Doesn't require any extensions, scanning of QRCodes, or any other unfriendly processes for daily use. - Acts like a "server" in the sense that sensitive information may be safely stored in it. Many DID methods require a secret for certain actions, e.g.: uPort requires an app secret to request normal and verified credentials. -- Has a wide support among devices. If we make it a PWA, users may install the application in the OS itself, further enhancing the user experience. Later on, we can develop native mobile apps to support OS's that don't yet allow PWA to be installed natively. +- Has a wide support among devices. If we make it a Progressive Web App (PWA), users may install the application in the OS itself, further enhancing the user experience. Later on, we can develop native mobile apps to support OS's that don't yet allow PWAs to be installed natively. - Allows the user to choose between several identities when authenticating, useful for people that manage companies, organizations or similar. ### Managing identities Users will be able to create identities using their preferred DID method or associate existing ones. They will be guided throughout the process according to the chosen DID method. Once they complete it, they will have successfully created a Device Key. -All the Device Private Keys will be encrypted with a passphrase to improve security. Even if a device gets stolen, the robber won't be able to use most features without the passphrase as all the information stored locally will be encrypted with the Device Public Key. This gives time for the owner of the Identity to revoke the compromised device in the IdentityManager of another device. +All the Device Private Keys will be locked to improve security. One such locking method is using a passphrase to encrypt the Device Private Key. Other methods, such as [biometric signatures](https://en.wikipedia.org/wiki/Electronic_signature#Biometric_signature), can be used instead if they prove to be effective and are available in the user's device. + +Even if a device gets stolen, the robber won't be able to use most features without unlocking the Device Private Key as all the information stored locally will be encrypted with the Device Public Key. This gives time for the owner of the Identity to revoke the compromised device in the IdentityManager of another device. Because the identity was linked to this device at setup time, and depending on the DID method, profile information and verifiable claims might become stale. For this reason, users will be able to sync up with their identity to update any stale data. @@ -124,7 +130,7 @@ The exact way in how the claims will be stored is dependent on the DID method. F ### Authentication on applications -Peer-Star applications will use the IdentityManagerClient to manage the user's session. +Peer-Star applications will use the IdentityManagerClient to manage the user's session via Session Keys. When bootstrapped, the IdentityManagerClient will attempt to read the Session Public Key from the local storage of the applications' origin. The IdentityManagerClient then takes the Session Public Key and queries the IdentityManager to retrieve the session data associated to it. If the IdentityManager responds back with the session data, the user is authenticated and, as such, there's an Authenticated Session. If the IdentityManager doesn't recognize that Session Public Key or if there's no Session Public Key in the first place, there's no Authenticated Session, meaning that no user is authenticated. In such cases, the application may request the Identity Manager to authenticate the user, typically via a login button. @@ -148,9 +154,10 @@ Ultimately, the application may choose between both methods for different situat ### Managing application sessions -Users will be able to revoke any application session listed on the identity's Authenticated Session list. Revoking a session will essentially delete the application session from the IdentityManager local storage. +Users will be able to revoke any session listed on the identity's Authenticated Session list at any time. Revoking a session will essentially delete the application session from the IdentityManager local storage. +Additionally, each session has a TTL that limits its lifespan and states when they expire. Expired sessions are automatically revoked. -Even if a malicious application persists the session data for future use, it will be unable to sign artifacts, such as Ephemeral Keys, with both the Session Key and the Device Key, rendering the application useless in those scenarios. +Applications will be unable to sign artifacts or decypher payload if their sessions are revoked or non-existent. This is guaranteed by declining such requests made by applications to the IdentityManager. ### Revoking a device From b6d6880a4dbdb8b9b71e4f5e0016ab8ee4465d78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Santos?= Date: Tue, 26 Jun 2018 16:24:08 +0100 Subject: [PATCH 10/23] docs: did methods comparison --- docs/did-methods-comparison.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/did-methods-comparison.md diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md new file mode 100644 index 0000000..3de1404 --- /dev/null +++ b/docs/did-methods-comparison.md @@ -0,0 +1,21 @@ +# Decentralized Identity Systems Survey + + +| | uPort | Sovrin | Blockstack | ERC-725 | +| -------- | -------- | -------- | ---------- | -------- | +| P2P Friendly | ❌ | ✔️ | ✔️ | ⚠️ [1] | +| Verifiable Claims | ⚠️ [2] | ✔️ | ❌ | ⚠️ [3] | +| Aliasing | ❌ | ✔️ | ✔️ | ❌ | +| Delegate Keys | ❌ [4] | ✔️ | ❌ | ✔️ | +| Key Rotation & Revocation | ✔️ [5] | ✔️ | ❌ | ✔️ | +| Social-Key Recovery | ? | ✔️ | ❌ | ✔️ | +| Costs | $ | ? | $$ [6] | $$$ | +| Identity Wallet UI | ✔️ | ❌ | ✔️ | ❌ [7] | + +**[1]** There's no Identity Wallet applications that implement `erc725` yet. +**[2]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. +**[3]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. +**[4]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. +**[5]** Key rotation & revocation is possible via a (optional) Proxy Contract +**[6]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username +**[7]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com From 023dd5c2d3da275955b82fde4b1423ffc6184282 Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 26 Jun 2018 17:56:48 +0200 Subject: [PATCH 11/23] Update did-methods-comparison.md --- docs/did-methods-comparison.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index 3de1404..1bd3a78 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -12,10 +12,10 @@ | Costs | $ | ? | $$ [6] | $$$ | | Identity Wallet UI | ✔️ | ❌ | ✔️ | ❌ [7] | -**[1]** There's no Identity Wallet applications that implement `erc725` yet. -**[2]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. -**[3]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. -**[4]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. -**[5]** Key rotation & revocation is possible via a (optional) Proxy Contract -**[6]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username -**[7]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com +- **[1]** There's no Identity Wallet applications that implement `erc725` yet. +- **[2]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. +- **[3]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. +- **[4]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. +- **[5]** Key rotation & revocation is possible via a (optional) Proxy Contract +- **[6]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username +- **[7]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com From fbdab9782844055ba80172935f335c0032fab4a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 27 Jun 2018 09:40:57 +0100 Subject: [PATCH 12/23] docs: update with suggestions --- docs/rfc-identity.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 99825aa..c16c49f 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -46,7 +46,7 @@ In a simple configuration, there's only a key that owns the DID, called the Mast 2. Over exposes the private key: A Master Key should be used as few times as possible. Using it a lot makes it easier for an attacker to gain access to it. 3. If the Master Key is compromised, the attacker is able to completely impersonate the real DID owner. -The DID spec states that DID methods must provide a way for the owner to rotate keys, which solves `2`. The DID spec also states that DID methods must provide a way to recover the DID (e.g.: in case of theft), which solves `3`. +The DID spec states that DID methods must provide a way for the owner to rotate keys, which solves `2`. The DID spec also states that DID methods should provide a way to recover the DID (e.g.: in case of theft) via trusted parties, which solves `3`. Nevertheless, the [DID specification](https://w3c-ccg.github.io/did-spec/) advises DID methods to support adding [delegate keys](https://w3c-ccg.github.io/did-spec/#authorization-and-delegation) that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. Delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). @@ -65,7 +65,7 @@ Typical DApps flows require a relying party to trust another. We can leverage DI To illustrate how [DID-Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) works, consider the following example: Alice wants to share a secret with Bob. -After agreeing on a transport, Alice presents herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing with her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: +After agreeing on a transport, Alice introduces herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing with her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: 1. Decrypt Alice's message 2. Resolve Alice's DID to a DID-Document @@ -95,7 +95,7 @@ The IdentityManager is a web-page hosted on IPFS and reachable via a specific UR - Manage Verifiable Claims of identities - Authenticate to dApps (sessions) -Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager it will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. +Because it runs on its own domain, it provides a sandboxed environment where access to functionality and data is completely controlled. More specifically, all interactions made with the IdentityManager will be made via [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) where control and data segmentation is made via the messages' origin. All private keys, such as Device Private Keys and Session Private Keys, will be safely stored in the IdentityManager local storage. Applications must interact with the IdentityManager to sign or decypher payload that uses such keys. From da3b625929601395c799777c651b83d6c7389be5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Sat, 7 Jul 2018 11:59:15 +0100 Subject: [PATCH 13/23] docs: update Decentralized Identity Systems Survey --- docs/did-methods-comparison.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index 1bd3a78..3ccaac4 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -3,19 +3,20 @@ | | uPort | Sovrin | Blockstack | ERC-725 | | -------- | -------- | -------- | ---------- | -------- | -| P2P Friendly | ❌ | ✔️ | ✔️ | ⚠️ [1] | -| Verifiable Claims | ⚠️ [2] | ✔️ | ❌ | ⚠️ [3] | +| Identity Wallet UI | ✔️ | ❌ | ✔️ | ❌ [1] | +| P2P-friendly Authentication | ❌ | ✔️ | ⚠️ [2] | ⚠️ [3] | +| Verifiable Claims | ⚠️ [4] | ✔️ | ❌ | ⚠️ [5] | | Aliasing | ❌ | ✔️ | ✔️ | ❌ | -| Delegate Keys | ❌ [4] | ✔️ | ❌ | ✔️ | -| Key Rotation & Revocation | ✔️ [5] | ✔️ | ❌ | ✔️ | +| Delegate Keys | ❌ [6] | ✔️ | ❌ | ✔️ | +| Key Rotation & Revocation | ✔️ [7] | ✔️ | ❌ | ✔️ | | Social-Key Recovery | ? | ✔️ | ❌ | ✔️ | -| Costs | $ | ? | $$ [6] | $$$ | -| Identity Wallet UI | ✔️ | ❌ | ✔️ | ❌ [7] | +| Costs | $ | ? | $$ [8] | $$$ | -- **[1]** There's no Identity Wallet applications that implement `erc725` yet. -- **[2]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. -- **[3]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. -- **[4]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. -- **[5]** Key rotation & revocation is possible via a (optional) Proxy Contract -- **[6]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username -- **[7]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com +- **[1]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com +- **[2]** It's unclear how one can prove control over the DID: https://forum.blockstack.org/t/got-a-few-questions-considering-using-blockstack/5608 +- **[3]** There's no authentication libraries that implement `erc725` yet. +- **[4]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. +- **[5]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. +- **[6]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. +- **[7]** Key rotation & revocation is possible via a (optional) Proxy Contract +- **[9]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username From 3482de3247a66b6ca9afcf9e892cc01c0cbb7a8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Sat, 7 Jul 2018 21:00:30 +0100 Subject: [PATCH 14/23] docs: improve accuracy of Decentralized Identity Systems Survey --- docs/did-methods-comparison.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index 3ccaac4..cf0ed09 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -3,20 +3,22 @@ | | uPort | Sovrin | Blockstack | ERC-725 | | -------- | -------- | -------- | ---------- | -------- | -| Identity Wallet UI | ✔️ | ❌ | ✔️ | ❌ [1] | -| P2P-friendly Authentication | ❌ | ✔️ | ⚠️ [2] | ⚠️ [3] | -| Verifiable Claims | ⚠️ [4] | ✔️ | ❌ | ⚠️ [5] | -| Aliasing | ❌ | ✔️ | ✔️ | ❌ | -| Delegate Keys | ❌ [6] | ✔️ | ❌ | ✔️ | -| Key Rotation & Revocation | ✔️ [7] | ✔️ | ❌ | ✔️ | +| Identity Wallet UI | ✔️ | ❌ [1] | ✔️ | ❌ [2] | +| P2P-friendly Authentication | ❌ | ? [1] | ⚠️ [3] | ? [4] | +| Verifiable Claims | ⚠️ [5] | ✔️ | ⚠️ [6] | ⚠️ [7] | +| Aliasing | ❌ | ✔️ | ❌ | ❌ | +| Delegate Keys | ❌ [8] | ✔️ | ❌ | ✔️ | +| Key Rotation & Revocation | ✔️ [9] | ✔️ | ❌ | ✔️ | | Social-Key Recovery | ? | ✔️ | ❌ | ✔️ | -| Costs | $ | ? | $$ [8] | $$$ | +| Costs | $ | ? | $$ [10] | $$$ | -- **[1]** OriginProtocol developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com -- **[2]** It's unclear how one can prove control over the DID: https://forum.blockstack.org/t/got-a-few-questions-considering-using-blockstack/5608 -- **[3]** There's no authentication libraries that implement `erc725` yet. -- **[4]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. -- **[5]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. -- **[6]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. -- **[7]** Key rotation & revocation is possible via a (optional) Proxy Contract -- **[9]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username +- **[1]** Evernym is developing connect.me which will provide a Wallet for Sovrin. +- **[2]** [OriginProtocol](https://www.originprotocol.com/en) developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com. +- **[3]** It's unclear how one can prove control over the DID: https://forum.blockstack.org/t/got-a-few-questions-considering-using-blockstack/5608. +- **[4]** There's no authentication/client libraries that implement `erc725` yet. +- **[5]** uPort claims & proofs is a simple key-value storage. Verifiable Claims can be stored within as values of that storage. +- **[6]** We can prove ownership over social accounts but the data model is not compatible with Verifiable Claims. Nevertheless we probably could adapt data to be compatible. +- **[7]** `erc725` is studying the possibility to embrace Verifiable Claims but as of now, the `data` and `uri` of claims are agnostic. +- **[8]** uPort is working on a new DID method, called `ethr`, that will support delegates: https://github.com/uport-project/ethr-did-resolver. +- **[9]** Key rotation & revocation is possible via a (optional) Proxy Contract. +- **[10]** The identity creation is free but one must (optionally) pay ~0.001096 bitcoins to have a username. From 72a173b6cd98485b88341a8117318dc921e7b961 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Sat, 7 Jul 2018 21:02:02 +0100 Subject: [PATCH 15/23] docs: use question mark emoji --- docs/did-methods-comparison.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index cf0ed09..c0d8793 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -4,13 +4,13 @@ | | uPort | Sovrin | Blockstack | ERC-725 | | -------- | -------- | -------- | ---------- | -------- | | Identity Wallet UI | ✔️ | ❌ [1] | ✔️ | ❌ [2] | -| P2P-friendly Authentication | ❌ | ? [1] | ⚠️ [3] | ? [4] | +| P2P-friendly Authentication | ❌ | ❓ [1] | ⚠️ [3] | ❓ [4] | | Verifiable Claims | ⚠️ [5] | ✔️ | ⚠️ [6] | ⚠️ [7] | | Aliasing | ❌ | ✔️ | ❌ | ❌ | | Delegate Keys | ❌ [8] | ✔️ | ❌ | ✔️ | | Key Rotation & Revocation | ✔️ [9] | ✔️ | ❌ | ✔️ | -| Social-Key Recovery | ? | ✔️ | ❌ | ✔️ | -| Costs | $ | ? | $$ [10] | $$$ | +| Social-Key Recovery | ❓ | ✔️ | ❌ | ✔️ | +| Costs | $ | ❓ | $$ [10] | $$$ | - **[1]** Evernym is developing connect.me which will provide a Wallet for Sovrin. - **[2]** [OriginProtocol](https://www.originprotocol.com/en) developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com. From 6ad74919cd276db1e6542a87151d56e36839449b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Sun, 8 Jul 2018 04:15:53 +0100 Subject: [PATCH 16/23] docs: switch blockstack and sovrin on aliases --- docs/did-methods-comparison.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index c0d8793..34c6ad2 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -6,7 +6,7 @@ | Identity Wallet UI | ✔️ | ❌ [1] | ✔️ | ❌ [2] | | P2P-friendly Authentication | ❌ | ❓ [1] | ⚠️ [3] | ❓ [4] | | Verifiable Claims | ⚠️ [5] | ✔️ | ⚠️ [6] | ⚠️ [7] | -| Aliasing | ❌ | ✔️ | ❌ | ❌ | +| Aliasing | ❌ | ❌ | ✔️ | ❌ | | Delegate Keys | ❌ [8] | ✔️ | ❌ | ✔️ | | Key Rotation & Revocation | ✔️ [9] | ✔️ | ❌ | ✔️ | | Social-Key Recovery | ❓ | ✔️ | ❌ | ✔️ | From c3e5a9d17ff644e89e51864431259474870cc45c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Sun, 8 Jul 2018 04:18:23 +0100 Subject: [PATCH 17/23] docs: update sovrin wallet ui --- docs/did-methods-comparison.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/did-methods-comparison.md b/docs/did-methods-comparison.md index 34c6ad2..9052f1b 100644 --- a/docs/did-methods-comparison.md +++ b/docs/did-methods-comparison.md @@ -12,7 +12,7 @@ | Social-Key Recovery | ❓ | ✔️ | ❌ | ✔️ | | Costs | $ | ❓ | $$ [10] | $$$ | -- **[1]** Evernym is developing connect.me which will provide a Wallet for Sovrin. +- **[1]** Sovrin doesn't have a Wallet app yet but Evernym is developing connect.me which is in closed beta. - **[2]** [OriginProtocol](https://www.originprotocol.com/en) developed a "playground" to demonstrate the potential of the DID method, but it's not production ready nor enables users to authenticate to dApps: https://erc725.originprotocol.com. - **[3]** It's unclear how one can prove control over the DID: https://forum.blockstack.org/t/got-a-few-questions-considering-using-blockstack/5608. - **[4]** There's no authentication/client libraries that implement `erc725` yet. From 8e2ed228200808e9be0f4cea80895fa6b826cb91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 11 Jul 2018 12:59:33 +0200 Subject: [PATCH 18/23] docs: improve DID section --- docs/rfc-identity.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index c16c49f..03c2263 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -26,9 +26,18 @@ This is a proposal for an identity management system for Peer-Star, named Peer-S A Decentralized Identifier (DID) is a string that uniquely maps to an identity, e.g. `did:btcr:123-445-333`. This standard is fully described in the [W3C DID spec](https://w3c-ccg.github.io/did-spec/) and is being widely adopted to create digital identities. -There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a set of public keys that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. +![DID Syntax](https://i.imgur.com/MRLCi8v.png) -The owner of a DID can use the DID's private keys to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public keys listed in the DID-Document. +Each method has its own way to resolve a DID to a DID-Document. A DID-Document obeys a specified schema and it contains, among other things, a set of public keys that entities can use to establish communication (encrypt, verify digital signatures) with the DID owner. There are already several DID methods, such as uPort and Sovrin, which are listed in the [DID Method Registry](https://w3c-ccg.github.io/did-method-registry/). + +The DID owner can use the DID's private keys to digitally sign artifacts. Any party can retrieve the DID-Document and verify the digital signature against the public keys listed in the DID-Document. + + +In summary: + +- A DID is a persistent and immutable ID - underlying public keys change while DIDs don't +- It doesn't require a central authority to change the attributes of the DID Document +- Ownership of the DID can be cryptographically verified ### Self-signed Verifiable Claims From 2ad6cbf175d313466fb839eb17d93f1465d9fac8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 11 Jul 2018 12:59:40 +0200 Subject: [PATCH 19/23] docs: add "Verifying signatures" --- docs/rfc-identity.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 03c2263..88f7f78 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -161,6 +161,24 @@ The second method provides more security as the user is prompted for the Device Ultimately, the application may choose between both methods for different situations depending on the security degree they want to have. +#### Verifying signatures + +Any party might verify the authenticity and authorship of artifacts signed by other parties. + +- The verification of an artifact signed by the Session Public Key is made by: + + 1. Verify the signature of the artifact against the Session Public Key of author + 2. Verify the signature of the Session Public Key of the author against the Device Public Key + 3. Verify if the Device Public Key is present in the DID document associated with the DID + + +- The verification of an artifact signed by the Device Public Key is made by: + + 1. Verify the signature of the artifact against the Session Public Key of author + 2. Verify if the Device Public Key is present in the DID document associated with the DID + +There will be functions offered by the IdentityManagerClient to verify signatures using the processes described above. + ### Managing application sessions Users will be able to revoke any session listed on the identity's Authenticated Session list at any time. Revoking a session will essentially delete the application session from the IdentityManager local storage. From 8a8471859fde73fc5de4240ee474f11274011246 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 11 Jul 2018 13:02:08 +0200 Subject: [PATCH 20/23] docs: fix grammar typo --- docs/rfc-identity.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 88f7f78..5154aba 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -167,15 +167,15 @@ Any party might verify the authenticity and authorship of artifacts signed by ot - The verification of an artifact signed by the Session Public Key is made by: - 1. Verify the signature of the artifact against the Session Public Key of author - 2. Verify the signature of the Session Public Key of the author against the Device Public Key - 3. Verify if the Device Public Key is present in the DID document associated with the DID + 1. Verifying the signature of the artifact against the Session Public Key of the author + 2. Verifying the signature of the Session Public Key of the author against the Device Public Key + 3. Verifying if the Device Public Key is present in the DID document associated with the DID - The verification of an artifact signed by the Device Public Key is made by: - 1. Verify the signature of the artifact against the Session Public Key of author - 2. Verify if the Device Public Key is present in the DID document associated with the DID + 1. Verifying the signature of the artifact against the Session Public Key of the author + 2. Verifying if the Device Public Key is present in the DID document associated with the DID There will be functions offered by the IdentityManagerClient to verify signatures using the processes described above. From c249510b4873a9a4b58b245bf97dbe48513a2689 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Wed, 11 Jul 2018 13:18:08 +0200 Subject: [PATCH 21/23] docs: improve signatures explanation --- docs/rfc-identity.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index 5154aba..c266215 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -167,15 +167,14 @@ Any party might verify the authenticity and authorship of artifacts signed by ot - The verification of an artifact signed by the Session Public Key is made by: - 1. Verifying the signature of the artifact against the Session Public Key of the author - 2. Verifying the signature of the Session Public Key of the author against the Device Public Key - 3. Verifying if the Device Public Key is present in the DID document associated with the DID - + 1. Verifying the signature of the artifact against the Session Public Key of the author. + 2. Verifying the signature of the Session Public Key of the author against the Device Public Key of the author. This proves that the Session Public Key was authorized by the Device Public Key. + 3. Verifying if the Device Public Key of the author is present in the DID document associated with the DID. This proves that the Device Public Key was authorized by the Identity (author). - The verification of an artifact signed by the Device Public Key is made by: - 1. Verifying the signature of the artifact against the Session Public Key of the author - 2. Verifying if the Device Public Key is present in the DID document associated with the DID + 1. Verifying the signature of the artifact against the Device Public Key of the author. + 2. Verifying if the Device Public Key of the author is present in the DID document associated with the DID. This proves that the Device Public Key was authorized by the Identity (author). There will be functions offered by the IdentityManagerClient to verify signatures using the processes described above. From 4a9e620969c5d1294c118280f2ecc0257bc86cea Mon Sep 17 00:00:00 2001 From: Markus Sabadello Date: Wed, 1 Aug 2018 11:05:51 -0700 Subject: [PATCH 22/23] Link to final DID Auth paper (#18) --- docs/rfc-identity.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index c266215..cf4e39e 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -58,7 +58,7 @@ In a simple configuration, there's only a key that owns the DID, called the Mast The DID spec states that DID methods must provide a way for the owner to rotate keys, which solves `2`. The DID spec also states that DID methods should provide a way to recover the DID (e.g.: in case of theft) via trusted parties, which solves `3`. Nevertheless, the [DID specification](https://w3c-ccg.github.io/did-spec/) advises DID methods to support adding [delegate keys](https://w3c-ccg.github.io/did-spec/#authorization-and-delegation) that can act on behalf of the identity, but with granular capabilities. As an example, the [erc725](https://github.com/ethereum/EIPs/issues/725) DID method has such feature via adding keys with the `action` type, allowing such keys to perform signing or authentication. -Delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). +Delegate public keys will be listed in the DID-Document as well, which improves interoperability and compatibility with many other specs in the ecosystem, such as the [DID Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/final-documents/did-auth.pdf) and [Identity Hubs](https://github.com/decentralized-identity/hubs/blob/master/explainer.md). It's expected that the same entity will use Peer-Star applications from different devices, such as a desktop, laptop, smart-phone, or others. For the DID methods that support delegate keys, each device should have its own key added as a delegate. In case the DID method does not support delegate keys, the Master Key is used instead. In both cases, from now on, we will call these keys _Device Keys_. @@ -70,9 +70,9 @@ As of now, the DID spec does not specify how and where the revoked keys can be o ### Using DID-Auth to prove control of the DID -Typical DApps flows require a relying party to trust another. We can leverage DIDs and self-signed Verifiable Claims in a "handshake" ceremony. The ceremony should follow the [DID-Auth spec](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md). +Typical DApps flows require a relying party to trust another. We can leverage DIDs and self-signed Verifiable Claims in a "handshake" ceremony. The ceremony should follow the [DID-Auth spec](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/final-documents/did-auth.pdf). -To illustrate how [DID-Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/draft-documents/did_auth_draft.md) works, consider the following example: Alice wants to share a secret with Bob. +To illustrate how [DID-Auth](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/blob/master/final-documents/did-auth.pdf) works, consider the following example: Alice wants to share a secret with Bob. After agreeing on a transport, Alice introduces herself with a DID, a Device Public Key, and a set of self-signed Verifiable Claims. Alice does this by encrypting all this material, along with a nonce, with Bob's public key and signing with her `authentication` key (a key present in the DID-Document under the `authentication` property). To trust Alice, Bob must: From 16d50bf50e7bd1ce89f0fe0195e2b522a703766f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Cruz?= Date: Fri, 3 Aug 2018 14:20:30 -0700 Subject: [PATCH 23/23] docs: update link to revocation list issue --- docs/rfc-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc-identity.md b/docs/rfc-identity.md index cf4e39e..bf8f940 100644 --- a/docs/rfc-identity.md +++ b/docs/rfc-identity.md @@ -66,7 +66,7 @@ It's expected that the same entity will use Peer-Star applications from differen As previously stated, the entity in control of the DID may revoke a Device Key. Similarly to how non-revoked Public Device Keys keys are publicly listed in DID-Documents, revoked Public Device Keys should also be public. This is because a relying party must be able to verify signatures made in the past and, as such, must be able to assert that the public key is associated to the DID, even if it's revoked. -As of now, the DID spec does not specify how and where the revoked keys can be obtained. There's an [open issue](https://github.com/w3c-ccg/did-spec/issues/63) on the DID spec that brings this topic into the discussion and the W3C CCG working group is keen in listing revoked keys in the DID-Document. +As of now, the DID spec does not specify how and where the revoked keys can be obtained. There's an [open issue](https://github.com/w3c-ccg/did-spec/issues/96) on the DID spec that brings this topic into the discussion and the W3C CCG working group. ### Using DID-Auth to prove control of the DID