Pridobivanje identifikacijskih podatkov, vezanih na digitalno potrdilo

Spletni servis ca-sif-vpogled, verzija 2023-07-17-01

Spletni servis nudi vpogled v prevajalno tabelo digitalnih potrdil izdajateljev Državnega centra za storitve zaupanja SI-TRUST. Namenjen je aplikacijam, s katerimi upravljajo organi javnega sektorja. Servis odgovarja na poizvedbe aplikacij za posamezna potrdila. Za potrdilo s podano serijsko številko in podanim izdajateljem servis vrne enega ali več osebnih podatkov, ki so vezani na potrdilo:

EMŠO,
osebna davčna številka,
davčna številka organizacije,
matična številka organizacije.

Kateri od teh štirih podatkov so vezani na posamezno potrdilo, je odvisno od izdajatelja in vrste potrdila. Nimajo vsa potrdila določenih vseh štirih podatkov. Poleg tega je nabor podatkov omejen tudi za vsako poizvedujočo aplikacijo glede na zakonsko podlago, do katerih podatkov je aplikacija upravičena.

Dostop do servisa, naslov servisa ter specifikacija klica

Servis deluje po protokolu HTTPS RESTful. Odgovori imajo format "JSON Web Signature (JWS)" s kompaktno serializacijo.

Primer klica servisa v testnem okolju:
https://ws.si-trust.gov.si/ca-sif-vpogled-test?client=21-52&sn=0902201500001&ca=sitest-ca

Primer klica servisa v produkcijskem okolju:
https://ws.si-trust.gov.si/ca-sif-vpogled?client=21-52&sn=1235734514056&ca=sigov-ca

Ob vzpostavitvi seje HTTPS se mora odjemalska aplikacija predstaviti z veljavnim digitalnim potrdilom, ki je dogovorjeno med skrbnikom aplikacije in skrbnikom servisa ob novi namestitvi aplikacije oziroma ob poteku potrdila delujoče aplikacije.

Pomen vhodnih parametrov:

client: vnaprej dogovorjena številka, kratica ali kratek naziv, ki enolično določa (identificira) nameščeno aplikacijo. Ta podatek določi skrbnik servisa v dogovoru s skrbnikom aplikacije ob novi namestitvi aplikacije in ga veže na potrdilo, ki ga bo aplikacija uporabljala, ko bo odpirala seje HTTPS. Servis ob vsakem klicu prek potrdila seje HTTPS preveri, da je aplikacija avtorizirana za uporabo podanega client-a. Za aplikacije, ki so uporabljale stari protokol Oracle ODBC/JDBC, je client preddoločen kot kombinacija vrednosti sif_apl in zap_st_instal, ločenih z -. Primer: v gornjih dveh primerih klicev gre za sif_apl=21 in zap_st_instal=52.
sn: 13-mestna decimalna serijska številka digitalnega potrdila izdajatelja SI-TRUST. To je serijska številka v razločevalnem imenu imetnika potrdila in ne serijska številka samega potrdila. Kombinacija sn in ca enolično določa potrdilo, ki je predmet poizvedbe.
ca: naziv enega od izdajateljev digitalnih potrdil: sigen-ca, sigov-ca, si-pass-ca, eid-ca-high, eid-ca-low ali eid-ca-sign. V testnem okolju poleg teh še: sitest-ca, eid-test-ca-high, eid-test-ca-low ali eid-test-ca-sign. Kombinacija sn in ca enolično določa potrdilo, ki je predmet poizvedbe.

Vrstni red vhodnih parametrov je poljuben. Naziv izdajatelja je lahko podan z malimi, velikimi ali mešanimi črkami, nazivi parametrov morajo biti podani z malimi črkami.

Servis vsak vpogled zabeleži.

Specifikacija odgovora

