Skip to content

FEP-8b32: Object Integrity Proofs

by silverpill silverpill@firemail.cc submited on 2022-11-12

Summary

This proposal describes how ActivityPub servers and clients could create self-authenticating activities and objects.

HTTP signatures are often used for authentication during server-to-server interactions. However, this ties authentication to activity delivery, and limits the flexibility of the protocol.

Integrity proofs are sets of attributes that represent digital signatures and parameters required to verify them. These proofs can be added to any activity or object, allowing recipients to verify the identity of the actor and integrity of the data. That decouples authentication from the transport, and enables various protocol improvements such as activity relaying, embedded objects and client-side signing.

History

Mastodon supports Linked Data signatures since 2017, and a number of other platforms added support for them later. These signatures are similar to integrity proofs, but are based on outdated Linked Data Signatures 1.0 specification, which has been superseded by other standards.

Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Integrity proofs

The proposed authentication mechanism is based on Data Integrity specification.

Proof generation

The proof MUST be created according to the Data Integrity specification, section 4.1 Add Proof.

The process of proof generation consists of the following steps:

  • Canonicalization is a transformation of a JSON object into the form suitable for hashing, according to some deterministic algorithm.
  • Hashing is a process that calculates an identifier for the transformed data using a cryptographic hash function.
  • Signature generation is a process that calculates a value that protects the integrity of the input data from modification.

The resulting proof is added to the original JSON object under the key proof. Objects MAY contain multiple proofs.

Example of unsigned activity:

{
    "@context": [
        "https://www.w3.org/ns/activitystreams",
        "https://w3id.org/security/data-integrity/v1"
    ],
    "type": "Create",
    "actor": "https://server.example/users/alice",
    "object": {
        "type": "Note",
        "content": "Hello world"
    }
}

Example of activity with integrity proof:

{
    "@context": [
        "https://www.w3.org/ns/activitystreams",
        "https://w3id.org/security/data-integrity/v1"
    ],
    "type": "Create",
    "actor": "https://server.example/users/alice",
    "object": {
        "type": "Note",
        "content": "Hello world"
    },
    "proof": {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-jcs-2022",
        "verificationMethod": "https://server.example/users/alice#ed25519-key",
        "proofPurpose": "assertionMethod",
        "proofValue": "z3sXaxjKs4M3BRicwWA9peyNPJvJqxtGsDmpt1jjoHCjgeUf71TRFz56osPSfDErszyLp5Ks1EhYSgpDaNM977Rg2",
        "created": "2023-02-24T23:36:38Z"
    }
}

The list of attributes used in integrity proof is defined in Data Integrity specification, section 2.1 Proofs. The proof type SHOULD be DataIntegrityProof, as specified in section 1.3.1 DataIntegrityProof. The value of verificationMethod attribute SHOULD be an URL of actor’s public key or a DID associated with an actor. The value of proofPurpose attribute MUST be assertionMethod.

Proof verification

The recipient of activity SHOULD perform proof verification if it contains integrity proofs. Verification process MUST follow the Data Integrity specification, section 4.3 Verify Proof. It starts with the removal of a proof value from the JSON object. Then the object is canonicalized, hashed and signature verification is performed according to the parameters specified in the proof.

If both HTTP signature and integrity proof are used, the integrity proof MUST be given precedence over HTTP signature. The HTTP signature MAY be dismissed.

Algorithms

Implementers SHOULD pursue broad interoperability when choosing algorithms for integrity proofs.

eddsa-jcs-2022 cryptosuite is RECOMMENDED:

  • Canonicalization: JCS
  • Hashing: SHA-256
  • Signatures: EdDSA

Support for RSASSA-PKCS1-v1_5 signature algorithm is OPTIONAL but could be desirable for interoperability with legacy systems.

Backwards compatibility

Integrity proofs and Linked Data signatures can be used together, as they rely on different properties (proof and signature, respectively).

Test vectors

See fep-8b32.feature

Implementations

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.