Giters

MatrixAI / Polykey-Docs

Documentation for Polykey

Home Page:https://polykey.com/docs/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Write Wiki Page for Decentralized Trust Network

CMCDragonkai opened this issue · comments

commented

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

  • Compile linked issues into notes
  • Compile notes into skeleton
  • Write draft version of article (deadline Friday July 9th)
  • Final check over/final version
commented

Does this information go into the Polykey wiki (which is currently empty) or the js-polykey wiki? Above it specifies the Polykey wiki but we were talking about the js-polykey wiki before so just want to double check. @CMCDragonkai

commented

Goes into js-polykey wiki for now, we will reorganise it soon.

If I go for Polykey, polykey-desktop, polykey-mobile and js-polykey repos. Where we have tutorials, how-to guides and reference for all separate repositories. But then Polykey being the main repo will be where discussions and theory/discussion will be placed. This has some structural sense, but it might make it very difficult to see how all the pieces play together.

If we move the wiki entirely to Polykey, we have to consider what happens to the reference material relative to polykey-mobile and polykey-desktop.

A compromise might be:

  • Polykey contains tutorials, how-to guides, theory/discussion
  • js-polykey contains reference, how-to-guides (specific to js-polykey), and dev docs
  • polykey-desktop contains reference, how-to guides and dev docs
  • polykey-mobile contains reference, how-to guides and dev docs

But you can see most marketing material will derive from Polykey.

commented

@emmacasolin we need first draft by Friday.

commented

Introduce social discovery as the BLUF.

Then produce a narrative involving (in-order):

  • identities
  • gestalts
  • trust
  • sharing
  • discovery
commented

Notes for wiki:

keywords

  1. identity - authentication/secrets management
  2. trust - how do you know you can trust an identity? transitivity ->communication + quality of info - needs to meet certain qualifiers/acceptance criteria
    1. when you trust someone - judegemtn on how to qualify info they provide
    2. don't accept info at face value
    3. not binary -> levels
    4. relationship between 2 gestalts - is it transitive? a->b, b->c => a->c?
  3. gestalt - point of presence (there is some info (digital) that represents an entity e.g. person)
  4. BLUF - bottom line upfront (big idea upfront(summary) - then build up componentry)
    1. gestalts + digital identities - key argument/idea 1-2 sentences
  5. social discovery
  6. secret sharing
  7. compromise - identity providing info that's no longer representative of it (identity represents agent)
  8. social proof - Social proof is considered prominent in ambiguous social situations where people are unable to determine the appropriate mode of behavior, and is driven by the assumption that the surrounding people possess more knowledge about the current situation.
    1. are other people trusting the gestalt representative of the person/entity
  9. sigchain - chain of messages where each message is signed with a cyryptographic key - can prove authenticity/integrity of message
    1. authenticity - can check the message came from who it was meant to
    2. integrity - hasn't been mutated since
  • Social discovery is about being able to easily find entities (whether this be friends, teams, people, or machines) to be able to securely share secret information with them
  • Identities can be found through the identity's provider via an API. Such identities include GitHub, Facebook, Twitter, LinkedIn etc.
    • Identities are used to aid in authentication - if you trust that an identity belongs to a particular entity then it is authenticated
  • Gestalts are formed from identities: a message (or cryptolink) is posted by the user onto both a digital identity (on the identity provider) and a keynode (on its sigchain), which subsequently links them together via a process of augmentation
    • These messages are immutable once created, ensuring both their authenticity and integrity
    • The gestalt is formed through cryptolinks between nodes and identities as well as nodes with other nodes (cryptolinks cannot be formed between identities and other identities)
    • Gestalts act as a point of presence between identities (digital information) and entities (for example, people)
    • The linking of digital identities to keynodes provides a method of using social proof to confirm that the gestalt is representative of its supposed agent - if other people are saying that this person is who they say they are then you can be more confident that this is indeed the case
  • To share secrets with another gestalt, you must trust it. This trust can be based on an arbitrary qualification, such as social proof, but the quality and source of this information needs to meet certain acceptance criteria
    • Trust is a judgement made by qualifying the information that is provided - information should not be accepted at face value
    • Trust is not a binary decision, there are multiple levels of trust, and there are factors regarding trust that need to be considered such as whether or not it is transitive (for example, if you trust a gestalt, and that gestalt trusts another gestalt, does this mean that you should trust it as well?)
    • If you trust a gestalt then you trust that it has not been compromised - the identity is still representative of the agent it is supposed to represent
  • Once you trust another gestalt you can begin to share secret information with it
  • All of this machinery is necessary to easily manage the sharing of secrets in a way that aids the user experience
    • Discovery is made easier

