diff options
Diffstat (limited to 'zot.txt')
| -rw-r--r-- | zot.txt | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/zot.txt b/zot.txt new file mode 100644 index 000000000..0704875af --- /dev/null +++ b/zot.txt @@ -0,0 +1,304 @@ +This is the Zot! social communications protocol. + +Specification revision: 1 +02 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. 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 + + |