zot.txt

   1 This is the Zot! social communications protocol.
   2
   3 Specification revision: 1
   4 01 September 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 ****************
  18 * Zot delivery *
  19 ****************
  20
  21 Format of a zot wrapper. This completely encapsulates a salmon magic envelope
  22 and provides privacy protection, while defining a delivery envelope - a
  23 concept familiar to email systems. All addresses in zot are webfinger
  24 resolvable addresses containing both salmon and zot endpoints.
  25
  26
  27 <?xml version='1.0' encoding='UTF-8'?>
  28 <zot:msg xmlns:zot='http://purl.org/zot/1.0'>
  29  <zot:key>((key))</zot:key>
  30  <zot:iv>((iv))</zot:iv>
  31  <zot:env>((envelope))</zot:env>
  32  <zot:sig key_id="xxx">((sender signature))</zot:sig>
  33  <zot:alg>AES-256-CBC</zot:alg>
  34  <zot:data type='application/magic-envelope+xml'>((salmon))</zot:data>
  35 </zot:msg>
  36
  37
  38 zot:key
  39 *******
  40
  41 A suitable randomly generated encyption key of length 32 octets for encrypting
  42 the envelope and salmon packet. This is then encrypted with the sender's
  43 private key and base64url encoded.
  44
  45 zot:iv
  46 ******
  47
  48 A suitable randomly generated initialisation vector of length 16 octets for
  49 encrypting the envelope and salmon packet. This is then encrypted with the
  50 sender's private key and base64url encoded.
  51
  52 zot:env
  53 *******
  54
  55 This consists of RFC822-style header fields representing the sender and
  56 recipient(s). Example:
  57
  58 From: bob@example.com
  59 Sender: bob@example.com
  60 To: alice@example.com
  61
  62 Both "From:" and "Sender:" MUST be provided, and represent a webfinger
  63 address of the author and sender respectively. The webfinger address for
  64 the From address MUST contain a discoverable salmon public key that
  65 is needed to verify the enclosed salmon data. Sender is used to indicate
  66 the webfinger identity responsible for transmitting this message. From
  67 indicates the message author.
  68
  69 In web-based social systems, a reply to a message SHOULD be conveyed to all of
  70 the original message participants. Only the author of the original message
  71 may know all the recipients (such as those contained in Bcc: elements). The
  72 author of a message always provides 'From'. They MUST duplicate this
  73 information as 'Sender'.
  74
  75 A reply to a given message MUST be sent to the original From address, and MAY
  76 be sent to any additional addresses in the recipient list. The original author
  77 MUST send the reply to all known recipients of the original message, with
  78 their webfinger identity as Sender, and the comment/reply author as From.
  79
  80 Receiving agents SHOULD validate the From identity as the signer of the salmon
  81 magic envelope, and MAY reject it. They SHOULD also verify the Sender signature
  82 of the zot packet if it is different than the salmon signature. They MAY
  83 reject the message if the Sender is not allowed in their "friend list", or if
  84 they do not have a suitable relationship with the Sender, or if either
  85 signature fails to validate.
  86
  87
  88 To: *
  89
  90 indicates a public message with no specifically enumerated recipients.
  91
  92 The fields To:, Cc:, and/or Bcc: MAY be present. At least one recipient field
  93 MUST be present. These fields may use the entire syntax specified by RFC822,
  94 for example:
  95
  96 To: "Bob Smith" <bob@example.com>, "Alice Jones" <alice@example.com>
  97
  98 is a valid entry. A zot envelope is UTF-8 encoded, which differs from RFC822.
  99 The host component MUST be US-ASCII, with punycode translation of
 100 internationalised domain names applied.
 101
 102 The entire envelope is encrypted with alg using key and iv. Only AES-256-CBC
 103 is defined as an algorithm in this specification. The encrypted envelope is
 104 then base64url encoded for transmission.
 105
 106 The zot envelope MAY include remote addresses. A zot delivery agent MUST parse
 107 all addresses and determine whether a delivery address to the current endpoint
 108 is valid. This may be the result of:
 109
 110         1. An address contains the public message wildcard '*'
 111
 112         2. The current endpoint is a personal endpoint and one of the recipients
 113 listed in the To:, Cc:, or Bcc: addresses matches the webfinger address of
 114 the "owner" of the endpoint.
 115
 116         3. The current endpoint is a bulk delivery endpoint. The bulk delivery
 117 endpoint is defined elsewhere in this document. The bulk delivery agent
 118 will deliver to all local addresses found in the address lists.
 119
 120 zot:sig
 121 *******
 122
 123 The Sender of the message signs the underlying salmon data in the manner
 124 prescribed by salmon. If the Sender and From address are identical, the
 125 signature will be identical to the signature of the underlying salmon packet.
 126 If they are different, this signature is verified with the Sender's public
 127 key to verify the Sender.
 128
 129 zot:alg
 130 *******
 131
 132 Currently the only valid choice for alg is "AES-256-CBC".
 133
 134
 135 zot:data
 136 ********
 137
 138 The data field is a salmon magic envelope. This is encrypted with alg using
 139 key and iv. The result is then base64url encoded for transmission.
 140
 141 For the first release of this specification, the data format of the enclosed
 142 salmon SHOULD be 'application/atom+xml' representing an Atom formatted
 143 ActivityStream. Future revisions MAY allow other alternate data formats.
 144 All acceptable formats MUST be listed in an XRD property (described elsewhere
 145 in this document).
 146
 147
 148 Delivery
 149 ********
 150
 151 The zot message is then POSTed to the zot endpoint URL as
 152 application/text+xml and can be decoded/decrypted by the recipient using
 153 their private key.
 154
 155 The normal salmon endpoint for a service MAY be used as an alternate
 156 delivery method for non-encrypted (e.g. public) messages.
 157
 158 Discover of the zot endpoint is based on webfinger XRD:
 159
 160 <link rel="http://purl.org/zot/1.0/post"
 161         href="http://example/org/zot-endpoint" />
 162
 163
 164 Bulk Delivery
 165 *************
 166
 167 A site MAY provide a bulk delivery endpoint, which MAY be used to avoid
 168 multiple encryptions of the same data for a single destination.
 169 This is discoverable by providing a zot endpoint with a corresponding
 170 salmon public key in the site's .well-known/host-meta file.
 171 A delivery to this endpoint will deliver to all local recipients provided
 172 within the zot envelope.
 173
 174
 175 Extensibility
 176 *************
 177
 178 This specification is subject to change. The current version which is in
 179 effect at a given site may be noted by XRD properties. The following
 180 properties MUST be present in the XRD providing the relevant endpoint:
 181
 182 <Property xmlns:zot="http://purl.og/zot/1.0"
 183         type="http://purl.org/zot/1.0/version"
 184         zot:version="1" />
 185
 186 <Property xmlns:zot="http://purl.og/zot/1.0"
 187         type="http://purl.org/zot/1.0/accept"
 188         zot:accept="application/atom+xml" />
 189
 190 Version is specified in this document and indicates the current revision.
 191 Implementations MAY provide compatibility to multiple incompatible versions
 192 by using this version indication. The "accept" indicates a range of document
 193 content types which may be enclosed in the underlying salmon magic envelope.
 194 We anticipate this specification will in the future allow for a close variant
 195 of "message/rfc822" and which may include MIME. This may also be used to
 196 embed alternate message formats and protocols such as
 197 "application/x-diaspora+xml". If a delivery agent is unable to provide any
 198 acceptable data format, the delivery MUST be terminated/cancelled.
 199
 200
 201 **********************
 202 * Zid authentication *
 203 **********************
 204
 205 URLs may be present within a zot message which refer to private and/or
 206 protected resources. Zid uses OpenID to gain access to these protected
 207 resources. These could be private photos or profile information - or *any*
 208 web accessible resource. Using zid, these can have access controls which
 209 extends to any resolvable webfinger address.
 210
 211 Zid authentication relies on the presence of an OpenID provider element in
 212 webfinger, and a URL template which is applied to protected resources within
 213 a zot message.
 214
 215 The template is designated with the characters "{zid=}" within a URL of a zot
 216 message. When the page is rendered for viewing to an observer, this template
 217 is replaced with the webfinger address of the viewer (if known), or an empty
 218 string if the webfinger address of the viewer cannot be determined.
 219
 220 For example in a message body:
 221
 222 http://example.com/photos/bob/picture.jpg?{zid=}
 223
 224 refers to a private photo which is only visible to alice@example.com.
 225
 226 If Alice is viewing the page, the link is rendered with
 227
 228 http://example.com/photos/bob/picture.jpg?zid=alice@example.com
 229
 230 If the page viewer is unknown, it is rendered as
 231
 232 http://example.com/photos/bob/picture.jpg?zid=
 233
 234
 235 When the link is visited, the web server at example.com notes the presence of
 236 the zid parameter and uses information from webfinger to locate the OpenID
 237 provider for the zid webfinger address. It then redirects to the OpenID
 238 server and requests authentication of the given person. If this is successful,
 239 access to the protected resource is granted.
 240
 241 A browser cookie may be provided to avoid future authentication redirects
 242 and allow authenticated browsing to other resources on the website.
 243
 244 Only authentication via OpenID is defined in this version of the specification.
 245
 246 This can be used to provide access control of any web resource to any
 247 webfinger identity on the internet.
 248
 249 *********
 250 * Links *
 251 *********
 252
 253 Salmon Protocol
 254         http://www.salmon-protocol.org/salmon-protocol-summary
 255
 256 Salmon Magic Envelope
 257         http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html
 258
 259 Atom Activity Stream Draft
 260         http://activitystrea.ms/specs/atom/1.0/
 261
 262 Activty Stream Base Schema
 263         http://activitystrea.ms/head/activity-schema.html
 264
 265 WebFinger Protocol
 266         http://code.google.com/p/webfinger/wiki/WebFingerProtocol
 267
 268