Skip to content

FEP-521a: Representing actor's public keys

Authors Status Type Date received Date final Tracking issue Discussions Repository
silverpill @silverpill@mitra.social FINAL implementation 2023-07-08 2025-06-14 #130 Discussions codeberg

Summary

This proposal describes how to represent public keys associated with ActivityPub actors.

Rationale

Historically, Fediverse services used publicKey property to represent actor's public key. Implementations usually allow only one key per actor, therefore a new approach is needed to support use cases where additional keys are required.

Furthermore, publicKey property is considered deprecated and is not present in the latest version of Security Vocabulary.

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.

Multikey

Each public key MUST be represented as an object with Multikey type, as defined in section 2.2.2 Multikey of Controlled Identifiers specification. This object MUST have the following properties:

  • id: the unique global identifier of the public key.
  • type: the value of this property MUST be the string Multikey.
  • controller: the value of this property MUST match actor ID.
  • publicKeyMultibase: a Multibase encoded value of a Multicodec prefix and the public key. Implementations MUST use the base-58-btc alphabet.

Key IDs

Key identifiers MUST be absolute URIs.

Identifiers SHOULD be generated by appending a fragment identifier to the actor ID. That allows consumers to retrieve both actor object and associated keys with a single HTTP request. If actor's keys are identified using fragment identifiers, each key MUST have a unique fragment identifier.

Resolution of a URI containing a fragment identifier is performed using the algorithm specified in section 3.4 Fragment Resolution of Controlled Identifiers specification.

Key types

Implementers can use cryptographic keys of any type for which a Multicodec prefix is registered.

Adding keys to an actor object

Multikey objects are added to the actor object, which is considered a controlled identifier document, as described in Controlled Identifiers specification.

If the key is intended to be used for signing ActivityPub objects, it MUST be added to the assertionMethod array in the actor object.

Other use cases are out of scope of this proposal.

Implementations are discouraged from adding any objects to the assertionMethod array that do not conform to this specification. Implementations encountering non-conformant entries in the assertionMethod array SHOULD ignore them.

An actor MAY have no associated public keys.

Example

{
    "@context": [
        "https://www.w3.org/ns/activitystreams",
        "https://www.w3.org/ns/cid/v1"
    ],
    "type": "Person",
    "id": "https://server.example/users/alice",
    "inbox": "https://server.example/users/alice/inbox",
    "outbox": "https://server.example/users/alice/outbox",
    "assertionMethod": [
        {
            "id": "https://server.example/users/alice#ed25519-key",
            "type": "Multikey",
            "controller": "https://server.example/users/alice",
            "publicKeyMultibase": "z6MkrJVnaZkeFzdQyMZu1cgjg7k1pZZ6pvBQ7XJPt4swbTQ2"
        }
    ]
}

Security considerations

Each actor is expected to have a different secret key.

To prevent side-channel attacks, secret keys need to be stored in binary form. If stored as text, they need to be decoded using a constant-time algorithm.

Warning

Controlled Identifiers specification requires implementers to use the base-58-btc alphabet for multibase-encoded secret keys. This practice is discouraged because available implementations of Base58 decode algorithm may not be constant-time.

Test vectors

See fep-521a.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.