Loading CHANGES.md +5 −0 Original line number Diff line number Diff line Loading @@ -11,6 +11,11 @@ To be released. - Fedify now supports [Linked Data Signatures], which is outdated but still widely used in the fediverse. - A `Federation` object became to verify an activity's Linked Data Signatures if it has one. If Linked Data Signatures are verified, Object Integrity Proofs and HTTP Signatures are not verified. - `Context.sendActivity()` method became to sign an activity with Linked Data Signatures if there is at least one RSA-PKCS#1-v1.5 key pair. - Added `Signature` interface. - Added `signJsonLd()` function. - Added `SignJsonLdOptions` interface. Loading FEDERATION.md +2 −0 Original line number Diff line number Diff line Loading @@ -9,11 +9,13 @@ Supported federation protocols and standards - [ActivityPub] (S2S) - [WebFinger] - [HTTP Signatures] - [Linked Data Signatures] - [NodeInfo] [ActivityPub]: https://www.w3.org/TR/activitypub/ [WebFinger]: https://datatracker.ietf.org/doc/html/rfc7033 [HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures [Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/ [NodeInfo]: https://nodeinfo.diaspora.software/ Loading docs/manual/actor.md +10 −10 Original line number Diff line number Diff line Loading @@ -245,18 +245,20 @@ await kv.set(["keypair", "ed25519", handle], { > Fedify currently supports two key types: > > - RSA-PKCS#1-v1.5 (`"RSASSA-PKCS1-v1_5"`) is used for [HTTP > Signatures](./send.md#http-signatures). > Signatures](./send.md#http-signatures) and [Linked Data > Signatures](./send.md#linked-data-signatures). > - Ed25519 (`"Ed25519"`) is used for [Object Integrity > Proofs](./send.md#object-integrity-proofs). > > HTTP Signatures is a de facto standard for signing ActivityPub activities, > and Object Integrity Proofs is a new standard for verifying the integrity > of the objects in the fediverse. While HTTP Signatures is widely supported > in the fediverse, it's limited to the RSA-PKCS#1-v1.5 algorithm, > and unusable for [forwarding from inbox][1] and [several other cases][2]. > HTTP Signatures and Linked Data Signatures are de facto standards for signing > ActivityPub activities, and Object Integrity Proofs is a new standard for > verifying the integrity of the objects in the fediverse. While HTTP > Signatures and Linked Data Signatures are widely supported in the fediverse, > it's limited to the RSA-PKCS#1-v1.5 algorithm. > > If your federated app needs to support both HTTP Signatures and Object > Integrity Proofs, you need to generate both RSA-PKCS#1-v1.5 and Ed25519 key > If your federated app needs to support HTTP Signatures, Linked Data > Signatures, and Object Integrity Proofs at the same time, > you need to generate both RSA-PKCS#1-v1.5 and Ed25519 key > pairs for each actor, and store them in the database—and we recommend > you to support both key types. Loading Loading @@ -299,8 +301,6 @@ federation }); ~~~~ [1]: https://www.w3.org/TR/activitypub/#inbox-forwarding [2]: https://socialhub.activitypub.rocks/t/fep-8b32-object-integrity-proofs/2725/79?u=hongminhee [`CryptoKeyPair`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair [Deno KV]: https://deno.com/kv Loading docs/manual/log.md +21 −3 Original line number Diff line number Diff line Loading @@ -174,14 +174,32 @@ related to the document loader. When you are curious about what specific requests are made by the document loader, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "http"]` *This category is available since Fedify 0.9.0.* The `["fedify", "sig", "ld"]` category is used for logging messages related to [HTTP Signatures](./send.md#http-signatures). When you are curious about the signature verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "ld"]` *This category is available since Fedify 1.0.0.* The `["fedify", "sig", "ld"]` category is used for logging messages related to [Linked Data Signatures](./send.md#linked-data-signatures). When you are curious about the signature verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "proof"]` *This category is available since Fedify 0.10.0.* The `["fedify", "sig", "proof"]` category is used for logging messages related to Object Integrity Proofs. When you are curious about the proof verification process, you can check the log messages in this category with the `"debug"` level. to [Object Integrity Proofs](./send.md#object-integrity-proofs). When you are curious about the proof verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "key"]` Loading docs/manual/send.md +60 −13 Original line number Diff line number Diff line Loading @@ -318,6 +318,52 @@ Fedify selects the first RSA-PKCS#1-v1.5 key pair among them. [HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures Linked Data Signatures ---------------------- *This API is available since Fedify 1.0.0.* [Linked Data Signatures] is a more advanced and widely used, but *obsolete*, mechanism for signing portable ActivityPub activities. As of September 2024, major ActivityPub implementations, such as Mastodon, et al., still rely on Linked Data Signatures for signing portable activities, despite they declare that Linked Data Signatures is outdated. It shares the similar concept with [HTTP Signatures](#http-signatures), but unlike HTTP Signatures, it can be used for signing portable activities. For example, it can be used for [forwarding from inbox] and several other cases that HTTP Signatures cannot handle. Fedify automatically includes the Linked Data Signature of activities by signing them with the sender's private key if the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and the actor has any RSA-PKCS#1-v1.5 key pair. If there are multiple key pairs, Fedify uses the first RSA-PKCS#1-v1.5 key pair among them. > [!TIP] > The combination of HTTP Signatures and Linked Data Signatures is the most > widely supported way to sign activities in the fediverse, as of September > 2024. Despite Linked Data Signatures is outdated and not recommended for > new implementations, it is still widely used in the fediverse due to Mastodon > and other major implementations' reliance on it. > > However, for new implementations, you should consider using *both* [Object > Integrity Proofs](#object-integrity-proofs) and Linked Data Signatures > for maximum compatibility and future-proofing. Fortunately, Fedify supports > both Object Integrity Proofs and Linked Data Signatures simultaneously, > in addition to HTTP Signatures. > [!NOTE] > If an activity is signed with both HTTP Signatures and Linked Data Signatures, > the recipient verifies the Linked Data Signatures first when it is supported, > and ignores the HTTP Signatures if the Linked Data Signatures are valid. > If the recipient does not support Linked Data Signatures, it falls back to > verifying the HTTP Signatures. [Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/ [forwarding from inbox]: https://www.w3.org/TR/activitypub/#inbox-forwarding Object Integrity Proofs ----------------------- Loading @@ -325,10 +371,9 @@ Object Integrity Proofs [Object Integrity Proofs][FEP-8b32] is a mechanism to ensure the integrity of ActivityPub objects (not only activities!) in the fediverse. It shares the similar concept with [HTTP Signatures](#http-signatures), but it has more functionalities and is more flexible. For example, it can be used for [forwarding from inbox] and [several other cases] that HTTP Signatures cannot handle. However, as it is relatively new, it is not widely supported yet. the similar concept with [Linked Data Signatures](#linked-data-signatures), but it has more functionalities and is more flexible. However, as it is relatively new, it is not widely supported yet. Fedify automatically includes the integrity proof of activities by signing them with the sender's private key if the [actor keys dispatcher is Loading @@ -337,17 +382,19 @@ If there are multiple key pairs, Fedify creates the number of integrity proofs equal to the number of Ed25519 key pairs. > [!TIP] > HTTPS Signatures and Object Integrity Proofs can coexist in an application. > If an activity is signed with HTTP Signatures and Object Integrity Proofs, > the recipient verifies the Object Integrity Proofs first when it is supported, > and ignores the HTTP Signatures if the Object Integrity Proofs are valid. > HTTPS Signatures, Linked Data Signatures, and Object Integrity Proofs can > coexist in an application and be used together for maximum compatibility. > > If an activity is signed with HTTP Signatures, Linked Data Signatures, > and Object Integrity Proofs, the recipient verifies the Object Integrity > Proofs first when it is supported, and ignores the HTTP Signatures and > Linked Data Signatures if the Object Integrity Proofs are valid. > If the recipient does not support Object Integrity Proofs, it falls back to > verifying the HTTP Signatures. > verifying the HTTP Signatures and Linked Data Signatures. > > To support both HTTP Signatures and Object Integrity Proofs, you need to > generate both RSA-PKCS#1-v1.5 and Ed25519 key pairs for each actor, and > store them in the database. > To support HTTP Signatures, Linked Data Signatures, and Object Integrity > Proofs simultaneously, you need to generate both RSA-PKCS#1-v1.5 and Ed25519 > key pairs for each actor, and store them in the database. [FEP-8b32]: https://w3id.org/fep/8b32 [forwarding from inbox]: https://www.w3.org/TR/activitypub/#inbox-forwarding [several other cases]: https://socialhub.activitypub.rocks/t/fep-8b32-object-integrity-proofs/2725/79?u=hongminhee Loading
CHANGES.md +5 −0 Original line number Diff line number Diff line Loading @@ -11,6 +11,11 @@ To be released. - Fedify now supports [Linked Data Signatures], which is outdated but still widely used in the fediverse. - A `Federation` object became to verify an activity's Linked Data Signatures if it has one. If Linked Data Signatures are verified, Object Integrity Proofs and HTTP Signatures are not verified. - `Context.sendActivity()` method became to sign an activity with Linked Data Signatures if there is at least one RSA-PKCS#1-v1.5 key pair. - Added `Signature` interface. - Added `signJsonLd()` function. - Added `SignJsonLdOptions` interface. Loading
FEDERATION.md +2 −0 Original line number Diff line number Diff line Loading @@ -9,11 +9,13 @@ Supported federation protocols and standards - [ActivityPub] (S2S) - [WebFinger] - [HTTP Signatures] - [Linked Data Signatures] - [NodeInfo] [ActivityPub]: https://www.w3.org/TR/activitypub/ [WebFinger]: https://datatracker.ietf.org/doc/html/rfc7033 [HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures [Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/ [NodeInfo]: https://nodeinfo.diaspora.software/ Loading
docs/manual/actor.md +10 −10 Original line number Diff line number Diff line Loading @@ -245,18 +245,20 @@ await kv.set(["keypair", "ed25519", handle], { > Fedify currently supports two key types: > > - RSA-PKCS#1-v1.5 (`"RSASSA-PKCS1-v1_5"`) is used for [HTTP > Signatures](./send.md#http-signatures). > Signatures](./send.md#http-signatures) and [Linked Data > Signatures](./send.md#linked-data-signatures). > - Ed25519 (`"Ed25519"`) is used for [Object Integrity > Proofs](./send.md#object-integrity-proofs). > > HTTP Signatures is a de facto standard for signing ActivityPub activities, > and Object Integrity Proofs is a new standard for verifying the integrity > of the objects in the fediverse. While HTTP Signatures is widely supported > in the fediverse, it's limited to the RSA-PKCS#1-v1.5 algorithm, > and unusable for [forwarding from inbox][1] and [several other cases][2]. > HTTP Signatures and Linked Data Signatures are de facto standards for signing > ActivityPub activities, and Object Integrity Proofs is a new standard for > verifying the integrity of the objects in the fediverse. While HTTP > Signatures and Linked Data Signatures are widely supported in the fediverse, > it's limited to the RSA-PKCS#1-v1.5 algorithm. > > If your federated app needs to support both HTTP Signatures and Object > Integrity Proofs, you need to generate both RSA-PKCS#1-v1.5 and Ed25519 key > If your federated app needs to support HTTP Signatures, Linked Data > Signatures, and Object Integrity Proofs at the same time, > you need to generate both RSA-PKCS#1-v1.5 and Ed25519 key > pairs for each actor, and store them in the database—and we recommend > you to support both key types. Loading Loading @@ -299,8 +301,6 @@ federation }); ~~~~ [1]: https://www.w3.org/TR/activitypub/#inbox-forwarding [2]: https://socialhub.activitypub.rocks/t/fep-8b32-object-integrity-proofs/2725/79?u=hongminhee [`CryptoKeyPair`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair [Deno KV]: https://deno.com/kv Loading
docs/manual/log.md +21 −3 Original line number Diff line number Diff line Loading @@ -174,14 +174,32 @@ related to the document loader. When you are curious about what specific requests are made by the document loader, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "http"]` *This category is available since Fedify 0.9.0.* The `["fedify", "sig", "ld"]` category is used for logging messages related to [HTTP Signatures](./send.md#http-signatures). When you are curious about the signature verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "ld"]` *This category is available since Fedify 1.0.0.* The `["fedify", "sig", "ld"]` category is used for logging messages related to [Linked Data Signatures](./send.md#linked-data-signatures). When you are curious about the signature verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "proof"]` *This category is available since Fedify 0.10.0.* The `["fedify", "sig", "proof"]` category is used for logging messages related to Object Integrity Proofs. When you are curious about the proof verification process, you can check the log messages in this category with the `"debug"` level. to [Object Integrity Proofs](./send.md#object-integrity-proofs). When you are curious about the proof verification process, you can check the log messages in this category with the `"debug"` level. ### `["fedify", "sig", "key"]` Loading
docs/manual/send.md +60 −13 Original line number Diff line number Diff line Loading @@ -318,6 +318,52 @@ Fedify selects the first RSA-PKCS#1-v1.5 key pair among them. [HTTP Signatures]: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures Linked Data Signatures ---------------------- *This API is available since Fedify 1.0.0.* [Linked Data Signatures] is a more advanced and widely used, but *obsolete*, mechanism for signing portable ActivityPub activities. As of September 2024, major ActivityPub implementations, such as Mastodon, et al., still rely on Linked Data Signatures for signing portable activities, despite they declare that Linked Data Signatures is outdated. It shares the similar concept with [HTTP Signatures](#http-signatures), but unlike HTTP Signatures, it can be used for signing portable activities. For example, it can be used for [forwarding from inbox] and several other cases that HTTP Signatures cannot handle. Fedify automatically includes the Linked Data Signature of activities by signing them with the sender's private key if the [actor keys dispatcher is set](./actor.md#public-keys-of-an-actor) and the actor has any RSA-PKCS#1-v1.5 key pair. If there are multiple key pairs, Fedify uses the first RSA-PKCS#1-v1.5 key pair among them. > [!TIP] > The combination of HTTP Signatures and Linked Data Signatures is the most > widely supported way to sign activities in the fediverse, as of September > 2024. Despite Linked Data Signatures is outdated and not recommended for > new implementations, it is still widely used in the fediverse due to Mastodon > and other major implementations' reliance on it. > > However, for new implementations, you should consider using *both* [Object > Integrity Proofs](#object-integrity-proofs) and Linked Data Signatures > for maximum compatibility and future-proofing. Fortunately, Fedify supports > both Object Integrity Proofs and Linked Data Signatures simultaneously, > in addition to HTTP Signatures. > [!NOTE] > If an activity is signed with both HTTP Signatures and Linked Data Signatures, > the recipient verifies the Linked Data Signatures first when it is supported, > and ignores the HTTP Signatures if the Linked Data Signatures are valid. > If the recipient does not support Linked Data Signatures, it falls back to > verifying the HTTP Signatures. [Linked Data Signatures]: https://web.archive.org/web/20170923124140/https://w3c-dvcg.github.io/ld-signatures/ [forwarding from inbox]: https://www.w3.org/TR/activitypub/#inbox-forwarding Object Integrity Proofs ----------------------- Loading @@ -325,10 +371,9 @@ Object Integrity Proofs [Object Integrity Proofs][FEP-8b32] is a mechanism to ensure the integrity of ActivityPub objects (not only activities!) in the fediverse. It shares the similar concept with [HTTP Signatures](#http-signatures), but it has more functionalities and is more flexible. For example, it can be used for [forwarding from inbox] and [several other cases] that HTTP Signatures cannot handle. However, as it is relatively new, it is not widely supported yet. the similar concept with [Linked Data Signatures](#linked-data-signatures), but it has more functionalities and is more flexible. However, as it is relatively new, it is not widely supported yet. Fedify automatically includes the integrity proof of activities by signing them with the sender's private key if the [actor keys dispatcher is Loading @@ -337,17 +382,19 @@ If there are multiple key pairs, Fedify creates the number of integrity proofs equal to the number of Ed25519 key pairs. > [!TIP] > HTTPS Signatures and Object Integrity Proofs can coexist in an application. > If an activity is signed with HTTP Signatures and Object Integrity Proofs, > the recipient verifies the Object Integrity Proofs first when it is supported, > and ignores the HTTP Signatures if the Object Integrity Proofs are valid. > HTTPS Signatures, Linked Data Signatures, and Object Integrity Proofs can > coexist in an application and be used together for maximum compatibility. > > If an activity is signed with HTTP Signatures, Linked Data Signatures, > and Object Integrity Proofs, the recipient verifies the Object Integrity > Proofs first when it is supported, and ignores the HTTP Signatures and > Linked Data Signatures if the Object Integrity Proofs are valid. > If the recipient does not support Object Integrity Proofs, it falls back to > verifying the HTTP Signatures. > verifying the HTTP Signatures and Linked Data Signatures. > > To support both HTTP Signatures and Object Integrity Proofs, you need to > generate both RSA-PKCS#1-v1.5 and Ed25519 key pairs for each actor, and > store them in the database. > To support HTTP Signatures, Linked Data Signatures, and Object Integrity > Proofs simultaneously, you need to generate both RSA-PKCS#1-v1.5 and Ed25519 > key pairs for each actor, and store them in the database. [FEP-8b32]: https://w3id.org/fep/8b32 [forwarding from inbox]: https://www.w3.org/TR/activitypub/#inbox-forwarding [several other cases]: https://socialhub.activitypub.rocks/t/fep-8b32-object-integrity-proofs/2725/79?u=hongminhee
