Specification for federated social media protocol.

• Instance: a currently running server process, receiving HTTP requests/communicating with DB/etc.

• Server: logical unit of the fed system, consisting of 1 or more instances and a single logical database.

• Local server: the server a user is registered with, and accessing with that server's frontend.

• Remote server: a server the user is not registered with, and interactions will be proxied through the local server using the protocol we are discussing.

• Community: collection of posts related by a common topic on a single server (a subreddit).

• Post: basic unit of content in our protocol, can be nested and frontends may choose to render top level posts as primary pieces of content, with nested posts rendered as comments.

• User: entity representing a student/member of staff registered with a server. Users cannot be transferred between servers, but can of course view and interact with posts and communities on remote servers.

Caching can be streamlined by the addition of cache control headers in HTTP responses.

Servers SHOULD add cache control headers to their responses and MAY respect cache control headers that they receive.

A summary of cache control headers can be found here.

Implementations SHOULD (as much as possible) be RFC compliant. However this specification outlines a very restricted subset of this RFC that groups can implement without needing a library.

HTTP Server

Add Cache-Control: max-age=<seconds> to HTTP responses, where <seconds> is how long the client should cache the resourse for.

To prevent a resource bein cached, set <seconds> to 0.

A naive implementation might use a constant value, whereas a smarter implementation might change the value, depending on how likely the resource is to change.

HTTP Client

Cache resources for the number of seconds specified in max-age. After this time, fetch a new copy.

Without a way to verify that a request has originated from who it is claimed to have, anybody may send requests impersonating users (including administrators).

This propsal is based on a simplified version of the HTTP Signatures protocol.

Creating the Digest Header

Add the Digest header to every HTTP request. For simplicity, this is restricted to sha-512.

How do I implement it?

1. sha-512 hash the body of the HTTP request.
2. Base64 encode the output of the hash.
3. Add the header Digest: sha-512=<base64_sha512_hash> to the HTTP request where <base64_sha512_hash> is the value from step 2.

Warning

Some libraries may give the hash output as hex (rather than binary). In such a case, when Base64 encoding, you must convert from hex to Base64, not binary to Base64.

Creating the Signature Header

1. Make the public key available at /fed/key.

   • If your server does not support this security proposal, then the /fed/key endpoint should return a 501 Not Implemented error.
   • The public key should be serialised using the ASN.1 structure SubjectPublicKeyInfo defined in X.509 and encoded using PEM.

2. Construct the following string based on the values from the HTTP request (note that there is a line ending \n on all lines apart from the last):

   (request-target): post /fed/posts
   host: cooldomain.edu:8080
   client-host: anotherdomain.edu:7070
   user-id: johnsmith
   date: Tue, 07 Jun 2021 20:51:35 GMT
   digest: SHA-512=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

   There is a single space after each colon :. The part before the colon must be all lower-case. The part following the colon (after the space) should be taken verbatim from the source (do not change the case). The order of the key/value pairs MUST be the same as above.

   • (request-target) - <HTTP Method> <Request Path> (separated by a single space).
     • <HTTP Method> - GET, POST, PUT or DELETE, made lower-case.
     • <Request Path> e.g. /fed/posts.
   • host - The value from the Host HTTP header.
   • client-host - The value from the Client-Host HTTP header.
   • user-id - The value from the User-ID HTTP header. If the User-ID HTTP header is not included in the request, then this field should be omitted.
   • date - The value from the Date HTTP header.
   • digest - The value from the Digest HTTP header.

3. The string from step 2 should be rsa-sha512 signed using PKCS #1 (you will almost certainly need to use a library to do this).

4. The signature from step 3 should be Base64 encoded. See the previous warning.

5. Send the following header in the HTTP request (only including user-id if required by the request):

   Signature: keyId="rsa-global",algorithm="hs2019",headers="(request-target) host client-host user-id date digest",signature="<base64_signature>"

   All fields are static apart from the final signature field, which is the output from step 4.

You MUST NOT verify requests made to the GET /fed/key endpoint. All other requests MUST be verified.

Verifying the Signature Header

1. Obtain the public key from http://<host>/fed/key, where <host> is the value from the Host HTTP header.
   • If the server returns a 501 error, then it has not implemented this security proposal.
   • You may decide whether to accept the request without verification, or reject it.
   • You can not continue any further with verification (including verification of the Digest header).
2. Generate the string from step 1 of Creating the Signature Header.
3. Obtain the <base64_signature> from the Signature header:

   Signature: keyId="global",algorithm="rsa-sha512",headers="(request-target) host client-host user-id date digest",signature="<base64_signature>"

4. Using the rsa-sha512 algorithm, verify, using the public key from step 1, that <base64_signature> is valid using PKCS #1 (you will almost certainly need to use a library to do this).

Verifying the Digest Header

1. sha-512 hash the body of the HTTP request.
2. Base64 encode the output of the hash.
3. Verify that the output from step 2 matches the <base64_sha512_hash> value from the Digest header: Digest: sha-512=<base64_sha512_hash>.

