Start documenting Vervis federation technical details

This commit is contained in:
fr33domlover 2019-05-27 09:06:29 +00:00
parent 85777fa381
commit e86a2970ba

View file

@ -85,3 +85,151 @@ Per-project inbox, to which projects receive ticket comments from other
servers. If someone on another server publishes a comment on your project, then servers. If someone on another server publishes a comment on your project, then
your project will receive the comment at this endpoint and the comment will be your project will receive the comment at this endpoint and the comment will be
displayed when you visit the ticket page. displayed when you visit the ticket page.
## Spec
Federation in Vervis is done using ActivityPub. Below comes a description of
the details that aren't already common on the Fediverse. The details are
written informally in the form of short simple proposals.
### (A) Authentication
Vervis uses HTTP Signatures to authenticate messages received in inboxes. The
Host, (request-target), Date and Digest headers are required to be present and
used in the signature, and the Digest header must be verified by computing the
hash of the request body. Other headers may need signing too, as specified in
the proposals below.
The `publicKeyPem` field maps to the PEM encoding of the key. The PEM encoding
contains not just the key itself, but also a code specifying the key type. The
Fediverse de-facto standard is RSA, more precisely PKCS#1 v1.5, and used with
the SHA-256 hash algorithm. This is often referred to as RSA-SHA256.
If the `algorithm` is specified in the Signature header, it must match the key
type in the PEM. But `algorithm` isn't required, and we should probably stop
using it.
#### (1) Actor key(s) in a separate document
Allow an actor's signing key to be a separate document, rather than embedded in
the actor document. In Vervis, the use of that is for server-scope keys (see
proposal below), but otherwise, an embedded key is just as good.
```
GET /users/aviva/keys/key1
{ "@context": "https://w3id.org/security/v1"
, "@id": "https://example.dev/users/aviva/keys/key1"
, "@type": "Key"
, "owner": "https://example.dev/users/aviva"
, "publicKeyPem": "-----BEGIN PUBLIC KEY----- ..."
}
GET /users/aviva
{ "@context":
[ "https://www.w3.org/ns/activitystreams"
, "https://w3id.org/security/v1"
]
, "id": "https://example.dev/users/aviva
, "type": "Person"
, "preferredUsername": "aviva"
, "name": "Aviva"
, "inbox": "https://example.dev/users/aviva/inbox"
, "outbox": "https://example.dev/users/aviva/outbox"
, "publicKey": "https://example.dev/users/aviva/keys/key1"
}
```
Authentication requirements:
- The `keyId` from the signature header matches the `@id` in the document you
receive
- The and key and the owner actor IDs are on the same host
- They key specifies the `owner`, and the owner actor's `publicKey` links back
to the key
#### (2) Multiple actor keys
Allow an actor to specify more than one key, or no key at all. This means that
when you examine the owner actor of the key, you verify the actor links back to
the key by checking that the key is listed among the actor's keys (instead of
requiring/expecting only a single key to be specified by the actor).
The reason this is used in Vervis is for key rotation using a pair of
server-cope keys (see proposal below).
When used along with proposal A.1, each key may be either embedded in the
document, or a URI specifying the ID of a key defined in a separate document.
Actors that never need to post activities can simply not specify any keys at
all.
```
GET /users/aviva
{ "@context":
[ "https://www.w3.org/ns/activitystreams"
, "https://w3id.org/security/v1"
]
, "id": "https://example.dev/users/aviva
, "type": "Person"
, "preferredUsername": "aviva"
, "name": "Aviva"
, "inbox": "https://example.dev/users/aviva/inbox"
, "outbox": "https://example.dev/users/aviva/outbox"
, "publicKey":
[ { "id": "https://example.dev/users/aviva#main-key"
, "type": "Key"
, "owner": "https://example.dev/users/aviva"
, "publicKeyPem": "-----BEGIN PUBLIC KEY----- ..."
}
, "https://example.dev/users/aviva/extra-keys/extra-key1"
, "https://example.dev/users/aviva/extra-keys/extra-key2"
]
}
```
#### (3) Server-scope actor key
#### (4) Actor key expiration and revocation
#### (5) Ed25519 actor keys
#### (6) Key rotation using a pair of server-scope keys
### (B) ActivityPub
#### (1) Non-actor audience
#### (2) Authenticated inbox forwarding
#### (3) Non-announced following
#### (4) Object nesting depth
#### (5) Object capability authorization tokens
### (C) ForgeFed
#### (1) Actors
#### (2) Authorization and roles
#### (3) Comments
#### (4) Tickets
#### (5) Patches
#### (6) Merge requests
#### (7) Commits
#### (8) Forks
#### (9) SSH keys
#### (10) Pushes
#### (11) Avatars