logo

litepub.social

Website of https://litepub.social/ git clone https://hacktivis.me/git/litepub.social.git

lice.md (10720B)


  1. ---
  2. title: "Litepub Capability Enforcement (LiCE)"
  3. ---
  4. # Abstract
  5. Litepub Capability Enforcement (LiCE) is an extension to the [ActivityPub protocol][ap]
  6. which adds support for verifying and enforcing [object capabilities][wikipedia-ocap].
  7. [ap]: https://www.w3.org/TR/activitypub
  8. [wikipedia-ocap]: https://en.wikipedia.org/wiki/Object-capability_model
  9. # Overview
  10. LiCE provides two components that, when combined, define a security model based on the
  11. concept of object capabilities:
  12. * **Proof objects**: Objects which have been created by an *actor* which *controls*
  13. a given resource that delegate permissions related to that resource.
  14. * **Capability URIs**: Well-known or private endpoint URIs which either grant
  15. implicit permissions or return a proof object that permits delegation of permission
  16. to perform a given action.
  17. ## Security Levels
  18. LiCE implementations make use of both components in different ways, depending on the
  19. configured security level:
  20. * `disabled`: proof objects are neither verified nor generated upon request.
  21. * `permissive`: proof objects are not verified, but will be generated upon request.
  22. * `enforcing`: proof objects are verified and are also generated upon request.
  23. ### Why does LiCE have configurable security levels?
  24. *This section is non-normative.*
  25. LiCE has a configurable security level to allow for a transitional period, with the
  26. eventual goal that the entire ActivityPub network eventually adopts LiCE and defaults
  27. to running in an enforcing mode. It is strongly recommended that a "flag day" be set
  28. where all implementations transition to having a default security level of
  29. `enforcing`.
  30. # The `capabilities` Object
  31. Objects that have been security labeled have a new `capabilities` object that specifies
  32. what capabilities are implicitly granted or require specific permissions. Capabilities
  33. with implicit grants are defined using well-known URIs, such as `as:Public`.
  34. A basic object that has been labeled with a `capabilities` object looks like this:
  35. ```
  36. {
  37. "@context": [
  38. "https://www.w3.org/ns/activitystreams",
  39. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  40. ],
  41. "capabilities": {
  42. "reply": "https://example.social/caps/d4c4d96a-36d9-4df5-b9da-4b8c74e02567",
  43. "like": "https://www.w3.org/ns/activitystreams#Public",
  44. "announce": "https://example.social/caps/e379a28e-74ce-ed7a-928c-7c3a4b2158e4"
  45. },
  46. "id": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  47. "type": "Note",
  48. "content": "I'm really excited about the new capabilities feature!",
  49. "attributedTo": "https://example.social/users/bob"
  50. }
  51. ```
  52. In this example, `Like` activities are allowed from the public, `Announce` and
  53. `Create.inReplyTo` activities require explicit authorization in the form of a
  54. proof object.
  55. ## Optional Specifiers
  56. A `capabilities` object at the minimum is an object which contains the names of
  57. capabilities but may also contain additional specifiers in the typical JSON-LD
  58. way:
  59. ```
  60. {
  61. "@context": [
  62. "https://www.w3.org/ns/activitystreams",
  63. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  64. ],
  65. "capabilities": {
  66. "reply": {
  67. "id": "https://www.w3.org/ns/activitystreams#Public",
  68. "expires": "2019-09-15T12:00:00Z"
  69. },
  70. "like": "https://www.w3.org/ns/activitystreams#Public",
  71. "announce": "https://www.w3.org/ns/activitystreams#Public"
  72. },
  73. "id": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  74. "type": "Note",
  75. "content": "I'm really excited about the new capabilities feature!",
  76. "attributedTo": "https://example.social/users/bob"
  77. }
  78. ```
  79. > *TODO*: document a list of possible specifiers here. The `expires` specifier
  80. > is obvious, but there may be other specifiers worth examining.
  81. # Proof Objects
  82. When a URI is used for a capability that is not a well-known URI such as `as:Public`,
  83. then it is assumed to be an *authorization endpoint*. Authorization endpoints
  84. behave similarly to *inboxes* but return either a *proof object* or a rejection object
  85. as a response.
  86. Proof objects MUST:
  87. * be publicly accessible at the URI specified in their `id`
  88. * of type `Accept`
  89. * reference the allowed activity by either embedding it or referencing it by `id`
  90. An example proof object looks like this:
  91. ```
  92. {
  93. "@context": [
  94. "https://www.w3.org/ns/activitystreams",
  95. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  96. ],
  97. "id": "https://example.social/proofs/fa43926a-63e5-4133-9c52-36d5fc6094fa",
  98. "type": "Accept",
  99. "actor": "https://example.social/users/bob",
  100. "object": {
  101. "id": "https://example.social/activities/12945622-9ea5-46f9-9005-41c5a2364f9c",
  102. "type": "Like",
  103. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  104. "actor": "https://example.social/users/alyssa",
  105. "to": [
  106. "https://example.social/users/alyssa/followers",
  107. "https://example.social/users/bob"
  108. ]
  109. }
  110. }
  111. ```
  112. ### Attestation of Properties in the Referent Object
  113. An `attestations` object contains properties and values that must match the
  114. properties and values in the referent object.
  115. In the event that an `attestations` object is included, the `id` property
  116. MUST NOT be present.
  117. When verifying proof objects that contain an `attestations` object, the verifier
  118. MUST ensure that the object being authorized against the proof has the same
  119. properties as present in the proof object. In the event that the proof object's
  120. child fragments and the referent object disagree, the verifier MUST fail the
  121. verification.
  122. An example proof object with an `attestations` object:
  123. ```
  124. {
  125. "@context": [
  126. "https://www.w3.org/ns/activitystreams",
  127. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  128. ],
  129. "id": "https://example.social/proofs/fa43926a-63e5-4133-9c52-36d5fc6094fa",
  130. "type": "Accept",
  131. "actor": "https://example.social/users/bob",
  132. "object": {
  133. "id": "https://example.social/activities/12945622-9ea5-46f9-9005-41c5a2364f9c",
  134. "type": "Like",
  135. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  136. "actor": "https://example.social/users/alyssa",
  137. "to": [
  138. "https://example.social/users/alyssa/followers",
  139. "https://example.social/users/bob"
  140. ]
  141. }
  142. "attestations": {
  143. "type": "Like",
  144. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  145. "to": [
  146. "https://example.social/users/alyssa/followers",
  147. "https://example.social/users/bob"
  148. ]
  149. }
  150. }
  151. ```
  152. ## Invocation
  153. When a proof object is required in order to prove an activity is authorized, it MUST be
  154. attached as the `proof` field, either by embedding the object or referencing it by URI.
  155. This is known as a capability invocation.
  156. An example invocation where the proof object is embedded:
  157. ```
  158. {
  159. "@context": [
  160. "https://www.w3.org/ns/activitystreams",
  161. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  162. ],
  163. "id": "https://example.social/activities/12945622-9ea5-46f9-9005-41c5a2364f9c",
  164. "type": "Like",
  165. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  166. "actor": "https://example.social/users/alyssa",
  167. "to": [
  168. "https://example.social/users/alyssa/followers",
  169. "https://example.social/users/bob"
  170. ],
  171. "proof": {
  172. "id": "https://example.social/proofs/fa43926a-63e5-4133-9c52-36d5fc6094fa",
  173. "type": "Accept",
  174. "actor": "https://example.social/users/bob",
  175. "object": {
  176. "id": "https://example.social/activities/12945622-9ea5-46f9-9005-41c5a2364f9c",
  177. "type": "Like",
  178. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  179. "actor": "https://example.social/users/alyssa",
  180. "to": [
  181. "https://example.social/users/alyssa/followers",
  182. "https://example.social/users/bob"
  183. ]
  184. }
  185. }
  186. }
  187. ```
  188. An example where the proof object is referenced:
  189. ```
  190. {
  191. "@context": [
  192. "https://www.w3.org/ns/activitystreams",
  193. "https://litepub.social/litepub/lice-v0.0.1.jsonld"
  194. ],
  195. "id": "https://example.social/activities/12945622-9ea5-46f9-9005-41c5a2364f9c",
  196. "type": "Like",
  197. "object": "https://example.social/objects/d6cb8429-4d26-40fc-90ef-a100503afb73",
  198. "actor": "https://example.social/users/alyssa",
  199. "to": [
  200. "https://example.social/users/alyssa/followers",
  201. "https://example.social/users/bob"
  202. ],
  203. "proof": "https://example.social/proofs/fa43926a-63e5-4133-9c52-36d5fc6094fa"
  204. }
  205. ```
  206. ## Verification
  207. Proof objects SHOULD be verified before accepting any activity which references one.
  208. The default way to do this is to fetch the proof object at the given URI and verify
  209. that there is a cyclical relationship between the accepted activity and the activity
  210. which references the proof.
  211. An optional way of verifying a proof would be to use [Linked Data Signature][lds].
  212. If it is possible to verify the proof using a cryptographic signature, then refetching
  213. the proof object is not necessary. All implementations MUST support fallback to
  214. fetching the proof object if a valid signature is not present.
  215. [lds]: https://w3c-dvcg.github.io/ld-signatures/
  216. ### Verifying Attestations
  217. *This section is non-normative.*
  218. Implementations MUST check that properties in the `attestations` object match
  219. properties in the referent object. In most cases, this is done by doing a
  220. literal comparison.
  221. When comparing sets (JSON arrays), an implementation SHOULD iterate over the
  222. values in the attested property and verify set membership in the referent
  223. property for every value. As an optimization, an implementation MAY normalize
  224. a copy of both properties and match that the sequence is identical.
  225. # Security Considerations
  226. *This section is non-normative.*
  227. ## Recursive Object Fetching Denial of Service
  228. A malicious proof object could reference itself, either directly or indirectly.
  229. Implementations SHOULD limit the depth to which they fetch referenced activities and
  230. proof objects. A valid activity will never have a recursive loop, so the depth limit
  231. can be very low.
  232. ## Proof Object/Child Object Swapping
  233. A malicious server could swap the authorized object with a newer version that contains
  234. content that was not authorized by the granting server.
  235. Implementations SHOULD include key properties of the child object when generating a
  236. proof object, such as `content`, `name`, `summary` and `attachment`.
  237. ## Fake Direction Spoofing
  238. A malicious server could present a proof object using a third-party domain or third-party
  239. actor.
  240. Implementations SHOULD verify that the proof object is created by the same actor which
  241. created the content being interacted with.
  242. Implementations SHOULD verify that the proof object is at the same domain as the object
  243. being interacted with.