Spletni servis esei-get, verzija 2023-07-27-01
Spletni servis esei-get nudi dostop do enotne številke elektronske identifikacije (EŠEI) fizične osebe, ki je pridobila digitalno potrdilo pri enem od izdajateljev v Državnem centru za storitve zaupanja (SI-TRUST). Med ta potrdila sodijo:
- digitalna potrdila na osebni izkaznici,
- digitalna potrdila za oddaljeni podpis SI-PASS,
- (delno) digitalna potrdila SIGEN-CA ter
- (delno) digitalna potrdila SIGOV-CA.
esei-get: naslov in dostop do servisa ter specifikacija klica
Primer klica servisa v testnem okolju:
https://ws.si-trust.gov.si/esei-get-test?sn=4000348241024&ca=eid-test-ca-high
V produkcijskem okolju je podobno, le brez pripon -test.
Servis deluje po protokolu HTTPS RESTful. Odgovori imajo format "JSON Web Signature (JWS)" s kompaktno serializacijo.
V novejših potrdilih je točen URL za poizvedbo vpisan v javnem delu potrdila v razširitvi OID=1.3.6.1.4.1.58536.1.1.1.2.1. 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. Namenjeno mora biti uporabi fizičnim osebam in ne sme biti potrdilo spletišča, potrdilo informacijskega sistema ali elektronski žig.
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, ki ga je skrbnik aplikacije predhodno javil SI-TRUSTu.
Pomen vhodnih parametrov:
- sn: 13-mestna decimalna serijska številka digitalnega potrdila.
- 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.
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 vpogled zabeleži.
esei-get: specifikacija odgovora
Če potrdilo s podanim izdajateljem in podano serijsko številko obstaja in ne pride do nepredvidene napake, servis vrne status HTTP 200 in EŠEI imetnika potrdila danega izdajatelja z dano 13-mestno serijsko številko.
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. eyJzbiI6IjQwMDAzNDgyNDEwMjQiLCJlc2VpIjoiMTE3NjE1NDYyOSIsImlhdCI6 MTY5MDg3OTkyOSwiY2EiOiJFSUQtVEVTVC1DQS1ISUdIIiwianRpIjoiMmZlNGM3 OTYtOTAzOS00NmE5LThmOTYtZTgzMDRlODFlNzhkIn0. NZetsCMhlovwYqTmFCONbBKar0LED6_S1SsrBrA-LDxdgaOLXKkx7IshNv4Jd1qB H7Q03ABlC9WtvOxesT4HXhFcar7qbFmLk0GTOEFz8SeJ0G2K1iUV4mU6t0uC-SzZ piowfrq9ssmEN9Q-gCkgr4s_7Ok-UOq_MV7rcV4Ahmp2yviO9q4_uI9Up72pD3zt tEdIMTT-oU0rfb0Gg7RFiscNSaBgw_Em5l_OSkyRGp9qtqqjhzMhkeMqTXJO8A_n 6Nc-_HHrLSNRb_lY3hZGaUytuFlV1CRKEt2hsPNIRLEOtPrzIo35ZczF-0Fsj6-1 P3Kaeh5qpi5Aj2UmB86KYQ
Glava in vsebina (payload) po dekodiranju base64:
{"x5u":"https:\/\/ws.si-trust.gov.si\/esei-jws-certificate-test",
"alg":"RS256"}
{"sn":"4000348241024",
"esei":"1176154629",
"iat":1690879929,
"ca":"EID-TEST-CA-HIGH",
"jti":"2fe4c796-9039-46a9-8f96-e8304e81e78d"}
Opis polj:
- x5u: URL verige potrdil (več spodaj), s katerim je narejen podpis
- alg: algoritem podpisa
- sn: 13-mestna decimalna števika potrdila
- esei: enotna številka elektronske identifikacije državljana
- iat: čas izdelave žetona
- ca: oznaka izdajatelja
- jti: unikatna številka žetona
- valid: (samo v klicu esei-validate) ali je podano potrdilo s (ca,sn) bilo izdano osebi s številko esei
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 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. 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-LOWS) 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.