friendica/zot.txt

This is the Zot! social communications protocol. 

Specification revision: 1
15 September 2011

Mike Macgirvin
This specification is public domain.

Zot is a framework for secure delivery of messages on the web based on 
webfinger and encapsulating salmon.

First read the salmon and salmon magic envelope specifications. Zot also 
makes use of webfinger and ActivityStreams and several concepts from RFC822
(email). Zot encompasses the zot delivery framework and the zid remote
access protocol.

The current specification revision (1) is frozen until a reference 
implementation is available. After that, any protocol changes will require a 
change to the revision number.  

****************
* Zot delivery *
****************

Format of a zot wrapper. This completely encapsulates a salmon magic envelope 
and provides privacy protection, while defining a delivery envelope - a 
concept familiar to email systems. All addresses in zot are webfinger 
resolvable addresses containing zot endpoints and salmon public keys (zot 
is a superset of salmon). 


<?xml version='1.0' encoding='UTF-8'?>
<zot:msg xmlns:zot='http://purl.org/zot/1.0'>
 <zot:key>((key))</zot:key>
 <zot:iv>((iv))</zot:iv>
 <zot:env_key>((env_key))</zot:env_key>
 <zot:env_iv>((env_iv))</zot:env_iv>
 <zot:env>((envelope))</zot:env>
 <zot:sig key_id="xxx">((sender signature))</zot:sig>
 <zot:alg>AES-256-CBC</zot:alg>
 <zot:data type='application/magic-envelope+xml'>((salmon))</zot:data>
</zot:msg>


zot:key
*******

A suitable randomly generated encyption key of length 32 octets for encrypting 
the salmon packet. This is then encrypted with the sender's private key and 
base64url encoded.

zot:iv
******

A suitable randomly generated initialisation vector of length 16 octets for 
encrypting the salmon packet. This is then encrypted with the sender's private 
key and base64url encoded.

zot:env_key
***********

A suitable randomly generated encyption key of length 32 octets for encrypting 
the envelope. This is then encrypted with the recipient's public key and 
base64url encoded. For bulk deliveries, it is encrypted with the site bulk 
delivery public key.


zot:env_iv
**********

A suitable randomly generated initialisation vector of length 16 octets for 
encrypting the envelope. This is then encrypted with the recipient's public
key and base64url encoded. For bulk deliveries, it is encrypted with the site 
bulk delivery public key.


zot:env
*******

This consists of RFC822-style header fields representing the sender and 
recipient(s). Example:

From: bob@example.com
Sender: bob@example.com
To: alice@example.com

Both "From:" and "Sender:" MUST be provided, and represent a webfinger 
address of the author and sender respectively. The webfinger address for
the From address MUST contain a discoverable salmon public key that
is needed to verify the enclosed salmon data. Sender is used to indicate
the webfinger identity responsible for transmitting this message. From
indicates the message author. 

In web-based social systems, a reply to a message SHOULD be conveyed to all of 
the original message participants. Only the author of the original message 
may know all the recipients (such as those contained in Bcc: elements). The 
author of a message always provides 'From'. They MUST duplicate this 
information as 'Sender'.

A reply to a given message MUST be sent to the original From address, and MAY
be sent to any additional addresses in the recipient list. The original author
MUST send the reply to all known recipients of the original message, with 
their webfinger identity as Sender, and the comment/reply author as From.   

Receiving agents SHOULD validate the From identity as the signer of the salmon
magic envelope, and MAY reject it. They SHOULD also verify the Sender signature
of the zot packet if it is different than the salmon signature. They MAY 
reject the message if the Sender is not allowed in their "friend list", or if 
they do not have a suitable relationship with the Sender, or if either
signature fails to validate.  


To: *

indicates a public message with no specifically enumerated recipients.

The fields To:, Cc:, and/or Bcc: MAY be present. At least one recipient field
MUST be present. These fields may use the entire syntax specified by RFC822,
for example:

To: "Bob Smith" <bob@example.com>, "Alice Jones" <alice@example.com>

is a valid entry. A zot envelope is UTF-8 encoded, which differs from RFC822.
The host component MUST be US-ASCII, with punycode translation of 
internationalised domain names applied.

The entire envelope is then encrypted using alg with env_key and env_iv and
base64url encoded for transmission.

The zot envelope MAY include remote addresses. A zot delivery agent MUST parse
all addresses and determine whether a delivery address to the current endpoint
is valid. This may be the result of:

	1. An address contains the public message wildcard '*'

	2. The current endpoint is a personal endpoint and one of the recipients
listed in the To:, Cc:, or Bcc: addresses matches the webfinger address of
the "owner" of the endpoint.

	3. The current endpoint is a bulk delivery endpoint. The bulk delivery
endpoint is defined elsewhere in this document. The bulk delivery agent
will deliver to all local addresses found in the address lists. 

zot:sig
*******