relationships
identities -> gestalt -> trust -> sharing -> discovery

if you can trust a system -> can start sharing secret info with system
need to make sure this system represents the entity we think it is -> trusting a gestalt means making a judgement that the gestalt represents the real-world entity
-> leads to an explanation about how we form gestalts

commented

First draft has now been written. Some new terms were also added into the glossary (https://github.com/MatrixAI/js-polykey/wiki/Glossary)

commented
commented

Note that we are now moving these wikis to https://github.com/MatrixAI/Polykey/wiki.

For wikis to have images, those images need to be put into the repo. I'm going to start doing that by moving your article into Polykey now.

commented

This is now done, see: https://github.com/MatrixAI/Polykey/wiki We use an image embedded from https://github.com/MatrixAI/Polykey/blob/master/assets/divio_quadrant.png

So you can do the same for the screenshots we have used.

commented

Just a note @emmacasolin please use https://raw.githubusercontent.com/MatrixAI/Polykey/master/assets/divio_quadrant.png, this is the raw URL for the image, it is much faster to load.

commented

Uploaded some images from polykey-design to the Polykey GitHub so that they can be included in this wiki page. So far they've all been added to the page but I've only styled the first one so far.

commented

Added information about Keynode Identities (X.509 identity certificates) - will continue to look through polykey-design#31 for more information to include, particularly from https://gitlab.com/MatrixAI/Engineering/Polykey/polykey-design/-/issues/31#note_492869452

commented

Wiki page has been updated with subheadings, images, lists, and the information contained within polykey-design#31

commented

For @joshuakarp to review.

commented
  • Overall, I think it's really well-written - there were only a small number of changes I made (see the history for those), but they were very minor.
  • My only thought was that most of the images/diagrams are a bit too small - especially ones that have some detail in them. I think the size of all of the images should be bumped up by ~20%. Right now, I can't make out details in the GUI screens. I'm not sure if this is just my resolution though.
commented
commented

Yep, was that for me to do? Should I prioritise this or notifications?

commented
commented

Some extra feedback:

  • "Gestalt" concept isn’t defined or elaborated
  • "Keynode" concept isn't defined or elaborated
  • Any technical concept needs to be "introduced" first when they are not common knowledge. Consider the reader un-initiated.
  • Eventually all terms should link to other articles expanding on the concept. But you should at least define what these are or look at our dictionary/glossary.
  • The complete augmentation process should be described with a flow diagram. There are existing diagrams in our figma, do you have access to this, you can reuse that or build a new diagram properly in figma.
  • The "trust root" should be better explained. It should be based on the idea that at the end of the day you rely on social trust. You the user makes a judgement call based on social trust or other out-of-band mechanism (like a key-signing party), and then assign that as an "anchor" for trust.
  • More visuals including things like "anchor" and a trust chain formed in the Gestalt Graph.
  • Break up your concepts more into dot-points. Dot-points are easier to consume and easier to refer to.
  • You can link to wikipedia articles for some third party analogues or concepts. Many things should be googled to see if there are a third party explainer for it. Like trust anchor or trust root.
commented

Changes to be made based on feedback:

  • Make images bigger
  • Proper explanation of Gestalt Graph (there is a graph of gestalts, formed by all the users of Polykey keynodes)
  • How does the Gestalt Graph grow (node-node claims/node-identity claims)
  • How does the Gestalt Graph shrink
  • How does the Gestalt Graph affect the ACL + trust networks
  • Define + elaborate on "gestalt" concept
  • Define + elaborate on "keynode" concept
  • Add definitions for all technical concepts where they're introduced
  • Make sure all technical terms link to either a wikipedia page, glossary item (todo: cryptolink), or other article
  • Find/create and add flow diagram of the augmentation process
  • Better explanation of "trust root" (at the end of the day you rely on social trust. You the user makes a judgement call based on social trust or other out-of-band mechanism (like a key-signing party), and then assign that as an "anchor" for trust)
  • Visual for "anchor"
  • Visual for trust chain formed in Gestalt Graph
  • Visuals for any other concepts that would benefit
  • Break up paragraphs into dot-points + smaller paragraphs
commented

Very relevant paper I stumbled upon while researching: https://www.researchgate.net/publication/258763091_Trust_Networks

commented

The article has now been revised to incorporate the provided feedback above

commented

@emmacasolin here's some review.

In today's world, agents can be represented by their presence across digital identity providers. Through social discovery, these agents can be located and authenticated, and subsequently allowing for the secure sharing of secrets with desired entities.

  • You want to start with bottom line up front. What exactly is the problem or topic here?
  • You say that through "social discovery", these agents can be.... But why would you bring up social discovery here. Social discovery is a technique/technology we have built. Nobody knows what social discovery is at this point of reading the article.
  • You say that social discovery locates, authenticates, and then allows for secure sharing of secrets with desired entities. There are several problems here:
    • How does social discovery "authenticate"?
    • How does social discovery allow secure sharing?
    • Why do you use "desired entities" when you just use the technical term of agent

You need to begin with the purpose of the gestalt system. Start like this instead:

"To share secrets securely between people and machines, it all has to begin with identity. If we do not securely identify a person or a machine on the internet to share information with, it does not matter what encryption technology we use or how we use it, any secret shared would immediately be leaked and compromised. Therefore it is essential to understand how we can securely discovery identities, establish trust relationships between different identities in both public and private spaces, and authorize information sharing to these identities."

Notice that in my first paragraph I'm establishing the topics I'm going to be talking about. That's the bottom line.

Now you can lead into digital identities, gestalts, trust, sharing and then discovery in that order.. The very next paragraph should explain how digital identities are points of presences for agents (persons or machines). And the relevant details of that. I can see you're leading to gestalts afterwards. But I have some more comments.

Digital identities contain a vast amount and variety of information, so much so that digital identities can go as far as to authenticate agents and allow them access to services and secrets (for example, using a Facebook account to log into other websites). This ability comes not only from a digital identity's documentation of factual information (such as an agent's name, age, and acquaintances), but also information about behavior.

  • Digital identities contain a vast amount and variety of information - why is this relevant? This sentence is unnecessary.
  • Digital identities are not used to authenticate agents. Did you read the secrets management article? Authentication happens though using one of the 3 factors. You authenticate and thus known. Once you become known, you are associated to a digital identity.
  • Ok I see you're saying Facebook account can be used to log into another website. I get you're thinking that this is a usage of digital identity to login somewhere else. But technically this is not the case. What's happening is that a third party is piggybacking off Facebook's digital identity. They are just sharing a digital identity. But this isn't really relevant to Polykey here so I'd avoid talking about this.

