zot.txt

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