The Sender of the message signs the underlying salmon data in the manner 
prescribed by salmon. If the Sender and From address are identical, the
signature will be identical to the signature of the underlying salmon packet. 
If they are different, this signature is verified with the Sender's public 
key to verify the Sender. 

zot:alg
*******

Currently the only valid choice for alg is "AES-256-CBC". 


zot:data
********

The data field is a salmon magic envelope. This is encrypted with alg using 
key and iv. The result is then base64url encoded for transmission.

For the first release of this specification, the data format of the enclosed
salmon SHOULD be 'application/atom+xml' representing an Atom formatted
ActivityStream. Future revisions MAY allow other alternate data formats.
All acceptable formats MUST be listed in an XRD property (described elsewhere
in this document).  


Delivery
********

The zot message is then POSTed to the zot endpoint URL as 
application/text+xml and can be decoded/decrypted by the recipient using 
their private key.

The normal salmon endpoint for a service MAY be used as an alternate
delivery method for non-encrypted (e.g. public) messages. 

Discover of the zot endpoint is based on webfinger XRD:

<Link rel="http://purl.org/zot/1.0/post" 
	href="http://example/org/zot-endpoint" />


Bulk Delivery
*************

A site MAY provide a bulk delivery endpoint, which MAY be used to avoid
multiple encryptions of the same data for a single destination.
This is discoverable by providing a zot endpoint with a corresponding
salmon public key in the site's .well-known/host-meta file.
A delivery to this endpoint will deliver to all local recipients provided
within the zot envelope. 


Extensibility
*************

This specification is subject to change. The current version which is in
effect at a given site may be noted by XRD properties. The following 
properties MUST be present in the XRD providing the relevant endpoint:

<Property xmlns:zot="http://purl.og/zot/1.0"
	type="http://purl.org/zot/1.0/version"
	zot:version="1" />

<Property xmlns:zot="http://purl.og/zot/1.0"
	type="http://purl.org/zot/1.0/accept"
	zot:accept="application/atom+xml" />

Version is specified in this document and indicates the current revision.
Implementations MAY provide compatibility to multiple incompatible versions
by using this version indication. The "accept" indicates a range of document
content types which may be enclosed in the underlying salmon magic envelope.
We anticipate this specification will in the future allow for a close variant
of "message/rfc822" and which may include MIME. This may also be used to 
embed alternate message formats and protocols such as 
"application/x-diaspora+xml". If a delivery agent is unable to provide any
acceptable data format, the delivery MUST be terminated/cancelled. 

Foreign Messages
****************

Messages MAY be imported from other networks and systems which have no 
knowledge of salmon signatures. The salmon signature in this case MUST be the
exact string 'NOTSIGNED' to indicate that the author (From address) cannot be 
validated using salmon verification. This message MUST be relayed by a Sender
who can provide a valid salmon signature of the message via zot:sig. Delivery
systems MAY reject foreign messages.  



**********************
* Zid authentication *
**********************

URLs may be present within a zot message which refer to private and/or
protected resources. Zid uses OpenID to gain access to these protected
resources. These could be private photos or profile information - or *any*
web accessible resource. Using zid, these can have access controls which 
extends to any resolvable webfinger address.

Zid authentication relies on the presence of an OpenID provider element in
webfinger, and a URL template which is applied to protected resources within
a zot message.

The template is designated with the characters "{zid=}" within a URL of a zot
message. When the page is rendered for viewing to an observer, this template
is replaced with the webfinger address of the viewer (if known), or an empty
string if the webfinger address of the viewer cannot be determined.

For example in a message body:

http://example.com/photos/bob/picture.jpg?{zid=}

refers to a private photo which is only visible to alice@example.com.

If Alice is viewing the page, the link is rendered with

http://example.com/photos/bob/picture.jpg?zid=alice@example.com

If the page viewer is unknown, it is rendered as

http://example.com/photos/bob/picture.jpg?zid=


When the link is visited, the web server at example.com notes the presence of 
the zid parameter and uses information from webfinger to locate the OpenID 
provider for the zid webfinger address. It then redirects to the OpenID 
server and requests authentication of the given person. If this is successful,
access to the protected resource is granted.

A browser cookie may be provided to avoid future authentication redirects
and allow authenticated browsing to other resources on the website.

Only authentication via OpenID is defined in this version of the specification.

This can be used to provide access control of any web resource to any 
webfinger identity on the internet.


*********
* Links *
*********

Salmon Protocol
	http://www.salmon-protocol.org/salmon-protocol-summary

Salmon Magic Envelope
	http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-01.html

Atom Activity Stream Draft
	http://activitystrea.ms/specs/atom/1.0/

Activty Stream Base Schema
	http://activitystrea.ms/head/activity-schema.html

WebFinger Protocol
	http://code.google.com/p/webfinger/wiki/WebFingerProtocol