If you want to explain digital identities. It's best to stick with straightforward definitions of them and examples of them. Like:

"Digital identities are the artifacts of identity on the internet. They represent real-world agents (people or machines). If multiple digital identities are used to represent a single real-world agent, then each digital identity is a facet of the combined digital representation of the agent."

Give examples of: GitHub, Facebook, Twitter, LinkedIn etc. Take screenshots online of public people on the internet. Like a famous developer on Github. A famous person on LinkedIn/Twitter.

Remember to introduce terminology either by contextual usage, or by strict definition sentence.

Polykey takes advantage of this idea through the use of Gestalts - a word that comes from the adage "the whole is greater than the sum of its parts". Despite there being no physical links between the various digital identities that represent an agent, social proof allows us to infer that all of these identities can combine to form a greater whole. The Gestalts implemented within Polykey combine the information that is contained within digital identities with the secrets held within the vaults of Keynodes such that the result is a point of presence between identities and agents. Each Gestalt is comprised of:

  • You only explain what keynodes are way later in the article.
  • Bring up the "architecture of Polykey" so you can explain what a keynode is.
  • You can say, a Gestalt is X, Y, Z including keynode. Then you say: "In Polykey, keynodes are...".

Despite there being no physical links between the various digital identities that represent an agent, social proof allows us to infer that all of these identities can combine to form a greater whole.

  • Don't use the word physical links. There is no such thing here.
  • You don't actually explain what social proof is here.
  • Social proof does not allow us to infer that these identities forming a gestalt are correct. That's not how it works. Social proof is trust between gestalts. You're talking about DIs within a gestalt. These DIs within a gestalt can be trusted to form a federated identity due to the cryptographic links between the DIs. This is where you can talk about the augmentation process of Keynode to Identity and Keynode to Keynodes.
  • Don't talk about social proof until you get to the trust section.
