Integrating VouchSafe with Your .Net Application

How it works

Integrating VouchSafe into your .Net website is very easy with the help of the VouchSafe .Net API:

  1. Create an account and register your domain with us to get a public / private key pair for your website.
  2. Add a reference to VouchSafeAPI.dll into your project
  3. Add a <script> tag into the form you want to protect with VouchSafe and set its “src” attribute to the return value of the VouchSafe.GetScriptUrl method.
  4. In the code handling the form submission, call the VouchSafe.Validate method with the proper information. Inspect the VouchSafeResponse object returned to determine if the visitor completed the challenge successfully and take action in consequence.

You’ll find that setting up VouchSafe is virtually identical to integrating other key-based validation services like reCaptcha.

 

VouchSafe Web Service

VouchSafe Web Service only exposes two methods: Generate, (which returns the JavaScript responsible for adding and handling the VouchSafe challenge to a 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 a lot easier to simply use the helper methods provided by VouchSafeAPI.dll.

The VouchSafe API methods are discussed in more detail in the following section.

 

VouchSafeAPI Methods

GetScriptUrl(string PublicKey, [string ServerUrl]) : string

This method generates an URL pointing to the Generate action of VouchSafe Web Service. To include a VouchSafe challenge in your form include a <script> tag inside it and set its “src” attribute to the returned URL like so:

<script type="text/javascript" src="/GetScriptUrl_Return_Value_Here"></script>

When someone visits your web page, the VouchSafe challenge will appear in the form at the place where you have put the <script> tag. The exact way to get the returned URL inside your HTML will depend on the framework you are using.

@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 challenge.

@param serverURL: This is the URL of the VouchSafe Web Service. Do not modify this URL unless we notify you.

@return: This function will return a URL to the Generate method of our public API with your PublicKey as a parameter. As stated above, insert this URL as the “src” of a <script> tag inside the form you want to protect with VouchSafe.

 

Validate(HttpRequestBase Request, string PrivateKey, [string ServerUrlTemplate]) : VouchSafeResponse

or

Validate(HttpRequest Request, string PrivateKey, [string ServerUrlTemplate]) : VouchSafeResponse


This method extracts the VouchSafe challenge information from the given request and sends it to our server for validation. It then returns a VouchSafeResponse object that contains the validation result.

@param: Request: This is the standard HTTP request received after the user submits the form. This method is overloaded with either HttpRequest or HttpRequestBase to cover a wider array of scenarios.

@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 serverUrlTemplate: This is the URL of the VouchSafe Web Service. Do not modify this URL unless we notify you.

@return: this function will return a VouchSafeResponse object, which contains two properties:

  • bool Success: true if the challenge validation was successful, false otherwise
  • string Message: Contains an error message when the validation is unsuccessful.

 

Step-by-Step Instructions for Use

  1. Add the VouchSafeAPI.dll file to your project folder and include it as a dependency in Visual Studio.
  2.  

  3. Insert a <script> tag before the submit button of the form you want to protect with VouchSafe and set its “src” attribute to the return value of the GetScriptUrl method. When you request this page in a browser, you should see the VouchSafe button at the point you inserted the <script> tag. The button should work right away and should pop open a VouchSafe challenge when you click on it. If the button loads but displays an error code, refer to the Error codes and messages section for more information.
  4.  

  5. When a user submit a form containing a VouchSafe challenge, simply call the Validate method with the received HTTP request and your VouchSafe private key. The returned value will be an object of type VouchSafeResponse with two properties. VouchSafeResponse.Success is a boolean that tells you if the validation was successful or not. In the case of an unsuccessful validation, VouchSafeResponse.Message will contain one of the error messages (see Error codes and messages section)
  6.  

  7. 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.
  8.  

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

 

 

VouchSafe Web Service API

These are the actions exposed directly by the VouchSafe Web Service API.  The functions defined in VouchSafeAPI.dll 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.