API-tarkistesumman laskeminen

API-tarkistesumma on olennainen osa turvallista API-kutsua, jolla varmistetaan, että viesti tulee luotetusta lähteestä. Tarkistesumma muodostetaan yhdistämällä seuraavat elementit:

•API URL: Kutsun kohde-URL

•Reitti: API:n polku

•JSON-data: Lähetettävä data

•Aikaleima: Kutsun tekohetken aikaleima (sekunteina UNIX-aikana)

•Yhteinen tunniste: Ylläpidosta löytyvä avain

Tarkistesumma muodostetaan yhdistämällä nämä tiedot merkkijonoksi ja laskemalla sen SHA1-hash.

Kaava:

signature = sha1(API_URL + route + json_data + timestamp + shared_secret)

Esimerkkidata:

• URL: https://api.cmfile.net/v1/api/lists.json

• JSON: {"name":"My list","language":"fi","auto_suppress":true}

• Aikaleima: 1724851326

• Yhteinen tunniste (shared_secret): 1234567890123456789012345678901234567890

Esimerkkidatan hash:

aa8d536e337ce80d33fcbf5dfcac61ca08fd0822

Esimerkkitoteutukset

PHP:

function signature($route, $json, $timeStamp = null, $apiUrl, $sharedSecret)
{
    $timeStamp = is_null($timeStamp) ? time() : $timeStamp;
    $signature = sha1($apiUrl . $route . $json . $timeStamp . $sharedSecret);
    return $signature;
  }
  
// Esimerkki:
echo signature('/v1/api/lists.json', '{"name":"My list","language":"fi","auto_suppress":true}', '1724851326', 'https://api.cmfile.net', '1234567890123456789012345678901234567890');

Java:

import java.security.MessageDigest;
import java.nio.charset.StandardCharsets;

public class ApiSignature {

    public static String signature(String route, String json, String timeStamp, String apiUrl, String sharedSecret) throws Exception {
        String data = apiUrl + route + json + timeStamp + sharedSecret;
        
        MessageDigest digest = MessageDigest.getInstance("SHA-1");
        byte[] hash = digest.digest(data.getBytes(StandardCharsets.UTF_8));
        
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    }

    public static void main(String[] args) throws Exception {
        String route = "/v1/api/lists.json";
        String json = "{\"name\":\"My list\",\"language\":\"fi\",\"auto_suppress\":true}";
        String timeStamp = "1724851326";
        String apiUrl = "https://api.cmfile.net";
        String sharedSecret = "1234567890123456789012345678901234567890";

        System.out.println(signature(route, json, timeStamp, apiUrl, sharedSecret));
    }
}

Node / Javascript:

// Jos käytät Node.js-ympäristöä, asenna CryptoJS npm:llä: npm install crypto-js
// Selainympäristössä voit käyttää CDN:ää: https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js

// Funktio, joka laskee API-tarkistesumman CryptoJS:llä (selainympäristö tai Node.js)
function signature(route, json, timeStamp, apiUrl, sharedSecret) {
    // Yhdistetään data merkkijonoksi
    const data = apiUrl + route + json + timeStamp + sharedSecret;

    // Lasketaan SHA-1 hash CryptoJS:llä
    const hash = CryptoJS.SHA1(data).toString();

    return hash;
}

// Esimerkkidata
const route = "/v1/api/lists.json";
const json = '{"name":"My list","language":"fi","auto_suppress":true}';
const timeStamp = "1724851326";
const apiUrl = "https://api.cmfile.net";
const sharedSecret = "1234567890123456789012345678901234567890";

// Lasketaan tarkistesumma
console.log(signature(route, json, timeStamp, apiUrl, sharedSecret));