commented

@emmacasolin also try to use a word/writer to just check grammar at the end of writing. There was a few grammar mistakes I found that should be trivially solved every time you update.

commented

Also add Keynode to the Glossary and refer to it when you talk about Keynode at the beginning of the article.

commented

As for better writing style when linking different articles, please see this: https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Linking

In particular "repeated linking".

commented

BTW, in order to align terminology, I've changed the above usage of "entity" to "agent".

commented

Very relevant paper I stumbled upon while researching: https://www.researchgate.net/publication/258763091_Trust_Networks

This paper is indeed relevant. Nice find. It does provide a greater theoretical understanding of trust networks, and therefore we will be able to later review it in detail and understand how PK fits in the big-picture architecture of global trust networks.

commented

@CMCDragonkai I think you might have missed a paragraph in your above review? I defined and explained social proof in this paragraph just above where I introduce gestalts:

Unlike factual information, behavioral information is hard to imitate. As a consequence, this information can be utilized to create a reliable representation of an agent. Social proof is a concept that taps into this idea: that the people around you will often collectively hold more information about the current environment or situation than yourself. If a large enough number of people believe that a digital identity is a reliable representation of a particular agent, then this information can be used to form a decision of whether or not this information is accurate.

commented

Yes I know that one, I believe that comes afterwards. Don't talk about social proof until you have gestalts trusting gestalts.

commented

Yeah I've copied and pasted it into a later section for now and will link it in better at a later stage

commented

See my core activity 3 section in the R&D report. Notice I focus on identity first.

And we can state that this entire architecture forms a trust network.

commented

@emmacasolin I'd like you start using sequence diagrams for the augmentation process. I think it's a good idea to map out how our augmentation procedure works. Then it can also be done for node claims.

commented

@tegefaulkes is also making use of sequence diagrams for the session authentication protocol, so it's good idea to share diagrams as we talk about these protocols.

commented

@emmacasolin you can start with ASCIIflow first to prototype it, and then later use plantuml to make it more maintainable.

commented

Most of the content work is done for this iteration, Friday will just be finishing off the diagrams. So far I've prototyped the augmentation sequence diagram:

┌────────┐                            ┌─────────┐                           ┌───────────────────┐
│ Agent  │                            │ Keynode │                           │ Identity Provider │
└────┬───┘                            └────┬────┘                           └──────────┬────────┘
     │                                     │                                           │
     │ Request DI augmentation             │                                           │
     ├────────────────────────────────────►│                                           │
     │                                     │ Register IdP                              │
     │                                     ├──────────────┐                            │
     │                                     │              │                            │
     │                                     │◄─────────────┘                            │
     │                                     │                                           │
     │                                     │ Send authentication request               │
     │                                     ├──────────────────────────────────────────►│
     │                                     │                                           │
     │                                     │          Respond with authentication code │
     │                                     │◄──────────────────────────────────────────┤
     │                                     │                                           │
     │    Respond with authentication code │                                           │
     │◄────────────────────────────────────┤                                           │
     │                                     │                                           │
     │ Perform authorization action        │                                           │
     ├─────────────────────────────────────┼──────────────────────────────────────────►│
     │                                     │                                           │
     │                                     │ Request access token                      │
     │                                     ├──────────────────────────────────────────►│
     │                                     │                                           │
     │                                     │                 Respond with access token │
     │                                     │◄──────────────────────────────────────────┤
     │                                     │                                           │
     │                                     │ Generate claim on sigchain                │
     │                                     ├────────────────────────────┐              │
     │                                     │                            │              │
     │                                     │◄───────────────────────────┘              │
     │                                     │                                           │
     │                                     │ Publish claim to DI using access token    │
     │                                     ├──────────────────────────────────────────►│
     │                                     │                                           │
     │                                     │              Respond with claimId and url │
     │                                     │◄──────────────────────────────────────────┤
     │                                     │                                           │
     │                                     │                                           │
     │                                     │                                           │
     │                                     │                                           │

And I'll make a proper version with plantuml on Friday.

