search

MatrixAI / Polykey-Docs

Documentation for Polykey
https://polykey.com/docs/
GNU General Public License v3.0
1 stars 5 forks source link

Write Wiki Page for Decentralized Trust Network #5

Closed CMCDragonkai closed 2 years ago

CMCDragonkai commented 3 years ago

Specification

Our polykey-design repo has lots of information on how DIs and Gestalts and Social Discovery works.

All of this information should be synthesized into the Polykey wiki, the js-polykey wiki should be focused on the CLI-side of the situation.

Additional context

The wiki page can be found here: https://github.com/MatrixAI/Polykey/wiki/Decentralized-Trust-Network

Tasks

CMCDragonkai commented 3 years ago

I've rewritten the first sections before going into the trust network architecture.

So now I've moved most of your content underneath the "Trust Network Architecture".

Those sections afterwards still require a review as the explanations get more technical.

CMCDragonkai commented 3 years ago

I believe the diagram from scuttlebutt is more appropriate for our Keynode Sigchain section:

CMCDragonkai commented 3 years ago

I'm going to have to have to push the final revision of the later structure and diagrams to a later time or until you can revisit it @emmacasolin. Current issues:

Polykey's secrets are stored in Vaults that are managed and shared between Keynodes. Each Keynode possesses a digital identity in Polykey's trust network. These identities start with root public & private key pair and along with other information is put together into a X.509 certificate.

This should link to another section about the root public & private key pair. Or a glossary that expands on it. And a diagram that shows what a keypair is. For example: https://ssbc.github.io/scuttlebutt-protocol-guide/#keys-and-identities. This may need to be a separate page as we can document what our keypair structure is.

  • The Keynode Identity Certificate provides information about its public key, as well as the owner of this public key.
  • The key owner, as well as other entities (represented by their own X.509 certificates) can sign claims held on the Keynode Identity Certificate to verify their authenticity.

Keep to maintaining the same terminology:

The diagram for X.509 needs to be replaced with something that shows how we use X.509 and that the relationships between root certificates is in order of renewal, not a trust hierarchy. It must be explicitly explained that while X.509 has historically been used for strict hierarchy of certificate authorities, here we are using it as points of presences in a web of trust. At the end of the day the X.509 is just a data structure, and we reusing parts of this data structure for our purposes.

These Keynodes are at the core of Polykey's system of authentication, which is managed by a Polykey Agent. The Polykey Agent has access to all of the Keynodes stored on a particular computing device and is the user's interface to all of Polykey's functionality.

The Polykey Agent is a technical concept. Do not mention it here. It confuses it with the "agent" we are talking about being a catch all word for person or machine. Also the Agent does not have access to all the Keynodes. The Keynodes each individually would have a separate agent, but that's not really relevant to this article. This paragraph should be removed.

Node-to-Identity claims consist of a singly-signed statement on one Keynode claiming ownership over a particular digital identity, as well as a similar singly-signed statement (signed by the Keynode) on the digital identity (made by itself). This process is known as digital identity augmentation.

I think you're better off labelling the diagram itself. Suppose you gave a label to each link between Node to Node and Node to Identity. This diagram could be done on asciiflow.

Then you can explain afterwards what each link is. I think that will be clearer that the cryptographic links are just crossposted signed messages claiming mutual ownership. Refer to my revised Reputation Systems and Trust Networks to ensure consistent terminology.

Doubly signed and singly signed are kind of confusing. You should be clear that the doubly signed means they are signed from both keynodes. While singly signed means that only the node is signing it, and explain that the reason is because most existing digital identity providers do not provide a public key as part of their digital identities.

Our augmentation process is what allows Polykey to utilize digital identities for authentication. The inspiration for this comes from Keybase, however, we have chosen to develop a decentralized platform over Keybase's use of a central server and distributed clients.

The identity augmentation process is indeed inspired by keybase, but I don't think that diagram helps. Here we should focus on Polykey's flow, not keybase. So a passing mention of keybase is fine, but our flow is distinct now. Perhaps a diagram from our GUI that shows the authorisation step, the signed claim on the github provider and so on. Figma can do this easily.

  1. Authorization: Before a digital identity can be augmented, Polykey needs permission to access, and make changes to, the digital identity through its provider. We utilize OAuth for this process, allowing only secure, delegated access to user data.

