1 This is the Zot! social communications protocol.
3 Specification revision: 1
7 This specification is public domain.
9 Zot is a framework for secure delivery of messages on the web based on
10 webfinger and encapsulating salmon.
12 First read the salmon and salmon magic envelope specifications. Zot also
13 makes use of webfinger and ActivityStreams and several concepts from RFC822
14 (email). Zot encompasses the zot delivery framework and the zid remote
17 The current specification revision (1) is frozen until a reference
18 implementation is available. After that, any protocol changes will require a
19 change to the revision number.
25 Format of a zot wrapper. This completely encapsulates a salmon magic envelope
26 and provides privacy protection, while defining a delivery envelope - a
27 concept familiar to email systems. All addresses in zot are webfinger
28 resolvable addresses containing zot endpoints and salmon public keys (zot
29 is a superset of salmon).
32 <?xml version='1.0' encoding='UTF-8'?>
33 <zot:msg xmlns:zot='http://purl.org/zot/1.0'>
34 <zot:key>((key))</zot:key>
35 <zot:iv>((iv))</zot:iv>
36 <zot:env_key>((env_key))</zot:env_key>
37 <zot:env_iv>((env_iv))</zot:env_iv>
38 <zot:env>((envelope))</zot:env>
39 <zot:sig key_id="xxx">((sender signature))</zot:sig>
40 <zot:alg>AES-256-CBC</zot:alg>
41 <zot:data type='application/magic-envelope+xml'>((salmon))</zot:data>
48 A suitable randomly generated encyption key of length 32 octets for encrypting
49 the salmon packet. This is then encrypted with the sender's private key and
55 A suitable randomly generated initialisation vector of length 16 octets for
56 encrypting the salmon packet. This is then encrypted with the sender's private
57 key and base64url encoded.
62 A suitable randomly generated encyption key of length 32 octets for encrypting
63 the envelope. This is then encrypted with the recipient's public key and
64 base64url encoded. For bulk deliveries, it is encrypted with the site bulk
71 A suitable randomly generated initialisation vector of length 16 octets for
72 encrypting the envelope. This is then encrypted with the recipient's public
73 key and base64url encoded. For bulk deliveries, it is encrypted with the site
74 bulk delivery public key.
80 This consists of RFC822-style header fields representing the sender and
81 recipient(s). Line lengths have no defined limit and RFC822 continuation
82 lines are not supported. If an inbound server is not able to process an
83 envelope or post due to size constraints, it SHOULD return a
84 "413 Entity too large" HTTP response.
88 Z-From: zot:bob@example.com
89 Z-Sender: zot:bob@example.com
90 Z-To: zot:alice@example.com
92 Both "Z-From:" and "Z-Sender:" MUST be provided, and represent a single
93 webfinger address of the author and sender respectively. The webfinger
94 address for the From address MUST contain a discoverable salmon public key
95 which is needed to verify the enclosed salmon data. Sender is used to indicate
96 the webfinger identity responsible for transmitting this message. From
97 indicates the message author.
99 In web-based social systems, a reply to a message SHOULD be conveyed to all of
100 the original message participants. Only the author of the original message
101 may know all the recipients (such as those contained in Bcc: elements). The
102 author of a message always provides 'From'. They MUST duplicate this
103 information as 'Sender' when posting a followup message.
105 A reply to a given message MUST be sent to the From address of the original
106 post, and MAY be sent to any additional addresses in the recipient list. The
107 original post author MUST send the reply to all known recipients of the
108 original message, with their webfinger identity as Sender, and the
109 comment/reply author as From.
111 Receiving agents SHOULD validate the From identity as the signer of the salmon
112 magic envelope, and MAY reject it. They SHOULD also verify the Sender signature
113 of the zot packet if it is different than the salmon signature. They MAY
114 reject the message if the Sender is not allowed in their "friend list", or if
115 they do not have a suitable relationship with the Sender, or if either
116 signature fails to validate. Rejected messages for one of these reasons SHOULD
117 be indicated with a "400 Bad Request" HTTP response.
122 indicates a public message with no specifically enumerated recipients.
124 The fields Z-To: and/or Z-Bcc: MAY be present. At least one recipient field
127 Z-To: zot:bob@example.com, zot:alice@example.com, mailto:dave@example.com
128 Z-Bcc: zot:https://example.com/profile/richard
130 are valid entries. Adresses are comma separated and individual entries MUST NOT
131 contain commas. There MAY be any number of ASCII space characters between
132 entries for legibility. Header lines are terminated with a linefeed character
135 This specification provides the following foreign protocol address prefixes
136 for use in Z-To: or Z-Bcc: elements:
138 zot: - normal zot delivery using webfinger or LRDD resolvable address
139 ostatus: - normal OStatus delivery using webfinger or LRDD resovable address
140 diaspora: - Diaspora network delivery using webfinger address
141 facebook: - Facebook profile page URL
142 twitter: - Twitter personal page URL without AJAX '#!' fragment
143 mailto: - email RFC822/ESMTP address
147 twitter:http://twitter.com/bjensen
148 facebook:http://facebook.com/profile.php?id=000000001
150 Foreign protocol addresses which have not been defined in this specification
151 or future revisions of this specification and which are unknown to the
152 recipient delivery process MAY be ignored.
154 In cases where an address may contain either a webfinger or LRDD address, the
155 webfinger address SHOULD be used preferentially.
161 The Z-Bcc element may contain one or more addresses which are hidden from end
162 user presentation. A zot receiving system MUST NOT store or allow for
163 the display of the Bcc information. Implementations which require extreme
164 privacy SHOULD send individual posts to each of the Bcc: recipients containing
165 only a single address. They MAY send all Bcc: posts using bulk delivery,
166 however this may have privacy implications as there is no guarantee a
167 receiving system will not log, store, or otherwise reveal the contents of the
170 Z-To: addresses MAY be shown to an end user.
177 The entire envelope is encrypted using alg with env_key and env_iv and
178 base64url encoded for transmission.
180 The zot envelope MAY include remote addresses. A zot inbound delivery agent
181 MUST parse the envelope and determine whether a delivery address to the
182 current endpoint is valid. This may be the result of:
184 1. An address contains the public message wildcard '*'
186 2. The current endpoint is a personal endpoint and one of the recipients
187 listed in the Z-To: or Z-Bcc: addresses matches the webfinger address of
188 the "owner" of the endpoint.
190 3. The current endpoint is a bulk delivery endpoint. The bulk delivery
191 endpoint is defined elsewhere in this document. The bulk delivery agent
192 will deliver to all local addresses found in the address lists.
197 The Sender of the message signs the underlying salmon data in the manner
198 prescribed by salmon. If the Sender and From address are identical, the
199 signature will be identical to the signature of the underlying salmon packet.
200 If they are different, this signature is verified with the Sender's public
201 key to verify the Sender.
206 Currently the only valid choice for alg is "AES-256-CBC".
212 The data field is a salmon magic envelope. This is encrypted with alg using
213 key and iv. The result is then base64url encoded for transmission.
215 For the first release of this specification, the data format of the enclosed
216 salmon SHOULD be 'application/atom+xml' representing an Atom formatted
217 ActivityStream. Future revisions MAY allow other alternate data formats.
218 All acceptable formats MUST be listed in an XRD property (described elsewhere
225 The zot message is then POSTed to the zot endpoint URL as
226 application/text+xml and can be decoded/decrypted by the recipient using
229 The normal salmon endpoint for a service MAY be used as an alternate
230 delivery method for non-encrypted (e.g. public) messages.
232 Discover of the zot endpoint is based on webfinger XRD:
234 <Link rel="http://purl.org/zot/1.0/post"
235 href="http://example/org/zot-endpoint" />
241 A site MAY provide a bulk delivery endpoint, which MAY be used to avoid
242 multiple encryptions of the same data for a single destination.
243 This is discoverable by providing a zot endpoint with a corresponding
244 salmon public key in the site's .well-known/host-meta file.
245 A delivery to this endpoint will deliver to all local recipients provided
246 within the zot envelope.
252 This specification is subject to change. The current version which is in
253 effect at a given site may be noted by XRD properties. The following
254 properties MUST be present in the XRD providing the relevant endpoint:
256 <Property xmlns:zot="http://purl.og/zot/1.0"
257 type="http://purl.org/zot/1.0/version"
260 <Property xmlns:zot="http://purl.og/zot/1.0"
261 type="http://purl.org/zot/1.0/accept"
262 zot:accept="application/atom+xml" />
264 Version is specified in this document and indicates the current revision.
265 Implementations MAY provide compatibility to multiple incompatible versions
266 by using this version indication. The "accept" indicates a range of document
267 content types which may be enclosed in the underlying salmon magic envelope.
268 We anticipate this specification will in the future allow for a close variant
269 of "message/rfc822" and which may include MIME. This may also be used to
270 embed alternate message formats and protocols such as
271 "application/x-diaspora+xml". If a delivery agent is unable to provide any
272 acceptable data format to the remote system, the delivery to that system MUST
273 be terminated/cancelled.
278 Messages MAY be imported from other networks and systems which have no
279 knowledge of salmon signatures. The salmon signature in this case MUST be the
280 exact string 'NOTSIGNED' to indicate that the author (From address) cannot be
281 validated using salmon verification. This message MUST be relayed by a Sender
282 who can provide a valid salmon signature of the message via zot:sig. Delivery
283 systems MAY reject foreign messages.
289 *******************************
290 * Zid (Zot-ID) authentication *
291 *******************************
293 This section of the document is considered separate from the delivery
294 specification precding it and represents a different protocol, which is
295 currently incomplete. This will be split off into another document in the
296 future, but is presented here as a synergistic component of the Zot network
300 URLs may be present within a zot message which refer to private and/or
301 protected resources. Zid uses OpenID to gain access to these protected
302 resources. These could be private photos or profile information - or *any*
303 web accessible resource. Using zid, these can have access controls which
304 extends to any resolvable webfinger address.
306 Zid authentication relies on the presence of an OpenID provider element in
307 webfinger, and a URL template which is applied to protected resources within
310 The template is designated with the characters "{zid=}" within a URL of a zot
311 message. When the page is rendered for viewing to an observer, this template
312 is replaced with the webfinger address of the viewer (if known), or an empty
313 string if the webfinger address of the viewer cannot be determined.
315 For example in a message body:
317 http://example.com/photos/bob/picture.jpg?{zid=}
319 refers to a private photo which is only visible to alice@example.com.
321 If Alice is viewing the page, the link is rendered with
323 http://example.com/photos/bob/picture.jpg?zid=alice@example.com
325 If the page viewer is unknown, it is rendered as
327 http://example.com/photos/bob/picture.jpg?zid=
330 When the link is visited, the web server at example.com notes the presence of
331 the zid parameter and uses information from webfinger to locate the OpenID
332 provider for the zid webfinger address. It then redirects to the OpenID
333 server and requests authentication of the given person. If this is successful,
334 access to the protected resource is granted.
336 A browser cookie may be provided to avoid future authentication redirects
337 and allow authenticated browsing to other resources on the website.
339 Only authentication via OpenID is defined in this version of the specification.
341 This can be used to provide access control of any web resource to any
342 webfinger identity on the internet.
350 http://www.salmon-protocol.org/salmon-protocol-summary
352 Salmon Magic Envelope
353 http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html
355 Atom Activity Stream Draft
356 http://activitystrea.ms/specs/atom/1.0/
358 Activty Stream Base Schema
359 http://activitystrea.ms/head/activity-schema.html
362 http://code.google.com/p/webfinger/wiki/WebFingerProtocol