Example code for Homing Space

This documentation is deprecated. The process is MUCH simpler now

This page contains 3 files that a merchant's tech team has to create; in order to welcome Homing Space users onto their website! The 3 files we wrote are in PHP, but you can use any suitable language.

Read the technical documentation on how and when to use these three files.

First File
This is the first file. Let's call this "merchant.php" 

It contains the form with practically just TWO input form. The first input asks for the user's persona username. The second one is hidden or read-only.  It's value would be a specially formatted string that contains the scope names (explained in the tech documentation)

You MUST state clearly the Homing Space username of the person whos keys were used to manage this entry into your website. Why? Because that name would be presented to the user coming in and he/she should not get confused.

If you want you can also add recaptcha into this form; if you think hackers are going to keep submitting this form. But NEVER ask for any other inputs from the user -- especially password!

<div align="center"> <h2>NiceLaundry</h2> <i><small>Dont wash dirty laundry in public! Keep your data private!</small></i> <hr/> <form action="homingentry-sign.php" method="POST"> Your Homing Space name <input name="u" /><br/> The data that will be collected from your Homing Space <input name="s" readonly="true" value="fullname;email|birthday" /><br/> <input type="submit" value="Simply enter!"/> <br/><br/> <i>This site is managed by [merchand]</i> <!-- change the username "merchand" to the Homing Space persona username, of that person and who is the creator/manager for this website--> </div>

Second File

This actually contains the main business logic. Let us call this "homingentry-sign.php"

This file is the "action"  for the first file. This file uses the libsodium (NaCL) library to do the cryptographic signing, etc.

