document the ping packet - and remove the ancient rusty brown square default profile photos.

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) {