API Implementation

Protecting your site with CryptoPhoto is quick and easy.

API Implementation
background © P.Gunther

CryptoPhoto API Session


Before being able to deploy the CryptoPhoto service into your website, you must register a new CryptoPhoto administration account and obtain a set of API Keys.

Creating and configuring a CryptoPhoto administration account is described here.

Before an end user can use the CryptoPhoto service, you (3rd party) have to obtain a CryptoPhoto session ID from CryptoPhoto.com.


This is achieved by doing a POST request to http[s]://CryptoPhoto.com/api/get/session. Below are the relevant parameters.


API Request


URL: http[s]://CryptoPhoto.com/api/get/session

Parameters (sent via POST)
publickey (required) Your CryptoPhoto Application public key
uid (required) A unique ID associated with your user on your website
time (required) Number of seconds since epoch (GMT)
signature (required) HMAC-SHA1 of privatekey, time, uid and publickey.

eg. hmac_sha1_hex( $privatekey . $time . $uid . $publickey, $privatekey )
ip (required) The IP address of the user who needs access to CryptoPhoto service
authentication (default false) Set this parameter to true if the CryptoPhoto session ID will be used for Challenge Widget

API Response


The response is a series of strings separated by \n. To read the string, split the line and read each field. (New lines may be added in the future)


Line 1 "success" or "error". Success if we managed to create a new CryptoPhoto session.
Line 2

If Line 1 is error, then this string will be an error code.


If Line 1 is success, then this string will be an unique CryptoPhoto session ID. Store this ID for further use (bear in mind that sessions ID are valid only for 30 minutes).

Line 3

true/false


If "true" then the user associated with "uid" has a CryptoPhoto token generated and downloaded. Otherwise he doesn't.

Line 4

signature


HMAC-SHA1 of publickey, privatekey, time, and uid

eg. hmac_sha1_hex( $publickey . $time . $uid . $privatekey, $privatekey )

time and uid are used from the API request

Displaying CryptoPhoto Token Generation Widget


The first step in integrating CryptoPhoto is making the Token Generation Widget show up on one of your user's account page.

Your user can then use this page to create/download new CryptoPhoto Token or manage existent Tokens.


To make the Token Generation Widget appear when your page loads, you will need to insert this snippet of JavaScript code in your <form> element and replace session_id with the CryptoPhoto session ID obtained at the previous step:


 <script type="text/javascript"
   src="https://CryptoPhoto.com/api/token?sd=session_id">
 </script>

So your page will look something like this:


  <!-- ... your HTML content ... -->

  <form action="" method="post">

    <!-- ... your form code here ... -->

    <script type="text/javascript"
      src="https://CryptoPhoto.com/api/token?sd=session_id">
    </script>
    
    <!-- ... more of your form code here ... -->

  </form>

  <!-- ... more of your HTML content ... -->

Displaying CryptoPhoto Challenge Widget


The first step in integrating CryptoPhoto is making the CryptoPhoto Challenge Widget show up on a page after the user has been authenticated by the usual username/password techniques.


We recommend showing the CryptoPhoto Challenge Widget image after you've acquired your user's name and password, so that you know which uid to use when getting a new CryptoPhoto session ID.


To make the CryptoPhoto Challenge Widget appear when your page loads, you will need to insert this snippet of JavaScript code in your <form> element and replace session_id with the CryptoPhoto session ID obtained at the previous step:


 <script type="text/javascript"
   src="https://CryptoPhoto.com/api/challenge?sd=session_id">
 </script>

So your page will look something like this:


  <!-- ... your HTML content ... -->

  <form action="" method="post">

    <!-- ... your form code here ... -->

    <script type="text/javascript"
      src="https://CryptoPhoto.com/api/challenge?sd=session_id">
    </script>
    
    <!-- ... more of your form code here ... -->

  </form>

  <!-- ... more of your HTML content ... -->

There are four new form fields created:


  • token_response_field_row is a text field where the user enters their row code. It corresponds to the "response_row" parameter required by the CryptoPhoto verification API.
  • token_response_field_col is a text field where the user enters their column response. It corresponds to the "response_col" parameter required by the CryptoPhoto verification API.
  • token_selector is a drop down containing all tokens associated with the user. It corresponds to the "selector" parameter required by the CryptoPhoto verification API.
  • cp_phc is a text field that will be automatically filled when the user authenticates with a mobile device. It corresponds to the "cph" parameter required by the CryptoPhoto verification API.

These four fields will be passed to the script on your server that processes this form and verifies the CryptoPhoto response via the CryptoPhoto verification API.

Verifying the User's Answer


After your page is successfully displaying CryptoPhoto Challenge Widget, you need to configure your form to check whether the answers entered by the users are correct. This is achieved by doing a POST request to http[s]://CryptoPhoto.com/api/verify. Below are the relevant parameters.


API Request


URL: http[s]://CryptoPhoto.com/api/verify

Parameters (sent via POST)
publickey (required) Your CryptoPhoto Application public key
uid (required) A unique ID associated with your user on your website
time (required) Number of seconds since epoch (GMT)
signature (required) HMAC-SHA1 of privatekey, time, uid and publickey.

eg. hmac_sha1_hex( $privatekey . $time . $uid . $publickey, $privatekey )
response_row (required) The value of "token_response_field_row" sent via the form
response_col (required) The value of "token_response_field_col" sent via the form
selector (required) The value of "cp_selector" sent via the form
cph (required) The value of "cp_cph" sent via the form
ip (required) The IP address of the user who solved the CryptoPhoto Challenge

API Response


The response from verify is a series of strings separated by \n. To read the string, split the line and read each field. (New lines may be added in the future)


Line 1 "success" or "error". Success if user has enter proper Token codes.
Line 2 If Line 1 is error, then this string will be an error code.
Line 3

signature


HMAC-SHA1 of publickey, time, uid and privatekey

eg. hmac_sha1_hex( $publickey . $time . $uid . $privatekey, $privatekey )

time and uid are used from the API request