9.6 KiB

Raw Permalink Blame History

slug	authors	status	dateReceived	relatedFeps	trackingIssue	discussionsTo
8b32	silverpill <@silverpill@mitra.social>	DRAFT	2022-11-12	FEP-521a	https://codeberg.org/fediverse/fep/issues/29	https://codeberg.org/fediverse/fep/issues/29

FEP-8b32: Object Integrity Proofs

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.3 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.

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 3.1 DataIntegrityProof. The value of proofPurpose attribute MUST be assertionMethod.

The value of the verificationMethod attribute of the proof can be an URL of a public key or a DID. The controller document where verification method is expressed MUST be an actor object or another document that can be provably associated with an ActivityPub actor (e.g. a DID document).

Proof verification

Recipients of an object SHOULD perform proof verification if it contains integrity proofs. Verification process MUST follow the Data Integrity specification, section 4.5 Verify Proof. It starts with the removal of the proof value from the JSON object. Then verification method is retrieved from the controller document as described in section 4.7 Retrieve Verification Method. 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 are expected to pursue broad interoperability when choosing algorithms for integrity proofs.

eddsa-jcs-2022 cryptosuite is RECOMMENDED:

Canonicalization: JCS
Hashing: SHA-256
Signatures: EdDSA

WARNING: eddsa-jcs-2022 cryptosuite specification is not stable and may change before it becomes a W3C Recommendation. In particular, the processing of nested objects is not well defined.

Backward compatibility

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

If compatiblity with legacy systems is desired, the integrity proof MUST be created and inserted before the generation of the linked data signature.

If both proof and signature are present in a received object, the linked data signature MUST be removed before the verification of the integrity proof.

Special cases

Activities

The controller of the verification method MUST match the actor of activity, or be associated with that actor.

Nested objects

Nested objects containing integrity proofs that use JCS canonicalization algorithm might not be compatible with JSON-LD processors. To avoid verification errors, implementers MAY re-define properties such as object as having @json type when signing objects containing other signed objects.

WARNING: eddsa-jcs-2022 cryptosuite specification is not stable and recommendations for nested objects may change before it becomes a W3C Recommendation.

Examples

Signed object

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

Signed 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",
    "attributedTo": "https://server.example/users/alice",
    "content": "Hello world"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "https://server.example/users/alice#ed25519-key",
    "proofPurpose": "assertionMethod",
    "proofValue": "...",
    "created": "2023-02-24T23:36:38Z"
  }
}

Signed activity with embedded signed object

WARNING: recommendations for nested objects may change in the future, see Nested objects section.

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

Test vectors

See fep-8b32.feature

Implementations

Mitra
Vervis (generation, verification)
Streams
Hubzilla

References

Christine Lemmer Webber, Jessica Tallon, ActivityPub, 2018
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, 1997
Dave Longley, Manu Sporny, Verifiable Credential Data Integrity 1.0, 2023
Manu Sporny, Dave Longley, Markus Sabadell, Drummond Reed, Orie Steele, Christopher Allen, Decentralized Identifiers (DIDs) v1.0, 2022
Dave Longley, Manu Sporny, Data Integrity EdDSA Cryptosuites v1.0, 2023
A. Rundgren, B. Jordan, S. Erdtman, JSON Canonicalization Scheme (JCS), 2020

Copyright

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.

9.6 KiB Raw Permalink Blame History