Python

Uses the crytography library.

Exporting a Public Key

from cryptography.hazmat.primitives import serialization

with open("private.pem", "rb") as key_file:
   private_key = serialization.load_pem_private_key(
      key_file.read(),
      password=None,
   )

public_key = private_key.public_key()
pem = public_key.public_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PublicFormat.SubjectPublicKeyInfo
)

print(pem.decode("utf-8"))

Generating a Digest

import base64
from cryptography.hazmat.primitives import hashes

digest = hashes.Hash(hashes.SHA512())
digest.update(b"A message")

base64encoded = base64.b64encode(digest.finalize())

print(base64encoded.decode("ascii"))

Signing a String

import base64
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding

with open("private.pem", "rb") as key_file:
   private_key = serialization.load_pem_private_key(
      key_file.read(),
      password=None,
   )

message = b"A message I want to sign"
signature = private_key.sign(
    message,
    padding.PKCS1v15(),
    hashes.SHA512()
)

print(base64.b64encode(signature).decode("ascii"))

Verifying a Signature

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding

# You should get the public key from `/fed/key`.
with open("public.pem", "rb") as key_file:
    public_key = serialization.load_pem_public_key(key_file.read())

# Get the signature from the HTTP header.
encoded_signature = "ij3WqCSE+289DW4KV3Rh//4mZ1dev5I7m6rUrYyvcojmPBhuVzqxJ0XLoWPKtGz6aVYi4k+Ide1zTGUIAOWQEwCiT4WP/GrsYukwgAfgS9q80YgiKIyqVBvc953XLVzgnOT+8X2HQ/LTg+BwP23kLeEXPabxhMN323L+gVWVyoiIUYEf0B34PbPq/KTPqW/rHtup6ovSRfvy8Bqeqmtpmc0gJwR7WnKRYEiVn40yRQDxtO6zSjvmObv5U2BKCjprnOAp5yfKzROkpfqui1yjKMp5RfA+NILGiJSSQwgGe1eG0QOWYoW8JecLOrxBHOJMuFc0wDQ0k9cip/nAc/T5Cw=="

decoded_signature = base64.b64decode(encoded_signature)

# If this throws an InvalidSignature exception, then the signature
# was invalid.
public_key.verify(
    decoded_signature,
    message,
    padding.PKCS1v15(),
    hashes.SHA512()
)

Node

Exporting a Public Key

const crypto = require("crypto");
const fs = require("fs");

const publicKey = crypto.createPublicKey({
  key: fs.readFileSync("private.pem"),
  format: "pem"
});

const encodedPublicKey = publicKey.export({
  type: "spki",
  format: "pem"
});

console.log(encodedPublicKey);

Generating a Digest

const crypto = require("crypto");

const hash = crypto.createHash("sha512");
hash.update("A message");

const digest = hash.digest("base64");

console.log(digest);

Signing a String

const crypto = require("crypto");
const fs = require("fs");

const privateKey = crypto.createPrivateKey({
  key: fs.readFileSync("private.pem"),
  format: "pem"
});

const sign = crypto.createSign("SHA512");
sign.write("A message I want to sign");
sign.end();

const signature = sign.sign(privateKey, "base64");

console.log(signature);

Verifying a Signature

const crypto = require("crypto");
const fs = require("fs");

const publicKey = crypto.createPublicKey({
  key: fs.readFileSync("private.pem"),
  format: "pem"
});

const signature = "ij3WqCSE+289DW4KV3Rh//4mZ1dev5I7m6rUrYyvcojmPBhuVzqxJ0XLoWPKtGz6aVYi4k+Ide1zTGUIAOWQEwCiT4WP/GrsYukwgAfgS9q80YgiKIyqVBvc953XLVzgnOT+8X2HQ/LTg+BwP23kLeEXPabxhMN323L+gVWVyoiIUYEf0B34PbPq/KTPqW/rHtup6ovSRfvy8Bqeqmtpmc0gJwR7WnKRYEiVn40yRQDxtO6zSjvmObv5U2BKCjprnOAp5yfKzROkpfqui1yjKMp5RfA+NILGiJSSQwgGe1eG0QOWYoW8JecLOrxBHOJMuFc0wDQ0k9cip/nAc/T5Cw==";

const verify = crypto.createVerify("SHA512");
verify.write("A message I want to sign");
verify.end();

const result = verify.verify(publicKey, signature, "base64");
console.log(result);

There has been a newly published (November 2020) diverging specification for signing HTTP messages: Signing HTTP Messages. This proposal is based on the predessor specification.

PKCS #1 is used over PSS to simplify implementation.

At the moment, a MITM attack could replace the public key at /fed/key with another. This can be solved either by:

• enforcing HTTPS (perhaps using our own agreed upon certificate authority);
• using a X.509 certificiate instead of a public key, which we use our own authority to sign.