From: friendica Date: Sat, 10 Mar 2012 03:50:31 +0000 (-0800) Subject: spec directory X-Git-Url: https://git.mxchange.org/?a=commitdiff_plain;h=0e3b9097f68e3bc6fcd3a9b18f0715951300bbd1;p=friendica.git spec directory --- diff --git a/spec/dfrn-snap2.jpg b/spec/dfrn-snap2.jpg new file mode 100755 index 0000000000..ee00f5654c Binary files /dev/null and b/spec/dfrn-snap2.jpg differ diff --git a/spec/dfrn2.odt b/spec/dfrn2.odt new file mode 100755 index 0000000000..390fc4bb85 Binary files /dev/null and b/spec/dfrn2.odt differ diff --git a/spec/dfrn2.pdf b/spec/dfrn2.pdf new file mode 100755 index 0000000000..e46225f7e9 Binary files /dev/null and b/spec/dfrn2.pdf differ diff --git a/spec/zot.txt b/spec/zot.txt new file mode 100755 index 0000000000..2c3bbb1800 --- /dev/null +++ b/spec/zot.txt @@ -0,0 +1,362 @@ +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). + + + + + ((key)) + ((iv)) + ((env_key)) + ((env_iv)) + ((envelope)) + ((sender signature)) + AES-256-CBC + ((salmon)) + + + +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). 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. Adresses 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: + + + + +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: + +1 +application/atom+xml + + +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/ + +Activty Stream Base Schema + http://activitystrea.ms/head/activity-schema.html + +WebFinger Protocol + http://code.google.com/p/webfinger/wiki/WebFingerProtocol + + diff --git a/zot.txt b/zot.txt deleted file mode 100755 index 2c3bbb1800..0000000000 --- a/zot.txt +++ /dev/null @@ -1,362 +0,0 @@ -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). - - - - - ((key)) - ((iv)) - ((env_key)) - ((env_iv)) - ((envelope)) - ((sender signature)) - AES-256-CBC - ((salmon)) - - - -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). 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. Adresses 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: - - - - -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: - -1 -application/atom+xml - - -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/ - -Activty Stream Base Schema - http://activitystrea.ms/head/activity-schema.html - -WebFinger Protocol - http://code.google.com/p/webfinger/wiki/WebFingerProtocol - -