Podpora uporabnikom » Priporočila za razvijalce » Preverjanje EŠEI poslovnega subjekta

Preverjanje enotne številke elektronske identifikacije poslovnega subjekta

Spletni servis eseips-validate, verzija 2023-07-27-01

Spletni servis eseips-validate nudi odgovor, ali je bilo določeno digitalno potrdilo izdano poslovnemu subjektu z določeno enotno številko elektronske identifikacije (EŠEI) poslovnega subjekta. Servis nudi odgovore za digitalna potrdila izdajateljev v Državnem centru za storitve zaupanja (SI-TRUST). Poslovnim subjektom izdajata digitalna potrdila naslednja izdajatelja:

  • SIGEN-CA in
  • SIGOV-CA.

eseips-validate: naslov in dostop do servisa ter specifikacija klica

Primer klica servisa v testnem okolju:

https://ws.si-trust.gov.si/eseips-validate-test?sn=2494945716010&ca=sigen-ca&esei=2162841220

V produkcijskem okolju je podobno, le brez pripone -test.

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

V novejših potrdilih je URL za poizvedbo vpisan v javnem delu potrdila v razširitvi OID=1.3.6.1.4.1.58536.1.1.1.3.2, pri čemer je treba zadnjih 10 ničel (parameter esei) zamenjati s preverjanim EŠEI. Za starejša potrdila lahko odjemalska aplikacija sestavi poizvedbo s podobnim URL tako, da serijsko številko (parameter sn) izlušči iz polja serialNumber v razločevalnem imenu imetnika potrdila.

Digitalno potrdilo, ki nastopa v poizvedbi, mora biti izdano pri enem od izdajateljev v SI-TRUST za poslovne subjekte.

Potrdilo je enolično določeno z oznako izdajatelja in 13-mestno serijsko števiko.

Ob klicu servisa in vzpostavitvi seje TLS se mora odjemalska aplikacija predstaviti z veljavnim digitalnim potrdilom. Tega potrdila ni potrebano predhodno javljati SI-TRUSTu.

Pomen vhodnih parametrov:

  • sn: 13-mestna decimalna serijska številka digitalnega potrdila.
  • ca: naziv enega od izdajateljev digitalnih potrdil: sigen-ca ali sigov-ca, v testnem okolju tudi sitest-ca.
  • esei: enotna številka elektronske identifikacije (EŠEI) poslovnega subjekta

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.

Strežnik klic zabeleži samo zaradi morebitne pomoči pri razhroščevanju aplikacij, preprečevanju masovnih poizvedb, napadov DOS itd. Trajna povezava z osebo ali potrdilom se ne zabeleži.

eseips-validate: specifikacija odgovora

Če ne pride do nepredvidene napake, servis vrne status HTTP 200 in v parametru valid vrednost true ali false glede na to, ali je bilo potrdilo danega izdajatelja z dano 13-mestno serijsko številko izdano poslovnemu subjketu z dano EŠEI.

Format odgovora je žeton JWT (JSON Web Token) in je podpisan z JWS (JSON Web Signature). Rezultat se nahaja v srednjem delu (payload) odgovora, med prvo in drugo piko. Odgovor je zakodiran z "Base64", tako kot predpisuje standard za JWT/JWS.

Primer telesa HTTP v odgovoru na gornji primer klica v testnem okolju (z dodanimi prelomi vrstic):

eyJ4NXUiOiJodHRwczpcL1wvd3Muc2ktdHJ1c3QuZ292LnNpXC9lc2VpLWp3cy1j
ZXJ0aWZpY2F0ZS10ZXN0IiwiYWxnIjoiUlMyNTYifQ.
eyJ2YWxpZCI6dHJ1ZSwic24iOiIyNDk0OTQ1NzE2MDEwIiwiZXNlaSI6IjIxNjI4
NDEyMjAiLCJpYXQiOjE2OTA4ODg0MzQsImNhIjoiU0lHRU4tQ0EiLCJqdGkiOiI4
MjJhY2FkNy0xNDY1LTQ5NzQtOGQ2NS1kODA3OThmMTA4Y2YifQ.
FTSaOjUwyucyihH55jcHUT9v6O_5EIU9kv4B0zdrubK9Zr38IpwKTIXRrRgNBj62
FaBP4gMqWkL6fipEadyl-0FIaCsCBx4tRaZqjgwlpOpjWkjxnNfvh0BXYCxZytPd
MPV1YxV55IJBaDHCbySxhLis7hcGb4Ifhix9h3wJiQRuhFFyaKxvaHtEIuSqRrya
CnzCPXrDLwJj0Ds_nrli-BpfdQuIXVaCoZj-6Mo76xE2GhZrb8CFVniV8ZmoYcCb
xlf40-Tbl2dPYTVjmbppil9sE_k8vSWRBdr-mKkpPYeWTzRW0dS99UBKmoE4S7Ye
X99fQKSSNtmhooeG_ty-Jg

Glava in vsebina (payload) po dekodiranju base64:

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

{"valid":true,
 "sn":"2494945716010",
 "esei":"2162841220",
 "iat":1690888434,
 "ca":"SIGEN-CA",
 "jti":"822acad7-1465-4974-8d65-d80798f108cf"}

Opis polj:

  • x5u: URL verige potrdil (več spodaj), s katerim je narejen podpis
  • alg: algoritem podpisa
  • valid: ali je potrdilo (ca,sn) bilo izdano poslovnemu subjektu esei
  • sn: 13-mestna decimalna števika potrdila
  • esei: enotna številka elektronske identifikacije poslovnega subjekta
  • iat: čas izdelave žetona
  • ca: oznaka izdajatelja
  • jti: unikatna številka žetona

Veriga potrdil v datoteki na naslovu x5u se začne s potrdilom, s katerim je žeton podpisan, in nadaljuje s potrdili izdajateljev. Veriga ne vsebuje korenskega potrdila, ki je na produkciji standardni SI-TRUST Root, na testu pa je potrdilo SI-CA Root Test objavljeno na strani https://www.si-trust.gov.si/sl/podpora-uporabnikom/testna-digitalna-potrdila/

Če pride do 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. Tukaj niso opisane napake pred ali med vzpostavitvijo seje HTTPS.

Možni sta dve obliki opisa napake:

{"errorCode":"ST-114-936",
 "errorDetails":"Podani ca (EID-CA-LOW...) ni veljaven ali se ne ujema s tipom..."}

{"errors":
 {"ca":"(not (storitve-ca.web-ui/existing-ca \"SITEST_CA\"))",
  "sn":"(not (\"13 mest\" \"27092016120011\"))"}}

Prvo obliko generira servis za semantične napake in drugo knjižnica Swagger za sintaktične napake, npr. za napačna ali manjkajoča imena parametrov.