zot.txt

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