Environment setup
=================

As described in the :ref:`security_auth` chapter, the relationship between the in-browser JavaScript code and the SCWS service must be established using a specific :ref:`webapp_certificate` provided by Idopte, and a challenge-response authentication scheme. The functions decribed below must be called before any other API methods to achieve this.

Client-side
-----------

.. js:autofunction:: SCWS.findService
.. js:autofunction:: SCWS.createEnvironment

Below is an example usage of these functions, with the call to a specific server-side ``signchallenge.php`` script to produce the required signature:

.. code-block:: js

	var webappcert = "4HfLHzMS05>]T+PeNPw<X/qE2d+7^Fi4*tXK5XUSpj-5F?v220vO$U&V?<[}t1$T{SgWs]g1wFx0t^wKX88E=tBG:>Q=?r-f-mJ4nre!!s7cqOJ0/Os@Kw?HHaS>ewC+WPnDEbhxh:6MUtZIt0+D^Wa2eO?(&l.>A0MDw!JF2K0[8TM{W^[FLaq?oRb{WDRmEmo#oEoV3e<fhfH[+Cl7y)FJF0fMO28[.s=0JC@3ymR*]Zxq!{^$KgsBYg/7Ad.EHJiiea.!K@G&:H=1&T{K</+P7k]^-6GnEr*GM=?6{8Sk&w.VduRhSE!kr)QHYv$yi";
	return SCWS.findService(webbappcert).then(function(challenge) {
		return new Promise(function(resolve, reject) {
			var req = new XMLHttpRequest();
			req.onreadystatechange = function () {
    			if (this.readyState === 4) {
					if (this.status === 200)
						resolve(req.responseText);
					else
						reject(new Error("Challenge signature failed"));
				}
			};
			req.open("GET", "signchallenge.php?rnd=" + challenge, true);
			req.send();
		}).then(function(signature) {
			return SCWS.createEnvironment(signature);
		})
	});

This will return a ``Promise`` resolved once the entire environment setup operation is done.

Environments can be explicitly destroyed using the following function:

.. js:autofunction:: SCWS.destroyEnvironment

The status of the underlying service can optionally be monitored by providing the following callback function:

.. js:autoattribute:: SCWS.onserviceunresponsive

Server-side
-----------

The web application server must be able to produce the signature from the challenge generated by the SCWS. This can be achieved with a script on the server side. Below is an example PHP implementation of the ``signchallenge.php`` script as required by the above client-side code:

.. code-block:: php

	<?php
		$k = <<<EOT
	-----BEGIN RSA PRIVATE KEY-----
	MIIBOgIBAAJBAMPMNNpbZZddeT/GTjU0PWuuN9VEGpxXJTAkmZY02o8238fQ2ynt
	N40FVl08YksWBO/74XEjU30mAjuaz/FB2kkCAwEAAQJBALoMlsROSLCWD5q8EqCX
	rS1e9IrgFfEtFZczkAWc33lo3FnFeFTXSMVCloNCBWU35od4zTOhdRPAWpQ1Mzxi
	aCkCIQD9qjKjNvbDXjUcCNqdiJxPDlPGpa78yzyCCUA/+TNwVwIhAMWZoqZO3eWq
	SCBTLelVQsg6CwJh9W7vlezvWxUni+ZfAiAopBAg3jmC66EOsMx12OFSOTVq6jiy
	/8zd+KV2mnKHWQIgVpZiLZo1piQeAvwwDCUuZGr61Ap08C3QdsjUEssHhOUCIBee
	72JZuJeABcv7lHhAWzsiCddVAkdnZKUo6ubaxw3u
	-----END RSA PRIVATE KEY-----
	EOT;
		$output = "";
		openssl_private_encrypt(hex2bin($_GET["rnd"]), $output, openssl_pkey_get_private($k));
		echo bin2hex($output);
	?>

The key included in this script represents the :ref:`security_auth` key generated on the customer's side, whose public key is provided to Idopte when requesting the :ref:`webapp_certificate`.

.. caution::

	Note that the above script does not check the origin of the request. This is volontary, as ensuring that the request effectively comes from a valid client is the responsibility of the web application developer, and depends on the architecture of the entire application. However, not checking the origin of the request before producing the signature is a security weakness and should be avoided. Standard methods such as cookies, or session mechanisms, can be used to solve this requirement.