Če potrdilo s podanim izdajateljem in podano serijsko številko obstaja in ne pride do nepredvidene napake, servis vrne status HTTP 200 in osebne podatke imetnika potrdila. Katere od osebnih podatkov servis lahko vrača določeni namestitvi aplikacije, je dogovorjeno ob novi namestitvi aplikacije. Format vrnjenih podatkov je JWT (JSON Web Token) in je podpisan z JWS (JSON Web Signature). Osebni podatki se nahajajo v srednjem delu (payload) odgovora, med prvo in drugo piko. Zakodirani so z Base 64, tako kot predpisuje standard za JWT/JWS. Primer odgovora (telo HTTP, v formatu Base64, z dodanimi prelomi vrstic) na gornji primer klica v testnem okolju je:

eyJ4NXUiOiJodHRwczpcL1wvd3Muc2ktdHJ1c3QuZ292LnNpXC9lc2VpLWp3cy1j
ZXJ0aWZpY2F0ZS10ZXN0IiwiYWxnIjoiUlMyNTYifQ.
eyJzbiI6IjA5MDIyMDE1MDAwMDEiLCJjYV9zaWYiOnsiZW1zbyI6IjIzMDk5ODA1
MDQwMDgiLCJkYXZfc3RfcHJhdm5lX29zZWJlIjpudWxsLCJkYXZfc3QiOiI5OTc2
NDg2NSJ9LCJpYXQiOjE2ODk3NjM2OTMsImNhIjoiU0lURVNULUNBIiwianRpIjoi
NWE5ODYwNmQtYWIyNi00OGVkLTljZmEtNWEyNmE4ZTY5ZGJmIn0.
itmQ1KIEu5nYzwXwxgbf7RUl-4pwB3NL3YbepuB3IUyVmhqYOTGkdAqANFMAB_U-
lwZd57M4yy-yTUitJVn-n7QvW8D8VIlor0XQrQrZsAAnY6DvYHisHXjuc1ZsR_lr
vX6dIgh8UuAUAdkbzAs-QuUGMHX9EntpLrL3MY-uYgFNmSxPZARHeqSOuZDQ6XN9
7MrbqWskC-4NGqE-3ZDyU1_VH5nOTaTNHTqQEn2z2f_A9HWcIZSdnD5VeENV6wJY
Z_C4ZnpY_AXGsGSdxcnvjRPNF9BGhKOPwR6QOXzfqBY-5b9l9t9CQi5_0k4JUH5m
RwsA30rsXXWKRf-g3moshg

Dekodiran prvi del, do prve pike, vsebuje glavo JOSE (JOSE Header):

{"x5u":"https:\/\/ws.si-trust.gov.si\/esei-jws-certificate-test",
 "alg":"RS256"}

Drugi del, med prvo in drugo piko, vsebuje trditve (claims) JWT, poleg osebnih podatkov še nekaj podatkov po specifikaciji JWT:

{"sn":"0902201500001",
 "ca_sif":{
     "emso":"2309980504008",
     "dav_st_pravne_osebe":null,
     "dav_st":"99764865"},
 "iat":1689763693,
 "ca":"SITEST-CA",
 "jti":"5a98606d-ab26-48ed-9cfa-5a26a8e69dbf"}

Tretji del, od druge pike do konca, je podpis prvih dveh.

Pomen polj v prvih dveh delih:

alg: algoritem podpisa,
iat: čas, ob katerem je narejen odgovor,
x5u: naslov javnega dela potrdila, s katerim je podpisan odgovor.
jti: unikatna številka odgovora,
sn: serijska številka, ki je bila podana,
ca: naziv izdajatelja, ki je bil podan,
ca_sif: skupina osebnih podatkov iz prevajalne tabele,
emso: EMŠO imetnika potrdila ali null, če potrdilo nima tega podatka,
dav_st: davčna številka imetnika ali null, če potrdilo nima tega podatka,
mat_st: matična številka organizacije imetnika ali null, če potrdilo nima tega podatka,
dav_st_pravne_osebe: davčna številka organizacije imetnika ali null, če potrdilo nima tega podatka.

Če potrdilo s podano serijsko številko in izdajateljem ne obstaja ali če pride do druge napake na aplikacijskem nivoju (nepravilna poizvedba, izpad zalednega strežnika itd.), servis vrne status HTTP različen od 200 in v telesu HTTP dodatne informacije o napaki v formatu JSON. Napaka pred ali med vzpostavitvijo seje HTTPS ni napaka na aplikacijskem nivoju.