The exact authorization protocol may be OAuth, more precisely OAuth2. So you should say, this is "usually" done with OAuth2.

  1. Updating access permissions: The first step of the augmentation process itself is to update Keynode and Gestalt permissions. This step links the Keynode and digital identity inside the user's Gestalt and updates (or creates) Keynode permissions in the ACL to reflect these changes (see Sharing below for an explanation of the ACL).

Are you sure this is the first step of the augmentation process? I believe the updating the GestaltGraph only happens at the end of the augmentation process. But what exactly are you updating the ACL for? This I'm not sure about.

  • Vault Permissions: Permissions given to other Keynodes that extend only to one or more of your Vaults.

I don't think these technical details about the ACL are on-topic for this article. These are reference material for another part of the wiki.

Once a Gestalt is trusted it then becomes possible to share secret information with it (see Secrets Management for a detailed discussion of secret sharing), however, this trust must extend both ways. We will refer to this concept as Gestalt Trust.

You should reduce talking too much detail about the ACL, since it's an implementation detail here. This is a theory discussion, so what your really want to say, is that users can elect to enable trust between gestalts, which is recorded in their local ACL. This is what enables the receiving of sharing notification messages. When both gestalts trust each other, then notification messages can be received mutually. This is intended to prevent spam.

I've taken out the trust section and incorporated into the earlier paragraphs, but some useful points are later down in the article, that can be incorporated back into your discovery, and as an ending statement about the Polykey acting as a platform for more sophisticated privilege granting systems and trust based applications.

CMCDragonkai commented 3 years ago

I want to use https://kroki.io/ to embed our plantuml diagrams.

CMCDragonkai commented 3 years ago

Should link this https://en.wikipedia.org/wiki/Key_server_(cryptographic) into either our Glossary or when we talk about "decentralizing" a public key server.

joshuakarp commented 3 years ago

In my opinion, based on our chat this afternoon, the Trust Network Architecture should be basically migrated into the reference documentation.

i.e. theory (which is where this wiki article would be) is purely external theory (i.e. no mention of Polykey implementation/specifics). Reference is where we talk about our implementation.

CMCDragonkai commented 3 years ago

Well the article has been expanded to talk about the outside world. So it should be theory. There are parts that would be good for reference yes. But reference should actually have coding related details.

On 29 October 2021 4:46:56 pm AEDT, Josh @.***> wrote:

In my opinion, based on our chat this afternoon, the Trust Network Architecture should be basically migrated into the reference documentation.

i.e. theory (which is where this wiki article would be) is purely external theory (i.e. no mention of Polykey implementation/specifics). Reference is where we talk about our implementation.

-- You are receiving this because you were assigned. Reply to this email directly or view it on GitHub: https://github.com/MatrixAI/Polykey/issues/1#issuecomment-954447517 -- Sent from my Android device with K-9 Mail. Please excuse my brevity.

joshuakarp commented 3 years ago

I feel we need to make the distinction and separation between "reference" and "theory" as clear as possible, to make maintaining the wiki as clear and easy as possible. Because based on our chat on Friday, I'm struggling to see why specifically the Trust Network Architecture section should be in theory. These parts specifically talk about sections of the Polykey implementation (gestalt graph, sigchain, gestalt discovery). This kind of information would then need to be repeated (and expanded upon) in the reference section.

My understanding of the sections:

CMCDragonkai commented 3 years ago

Yes there is definitely parts that would be repeated or factored out into the reference. But I wanted to keep the Trust Network Architecture high level enough that it doesn't go into the specific code details. It's more about explaining how the architecture works in general. So I think the article is fine for what it's in its content, but it does require some cleaning up according to my review here: https://github.com/MatrixAI/Polykey/issues/1#issuecomment-933153630

So this is still pending work from @emmacasolin

CMCDragonkai commented 2 years ago

Moving this to main Polykey repo.

CMCDragonkai commented 2 years ago

Closing this as this is mostly done it will require reviewing the content later.