OPAY / Techninė informacija / Web API / Skaitmeninis duomenų pasirašymas

Skaitmeninis duomenų pasirašymas

Apsikeisdami duomenimis naudojame du pasirašymo būdus (arba vieną, arba kitą):

  • sitmetrinio pasirašymo. Kai abi šalys tiek pasirašymui, tiek parašo tikrinimui naudoja tą patį slaptažodį.
    Pasirašymo slaptažodžio pavyzdys:

    33cec89hjab1d77b10d21fba67528g5h

  • asimetrinio pasirašymo. Kai šalys susigeneruoja privačius raktus, pagal juos susigeneruoja SSL sertifikatus ir tais sertifikatais apsikeičia. Duomenų pasirašymui naudoja privačius raktus, o parašo tikrinimui (gavus duomenis iš partnerio) naudoja partnerio sertifikatą.
    SSL sertifikato pavyzdys:

    SSL Sertifikatas

Prieš pasirašant duomenis ar prieš tikrinant pasirašytų duomenų autentiškumą, labai svarbu laikytis vienodos parametrų apjungimo į vientisą eilutę tvarkos.


Parametrų apjungimo į vientisą eilutę tvarka (Pasirašymo / parašo tikrinimo eilutė)

Parametrai (duomenys), kuriuos siųsite į OPAY ar kuriuos iš OPAY gausite, bus išdėstyti eilės tvarka, kurią nustatys siunčiančioji pusė. Pavyzdys PHP kalba, jei ruoštumėtės išsiųsti užklausą iš trijų parametrų:

$arrayOfParameters['paramName1'] = 'Parametras 1';
$arrayOfParameters['paramName2'] = 'Parametras 2';
$arrayOfParameters['paramName3'] = 'Parametras ąč';

Siunčiant šiuos parametrus HTTP POST metodu, jie galėtų būtų sujungti į tokią eilutę (parametrų išdėstymo tvarka nėra svarbi):

paramName1=Parametras+1&paramName2=Parametras+2&paramName3=Parametras+%C4%85%C4%8D

Pasirašant parametrus ar tikrinant jų parašą, parametrus taip pat reikia sujungti į vieną eilutę, tik
kitaip nei HTTP POST parametrų eilutėje, tarp parametro pavadinimo ir jo reikšmės nededamas
lygybės ženklas (=), parametrai neatskiriami ampersando ženklu (&). Parametrų pavadinimai su jų
reikšmėmis sujungiami į vieną ilgą žodį - eilutę. Šios eilutės specialieji ir ne ASCII simboliai
nekeičiami jų atitikmenimis (angl. url encoding), kaip tai daroma HTTP POST eilutėje. Eilutės
pavyzdys:

paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč

DĖMESIO! Pasirašymui ar parašo tikrinimui naudojamos eilutės parametrų eilės tvarka privalo sutapti su siunčiamų parametrų eilės tvarka. Kitaip sakant, kokia tvarka surikiuoti siunčiami ar gaunami parametrai, tokia tvarka turi ir būti suformuota pasirašymui ar parašo tikrinimui skirta eilutė.


Simetrinis pasirašymas ir parašo tikrinimas

Pasirašymas

Pasirašant  parametrus,  iš  visų  siuntimui  paruoštų  parametrų  (neįtraukiant  parametrų password_signature ir rsa_signature) reikia suformuoti pasirašymo eilutę.
Pasirašymas simetriniu būdu vyksta pasirašymo / parašo tikrinimo eilutę ir pasirašymo slaptažodį sujungiant į vieną eilutę, ir ją išmaišant md5 algoritmu.

$string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
$password = '33cec89hjab1d77b10d21fba67528g5h';
$signature = md5($string . $password);

Gautas simetrinis parašas pridedamas kaip password_signature parametras prie paruoštų siuntimui parametrų, kurie siunčiami į OPAY. Pageidautina, kad prieš siunčiant paruoštus parametrus į OPAY, parametrai dar būtų užkoduoti ir siunčiami kap vienas parametras enocoded (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

Parašo tikrinimas

Parašas tikrinamas iš visų gautų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) suformuojant pasirašymui / parašo tikrinimui skirtą eilutę. OPAY siunčia parametrus užkoduotus į vieną parametrą encoded, todėl norimiems parametrams gauti, reikės išsikoduoti encoded parametro reikšmę (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).
Pasirašymui / parašo tikrinimui skirtą eilutę pasirašome, o gautą rezultatą palyginame su gauto parametro password_signature reikšme. Jeigu reikšmės sutampa – autentifikacija pavyko.

$string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
$password = '33cec89hjab1d77b10d21fba67528g5h';
$signature = md5($string . $password); 
if ($arrayOfParameters['password_signature'] == $signature) {
// Duomenų autentifikacija pavyko - SĖKMĖ
} else {
// Duomenys neatitinka parašo - NESĖKMĖ
}

Asimetrinis pasirašymas ir parašo tikrinimas

Privataus rakto ir SSL sertifikato generavimas

