P2 Extension: polyproto-auth

v1.0.0-alpha.1 - Treat this as an unfinished draft. Semantic versioning v2.0.0 is used to version this specification. The version number specified here also applies to the API documentation.

The polyproto-auth extension is a protocol extension for polyproto that provides a basic authentication mechanism to register new users and authenticate existing users.

• P2 Extension: polyproto-auth
• 1. Registration of a new actor
• 1.1 Registering a new actor on a polyproto home server
• 1.2 Authenticating a new client on a polyproto home server
• 1.3 Authenticating on a foreign server

1. Registration of a new actor

Registering a new actor in the context of polyproto is done through an API route defined in the polyproto-auth "No registration needed" API documentation.

1.1 Registering a new actor on a polyproto home server

To register, the client sends the necessary information to their home server. The server verifies the data, checks username availability, and responds with HTTP 201 and the new identity's federation ID, if successful. However, a session token is not provided until the actor authenticates a client, as detailed in section 1.2.

sequenceDiagram
autonumber

actor c as Client
participant s as Server

c->>s: Registration information
s->>s: Verify correctness of provided information,<br />check if username is available, etc

alt verification successful
  s->>s: Verify provided CSR

  alt CSR okay
    s->>s: Sign CSR
    s->>c: HTTP status code 201, with actor federation ID
  end
end

Fig. 1: Sequence diagram of a successful identity creation process.

1.2 Authenticating a new client on a polyproto home server

To access their account from a new device, an actor authenticates the session with their home server by sending authentication information and a certificate signing request (CSR) for the new client. If verified successfully, the server signs the CSR and responds with the newly generated ID-Cert and a session token corresponding to this ID-Cert.

sequenceDiagram
autonumber

actor c as Client
participant s as Server

c->>s: Auth information, CSR
s->>s: Verify correctness of provided auth information

alt Verified successfully
  s->>s: Verify provided CSR
  alt CSR okay
  s->>s: Sign CSR
  s->>c: HTTP status code 201, ID-Cert + session token
  end
end

Fig. 2: Sequence diagram of a successful client authentication process.

The client is now authenticated and can use the session token and ID-Cert to perform actions on behalf of the actor identified by the ID-Cert.

1.3 Authenticating on a foreign server

Authenticating on a foreign server requires the actor to sign a challenge string with their private identity key and send it, along with their ID-Cert, to the server. The server then validates the ID-Cert's origin, the challenge string's signature, and the ID-Cert's validity.

If the verification is successful, the foreign server can issue a session token to the actor.

Example: Say that Alice is on server A, and wants to authenticate on Server B, using her existing identity.

Alice's client sends a request to Server B for a challenge string, telling Server B the session ID they are communicating from in the process. Upon receiving a response, Alice signs this challenge string with the correct private key. They then send the signature to Server B. Server B can now verify that it was actually Alice who signed the string, and not a malicious outsider. Server B does this by requesting Alice's ID-Cert, specifically the ID-Cert matching the session ID Alice identified with to Server B. If all goes well, server B will send a newly generated session token back to Alice's client. Alice's client can then authenticate with server B by using this token.

sequenceDiagram
autonumber

actor a as Alice
participant sb as Server B
participant sa as Server A

a->>sb: Challenge string request including current Session ID
sb->>a: Challenge string
a->>sb: Signed challenge, ID-Cert, optional payload
sb->>sa: Get Server A Public Certificate
sa->>sb: Send Public Certificate
sb->>sb: Verify signature of challenge string
sb->>a: Session token, optional payload

Fig. 3: Sequence diagram of a successful identity verification.

In the diagram, Alice's "optional payload" is extra data that might be requested by servers. This is useful when using a single identity across various polyproto implementations, due to differing information needs. The payload is signed with the actor's private identity key.

Likewise, the "optional payload" sent by the server in the above diagram can be used by implementations to send additional information to the client. An example might be initial account information.

Example

Alice currently has a polyproto identity, which she created when signing up for "https://example.com/chat". When signing up for this service, she didn't need to provide any additional information on registration. However, when she wants to actor her existing identity to sign up for "https://example.com/social", she is asked to provide her email address, which she can provide as the "optional payload". The server can then store the email address in its' database, associate it with Alice's identity, and let Alice log in with her existing identity.

If Alice's session token expires, they can repeat this process of requesting a challenge string and, together with her ID-Cert, exchange it for a session token. However, if Alice wants to access this third party account from a completely new device, they will have to perform the steps described in section 1.2 to obtain a valid ID-Cert for that session.

---

• Actor - An entity represented by a federation ID, registered on a home server. Actors can be users, bots, or any other entity with a federation ID.
• CA, Certificate Authority - Any home server that issues and publicly attests to the validity of ID-Certs. In polyproto, only home servers are CAs.
• Client - Any application used by an actor to connect to an instance.
• CSR, Certificate Signing Request - A request sent to a CA to obtain a certificate. It holds information about the entity requesting the certificate, including their public identity key.
• DN, Distinguished Name - A set of RDNs (Relative Distinguished Names) that uniquely identify a certificate. See https://ldap.com/ldap-dns-and-rdns/
• Federation ID - A unique identifier; In public contexts, usually actor@subdomain.example.com, where bold parts are required and non-bold parts are optional.
• Foreign server - An instance that an actor is not registered on; essentially a third party.
• Home server - The instance that an actor is registered on. Any polyproto-core compliant server hosted on the same domain is also considered a home server. A home server is the instance that publicly attests to the validity of all legitimate ID-Certs issued under its FQDN. A domain can have many home servers, but only one per subdomain.
• ID-CSR - A certificate signing request for a client's identity key pair. It is used to obtain an ID-Cert.
• Identity - Synonymous with "Federation ID".
• Identity Key Pair - A key pair associating an identity with a set of cryptographic keys used to sign and possibly encrypt messages.
• Instance - A server hosting polyproto compliant software for clients.

• Message, Messages: In the context of this protocol specification, a message is any piece of data sent by a client that is intended to be identifiable as being sent by a specific actor. To qualify as a "message", this piece of data must also, at any point in time, and also if only briefly, be visible to other users or to the unauthenticated public. Examples of things that would qualify as messages include:

  • A message sent to another actor in a chat application
  • A post on a social media platform
  • A "like" interaction on a social media platform
  • Reaction emojis in Discord-like chat applications
  • Group join or leave messages
  • Reporting a post or actor, if the report is not anonymous

• P2 - Shortened form of polyproto.

• P2 Extension - A polyproto extension.
• polyproto-chat - The chat-API used by Polyphony. An extension of the polyproto protocol, defining the routes and capabilities of the chat-API used by Polyphony.
• polyproto - The core federation protocol and APIs of polyproto, enabling identification and authorization on foreign servers. It is independent of the chat-API used.
• Root Certificate - A certificate used to sign other certificates, establishing a chain of trust. In polyproto, only home servers have root certificates.
• Service: Any application-specific implementation of polyproto, defined by a P2 extension. All services are P2 extensions, but not all P2 extensions are services. polyproto-chat is an example of a service.
• Session - A specific period of authenticated interaction between a client and an instance. During the lifetime of a session, the client can perform actions as the actor they are authenticated as.
• Session ID - See polyproto specification: Section 6.1.1.3