362 lines
13 KiB
Text
362 lines
13 KiB
Text
This is the Zot! social communications protocol.
|
|
|
|
Specification revision: 1
|
|
2 October 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 encryption 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 encryption 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). Line lengths have no defined limit and RFC822 continuation
|
|
lines are not supported. If an inbound server is not able to process an
|
|
envelope or post due to size constraints, it SHOULD return a
|
|
"413 Entity too large" HTTP response.
|
|
|
|
Example:
|
|
|
|
Z-From: zot:bob@example.com
|
|
Z-Sender: zot:bob@example.com
|
|
Z-To: zot:alice@example.com
|
|
|
|
Both "Z-From:" and "Z-Sender:" MUST be provided, and represent a single
|
|
webfinger address of the author and sender respectively. The webfinger
|
|
address for the From address MUST contain a discoverable salmon public key
|
|
which 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' when posting a followup message.
|
|
|
|
A reply to a given message MUST be sent to the From address of the original
|
|
post, and MAY be sent to any additional addresses in the recipient list. The
|
|
original post 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. Rejected messages for one of these reasons SHOULD
|
|
be indicated with a "400 Bad Request" HTTP response.
|
|
|
|
|
|
Z-To: *
|
|
|
|
indicates a public message with no specifically enumerated recipients.
|
|
|
|
The fields Z-To: and/or Z-Bcc: MAY be present. At least one recipient field
|
|
MUST be present.
|
|
|
|
Z-To: zot:bob@example.com, zot:alice@example.com, mailto:dave@example.com
|
|
Z-Bcc: zot:https://example.com/profile/richard
|
|
|
|
are valid entries. Addresses are comma separated and individual entries MUST NOT
|
|
contain commas. There MAY be any number of ASCII space characters between
|
|
entries for legibility. Header lines are terminated with a linefeed character
|
|
(ASCII 0x0A).
|
|
|
|
This specification provides the following protocol address prefixes
|
|
for use in Z-To: or Z-Bcc: elements:
|
|
|
|
zot: - normal zot delivery using webfinger or LRDD resolvable address
|
|
dfrn: - legacy DFRN mode delivery using webfinger or LRDD resovable address
|
|
ostatus: - normal OStatus delivery using webfinger or LRDD resovable address
|
|
diaspora: - Diaspora network delivery using webfinger address
|
|
facebook: - Facebook profile page URL
|
|
twitter: - Twitter personal page URL without AJAX '#!' fragment
|
|
mailto: - email RFC822/ESMTP address
|
|
|
|
Examples:
|
|
|
|
twitter:http://twitter.com/bjensen
|
|
facebook:http://facebook.com/profile.php?id=000000001
|
|
|
|
Foreign protocol addresses which have not been defined in this specification
|
|
or future revisions of this specification and which are unknown to the
|
|
recipient delivery process MAY be ignored.
|
|
|
|
In cases where an address may contain either a webfinger or LRDD address, the
|
|
webfinger address SHOULD be used preferentially.
|
|
|
|
|
|
Z-Bcc:
|
|
******
|
|
|
|
The Z-Bcc element may contain one or more addresses which are hidden from end
|
|
user presentation. A zot receiving system MUST NOT store or allow for
|
|
the display of the Bcc information. Implementations which require extreme
|
|
privacy SHOULD send individual posts to each of the Bcc: recipients containing
|
|
only a single address. They MAY send all Bcc: posts using bulk delivery,
|
|
however this may have privacy implications as there is no guarantee a
|
|
receiving system will not log, store, or otherwise reveal the contents of the
|
|
Bcc recipient list.
|
|
|
|
Z-To: addresses MAY be shown to an end user.
|
|
|
|
|
|
Envelope encryption
|
|
*******************
|
|
|
|
|
|
The entire envelope is encrypted using alg with env_key and env_iv and
|
|
base64url encoded for transmission.
|
|
|
|
The zot envelope MAY include remote addresses. A zot inbound delivery agent
|
|
MUST parse the envelope 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 Z-To: or Z-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 type="http://purl.org/zot/1.0/version">1</Property>
|
|
<Property type="http://purl.org/zot/1.0/accept">application/atom+xml</Property>
|
|
|
|
|
|
Version is specified in this document and indicates the current revision.
|
|
Version is an increasing non-zero integer value. There are no minor versions.
|
|
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 to the remote system, the delivery to that system 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 (Zot-ID) authentication *
|
|
*******************************
|
|
|
|
This section of the document is considered separate from the delivery
|
|
specification precding it and represents a different protocol, which is
|
|
currently incomplete. This will be split off into another document in the
|
|
future, but is presented here as a synergistic component of the Zot network
|
|
model.
|
|
|
|
|
|
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/
|
|
|
|
Activity Stream Base Schema
|
|
http://activitystrea.ms/head/activity-schema.html
|
|
|
|
WebFinger Protocol
|
|
http://code.google.com/p/webfinger/wiki/WebFingerProtocol
|
|
|
|
|