commit: 9c5435a1eafc7f244fd53084e7bc460d66d05b2d
parent 069c033dc8079124ef94b363e8659be95eef2b33
Author: Haelwenn (lanodan) Monnier <contact@hacktivis.me>
Date: Wed, 25 Nov 2020 04:55:48 +0100
overview: Migrate to SHTML
Diffstat:
| D | overview.md | 114 | ------------------------------------------------------------------------------- |
| A | overview.shtml | 101 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 101 insertions(+), 114 deletions(-)
diff --git a/overview.md b/overview.md
@@ -1,114 +0,0 @@
----
-title: "LitePub top-level overview"
----
-
-LitePub is a family of similar server-to-server protocols which each constitute a profile
-of [ActivityPub][ap]. They have been stripped down and are intended to be lightweight
-with easily understood security properties.
-
- [ap]: https://www.w3.org/TR/activitypub/
-
-Information about differences between LitePub and ActivityPub can be found in the
-[LitePub for ActivityPub implementors][ap-compat] document.
-
- [ap-compat]: ap-compat.html
-
-
-## Overview
-
-In LitePub, operations are modelled as interactions between `actors`. An actor could be,
-amongst other things, an user account, a bot, or a service. LitePub implementations
-process messages which are delivered to `inboxes` and apply side effects based on the
-interpretation of those messages. The exact behavior an implementation may take when
-presented with a message is implementation-defined.
-
-
-### Message delivery
-
-Messages are addressed to either `actors` or `collections`. Every `actor` MUST have an
-`inbox` property and MAY have a `sharedInbox` property. If an `actor` has a `sharedInbox`
-property, then an implementation MAY choose to deliver the message to the `sharedInbox`
-instead of directly to the actor's inbox.
-
-Handling of `collections` SHOULD be treated as aliases for a group of known `actors`.
-Implementations MUST NOT attempt delivery directly to a `collection`.
-
-Delivered messages MUST be signed and then delivered to `inboxes`. The receiving server
-MUST authenticate the message following the rules below in the [Message authentication][auth]
-section.
-
- [auth]: #message-authentication
-
-
-### Message authentication
-
-LitePub messages are authenticated using a construction based on [HTTP Signatures][httpsigs].
-The `date` and `digest` headers MUST be signed, additional headers MAY be signed.
-
- [httpsigs]: https://tools.ietf.org/html/draft-cavage-http-signatures-10
-
-
-#### The `digest` header
-
-LitePub messages MUST have a `digest` header of the following construction:
-
- * The hash method used
- * An equals sign (`=`)
- * The checksum from the hash method used in [base64 encoding][base64].
-
-At a minimum, the SHA2-256 hash method MUST be used, using the identifier `SHA-256`.
-Implementations MAY send other digests by separating them with a space and using the
-same construction.
-
-To generate the digest, the binary message body is hashed using the selected hash method.
-Implementations MUST verify that the signed digest header matches the received message
-body.
-
-An example digest header:
-
-```
-Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
-```
-
-An example digest header with multiple digests:
-
-```
-Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
- SHA-512=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
-```
-
- [base64]: https://tools.ietf.org/html/rfc4648
-
-
-### Message transience
-
-*This section is non-normative.*
-
-An important property of LitePub verses ActivityPub is that messages are intended to be
-transient, when message handling is properly implemented in this way, significant security
-advantages over the original ActivityPub approach are achieved, such as message deniability.
-
-In respect to the LitePub specification process, this means that care has been taken to
-minimize the leakage of both message contents and data which can be used to forensically
-authenticate those messages.
-
-It should be considered a significant violation of this specification to handle messages
-in a way that could result in the leakage of message contents or signature data to third
-parties. However, strict adherence to the LitePub core protocol should result in an
-implementation which handles messages in a secure manner.
-
-
-### Inclusion of objects by reference
-
-*This section is non-normative.*
-
-Another important property of LitePub verses ActivityPub is that message data integrity
-is controlled by the server which publishes the original message. Accordingly, all
-message which reference another message MUST do so using the message's `id`. The `id`
-of the message may be treated as a *reference*, as in JSON-LD.
-
-When a message is deleted, the URI associated with the message `id` MUST NOT respond
-and SHOULD respond with an HTTP 404 or equivalent error code. This does two things:
-
- * prevents further dissemination of the message through the federated graph
- * provides plausible deniability about the existence of a message (spoofing argument)
diff --git a/overview.shtml b/overview.shtml
@@ -0,0 +1,101 @@
+<!--#set var="title" value='LitePub Overview'--><!--#include file="templates/header.shtml" -->
+<p>
+LitePub is a family of similar server-to-server protocols which each constitute a profile of <a href="https://www.w3.org/TR/activitypub/">ActivityPub</a>. They have been stripped down and are intended to be lightweight with easily understood security properties.
+</p>
+
+<p>
+Information about differences between LitePub and ActivityPub can be found in the <a href="/ap-compat">LitePub for ActivityPub implementors</a> document.
+</p>
+
+<h2 id="overview">Overview</h2>
+<p>
+In LitePub, operations are modelled as interactions between <code>Actor</code>s. An actor could be,
+amongst other things, an user account, a bot, or a service. LitePub implementations
+process messages which are delivered to <code>inbox</code>es and apply side effects based on the
+interpretation of those messages. The exact behavior an implementation may take when
+presented with a message is implementation-defined.
+</p>
+
+<h3 id="message-delivery">Message delivery</h3>
+<p>
+Messages are addressed to either <code>actor</code>s or <code>collection</code>. Every <code>actor</code> MUST have an
+<code>inbox</code> property and MAY have a <code>sharedInbox</code> property. If an <code>actor</code> has a <code>sharedInbox</code>
+property, then an implementation MAY choose to deliver the message to the <code>sharedInbox</code>
+instead of directly to the actor's inbox.
+</p>
+<p>
+Handling of <code>collection</code>s SHOULD be treated as aliases for a group of known <code>actors</code>.
+Implementations MUST NOT attempt delivery directly to a <code>collection</code>.
+</p>
+<p>
+Delivered messages MUST be signed and then delivered to <code>inbox</code>es. The receiving server
+MUST authenticate the message following the rules below in the <a href="#message-authentication">Message authentication</a>
+section.
+</p>
+
+<h3 id="message-authentication">Message authentication</h3>
+<p>
+LitePub messages are authenticated using a construction based on <a href="https://tools.ietf.org/html/draft-cavage-http-signatures-10">HTTP Signatures</a>.
+The <code>date</code> and <code>digest</code> headers MUST be signed, additional headers MAY be signed.
+<!-- TODO: See what pleroma requires nowadays -->
+</p>
+
+<h4>The <code>digest</code> header</h4>
+<p>
+LitePub messages MUST have a <code>digest</code> header of the following construction:
+<ul>
+ <li>The hash method used</li>
+ <li>An equals sign (<code>=</code>)</li>
+ <li>The checksum from the hash method used in <a href="https://tools.ietf.org/html/rfc4648">base64 encoding</a>.</li>
+</ul>
+</p>
+<p>At a minimum, the SHA2-256 hash method MUST be used, using the identifier <code>SHA-256</code>. Implementations MAY send other digests by separating them with a space and using the same construction.</p>
+<p>To generate the digest, the binary message body is hashed using the selected hash method. Implementations MUST verify that the signed digest header matches the received message body.</p>
+<p>An example digest header:
+<pre><code>
+Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+</code></pre>
+</p>
+<p>An example digest header with multiple digests:
+<pre><code>
+Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+ SHA-512=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+</code></pre>
+</p>
+
+<h3>Message transience</h3>
+<p class="note">This section is non-normative.</p>
+<p>
+An important property of LitePub verses ActivityPub is that messages are intended to be
+transient, when message handling is properly implemented in this way, significant security
+advantages over the original ActivityPub approach are achieved, such as message deniability.
+</p>
+<p>
+In respect to the LitePub specification process, this means that care has been taken to
+minimize the leakage of both message contents and data which can be used to forensically
+authenticate those messages.
+</p>
+<p>
+It should be considered a significant violation of this specification to handle messages
+in a way that could result in the leakage of message contents or signature data to third
+parties. However, strict adherence to the LitePub core protocol should result in an
+implementation which handles messages in a secure manner.
+</p>
+
+<h3>Inclusion of objects by reference</h3>
+<p class="note">This section is non-normative.</p>
+<p>
+Another important property of LitePub verses ActivityPub is that message data integrity
+is controlled by the server which publishes the original message. Accordingly, all
+message which reference another message MUST do so using the message's <code>id</code>. The <code>id</code>
+of the message may be treated as a <em>reference</em>, as in JSON-LD.
+</p>
+<p>
+When a message is deleted, the URI associated with the message <code>id</code> MUST NOT respond
+and SHOULD respond with an HTTP 404 or equivalent error code. This does two things:
+<ul>
+ <li>prevents further dissemination of the message through the federated graph</li>
+ <li>provides plausible deniability about the existence of a message (spoofing argument)</li>
+</ul>
+</p>
+<!--#include file="templates/footer.shtml" -->