<?php header('Content-type: text/html'); ////////////////////USAGE///////////////////////////////// // Usage: // // First ensure that the configuration below is // all correct // // // Then $_POST to this module. // // That is done by a login page which has // a post form with 2 fields (2nd one can // be hidden). The action of that form // would be this page you are reading now // // Two input fields named: u and s, are needed // u is the username typed by the user and s // is the scopes that the merchants site would pick up // // You could define $scopes here itself but // it is more polite to define it at the main // entry form where the user types his/her // homing space name -- so that the user // is aware RIGHT at the beginning the list of private // data that are picked up from the user // That way the user is well informed whether // to enter the site or go away // // See the sample PHP file merchant.php //The Scopes have this format: //Before pipe character = mandatory //After pipe character = optional //Delimiter should be semicolon //The entire list of possible scopes //that a merchant can ask for can //grow over time. Check the latest //at https://my.homing.space/scopes.txt //Example: $scopes="fullname;email|birthday"; //This is a pass-thru server module //It actually would take the user //to the my.homing.space site after //setting up all the values //that are crucial data for my.homing.space //The actual work is done at my.homing.space/enter.yaws /////////////////////////////////////////////////////////// ///////////////////////Configuration////////////////////// //All the configuration variables are MANDATORY //Merchant pays Homing Space for each login //(a very tiny amount per login. Free for //the initial days of Homing Space) //So Merchant has to setup a SecretSauce //and its accompanying code $secret_sauce= "drserstsrtt"; //Never EVER reveal this in any client side Javascript, etc //Each $secret_sauce has a code associated with it //That needs to be specified here. The $secret_sauce //is to be obtained from https://my.homing.space/secretsauce.yaws $secretSauceCode= "MIDEDFEE"; //This secret sauce would be checked at Homing Space //So that both the merchant and Homing Space knows //they are on the same page. (Get it? "same page" hehehe) //See below on how the such secretsauce makes the OTP for //Homing Space to count the login //The secret Sauce ideally should be only for this specific site //So that the auditing of the charges becomes very clear. However //if the mechant chooses, the same secret sauce can be used //on multiple sites -- but then the login counter would //grow rapidly as it would increment the counter at the login //of any those sites. //A merchant can easily obtain one pair (secret sauce, and its code) //at https://my.homing.space/secretsauce.yaws //Initially after the launch of Homing Space, all usage of the secret //sauce is totally free, so hurry and get your code fast! // This is the folder where the merchant // has saved his/her own private key of his/her own // homingspace registration // One the merchant picks up his/her own account at Homing Space // visit https://my.homing.space/reveal.yaws to get the values // of the secret keys -- as those would be saved // inside the phone of the merchant $serverdatadir = "./serverdata/"; //This is the filename used $serversecret_sign= "serversecret_sign.txt"; //The merchant ALSO needs to use the Homing Space himself/herself //So specify that Homing Space ID here. $merchant_homing_name = "merchand"; //This is the title that gets displayed to the user when entering $merchant_site_title="NiceLaundry welcomes you"; //This is merchant's own salt. NOT known to homing.space //make sure it does NOT seen by anyone. Not even homing space. $ourprivatesalt = "adfstwsfswtwsvsdf"; ///// Largely, the rest of the code can be left untouched //// //// But do read this section: UNDERSTANDING THE ENDPOINT //// if you want to customize this /////////////////////////////////////////////////////////////// //I did not use composer install; instead //I used 'manual' installation from the github sites require_once "sodium_compat-1.7.0/autoload.php"; require_once "random_compat-2.0.17/lib/random.php"; $u= $_POST['u']; $scopes= $_POST['s']; $tim = time(); //Server time instead of browser time //The homing.space server has the correct time //But in this version, we pass $tim to homing.space. //So there are no chances of errors. In a future //version, Homing Space may check the time too // //See POST form below //This otp is verified by Homing Space, so that the //successful login can be counted, the "accounts payable" //of the merchant is properly updated $otp = md5($secret_sauce.$u.$tim); ////////////////////// UNDERSTANDING THE ENDPOINT ///////////////////// ////////// SUGGESTED method to create an endpoint //////////(where the user lands after authentication) // // This is a suggested way to pass on // Merchants own OTP to the endpoint. // The idea is that when the user finally reaches // the endpoint, the merchant should know who // was it. This is done using another otp (otp2, configured earlier) // but this time it is for the merchants own satisfaction // ////////////////////////////////// $otp2= md5($ourprivatesalt.$u.$tim); //Of course the merchant can another logic here //accessing a database, etc. // //But we think this strategy is good enough. //We feel no database need to be accessed //at this stage. Let the user land at the //specified endpoint and only then the merchant can //do all the session-cookie setting, database //checks, add to the database, etc //This otp2 is checked by the merchant when the user finally goes to //its own site's endpoint... Maybe the endpoint may //reject if the $tim has gone on too long //(To prevent replay of the same endpoint after some pre-decided time. // But all that is left to the merchant // On how exactly the endpoint reacts when the user appears there) $TheEndPointUrl = "https://simplysign.in/test.php?otp=$otp2&u=$u&scopes=$scopes"; //NOTE: the ENTIRE url of the ENDPOINT has to be specified above //ALL the query string parameters are optional; but it is quite //likely that you COULD BE including $u :-) //Apart from the actual parameters you attach here //our system would ALSO pass the "fingerprint" of the user //in the Query string as "f_in_g" when the user actually //comes to this endpoint. Read the docs, and below: ///////////////IMPORTANT: Preventing sock-puppet accounts///////////////////// //Before the user reaches the endpoint, the "fingerprint" of the user //is also sent by Homing space. An extra field would be added to the //other field passed on by the above endpoint query_string (otp, u, scopes) // //This special field is called: "f_in_g" The merchant can make use of //its value for its own housekeeping! // //The merchant can check if the same user is coming under //a different persona name // //(Remember a user can have 7 personas in Homing Space. // But all would have same fingerprint!) //The merchant can choose to disallow the same person taking more than one //accounts at the same site of the merchant. For e.g. if there is a merchant //offering some 10Gb space free, some people may want to get 20 Gb by //registering twice there. But this f_in_g can catch most of such attempts // //Though this does NOT prevent a complete prevention of fake, //sybil (sock-puppet) accounts but it can surely reduce a large number of them ////////////////////////////understanding endpoint//////////////////// $server_sk64 = trim(file_get_contents("$serverdatadir$serversecret_sign")); $server_sk= base64_decode($server_sk64); //The signing is done on string that concatenates the time with the endpointurl //This is IMPORTANT, as that is how the user comes to know that indeed //This merchant was the right one $signature = \Sodium\crypto_sign_detached($tim.$TheEndPointUrl, $server_sk); $signature_base64 = base64_encode($signature); //After signing, all the required parameters are posted directly to //my.homing.space for processing there. //This is an ephemeral pass-thru form. //DO NOT CHANGE Anything below ?> <form name="enterhom" id="enterhom" action="https://my.homing.space/enter.yaws" method="POST"> <input type="hidden" name="sig" value="<?= $signature_base64; ?>"/> <input type="hidden" name="ept" value="<?=$TheEndPointUrl; ?>" /> <input type="hidden" name="mtitle" value="<?=$merchant_site_title;?>" /> <input type="hidden" name="otp" value="<?=$otp; ?>" /> <input type="hidden" name="merchname" value="<?=$merchant_homing_name;?>" /> <input type="hidden" name="servid" value="<?= $secretSauceCode;?>" /> <input type="hidden" name="u" value="<?= $u; ?>"/> <input type="hidden" name="tim" value="<?=$tim; ?>"/> </form> <script> //alert("Name = <?= $u; ?>"); document.getElementById("enterhom").submit(); </script>

Third File

The following is the 3rd file -- the end point which the user eventually comes to (once he/she is authenticated) This file is the one that finally takes the person into the merchant's website.

In this example we are merely showing the $_GET and $_POST variables. that are available here.  

Obviously this endpoint is a serious piece of code for your website -- you would need to check your special OTP that got passed here, you may need to chedck the fingerprint of the user (in case he/she had come with another persona username), dataase activities, Session cookie activities and so on. 

In case of mobile-apps, you would need to redirect the browser to open your app on the phone.

In case the website is working on a regular computer, then the job of this particular code is to give a special numeric OTP displayed on the screen of the browser -- so that the user can then enter that into his computer, and get inside!

VERY IMPORTANT: The full URL of this endpoint MUST be given in the second file, if the browser has to return back here!

<?php header("Content-type: text/plain"); echo "\n\nWelcome!\nIf you can read this, it means the Test Merchant has allowed you in! The strange stuff you can read below are all for programmers who want to implement Homing Space way of welcoming users! Take care and have a nice day! -------------------------------------------------\n\n"; echo "The GET query_string:\n_______________\n"; print_r($_GET); echo "\nThe POST variables:\n___________________\n"; print_r($_POST);