An Overview of polyproto
This overview page is not yet finished. However, what's there is already representative of what the polyproto protocol is about.
polyproto is a family of protocols, or a set of rules that different apps and websites can use to represent you in a way that protects your ownership of your identity. In the same way your company or university lets you access all their devices and websites using the same credentials, polyproto lets you use the same account on all apps and websites that support it. However, with polyproto, there's no company or organization that controls your personal information. You own it, and you can take it wherever you want.
In other words, the polyproto-core specification describes a federated identity protocol that can be used for almost anything. The polyproto family also includes a number of extensions that let people use their identities in different kinds of apps. One notable example is polyproto-chat which describes a message exchange protocol for secure instant messaging.
This kind of extension is what the polyproto-core specification calls a service extension. The polyproto-core specification also describes a second type of extensions, named capability extensions, which introduce major technological additions for use in other extensions. polyproto-core is a simple protocol intended to be widely useful. Extra features needed for specific kinds of apps can be added through this other kind of extension. One example is polyproto-mls, implementing Messaging Layer Security, which gives people a safe way to establish encrypted channels for sending messages privately.
If you're interested in building an app or website that prioritizes federation, autonomy and data integrity, then polyproto may be for you. This page is intended for anyone who wants to understand how polyproto works on a technical level.
Identity
A user's identity is always represented by a Federation ID (FID). Conceptually, FIDs are nothing new, and they look like this:
xenia@some.example.com
Everything after the @ is your Home Servers' domain, and the part before the @ is your username.
Together, these form an individual, yet globally unique, identifier.
Certificates and Keys
Identity Certificates (ID-Certs) represent your identity when logged in on different sessions. Each Identity Certificate contains the following information:
- Your FID, to uniquely identify your account.
- A session ID, which is unique for each session and does not change, even if the keys change.
- An expiry date, after which the certificate becomes invalid.
- A signature generated by your home server, which acts as part of the proof that this certificate was actually issued by your home server.
- Some information from your home server, including the server's domain and the certificate serial number.
- Information about the signature algorithm your home server uses.
and, last but not least:
- The client's public identity key.
For the sake of this overview, the most important parts here are the client public identity key, your federation ID, the home server's domain and the home server's signature for this certificate.
Message signing
When you, for example, chat with someone on a different server, that other server is fully in control of what data it chooses to present to you. To make sure that this server is always telling you the truth, and not, for example, sending you fake chat messages or social media posts, messages are signed using a client's public identity key.
This is how it works:
- As touched on previously, every user client has an own identity key pair, comprised of a public and a private key. The public key is cryptographically linked to the private key, meaning that this public key can belong to only this specific private key. Data is signed using the private key, which ONLY the client knows. Everyone can then use your public key to prove that this signature was generated by your client, and that the signature matches the data that was signed.
- Signatures are unique to a piece of data, meaning that two differing pieces of data signed by the same or different private keys will always1 produce different signatures. This is true even if the data only differs minutely (even by a single space, or a single comma).
- Your home server attests to a clients' key pair by creating a certificate for your public key, which it signs with its own secret public/private key pair, and then sends to you. Your private key is never sent anywhere at all, and it doesn't need to be.
Now, your public identity key and your home server's identity key are 'linked' to each other. This is represented in the ID-Cert you then receive from your home server.
- When communicating with another "foreign" server in polyproto, you first send that server your ID-Cert. The server can then prove the validity of your identity, simply by asking your home server for its public key and performing a quick signature verification.
- When sending data to the server, such as chat messages, your client computes the signature for that message using your private key, and attaches this signature to the message you send to other servers.
- Any user, at any point, can now take this signature, your identity certificate, and your home servers' public key and cryptographically verify that it was, in fact, you who sent the message, and that the message was not tampered with in any way. To distribute the load of ID-Cert requests more evenly, the server that the data exchange is happening on is responsible for caching and handing out users' ID-Certs.
If you're interested in the details, feel free to jump to section #6.1 in the protocol specification document, which covers this exact thing and more.
Trust
Trusting the smallest possible number of entities is great practice when it comes to security. polyproto makes sure that almost everyone you do trust is under constant scrutiny, and thus provides measures to verify a data authors' identity, and that the actual data has not been tampered with.
Aside from yourself, the entity with the most trust assigned to it is your home server. Creating your identity on a specific home server is a pledge from that server and its admins to you, in which they promise not to create sessions on your behalf, or to otherwise perform actions which can be publicly identified to be carried out by you, without your explicit consent.
If you ever decide your home server is no longer trustworthy, you can always migrate to another server while keeping the ownership status of your data on all servers you have sent data to, even if your home server is offline indefinitely.
Multi-use
polyprotos' API definitions and specification document intentionally leave space for implementation-specific data to be sent, where it makes sense. Nothing about the core protocol makes polyproto inherently unsuitable for any purpose.
Federation
Federation in polyproto means using one identity or client to interact with multiple servers or even services at once. Implementing federation is straightforward, and entirely seamless to use for end users.
Technology
Probably the most refreshing aspect about this new protocol is that it's really boring. There's really nothing new about any given atomic aspect of polyproto. Polyproto uses well-known, tried and battle-tested technologies, such as asymmetric encryption, X.509-based public key infrastructure and -certificates, digital signatures, JSON over REST and other well-established technologies such as WebSockets.
polyproto should be effortless both for developers and for end users, who, ideally, should never have to notice any of the technical stuff going on in the background.
Conclusion
This is just an outline of how polyproto works. Some details have been left out to keep this outline clearer and focus on the most important parts of the protocol. If you have read and understood this overview, you should have no - or at least way less - trouble reading the full protocol specification, which covers a lot more details!