Completed so far:

  • re-ordered a lot of content - article now follows the digital identities -> gestalts -> trust -> sharing -> discovery order much more clearly and headings align with this
  • better explanation of DIs with examples
  • added explanation of pk's architecture
  • more in-depth discussion of nuances of trust
  • better explanation of acl
  • better explanation of social discovery
  • open-ended conclusion about future direction re implications of the gestalt graph being a trust network

Still to do (Friday):

  • add explanation and sequence diagram demonstrating augmentation process (plantuml ver)
  • social discovery/gestalt traversal sequence diagram (asciiflow + plantuml ver)
  • put article through grammarly to resolve all spelling/grammar issues
commented

Awesome, will have a deep review this friday.

commented
commented

Can you copy paste the plantuml code as a .puml file somewhere. I just want to figure out the best way for storing and showing plantuml diagrams on GitHub wikis. Gitlab wikis have the ability to auto-render, unfortunate that GitHub doesn't.

I've made a folder in the wiki repo (like the images one) called files and put it in there

commented

I've made a prototype for the augmentation sequence diagram. It's in plantuml since I find that a little easier to work with since all the formatting is done automatically:

https://www.planttext.com/?text=LP7HQiCm34NV_HLQtlC3OuoM1KfO7qf6Fi2pHMAIsAwbREJl9zSfQz-CxhdIbNmWredNPLRgXKTS4EAidLTA6mu9UiAaJF2SmWpL9SpRX1iS1_HSWIQ8avAdumq-SVF1OYvEOiz6gDy5W5VeyBeYCJGjw7LOnA7P1Qz4l2Dzj9eHJeBfcK5x2yUFCqHCYoCIc7Pwya9VKlXnCin8rWN4gPNKx-e9FQRShSZ10xd1Z7ajwV5MrmNha6AGER-EHq1l9BqjbiTW3MRXgLurRd0I4rgxBx_dIRURE1jpnFLxTZJ-PsZQ-_G2F8qlLDlS5k-xSxbVXlS3Fh3LrseC4bLA7T1R-Ri_
commented

The wiki page is now finished for this iteration and is ready for review

commented

I'm going to be making some changes.

Firstly a rewording of some initial paragraphs to make it more authoritative. Replacing "can" with "is". No need to be unconfident in our ideas.

The secure sharing of secrets between people and machines begins with identity. If we do not securely identify an agent (person or machine) on the internet, with whom we wish to share secret information, then regardless of what encryption technology we use and how we use it, any secret shared would be compromised. Therefore, it is essential to understand how we can securely discover and authenticate identities, establish trust relationships between different identities in both public and private spaces, and authorize information sharing to these identities.

Digital identities are digital artifacts e.g. social media profiles, domains, public keys, that exist on the internet which represent real-world agents. If multiple digital identities are used to represent a single real-world agent, then each digital identity is a facet or point of presence of the combined digital gestalt.

Digital identities are hosted on identity provider platforms. Identity platforms are centralized or decentralized reputation systems. There are public (Facebook, LinkedIn, GitHub, Twitter) and private platforms (Active Directory, Slack). Public platforms allow agents to perform digital activities to signal social proof, and thus build a network of trust via digital identity reputation. Private platforms are simpler as trust is dictated by fiat.

After this, I want to then tie up the introduction with respect to existing platforms.

  • explain discovery of identities - you need this "namespace"
  • explain authentication - authentication of agents means identifying the agent, identity is the digital representation of all digital activities
  • explain how trust relationships are created - digital activities create social proof, social proof quantities "trust" (examples of scores, friend count, follower count... etc)
  • explain the decisions made on top of trust - depends on the platform capabilities

The first section should conclude with the reason to create a Polykey decentralized trust network. That is saying that these platforms are loosely connected atm.

The second section is now:

Decentralized Trust Network

Which is introducing PK's idea, and the keynodes.

Which can broken into (as in your existing structure):

  • Decentralized Trust Network
    • Gestalts
    • Augmentation
    • Trust
    • Sharing
    • Discovery

I think this will nicely expand in detail how PK's trust network addresses the above issues with existing trust networks.

commented

Some more changes...

The secure sharing of secrets between people and machines begins by authenticating digital identities. Authentication involves securely identifying an agent (person or machine) on the internet with whom we wish to share secret information. Without this, regardless of what encryption technology we use and how we use it, any secret shared would be compromised.

