commit: 324a5d2f0cfa8fbaa32a3d7dd7553125ba41666b
parent 19223f02432cc3ac177fe47faafb9e719b02a25c
Author: William Pitcock <nenolod@dereferenced.org>
Date: Thu, 8 Nov 2018 02:06:34 -0600
add overview document
Diffstat:
| M | _config.yml | 6 | ++++++ |
| A | overview.md | 98 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 104 insertions(+), 0 deletions(-)
diff --git a/_config.yml b/_config.yml
@@ -15,3 +15,9 @@ kramdown:
toc_levels: 2..2
layout: default
+
+defaults:
+ -
+ values:
+ layout: "default"
+ title: ""
diff --git a/overview.md b/overview.md
@@ -0,0 +1,98 @@
+---
+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.
