Integrating VouchSafe with Your Web Application

Getting Started

To get started with VouchSafe, you need to do the following:

  1. Create an account and register your domain with us to get a public / private key pair for your website.
  2. Include vouchsafe-lip.php in your project.
  3. Integrate VouchSafe into the front-end HTML form where you want the challenge to appear.
  4. Integrate VouchSafe with the back-end handler for the form or application you want to protect.

You can use the sample PHP Lib file included in this package to simplify integration with your website if you’re using PHP. You’ll find that setting up VouchSafe is virtually identical to integrating other key-based validation services like reCaptcha.

 

Public Methods Exposed by the VouchSafe API

VouchSafe’s public interface only exposes two methods: Generate, (which generates a new challenge and the HTML required to embed it in a web form), and Validate, (which examines a response submitted by a user and returns success or failure).

You can access these methods directly if you care creating your own custom code. However, it’s better if you wrap this functionality with a few helper methods as we have done in vouchsafe-lib.php. We recommend that you use vouchsafe-lib.php as a guide to developing your application even if you’re not using PHP.

The VouchSafe core methods are discussed in more detail later in this document.

 

vouchsafe-lib.php Key Functions

The key functions declared in vouchsafe-lib.php are documented below:

vouchsafe_get_html($publicKey, $serverUrl = ‘http://api.vouchsafe.com’): string


This function is used to generate a VouchSafe challenge to place on a web page or in a web form. When invoked, it will generate a block of HTML and corresponding HTML5/JavaScript functionality which you can simply insert into your page wherever you want the VouchSafe validation button to appear.

@param $publicKey: This is the public portion of the key pair which you receive when you register your domain with us. You must include this key in order to receive a response

@param $serverURL: This is the URL of the VouchSafe API server. Do not modify this URL unless we notify you.

@return: This function will return a URL encoded string which is the script which is used to generate the VouchSafe button and embed client-side functionality. This script contains a source which points to the VouchSafe server. The VouchSafe button will appear wherever you insert this code into your page.

 

vouchsafe_check_answer($privateKey, $challengeID, $response, $respondentIP, $serverUrl = ‘http://api.vouchsafe.com’, $extra_params = array()): VouchSafeResponse

This function is used to check the response submitted by a user. It returns true or false based on the response from the VouchSafe server after validating the answer. If the response is true, you can accept the user input. If the response is false, you can reject the user input.

@param $privateKey: This is the private portion of the key pair which you receive when you register your website with us along with the public key. This key must be kept privately and be used to validate the answer from the users. Without a private key, the answer cannot be validated. If a response is submitted without a valid private key, the VouchSafe server will return the error PrivateKey_NotFound.

@param $challengeID: is the ID of the current challenge, (which is provided as part of the package in response to Generate a challenge). When a page which includes VouchSafe validation is loaded, a new challenge is sent from the VouchSafe server to this page. This new challenge has an ID which will be posted along with the form when users click Submit. You must send this ID when submitting a user response for validation.

@param $response: This is an array which contains the path information which is generated when the user completes a challenge.

@param $respondentIP: This is the current IP of the server where your website is hosted.

@param serverURL: This is the URL of the VouchSafe server where the response will be sent.  This will be http://api.vouchsafe.com unless we notify you of a change in service.

@param $extra_params: This is an array of all extra parameters you want to handle when users click submit the form, (eg: the content from other form fields and elements). Note that in addition to processing these parameters if the response validates as true, you may want to use them to repopulate the form elements if the response validates as false, so the user doesn’t have to retype the form contents.

@return: this function will return a VouchSafeResponse object, which contains two variables: $is_valid (true or false) and $error, which is the error string returned if $is_valid is false.


 

Step-by-Step Instructions for Use

  1. Include vouchsafe-lib.php as a dependency in your project.
  2.  

  3. Create a script that calls vouchsafe_get_html() and inserts it into the page or web form you’d like to validate with VouchSafe. When you request this page in a browser, you should see the VouchSafe button a the point you inserted the HTML generated by vouchsafe_get_html(). The button should work right away and should pop open a VouchSafe challenge when you click on it.
    1. If you receive a loading error (error 102), it means your public key is invalid. Also, please note that the VouchSafe API server will not let you access the service from a localhost domain. You have to change your localhost domain to localhost.valid-domain at port 80.
  4.  

  5. In order to validate a user response, there are two inputs from the VouchSafe form will be sent along with the rest of the form data when the user presses the submit button:
    1. VouchSafe-challenge-id: this is an input entry from VouchSafe form when you include the script. This input contains the challenge ID whenever a challenge is sent from the server. You can simply use $_POST[“VouchSafe-challenge-id”] to retrieve this input.
    2. VouchSafe-challenge-response: this is the input which contains the path which users draw on the VouchSafe canvas. You can retrieve this input by using $_POST[“VouchSafe-challenge-response”]
    3. The two inputs above are used to provide the parameters for the function VouchSafe_check_answer(), and correspond to $challengeID, and $response.
  6.  

  7. The other two parameters that must be declared are the local IP address and the private key.
    1. The Local IP address can be retrieved with the PHP $_SERVER['REMOTE_ADDR'] environment variable.
    2. The private key is assigned to you when you register your domain at VouchSafe.com
    3. These two parameters correspond to the $privateKey and $respondentIP parameters for the VouchSafe_check_answer() function
  8.  

  9. Once you have all of the parameters, it’s time to send the answer to the server. If you use the function VouchSafe_check_answer() to validate your answer, you will receive a true or false response. The response from the server is in JSON format as the following: {‘Success’: true, “Message”: “Success”}. If the response is unsuccessful, the Message variable will include one of the following errors:
    1. PublicKey_NotFound: the public is invalid or does not exist. Verify your public key 
    2. PublicKey_WrongDomain:  
    3. PrivateKey_NotFound: the private key is invalid. Verify your private key on our website. 
    4. Parsing_BadPublicKeyFormat: 
    5. Parsing_BadPrivateKeyFormat: 
    6. Challenge_NoChallengeMatchGivenParameters:
  10.  

  11. If you don’t receive any of the errors above but still receive the false validation, it likely means the answer is incorrect. If the validation returns as a success, then the answer is correct.
  12.  

  13. If those errors persist, please contact us, and we’ll do our best to help you resolve the issue.

 

vouchsafe-lib.php Helper Functions

These functions are called internally and don’t need to be wired up directly to your application:

_vouchsafe_http_post($host, $path, $data, $port = 80): string


This is a private helper function which does the actual work of requesting a validation  (Validate) response from the VouchSafe API server. This function is invoked within vouchsafe_check_answer().

is the VouchSafe API server URL (http://api.vouchsafe.com)

@param $path: “/Challenge/Validate” (path to invoke the Validate method of the VouchSafe API)

@param $data: is an array which has the following format: array(
‘PrivateKey’ => $privateKey,
‘StringChallengeKey’ => $challengeID,
‘StringPath’ => $response,
‘RespondentIP’ => $respondentIP,
‘Host’ => $_SERVER[‘HTTP_HOST’]).

@param $port: is 80 by default

@return: this function will return a VouchSafeResponse object  

 

_vouchsafe_qs_encode($data) : string


This function is simply used to URL encode form data into a properly formatted query string preparatory to submitting it to the VouchSafe API server.  This function is invoked within _vouchsafe_http_post().

@param $data: array of string elements to be encoded

@return: string – Query string encoded request


VouchSafe Web Service API

These are the actions exposed directly by the VouchSafe Web Service API.  The functions defined in vouchsafe-lib.php simply make it easier to access and invoke these actions properly:

Generate(PublicKey): URL-encoded string


This action returns the JavaScript necessary to include a challenge on a web form. You should generally call it directly from a <script> “src” attribute.

@param PublicKey: this is the public portion of the key pair assigned to your domain when you register with VouchSafe

@return: URLencoded string

Example: http://api.vouchsafe.com/Challenge/Generate?PublicKey=”[PublicKey]”

 

Validate(PrivateKey, StringChallengeKey, StringPath, RespondentIP, Host): URL-encoded string


This action is used to submit a completed challenge to the VouchSafe Web Service for validation.

WARNING: To ensure the stability and responsiveness of our system, we have multiple servers running our Web Service. It is important that the Validation request be made to the same server that generated the challenge for the current visitor. This is done by reading the “vouchsafe-server-token” hidden field from the received form and by inserting it into the following URL template :

http://www.api i.e. if ServerToken = “1”, URL is  http://www.api

The ServerToken can either be an empty string OR a string containing a positive integer number. If it contains anything else, someone has modified the VouchSafe data manually. In such a case, do not call Validate, simply assume that the challenge has failed.

@param PrivateKey: This is the private portion of the key pair assigned to your domain when you register with VouchSafe

@param StringChallengeKey: this is the content of the “vouchsafe-challenge-id” hidden input field added to your form by the VouchSafe challenge.

@param StringPath: this is the content of the “vouchsafe-challenge-response” hidden field added to your form by the VouchSafe challenge.

@param RespondentIP: this is the IP address of the user who completed the challenge

@param Host: HTTP_HOST environment variable

@return: JSON encoded string containing an object with two properties, Success (bool) and Message (string)

 

Example: http//api1.vouchsafe.com/Challenge/Validate?PrivateKey=”[PrivateKey]”&StringChallengeKey=
”[StringChallengeKey]”&StringPath=”[StringPath]”&RespondentIP=”[RespondentIP]”&Host=”[Host]”

 

Error codes and Messages

Error codes/messages displayed on the VouchSafe button or returned after a failed VouchSafe Validation:

Error Code

Error Message

Explanation

100

Parsing_BadChallengeGuidFormat

The challenge key given is not a valid GUID. Make sure you are correctly using the value from the “vouchsafe-challenge-id” hidden field.

101

Parsing_BadPathFormat

The path string given contains invalid data. Make sure you are correctly using the value from the “vouchsafe-challenge-response” hidden field.

102

Parsing_BadPublicKeyFormat

The public key used is not a valid GUID. Verify your public key.

103

Parsing_BadPrivateKeyFormat

The private key used is not a valid GUID. Verify your private key.

300

Path_StartMissed

User did not start his path on the correct object

301

Path_EndMissed

User did not end his path on the correct object

302

Path_CrossedUnrelated

User path crossed an object not part of the solution

303

Path_PointsTooDistant

Points in the path were too distant from one another.

304

Path_CrossedItself

User path crossed itself but challenge is not an Exclusion challenge

305

Path_IsNotPolygon

User path is not a polygon but challenge is an exclusion challenge

306

Path_SolutionInsidePercentTooLow

The solution object is not inside the user path

307

Path_FillerInsidePercentTooHigh

Non-solution objects are inside the user path

350

Audio_BadEntry

The user answer to the audio challenge is invalid

401

PublicKey_NotFound

We could not find a key pair associated with the given public key. Verify your public key.

402

PublicKey_WrongDomain

The public key used is associated with a key pair that is not global or that defines a domain different from the current one. Make sure that the public key used is associated with the correct domain.

Also, please note that the VouchSafe Web Service will not let you access the service from a localhost domain. You have to change your localhost domain to localhost.valid-domain at port 80.

 

501

PrivateKey_NotFound

We could not find a key pair associated with the given private key

OR

The private key used is associated with a key pair that is not global or that defines a domain different from the current one.

Please verify the private key used and make sure it is associated with the correct domain.

601

Response_NoMatchFound

You are requesting validation for a challenge that has not been served or the respondent IP does not match the IP from which the challenge was originally requested. Make sure you are using the value from the “vouchsafe-challenge-id” and the proper visitor’s IP.

602

Response_SessionTimeout

You requested a validation for a challenge that was generated too long ago and has since expired.

800

System_Exception

An unknown exception happened during the Validation process. If you keep receiving this error please contact us.