diff options
Diffstat (limited to 'mod/post.php')
| -rw-r--r-- | mod/post.php | 175 |
1 files changed, 165 insertions, 10 deletions
diff --git a/mod/post.php b/mod/post.php index b425bc59d..d61f5d69e 100644 --- a/mod/post.php +++ b/mod/post.php @@ -243,10 +243,134 @@ function post_init(&$a) { * * Once decrypted, one will find the normal json_encoded zot message packet. * - * Standard packet: + * Defined packet types are: notify, purge, refresh, auth_check, ping, and pickup + * + * Standard packet: (used by notify, purge, refresh, and auth_check) + * + * { + * "type": "notify", + * "sender":{ + * "guid":"kgVFf_1...", + * "guid_sig":"PT9-TApzp...", + * "url":"http:\/\/podunk.edu", + * "url_sig":"T8Bp7j5...", + * }, + * "recipients": { optional recipient array }, + * "callback":"\/post", + * "version":1, + * "secret":"1eaa...", + * "secret_sig": "df89025470fac8..." + * } + * + * Signature fields are all signed with the sender channel private key and base64url encoded. + * Recipients are arrays of guid and guid_sig, which were previously signed with the recipients private + * key and base64url encoded and later obtained via channel discovery. Absence of recipients indicates + * a public message or visible to all potential listeners on this site. + * + * "pickup" packet: + * The pickup packet is sent in response to a notify packet from another site + * + * { + * "type":"pickup", + * "url":"http:\/\/example.com", + * "callback":"http:\/\/example.com\/post", + * "callback_sig":"teE1_fLI...", + * "secret":"1eaa...", + * "secret_sig":"O7nB4_..." + * } + * + * In the pickup packet, the sig fields correspond to the respective data element signed with this site's system + * private key and then base64url encoded. + * The "secret" is the same as the original secret from the notify packet. + * + * If verification is successful, a json structure is returned + * containing a success indicator and an array of type 'pickup'. + * Each pickup element contains the original notify request and a message field whose contents are + * dependent on the message type + * + * This JSON array is AES encapsulated using the site public key of the site that sent the initial zot pickup packet. + * Using the above example, this would be example.com. + * + * + * { + * "success":1, + * "pickup":{ + * "notify":{ + * "type":"notify", + * "sender":{ + * "guid":"kgVFf_...", + * "guid_sig":"PT9-TApz...", + * "url":"http:\/\/z.podunk.edu", + * "url_sig":"T8Bp7j5D..." + * }, + * "callback":"\/post", + * "version":1, + * "secret":"1eaa661..." + * }, + * "message":{ + * "type":"activity", + * "message_id":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu", + * "message_top":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu", + * "message_parent":"10b049ce384cbb2da9467319bc98169ab36290b8bbb403aa0c0accd9cb072e76@podunk.edu", + * "created":"2012-11-20 04:04:16", + * "edited":"2012-11-20 04:04:16", + * "title":"", + * "body":"Hi Nickordo", + * "app":"", + * "verb":"post", + * "object_type":"", + * "target_type":"", + * "permalink":"", + * "location":"", + * "longlat":"", + * "owner":{ + * "name":"Indigo", + * "address":"indigo@podunk.edu", + * "url":"http:\/\/podunk.edu", + * "photo":{ + * "mimetype":"image\/jpeg", + * "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5" + * }, + * "guid":"kgVFf_...", + * "guid_sig":"PT9-TAp...", + * }, + * "author":{ + * "name":"Indigo", + * "address":"indigo@podunk.edu", + * "url":"http:\/\/podunk.edu", + * "photo":{ + * "mimetype":"image\/jpeg", + * "src":"http:\/\/podunk.edu\/photo\/profile\/m\/5" + * }, + * "guid":"kgVFf_...", + * "guid_sig":"PT9-TAp..." + * } + * } + * } + *} + * + * Currently defined message types are 'activity', 'mail', 'profile' and 'channel_sync', which each have + * different content schemas. + * + * Ping packet: + * A ping packet does not require any parameters except the type. It may or may not be encrypted. + * + * { + * "type": "ping" + * } + * + * On receipt of a ping packet a ping response will be returned: + * + * { + * "success" : 1, + * "site" { + * "url" : +ping, and pickup + * + * Standard packet: (used by notify, purge, refresh, and auth_check) * * { - * "type": $message_type, + * "type": "notify", * "sender":{ * "guid":"kgVFf_1...", * "guid_sig":"PT9-TApzp...", @@ -260,9 +384,10 @@ function post_init(&$a) { * "secret_sig": "df89025470fac8..." * } * - * Signature fields are all signed with the sender's private key. - * Recipients are arrays of guid and guid_sig which were signed with the recipients private - * key and obtained via channel discovery. + * Signature fields are all signed with the sender channel private key and base64url encoded. + * Recipients are arrays of guid and guid_sig, which were previously signed with the recipients private + * key and base64url encoded and later obtained via channel discovery. Absence of recipients indicates + * a public message or visible to all potential listeners on this site. * * "pickup" packet: * The pickup packet is sent in response to a notify packet from another site @@ -276,7 +401,8 @@ function post_init(&$a) { * "secret_sig":"O7nB4_..." * } * - * In the pickup packet, the sig fields are the relevant data element signed with this site's system private key. + * In the pickup packet, the sig fields correspond to the respective data element signed with this site's system + * private key and then base64url encoded. * The "secret" is the same as the original secret from the notify packet. * * If verification is successful, a json structure is returned @@ -347,12 +473,41 @@ function post_init(&$a) { * * Currently defined message types are 'activity', 'mail', 'profile' and 'channel_sync', which each have * different content schemas. + * + * Ping packet: + * A ping packet does not require any parameters except the type. It may or may not be encrypted. + * + * { + * "type": "ping" + * } + * + * On receipt of a ping packet a ping response will be returned: + * + * { + * "success" : 1, + * "site" { + * "url":"http:\/\/podunk.edu", + * "url_sig":"T8Bp7j5...", + * "sitekey": "-----BEGIN PUBLIC KEY----- + * MIICIjANBgkqhkiG9w0BAQE..." + * } + * } + * + * The ping packet can be used to verify that a site has not been re-installed, and to + * initiate corrective action if it has. The url_sig is signed with the site private key + * and base64url encoded - and this should verify with the enclosed sitekey. Failure to + * verify indicates the site is corrupt or otherwise unable to communicate using zot. + * This return packet is not otherwise verified, so should be compared with other + * results obtained from this site which were verified prior to taking action. For instance + * if you have one verified result with this signature and key, and other records for this + * url which have different signatures and keys, it indicates that the site was re-installed + * and corrective action may commence (remove or mark invalid any entries with different + * signatures). + * If you have no records which match this url_sig and key - no corrective action should + * be taken as this packet may have been returned by an imposter. + * */ - - - - function post_post(&$a) { |