Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there) https://friendi.ca
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

362 lines
13 KiB

10 years ago
  1. This is the Zot! social communications protocol.
  2. Specification revision: 1
  3. 2 October 2011
  4. Mike Macgirvin
  5. This specification is public domain.
  6. Zot is a framework for secure delivery of messages on the web based on
  7. webfinger and encapsulating salmon.
  8. First read the salmon and salmon magic envelope specifications. Zot also
  9. makes use of webfinger and ActivityStreams and several concepts from RFC822
  10. (email). Zot encompasses the zot delivery framework and the zid remote
  11. access protocol.
  12. The current specification revision (1) is frozen until a reference
  13. implementation is available. After that, any protocol changes will require a
  14. change to the revision number.
  15. ****************
  16. * Zot delivery *
  17. ****************
  18. Format of a zot wrapper. This completely encapsulates a salmon magic envelope
  19. and provides privacy protection, while defining a delivery envelope - a
  20. concept familiar to email systems. All addresses in zot are webfinger
  21. resolvable addresses containing zot endpoints and salmon public keys (zot
  22. is a superset of salmon).
  23. <?xml version='1.0' encoding='UTF-8'?>
  24. <zot:msg xmlns:zot='http://purl.org/zot/1.0'>
  25. <zot:key>((key))</zot:key>
  26. <zot:iv>((iv))</zot:iv>
  27. <zot:env_key>((env_key))</zot:env_key>
  28. <zot:env_iv>((env_iv))</zot:env_iv>
  29. <zot:env>((envelope))</zot:env>
  30. <zot:sig key_id="xxx">((sender signature))</zot:sig>
  31. <zot:alg>AES-256-CBC</zot:alg>
  32. <zot:data type='application/magic-envelope+xml'>((salmon))</zot:data>
  33. </zot:msg>
  34. zot:key
  35. *******
  36. A suitable randomly generated encyption key of length 32 octets for encrypting
  37. the salmon packet. This is then encrypted with the sender's private key and
  38. base64url encoded.
  39. zot:iv
  40. ******
  41. A suitable randomly generated initialisation vector of length 16 octets for
  42. encrypting the salmon packet. This is then encrypted with the sender's private
  43. key and base64url encoded.
  44. zot:env_key
  45. ***********
  46. A suitable randomly generated encyption key of length 32 octets for encrypting
  47. the envelope. This is then encrypted with the recipient's public key and
  48. base64url encoded. For bulk deliveries, it is encrypted with the site bulk
  49. delivery public key.
  50. zot:env_iv
  51. **********
  52. A suitable randomly generated initialisation vector of length 16 octets for
  53. encrypting the envelope. This is then encrypted with the recipient's public
  54. key and base64url encoded. For bulk deliveries, it is encrypted with the site
  55. bulk delivery public key.
  56. zot:env
  57. *******
  58. This consists of RFC822-style header fields representing the sender and
  59. recipient(s). Line lengths have no defined limit and RFC822 continuation
  60. lines are not supported. If an inbound server is not able to process an
  61. envelope or post due to size constraints, it SHOULD return a
  62. "413 Entity too large" HTTP response.
  63. Example:
  64. Z-From: zot:bob@example.com
  65. Z-Sender: zot:bob@example.com
  66. Z-To: zot:alice@example.com
  67. Both "Z-From:" and "Z-Sender:" MUST be provided, and represent a single
  68. webfinger address of the author and sender respectively. The webfinger
  69. address for the From address MUST contain a discoverable salmon public key
  70. which is needed to verify the enclosed salmon data. Sender is used to indicate
  71. the webfinger identity responsible for transmitting this message. From
  72. indicates the message author.
  73. In web-based social systems, a reply to a message SHOULD be conveyed to all of
  74. the original message participants. Only the author of the original message
  75. may know all the recipients (such as those contained in Bcc: elements). The
  76. author of a message always provides 'From'. They MUST duplicate this
  77. information as 'Sender' when posting a followup message.
  78. A reply to a given message MUST be sent to the From address of the original
  79. post, and MAY be sent to any additional addresses in the recipient list. The
  80. original post author MUST send the reply to all known recipients of the
  81. original message, with their webfinger identity as Sender, and the
  82. comment/reply author as From.
  83. Receiving agents SHOULD validate the From identity as the signer of the salmon
  84. magic envelope, and MAY reject it. They SHOULD also verify the Sender signature
  85. of the zot packet if it is different than the salmon signature. They MAY
  86. reject the message if the Sender is not allowed in their "friend list", or if
  87. they do not have a suitable relationship with the Sender, or if either
  88. signature fails to validate. Rejected messages for one of these reasons SHOULD
  89. be indicated with a "400 Bad Request" HTTP response.
  90. Z-To: *
  91. indicates a public message with no specifically enumerated recipients.
  92. The fields Z-To: and/or Z-Bcc: MAY be present. At least one recipient field
  93. MUST be present.
  94. Z-To: zot:bob@example.com, zot:alice@example.com, mailto:dave@example.com
  95. Z-Bcc: zot:https://example.com/profile/richard
  96. are valid entries. Adresses are comma separated and individual entries MUST NOT
  97. contain commas. There MAY be any number of ASCII space characters between
  98. entries for legibility. Header lines are terminated with a linefeed character
  99. (ASCII 0x0A).
  100. This specification provides the following protocol address prefixes
  101. for use in Z-To: or Z-Bcc: elements:
  102. zot: - normal zot delivery using webfinger or LRDD resolvable address
  103. dfrn: - legacy DFRN mode delivery using webfinger or LRDD resovable address
  104. ostatus: - normal OStatus delivery using webfinger or LRDD resovable address
  105. diaspora: - Diaspora network delivery using webfinger address
  106. facebook: - Facebook profile page URL
  107. twitter: - Twitter personal page URL without AJAX '#!' fragment
  108. mailto: - email RFC822/ESMTP address
  109. Examples:
  110. twitter:http://twitter.com/bjensen
  111. facebook:http://facebook.com/profile.php?id=000000001
  112. Foreign protocol addresses which have not been defined in this specification
  113. or future revisions of this specification and which are unknown to the
  114. recipient delivery process MAY be ignored.
  115. In cases where an address may contain either a webfinger or LRDD address, the
  116. webfinger address SHOULD be used preferentially.
  117. Z-Bcc:
  118. ******
  119. The Z-Bcc element may contain one or more addresses which are hidden from end
  120. user presentation. A zot receiving system MUST NOT store or allow for
  121. the display of the Bcc information. Implementations which require extreme
  122. privacy SHOULD send individual posts to each of the Bcc: recipients containing
  123. only a single address. They MAY send all Bcc: posts using bulk delivery,
  124. however this may have privacy implications as there is no guarantee a
  125. receiving system will not log, store, or otherwise reveal the contents of the
  126. Bcc recipient list.
  127. Z-To: addresses MAY be shown to an end user.
  128. Envelope encryption
  129. *******************
  130. The entire envelope is encrypted using alg with env_key and env_iv and
  131. base64url encoded for transmission.
  132. The zot envelope MAY include remote addresses. A zot inbound delivery agent
  133. MUST parse the envelope and determine whether a delivery address to the
  134. current endpoint is valid. This may be the result of:
  135. 1. An address contains the public message wildcard '*'
  136. 2. The current endpoint is a personal endpoint and one of the recipients
  137. listed in the Z-To: or Z-Bcc: addresses matches the webfinger address of
  138. the "owner" of the endpoint.
  139. 3. The current endpoint is a bulk delivery endpoint. The bulk delivery
  140. endpoint is defined elsewhere in this document. The bulk delivery agent
  141. will deliver to all local addresses found in the address lists.
  142. zot:sig
  143. *******
  144. The Sender of the message signs the underlying salmon data in the manner
  145. prescribed by salmon. If the Sender and From address are identical, the
  146. signature will be identical to the signature of the underlying salmon packet.
  147. If they are different, this signature is verified with the Sender's public
  148. key to verify the Sender.
  149. zot:alg
  150. *******
  151. Currently the only valid choice for alg is "AES-256-CBC".
  152. zot:data
  153. ********
  154. The data field is a salmon magic envelope. This is encrypted with alg using
  155. key and iv. The result is then base64url encoded for transmission.
  156. For the first release of this specification, the data format of the enclosed
  157. salmon SHOULD be 'application/atom+xml' representing an Atom formatted
  158. ActivityStream. Future revisions MAY allow other alternate data formats.
  159. All acceptable formats MUST be listed in an XRD property (described elsewhere
  160. in this document).
  161. Delivery
  162. ********
  163. The zot message is then POSTed to the zot endpoint URL as
  164. application/text+xml and can be decoded/decrypted by the recipient using
  165. their private key.
  166. The normal salmon endpoint for a service MAY be used as an alternate
  167. delivery method for non-encrypted (e.g. public) messages.
  168. Discover of the zot endpoint is based on webfinger XRD:
  169. <Link rel="http://purl.org/zot/1.0/post"
  170. href="http://example/org/zot-endpoint" />
  171. Bulk Delivery
  172. *************
  173. A site MAY provide a bulk delivery endpoint, which MAY be used to avoid
  174. multiple encryptions of the same data for a single destination.
  175. This is discoverable by providing a zot endpoint with a corresponding
  176. salmon public key in the site's .well-known/host-meta file.
  177. A delivery to this endpoint will deliver to all local recipients provided
  178. within the zot envelope.
  179. Extensibility
  180. *************
  181. This specification is subject to change. The current version which is in
  182. effect at a given site may be noted by XRD properties. The following
  183. properties MUST be present in the XRD providing the relevant endpoint:
  184. <Property type="http://purl.org/zot/1.0/version">1</Property>
  185. <Property type="http://purl.org/zot/1.0/accept">application/atom+xml</Property>
  186. Version is specified in this document and indicates the current revision.
  187. Version is an increasing non-zero integer value. There are no minor versions.
  188. Implementations MAY provide compatibility to multiple incompatible versions
  189. by using this version indication. The "accept" indicates a range of document
  190. content types which may be enclosed in the underlying salmon magic envelope.
  191. We anticipate this specification will in the future allow for a close variant
  192. of "message/rfc822" and which may include MIME. This may also be used to
  193. embed alternate message formats and protocols such as
  194. "application/x-diaspora+xml". If a delivery agent is unable to provide any
  195. acceptable data format to the remote system, the delivery to that system MUST
  196. be terminated/cancelled.
  197. Foreign Messages
  198. ****************
  199. Messages MAY be imported from other networks and systems which have no
  200. knowledge of salmon signatures. The salmon signature in this case MUST be the
  201. exact string 'NOTSIGNED' to indicate that the author (From address) cannot be
  202. validated using salmon verification. This message MUST be relayed by a Sender
  203. who can provide a valid salmon signature of the message via zot:sig. Delivery
  204. systems MAY reject foreign messages.
  205. *******************************
  206. * Zid (Zot-ID) authentication *
  207. *******************************
  208. This section of the document is considered separate from the delivery
  209. specification precding it and represents a different protocol, which is
  210. currently incomplete. This will be split off into another document in the
  211. future, but is presented here as a synergistic component of the Zot network
  212. model.
  213. URLs may be present within a zot message which refer to private and/or
  214. protected resources. Zid uses OpenID to gain access to these protected
  215. resources. These could be private photos or profile information - or *any*
  216. web accessible resource. Using zid, these can have access controls which
  217. extends to any resolvable webfinger address.
  218. Zid authentication relies on the presence of an OpenID provider element in
  219. webfinger, and a URL template which is applied to protected resources within
  220. a zot message.
  221. The template is designated with the characters "{zid=}" within a URL of a zot
  222. message. When the page is rendered for viewing to an observer, this template
  223. is replaced with the webfinger address of the viewer (if known), or an empty
  224. string if the webfinger address of the viewer cannot be determined.
  225. For example in a message body:
  226. http://example.com/photos/bob/picture.jpg?{zid=}
  227. refers to a private photo which is only visible to alice@example.com.
  228. If Alice is viewing the page, the link is rendered with
  229. http://example.com/photos/bob/picture.jpg?zid=alice@example.com
  230. If the page viewer is unknown, it is rendered as
  231. http://example.com/photos/bob/picture.jpg?zid=
  232. When the link is visited, the web server at example.com notes the presence of
  233. the zid parameter and uses information from webfinger to locate the OpenID
  234. provider for the zid webfinger address. It then redirects to the OpenID
  235. server and requests authentication of the given person. If this is successful,
  236. access to the protected resource is granted.
  237. A browser cookie may be provided to avoid future authentication redirects
  238. and allow authenticated browsing to other resources on the website.
  239. Only authentication via OpenID is defined in this version of the specification.
  240. This can be used to provide access control of any web resource to any
  241. webfinger identity on the internet.
  242. *********
  243. * Links *
  244. *********
  245. Salmon Protocol
  246. http://www.salmon-protocol.org/salmon-protocol-summary
  247. Salmon Magic Envelope
  248. http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html
  249. Atom Activity Stream Draft
  250. http://activitystrea.ms/specs/atom/1.0/
  251. Activty Stream Base Schema
  252. http://activitystrea.ms/head/activity-schema.html
  253. WebFinger Protocol
  254. http://code.google.com/p/webfinger/wiki/WebFingerProtocol