Šiems  raktams  generuoti  OPAY  siūlo  naudoti  OpenSSL  programinę  įrangą
(https://www.openssl.org/).

Privatus raktas generuojamas komandinėje eilutėje įvedant komandą:

openssl genrsa -out privkey.pem 2048

Esamoje direktorijoje jums bus sugeneruotas tekstinis failas pavadinimu privkey.pem, kurio viduje rasite privatų raktą. Skaičius 2048 komandoje reiškia rakto ilgį bitais. Pagal saugumo reikalavimus taikomus šią dieną, tai trumpiausias rekomenduojamas rakto ilgis.

SSL sertifikatas generuojamas komandinėje eilutėje įvedant komandą:

openssl req -new -x509 -key privkey.pem -out cacert.pem -days 3650

Komandoje nurodytas privataus rakto failo pavadinimas (privkey.pem). Taip pat nurodytas tekstinio failo, kuris turi būti sukurtas ir į jį įrašytas SSL sertifikatas, pavadinimas (cacert.pem). Skaičius 3650 nurodo kiek dienų nuo sugeneravimo šis sertifikatas turi galioti. Pasibaigus šiam laikui reikėtų sugeneruoti naują sertifikatą ir jį pateikti OPAY. Pasibaigus sertifikato galiojimui OPAY sistema ir toliau tikrina Pardavėjo siunčiamas užklausas su pasibaigusio galiojimo sertifikatu. Sertifikato galiojimo pasibaigimas technine prasme jokios įtakos neturi. Kokį sertifikato galiojimo laiką nustatyti ir kada atnaujinti sertifikatą sprendžia Pardavėjas.

Įvedus SSL sertifikato generavimo komandą jūsų bus paprašyta suvesti įmonės duomenis. Pvz.:

Įmonės duomenys

Pasirašymas

Pasirašant  parametrus,  iš  visų  siuntimui  paruoštų  parametrų  (neįtraukiant  parametrų password_signature ir rsa_signature) reikia suformuoti pasirašymo eilutę ir ją pasirašyti.

// Pasirašymo / parašo tikrinimo eilutė
$string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
// Privatus raktas nuskaitomas iš failo ir priskiriamas kintamajam
$privateKey = file_get_contents(‘privkey.pem’);
// sukuriam privataus rakto resursą
$pkeyid = openssl_get_privatekey($privateKey);
if ($pkeyid !== false) {
    // pasirašome pasirašymo eilutę
    if (openssl_sign($string, $signature, $pkeyid) === true) { // jeigu pasirašyti pavyko
        // gautą parašą paverčiame į base64 koduotė eilutę
        if (($signature = base64_encode($signature)) !== false) { // jeigu paversti į base64 pavyko
            // rezultatą išvalome nuo naujos eilutės simbolių
            $signature = preg_replace("/[\r\n\t]*/", "", $signature); // gaunam reikiamą parašą
            // atlaisvinam atmintį nuo privataus rakto
            openssl_free_key($pkeyid);
        } else {
            // Klaida: base64 kodavimas nepavyko
        }
    } else {
        // Klaida: pasirašyti nepavyko
    }
} else {
// Klaida: neteisingo formato raktas
}

Gautas asimetrinis parašas pridedamas kaip rsa_signature parametras prie paruoštų siuntimui parametrų, kurie siunčiami į OPAY. Pageidautina, kad prieš siunčiant paruoštus parametrus į OPAY, parametrai dar būtų užkoduoti ir siunčiami kap vienas parametras enocoded (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

Parašo tikrinimas

Parašas tikrinamas iš visų gautų parametrų (neįtraukiant parametrų password_signature ir rsa_signature) suformuojant pasirašymui / parašo tikrinimui skirtą eilutę. OPAY siunčia parametrus užkoduotus į vieną parametrą encoded, todėl norimiems parametrams gauti, reikės išsikoduoti encoded parametro reikšmę (Žiūrėti skiltyje Duomenų kodavimas siekiant išvengti galimų iškraipymų).

// Pasirašymo / parašo tikrinimo eilutė
$string = 'paramName1Parametras 1paramName2Parametras 2paramName3Parametras ąč';
// Gautą parametro rsa_signature priskiriam kintamajam
$signature = $arrayOfParameters['rsa_signature'];
// OPAY sertifikatas nuskaitomas iš failo ir priskiriamas kintamajam
$certificate = file_get_contents('OPAYcert.pem');
// sukuriam viešojo rakto resursą
$pubkeyid = openssl_pkey_get_public($certificate);
if ($pubkeyid !== false) {
  // tikriname parašą
  $ok = openssl_verify($string, base64_decode($signature), $pubkeyid);
  openssl_free_key($pubkeyid); // atlaisvinam atmintį nuo sertifikato
  if ($ok === 1) {
  // Duomenų autentifikacija pavyko - SĖKMĖ
  } else if ($ok === 0) {
  // Duomenys neatitinka parašo - NESĖKMĖ
  } else {
  // Klaida: Parašo tikrinimas nepavyko
  }
} else {
// Klaida: neteisingo formato raktas
}