Bezbednost API integracije: ključevi, IP lista, HMAC potpis i rotacija

API ključ za fiskalizaciju je kredencijal koji izdaje račune u ime firme, pa se čuva kao lozinka. Tezga ga prima samo u zaglavlju, čuva samo njegov SHA-256 heš, dozvoljava do 20 imenovanih ključeva po firmi, uz opcije samo za čitanje i listu IP adresa, a telo zahteva može da se potpiše HMAC-SHA256 tajnom. Rotacija se najavljuje mejlom posle 76 dana, ali ključ se sam nikad ne menja.

Koji slojevi štite poziv?

Svaki zahtev prolazi kroz provere redom, pa je znanje o redosledu korisno kad tražiš uzrok greške. Pre bilo čega ograničava se veličina tela (512 KB), a tek onda se vidi da li je ključ ispravan.

Redosled provera: svaka kapija ima svoj kod, pa se iz koda odmah vidi na kom koraku je zahtev odbijen.

Kod	Šta znači	Šta da uradiš
401	Ključ nedostaje ili nije ispravan, ili potpis tela ne valja	Proveri zaglavlje i tajnu; potpis računaj nad istim bajtovima koje šalješ
402	Pretplata nije aktivna, kredit je potrošen, ili paket ne uključuje API	Nije problem ključa; proveri paket i pretplatu
403	Ključ samo za čitanje pokušava da upiše, ključ je za terminal kase, ili IP adresa nije na listi	Napravi ključ prave namene ili dodaj adresu servera na listu
429	Prekoračen broj zahteva u minuti	Sačekaj Retry-After sekundi i ponovi sa istim externalId

Kako se ključ pravi, čuva i opoziva?

Ključ se pravi u Podešavanja, Integracije, sa nazivom koji govori kome pripada (na primer „web shop RS” ili „ERP”). Prikazuje se jednom. U bazi ostaje samo SHA-256 heš i prvih nekoliko znakova za prepoznavanje na spisku, pa ga ni Tezga ne može ponovo da prikaže. Ako se izgubi, pravi se novi.

Pravilo je jedan ključ po sistemu. Tako se pauziranjem jednog ne ruši ostali, a svaki poziv se beleži sa ključem, rutom i ishodom, pa se vidi koja integracija šta radi. Ključ samo za čitanje ne može da izda račun, pa je prava vrednost za sistem koji na sajtu samo prikazuje račun. Ključ sa namenom „terminal kase” važi samo na kasi, a ne za API integracije, i obrnuto.

Lista IP adresa je opciona i vezuje se za ključ: pojedinačne adrese ili CIDR opseg. Kad je lista postavljena, zahtev sa druge adrese se odbija sa 403, pa ukraden ključ ne radi van tvoje mreže. Ako izvorna adresa ne može da se pročita, a lista postoji, zahtev se odbija, a ne propušta.

Šta je potpis tela zahteva i kad je obavezan?

Potpis je dodatni sloj preko ključa. Kad firma u Podešavanja, Integracije postavi tajnu za potpis, svaki poziv koji upisuje dokument (/order, /refund, /advance, /copy, kao i kalkulacija, nivelacija, artikli i kupci) mora da nosi zaglavlje X-Tezga-Signature: sha256= i HMAC-SHA256 tela. Bez tajne se proverava samo ključ. Poređenje je u konstantnom vremenu, a pogrešan potpis daje 401.

// Node.js: potpis se računa nad istim stringom koji se šalje
import { createHmac } from "node:crypto";

const telo = JSON.stringify(porudzbina);
const potpis = "sha256=" +
  createHmac("sha256", process.env.TEZGA_SIGNING_SECRET).update(telo).digest("hex");

await fetch("https://pos.narbiz.com/api/integrations/order?provider=custom", {
  method: "POST",
  headers: {
    "X-Tezga-Api-Key": process.env.TEZGA_API_KEY,
    "X-Tezga-Signature": potpis,
    "Content-Type": "application/json",
  },
  body: telo,
});

Isti princip važi u suprotnom smeru: webhook poruke Tezge nose potpis tvoje adrese, koji tvoj server proverava, kako je opisano u tekstu o webhook-ovima fiskalizacije. Tajna adrese počinje sa whsec_, čuva se šifrovano i ne rotira se sama: menjaš je u podešavanjima.

Šta radi rotacija, a šta ne?

Pozadinski posao jednom nedeljno proverava starost ključeva. Ključ star 76 dana donosi mejl firmi sa porukom da napravi novi. Ključ star 90 i više dana se gasi samo ako firma već ima noviji aktivan ključ i ako stari ključ nije korišćen bar 14 dana, jer integracija koja i dalje kuca na stari ključ ne sme da pukne tiho. U suprotnom podsetnik stiže svake nedelje. Posao nikad ne pravi ni ne menja ključeve.

Ispravan redosled za rotaciju je zato: napravi novi ključ, prebaci integraciju, sačekaj da stari miruje, pa ga opozovi. Dnevnik poziva po ključu pokazuje da li neko još koristi stari.

Gde ključ ne sme da bude?

• U kodu pregledača. React, Vue i mobilna aplikacija pozivaju sopstveni server, a on Tezgu. Ključ vidljiv u alatima za programere je ključ koji je javan.
• U adresi. Ključ se prihvata samo iz zaglavlja, ne iz parametra adrese, jer bi završio u pristupnim logovima, referer zaglavljima i istoriji pregledača.
• U repozitorijumu. Ključ ide u promenljivu okruženja ili sef tajni, i nikad u fajl pod verzijom.
• U logovima. Ne loguj zaglavlja zahteva; u logu odgovora dovoljan je externalId i PFR broj.
• Zajednički za sve. Jedan ključ za pet sistema ne može da se opozove bez prekida svih pet.

Kako se sprečava da test izda pravi račun?

Okruženje je osobina naloga, ne ključa: testni i produkcijski ključ izgledaju isto. Zato pri pokretanju pozovi GET /tax-labels i pročitaj polje okruzenje (produkcija, sandbox, simulacija ili nepovezano), pa test konfiguraciji ne dozvoli da nastavi ako je vrednost produkcija. Pravi račun ima verifikacioni link na suf.purs.gov.rs, a simulirani PFR broj počinje sa MOCK.

Izvori: OpenAPI opis Tezga eKase, verzija 1.6.0 (pos.narbiz.com/api/openapi.json), ИБ 1597; uputstvo za integratore (pos.narbiz.com/api-dokumentacija.pdf); strane Sigurnost i zaštita podataka i Enterprise (tezgafiskal.com); RFC 2104 (HMAC); OWASP API Security Top 10.