Currently secret sharing requires trusting third-party centralized platforms that provide the authentication of identities. Polykey has constructed a decentralized trust network which eliminates these middlemen so that secrets can be shared without trusting third-parties.

Decentralized Trust Network

Polykey's decentralized trust network is built on top of existing digital identities from centralized identity provider platforms.

Digital identities are digital artifacts (e.g. social media profiles, public keys, certificates) that exist on the internet and represent real-world agents. If multiple digital identities are used to represent a single agent, then each digital identity is a facet or point of presence of the combined identity.

The most commonly used digital identities are hosted on centralized identity provider platforms. There are public (Facebook, LinkedIn, GitHub, Twitter) and private platforms (Active Directory, Slack).


From top left to bottom: Digital identities for the CEOs of Twitter, GitHub, LinkedIn, and FaceBook

These platforms are reputation systems that allow agents to perform digital activities (that may have physical real-world effects) to signal social proof, and thus build a network of trust via reputation. Private platforms are simpler as trust is dictated by the platform's owner. For the purposes of this discussion, we're going to focus on public platforms.

On a surface-level identity provider platforms enables the following interaction cycle:

  1. Discovery - the ability to discover identities by querying social proof information, and tracing digital activities to identities.
  2. Trust - social proof is quantified by gamifying collaborative digital activities, e.g. reputation points, friend and follower count, likes and stars.
  3. Engagement - users rely on trust to help them engage in digital activities, e.g. posting comments, retweeting, sharing photos, answering questions.

The trust networks between each platform, and the effect of their social proof is loosely connected to each other. This is currently done mostly by "crossposting" or hyperlinking.

So basically we are going to straight to explaining the decentralized trust network after justifying why we need this.

I want to define trust relationships which leads us to creating cryptographic secure cross posts. Like we really need to define what is trust here. I see a trust section later, and that may be moved up above.

It's all about how it's built on top of digital identities and centralized trust networks. It allows us to introduce all the building blocks. So the overall structure is now:

  • Decentralized Trust Network
    • Digital Identities and Identity Providers
    • Trust and Reputation Systems
    • Keynode Sigchain
    • Gestalts
    • Identity Augmentation
    • Discovery
    • Secret Sharing

The title of the article can be "Decentralized Trust Network" since that's more primary to the point of this article.

commented

Will also have a references section of nice things to mention:

We may mention keybase as one of the first to do this... but I reckon I'll just have it in the references as it flows better.

commented

Not sure if the "claims" should be used, or should we still call it "augmentation", since I think CLI now uses "claims" keyword now. But we can explain it as a process of augmentation.

commented

The article is now renamed https://github.com/MatrixAI/Polykey/wiki/Decentralized-Trust-Network to better reflect the 2 core ideas of Polykey: Secrets Management and Decentralized Trust.

commented

The trust chain image of X.509 is a nice picture showing how PKIs use X.509, but it's not how we use it. So either we get a better picture/diagram for ourselves or we explain how this is how PKI use X.509 to create a certificate trust chain by having signature chain.

commented

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

  • Decentralized Trust Network
    • Digital Identities & Identity Providers
      • Reputation Systems and Trust Networks
    • 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.

commented

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

commented

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:

  • Root Certificate
  • Root Keypair
  • Use "agent" not "entity"
  • Who is the key owner? It's the agent that controls the keynode.
  • The certificate doesn't have claims. The claims are on our sigchain now. The certificate only contains information relating to:
    • The public key
    • The node id (which is derived from the public key)
    • Previous valid certificates, we use the certificate chain not to represent a trust hierarchy, but instead a chain of valid certificates, where prior certificates will expire earlier
    • Some custom OIDs related to Polykey version and the node signature.
    • Note that the node signature and the issue signature is different. Explaining this would be reference material, so we can leave this out for now.

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.

commented

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

commented

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.

commented

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.

commented
commented

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:

  • Theory: material regarding the outside world, with little to no reference to explicit Polykey implementation details
  • Reference: strictly material on what we've implemented in Polykey (should predominantly follow a similar structure to our source code)
commented

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: MatrixAI/Polykey#1 (comment)

So this is still pending work from @emmacasolin

commented

Moving this to main Polykey repo.

commented

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