6.1. Use of control signatures

Simpoll API offers control signatures mechanism to make data transfer between your site and polls secure.

Control signature — is MD5 hash from line composed of listed transferred parameter. «Salt» — secret key set in poll settings at «API» tab and added before hashing for support of confidentiality. Since the key is known only to you and Simpoll — the violator won’t be able to fake the signature, even if he knows its creation algorithm.

For the use of control signatures, the corresponding option in poll parameters on «API» tab should be enabled.

6.2. Signature of parameters sent to poll

The section 5 contains example of code sending parameters to the poll through hidden field. Since the content of this field if visible for a visitor, he can fake the page by changing parameters sent in this field. Control signature helps to avoid it.

Signature is MD5 hash from line consisting of secret key and values of all transferred parameters divided by colon:

					MD5 ( key:parameter1:parameter2 )

				

Parameter values in signature should be listed in the same order in which they appear in inquiry line.

Once formed the signature will be added to general list as a usual parameter with name sig.

Example of sending parameters to the poll (with control signature):

					<?php

						// Key of the poll control signature
						// is set in poll parameters on "API" tab
						$survey_secret_key = 'q1w2e3r4';

						// Array of parameters to be sent to
						// our site once the poll is passed.
						// Can be formed dynamically, if necessary.
						$params_arr = array(
							'user_id' => 123,
							'user_login' => 'anonymous'
						);

						// Create control signature for parameter array
						$signature = md5( $survey_secret_key . ':' . implode(':', $params_arr) );

						// Add control signature to parameter list
						$params_arr['sig'] = $signature;

						// Create URL-coded inquiry line
						$params_str = http_build_query($params_arr);

					?>

					<!—Create field with inquiry line -->
					<input type="hidden" id="simpoll_params" value="<?php echo $params_str; ?>" />

					<!—Connect the poll -->
					<script type="text/javascript" src="http://simpoll.pro/embed/framejs/aa7ca07e"></script>

				

Now if user changes any parameter, the signature will become invalid and Simpoll won’t show the poll and will notify the user on error.

6.3. Signature of poll results

The signature is created on the basis of another algorithm for the results sent to your site by Simpoll.

Since there is one or several arrays in response of Simpoll, the signature is made of poll's secret key and the line received after serialization of array with the answer:

					MD5 ( key:SERIALIZE( result array ) )

				

To check the signature by your side you should create it on the basis of results received from Simpoll and compare it with the signature sent from Simpoll. If received signatures mismatch, then the answer is considered invalid and the results should be rejected.

For example, you get the response from Simpoll through result.php script by POST method —

Example of signature check:

					<?php

						// Key of poll’s control signature
						// is set in parameters on "API" tab
						$survey_secret_key = 'q1w2e3r4';

						// Receive parameters sent from Simpoll through POST
						$results = $_POST;

						// Save signature received from Simpoll
						// and remove it from the list of results
						$server_sig = $results['sig'];
						unset($results['sig']);

						// Create own control signature
						// on the basis of key and results received from Simpoll
						$signature = md5( $survey_secret_key . ':' . serialize($results) );

						// Compare signatures
						if ($server_sig == $signature) {

							// ... signatures match, response is reliable ...

						} else {

							// ... signatures mismatch, exit ...
							exit;

						}

					?>
				

If $ _POST array (or $ _GET, depending on method) can contain parameters that are not connected with Simpoll (for example, parameters added by your CMS at every inquiry), then they should be deleted from result array to prevent their influence on formation of signature.

All parameters sent by Simpoll has prefix sp_, except of parameters that were sent by you.