spec/zot.txt

   1 This is the Zot! social communications protocol.
   2
   3 Specification revision: 1
   4 2 October 2011
   5
   6 Mike Macgirvin
   7 This specification is public domain.
   8
   9 Zot is a framework for secure delivery of messages on the web based on
  10 webfinger and encapsulating salmon.
  11
  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
  15 access protocol.
  16
  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.
  20
  21 ****************
  22 * Zot delivery *
  23 ****************
  24
  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).
  30
  31
  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>
  42 </zot:msg>
  43
  44
  45 zot:key
  46 *******
  47
  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
  50 base64url encoded.
  51
  52 zot:iv
  53 ******
  54
  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.
  58
  59 zot:env_key
  60 ***********
  61
  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
  65 delivery public key.
  66
  67
  68 zot:env_iv
  69 **********
  70
  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.
  75
  76
  77 zot:env
  78 *******
  79
  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.
  85
  86 Example:
  87
  88 Z-From: zot:bob@example.com
  89 Z-Sender: zot:bob@example.com
  90 Z-To: zot:alice@example.com
  91
  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.
  98
  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.
 104
 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.
 110
 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.
 118
 119
 120 Z-To: *
 121
 122 indicates a public message with no specifically enumerated recipients.
 123
 124 The fields Z-To: and/or Z-Bcc: MAY be present. At least one recipient field
 125 MUST be present.
 126
 127 Z-To: zot:bob@example.com, zot:alice@example.com, mailto:dave@example.com
 128 Z-Bcc: zot:https://example.com/profile/richard
 129
 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
 133 (ASCII 0x0A).
 134
 135 This specification provides the following protocol address prefixes
 136 for use in Z-To: or Z-Bcc: elements:
 137
 138 zot: - normal zot delivery using webfinger or LRDD resolvable address
 139 dfrn: - legacy DFRN mode delivery using webfinger or LRDD resovable address
 140 ostatus: - normal OStatus delivery using webfinger or LRDD resovable address
 141 diaspora: - Diaspora network delivery using webfinger address
 142 facebook: - Facebook profile page URL
 143 twitter: - Twitter personal page URL without AJAX '#!' fragment
 144 mailto: - email RFC822/ESMTP address
 145
 146 Examples:
 147
 148 twitter:http://twitter.com/bjensen
 149 facebook:http://facebook.com/profile.php?id=000000001
 150
 151 Foreign protocol addresses which have not been defined in this specification
 152 or future revisions of this specification and which are unknown to the
 153 recipient delivery process MAY be ignored.
 154
 155 In cases where an address may contain either a webfinger or LRDD address, the
 156 webfinger address SHOULD be used preferentially.
 157
 158
 159 Z-Bcc:
 160 ******
 161
 162 The Z-Bcc element may contain one or more addresses which are hidden from end
 163 user presentation. A zot receiving system MUST NOT store or allow for
 164 the display of the Bcc information. Implementations which require extreme
 165 privacy SHOULD send individual posts to each of the Bcc: recipients containing
 166 only a single address. They MAY send all Bcc: posts using bulk delivery,
 167 however this may have privacy implications as there is no guarantee a
 168 receiving system will not log, store, or otherwise reveal the contents of the
 169 Bcc recipient list.
 170
 171 Z-To: addresses MAY be shown to an end user.
 172
 173
 174 Envelope encryption
 175 *******************
 176
 177
 178 The entire envelope is encrypted using alg with env_key and env_iv and
 179 base64url encoded for transmission.
 180
 181 The zot envelope MAY include remote addresses. A zot inbound delivery agent
 182 MUST parse the envelope and determine whether a delivery address to the
 183 current endpoint is valid. This may be the result of:
 184
 185         1. An address contains the public message wildcard '*'
 186
 187         2. The current endpoint is a personal endpoint and one of the recipients
 188 listed in the Z-To: or Z-Bcc: addresses matches the webfinger address of
 189 the "owner" of the endpoint.
 190
 191         3. The current endpoint is a bulk delivery endpoint. The bulk delivery
 192 endpoint is defined elsewhere in this document. The bulk delivery agent
 193 will deliver to all local addresses found in the address lists.
 194
 195 zot:sig
 196 *******
 197
 198 The Sender of the message signs the underlying salmon data in the manner
 199 prescribed by salmon. If the Sender and From address are identical, the
 200 signature will be identical to the signature of the underlying salmon packet.
 201 If they are different, this signature is verified with the Sender's public
 202 key to verify the Sender.
 203
 204 zot:alg
 205 *******
 206
 207 Currently the only valid choice for alg is "AES-256-CBC".
 208
 209
 210 zot:data
 211 ********
 212
 213 The data field is a salmon magic envelope. This is encrypted with alg using
 214 key and iv. The result is then base64url encoded for transmission.
 215
 216 For the first release of this specification, the data format of the enclosed
 217 salmon SHOULD be 'application/atom+xml' representing an Atom formatted
 218 ActivityStream. Future revisions MAY allow other alternate data formats.
 219 All acceptable formats MUST be listed in an XRD property (described elsewhere
 220 in this document).
 221
 222
 223 Delivery
 224 ********
 225
 226 The zot message is then POSTed to the zot endpoint URL as
 227 application/text+xml and can be decoded/decrypted by the recipient using
 228 their private key.
 229
 230 The normal salmon endpoint for a service MAY be used as an alternate
 231 delivery method for non-encrypted (e.g. public) messages.
 232
 233 Discover of the zot endpoint is based on webfinger XRD:
 234
 235 <Link rel="http://purl.org/zot/1.0/post"
 236         href="http://example/org/zot-endpoint" />
 237
 238
 239 Bulk Delivery
 240 *************
 241
 242 A site MAY provide a bulk delivery endpoint, which MAY be used to avoid
 243 multiple encryptions of the same data for a single destination.
 244 This is discoverable by providing a zot endpoint with a corresponding
 245 salmon public key in the site's .well-known/host-meta file.
 246 A delivery to this endpoint will deliver to all local recipients provided
 247 within the zot envelope.
 248
 249
 250 Extensibility
 251 *************
 252
 253 This specification is subject to change. The current version which is in
 254 effect at a given site may be noted by XRD properties. The following
 255 properties MUST be present in the XRD providing the relevant endpoint:
 256
 257 <Property type="http://purl.org/zot/1.0/version">1</Property>
 258 <Property type="http://purl.org/zot/1.0/accept">application/atom+xml</Property>
 259
 260
 261 Version is specified in this document and indicates the current revision.
 262 Version is an increasing non-zero integer value. There are no minor versions.
 263 Implementations MAY provide compatibility to multiple incompatible versions
 264 by using this version indication. The "accept" indicates a range of document
 265 content types which may be enclosed in the underlying salmon magic envelope.
 266 We anticipate this specification will in the future allow for a close variant
 267 of "message/rfc822" and which may include MIME. This may also be used to
 268 embed alternate message formats and protocols such as
 269 "application/x-diaspora+xml". If a delivery agent is unable to provide any
 270 acceptable data format to the remote system, the delivery to that system MUST
 271 be terminated/cancelled.
 272
 273 Foreign Messages
 274 ****************
 275
 276 Messages MAY be imported from other networks and systems which have no
 277 knowledge of salmon signatures. The salmon signature in this case MUST be the
 278 exact string 'NOTSIGNED' to indicate that the author (From address) cannot be
 279 validated using salmon verification. This message MUST be relayed by a Sender
 280 who can provide a valid salmon signature of the message via zot:sig. Delivery
 281 systems MAY reject foreign messages.
 282
 283
 284
 285
 286
 287 *******************************
 288 * Zid (Zot-ID) authentication *
 289 *******************************
 290
 291 This section of the document is considered separate from the delivery
 292 specification precding it and represents a different protocol, which is
 293 currently incomplete. This will be split off into another document in the
 294 future, but is presented here as a synergistic component of the Zot network
 295 model.
 296
 297
 298 URLs may be present within a zot message which refer to private and/or
 299 protected resources. Zid uses OpenID to gain access to these protected
 300 resources. These could be private photos or profile information - or *any*
 301 web accessible resource. Using zid, these can have access controls which
 302 extends to any resolvable webfinger address.
 303
 304 Zid authentication relies on the presence of an OpenID provider element in
 305 webfinger, and a URL template which is applied to protected resources within
 306 a zot message.
 307
 308 The template is designated with the characters "{zid=}" within a URL of a zot
 309 message. When the page is rendered for viewing to an observer, this template
 310 is replaced with the webfinger address of the viewer (if known), or an empty
 311 string if the webfinger address of the viewer cannot be determined.
 312
 313 For example in a message body:
 314
 315 http://example.com/photos/bob/picture.jpg?{zid=}
 316
 317 refers to a private photo which is only visible to alice@example.com.
 318
 319 If Alice is viewing the page, the link is rendered with
 320
 321 http://example.com/photos/bob/picture.jpg?zid=alice@example.com
 322
 323 If the page viewer is unknown, it is rendered as
 324
 325 http://example.com/photos/bob/picture.jpg?zid=
 326
 327
 328 When the link is visited, the web server at example.com notes the presence of
 329 the zid parameter and uses information from webfinger to locate the OpenID
 330 provider for the zid webfinger address. It then redirects to the OpenID
 331 server and requests authentication of the given person. If this is successful,
 332 access to the protected resource is granted.
 333
 334 A browser cookie may be provided to avoid future authentication redirects
 335 and allow authenticated browsing to other resources on the website.
 336
 337 Only authentication via OpenID is defined in this version of the specification.
 338
 339 This can be used to provide access control of any web resource to any
 340 webfinger identity on the internet.
 341
 342
 343 *********
 344 * Links *
 345 *********
 346
 347 Salmon Protocol
 348         http://www.salmon-protocol.org/salmon-protocol-summary
 349
 350 Salmon Magic Envelope
 351         http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html
 352
 353 Atom Activity Stream Draft
 354         http://activitystrea.ms/specs/atom/1.0/
 355
 356 Activty Stream Base Schema
 357         http://activitystrea.ms/head/activity-schema.html
 358
 359 WebFinger Protocol
 360         http://code.google.com/p/webfinger/wiki/WebFingerProtocol
 361
 362