aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorfriendica <info@friendica.com>2013-11-28 16:13:09 -0800
committerfriendica <info@friendica.com>2013-11-28 16:13:09 -0800
commitff91541cfd753f0318f13835763bd86c5eafac53 (patch)
tree547d204b4e26736712828a5d9f42ad1d7f043ecc
parent2d7d145ebb3ac1a3d9282095be6246f4afdd2afe (diff)
downloadvolse-hubzilla-ff91541cfd753f0318f13835763bd86c5eafac53.tar.gz
volse-hubzilla-ff91541cfd753f0318f13835763bd86c5eafac53.tar.bz2
volse-hubzilla-ff91541cfd753f0318f13835763bd86c5eafac53.zip
zot doco
-rw-r--r--include/zot.php113
1 files changed, 96 insertions, 17 deletions
diff --git a/include/zot.php b/include/zot.php
index 0e92b0bff..6ee7665ee 100644
--- a/include/zot.php
+++ b/include/zot.php
@@ -353,7 +353,17 @@ function zot_refresh($them,$channel = null) {
* @function: zot_gethub
*
* A guid and a url, both signed by the sender, distinguish a known sender at a known location
- * This function looks these up to see if the channel is known. If not, we will need to verify it.
+ * This function looks these up to see if the channel is known and therefore previously verified.
+ * If not, we will need to verify it.
+ *
+ * @param array $arr
+ * $arr must contain:
+ * string $arr['guid'] => guid of conversant
+ * string $arr['guid_sig'] => guid signed with conversant's private key
+ * string $arr['url'] => URL of the origination hub of this communication
+ * string $arr['url_sig'] => URL signed with conversant's private key
+ *
+ *
* @returns: array => hubloc record
*/
@@ -380,6 +390,27 @@ function zot_gethub($arr) {
return null;
}
+/**
+ * @function zot_register_hub($arr)
+ *
+ * A communication has been received which has an unknown (to us) sender.
+ * Perform discovery based on our calculated hash of the sender at the origination address.
+ * This will fetch the discovery packet of the sender, which contains the public key we
+ * need to verify our guid and url signatures.
+ *
+ * @param array $arr
+ * $arr must contain:
+ * string $arr['guid'] => guid of conversant
+ * string $arr['guid_sig'] => guid signed with conversant's private key
+ * string $arr['url'] => URL of the origination hub of this communication
+ * string $arr['url_sig'] => URL signed with conversant's private key
+ *
+ *
+ * @returns array => 'success' (boolean true or false)
+ * 'message' (optional error string only if success is false)
+ */
+
+
function zot_register_hub($arr) {
$result = array('success' => false);
@@ -398,19 +429,43 @@ function zot_register_hub($arr) {
if($x['success']) {
$record = json_decode($x['body'],true);
- $c = import_xchan($record);
- if($c['success'])
- $result['success'] = true;
+
+ /*
+ * We now have a key - only continue registration if our signatures are valid
+ * AND the guid and guid sig in the returned packet match those provided in
+ * our current communication.
+ */
+
+ if((rsa_verify($arr['guid'],base64url_decode($arr['guid_sig']),$record['key']))
+ && (rsa_verify($arr['url'],base64url_decode($arr['url_sig']),$record['key']))
+ && ($arr['guid'] === $record['guid'])
+ && ($arr['guid_sig'] === $record['guid_sig'])) {
+
+ $c = import_xchan($record);
+ if($c['success'])
+ $result['success'] = true;
+ }
+ else {
+ logger('zot_register_hub: failure to verify returned packet.');
+ }
}
}
return $result;
}
-
-// Takes a json associative array from zot_finger and imports the xchan and hublocs
-// If the xchan already exists, update the name and photo if these have changed.
-//
+/**
+ * @function import_xchan($arr,$ud_flags = 1)
+ * Takes an associative array of a fecthed discovery packet and updates
+ * all internal data structures which need to be updated as a result.
+ *
+ * @param array $arr => json_decoded discovery packet
+ * @param int $ud_flags
+ * Determines whether to create a directory update record if any changes occur, default 1 or true
+ *
+ * @returns array => 'success' (boolean true or false)
+ * 'message' (optional error string only if success is false)
+ */
function import_xchan($arr,$ud_flags = 1) {
@@ -436,7 +491,6 @@ function import_xchan($arr,$ud_flags = 1) {
return $ret;
}
-
logger('import_xchan: ' . $xchan_hash, LOGGER_DEBUG);
$r = q("select * from xchan where xchan_hash = '%s' limit 1",
@@ -753,6 +807,20 @@ function import_xchan($arr,$ud_flags = 1) {
return $ret;
}
+/**
+ * @function zot_process_response($hub,$arr,$outq) {
+ * Called immediately after sending a zot message which is using queue processing
+ * Updates the queue item according to the response result and logs any information
+ * returned to aid communications troubleshooting.
+ *
+ * @param string $hub - url of site we just contacted
+ * @param array $arr - output of z_post_url()
+ * @param array $outq - The queue structure attached to this request
+ *
+ * @returns nothing
+ */
+
+
function zot_process_response($hub,$arr,$outq) {
if(! $arr['success']) {
@@ -788,14 +856,16 @@ function zot_process_response($hub,$arr,$outq) {
}
/**
- * @function: zot_fetch
+ * @function zot_fetch($arr)
*
- * We received a notification packet (in mod/post.php) that a message is waiting for us, and we've verified the sender.
- * Now send back a pickup message, using our message tracking ID ($arr['secret']), which we will sign.
- * The entire pickup message is encrypted with the remote site's public key.
- * If everything checks out on the remote end, we will receive back a packet containing one or more messages,
- * which will be processed before returning.
- *
+ * We received a notification packet (in mod/post.php) that a message is waiting for us, and we've verified the sender.
+ * Now send back a pickup message, using our message tracking ID ($arr['secret']), which we will sign with our site private key.
+ * The entire pickup message is encrypted with the remote site's public key.
+ * If everything checks out on the remote end, we will receive back a packet containing one or more messages,
+ * which will be processed and delivered before this function ultimately returns.
+ *
+ * @param array $arr
+ * decrypted and json decoded notify packet from remote site
*/
@@ -833,7 +903,16 @@ function zot_fetch($arr) {
* Process an incoming array of messages which were obtained via pickup, and
* import, update, delete as directed.
*
- * The message types handled here are 'activity' (e.g. posts), 'mail' and 'profile'
+ * @param array $arr => 'pickup' structure returned from remote site
+ * @param string $sender_url => the url specified by the sender in the initial communication
+ * we will verify the sender and url in each returned message structure and also verify
+ * that all the messages returned match the site url that we are currently processing.
+ *
+ * The message types handled here are 'activity' (e.g. posts), 'mail' , 'profile', and 'channel_sync'
+ *
+ * @returns array => array ( [0] => string $channel_hash, [1] => string $delivery_status, [2] => string $address )
+ * suitable for logging remotely, enumerating the processing results of each message/recipient combination.
+ *
*/
function zot_import($arr, $sender_url) {