zot.txt

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