Sumalaisen julkishallinnn VETUMA-palvelu versi 2.0 VETUMA Verkktunnistus ja -maksaminen
Sisällysluettel 1. Jhdant...3 2. Vetuma-rajapinnan yleiset minaisuudet...3 2.1 Kutsu- ja vastausviestien välitys...3 2.2 Parametrikäytännöt...5 2.3 Kutsu- ja vastaustyypit...5 2.4 Turvatarkisteen mudstaminen...6 2.5 Paluu VETUMA-palvelusta svellukseen...7 2.6 VETUMA-kutsujen yleiset parametrit...7 2.7 VETUMA-vastausten yleiset parametrit...14 3. Tunnistus, hyväksyminen ja allekirjitus (LOGIN-palvelutyyppi)...15 3.1 Menetelmät...16 3.2 LOGIN-palvelutyypin yleiset kutsu- ja vastausparametrit...17 3.2.1 Yleiset LOGIN-palvelutyypin kutsuparametrit... 17 3.2.2 Yleiset LOGIN-palvelutyypin vastausparametrit... 18 3.3 Käyttäjän tunnistus...20 3.3.1 Tunnistuskutsun parametrit...20 3.3.2 Tunnistusvastauksen parametrit... 21 3.4 Käyttäjän surittama hyväksyminen...21 3.4.1 Hyväksymiskutsun parametrit... 22 3.4.2 Hyväksymisvastauksen parametrit... 24 3.5 Käyttäjän surittama kiistämätön sähköinen allekirjitus...24 3.5.1 Allekirjituskutsun parametrit... 25 3.5.2 Allekirjitusvastauksen parametrit... 26 4. Verkkmaksaminen ja maksunpalautus (PAYMENT-palvelutyyppi)...27 4.1 Menetelmät...27 4.2 Maksatus...28 4.2.1 Maksatuskutsun parametrit... 29 4.2.2 Maksatusvastauksen parametrit... 36 4.3 Maksun palautus...38 4.3.1 Tuki verkkmaksupalveluissa... 39 4.3.2 Maksunpalautuskutsun parametrit... 40 4.3.3 Maksunpalautusvastauksen parametrit... 43 5. Yleinen pikkeustilanteiden käsittely...45 5.1 VETUMA-palvelun havaitsemat pikkeustilanteet...45 5.1.1 Paluu svellukseen pikkeustilanteissa... 45 5.1.2 Testiympäristön tuki kutsuvirheiden tutkimiselle... 46 5.2 Virhetilanteet kutsu- ja vastausviestien välityksessä...46 5.2.1 VETUMA-istunnn vanhentuminen... 46 5.2.2 Tistuvat kutsut... 47 6. Liitteet...47 2 (47)
1. JOHDANTO VETUMA-palvelu n kansalaisten verkktunnistus- ja maksamispalvelu jka n tarkitettu julkishallinnn rganisaatiiden asiintisvelluksien käyttöön. Fujitsu Services OY tuttaa palveluntuttajan minaisuudessa VETUMA-palvelun valtin ja kuntien eri rganisaatiiden käyttöön. VETUMA-palvelun svellushjelmille tarjama timinnallisuus n kuvattu erillisessä dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. VETUMA-palvelukknaisuus sisältää svelluksille tarjtun timinnallisuuden lisäksi mm. käyttäjähallintaan, laskutukseen ja raprtintiin liittyviä timintja. Edellä mainitussa timinnallisuuden kuvausdkumentissa n kuitenkin kuvattu ainastaan svelluksille tarjttu timinnallisuus. Svellukset vivat käyttää VETUMA-palvelun niille tarjamaa timinnallisuutta kutsurajapinnan kautta, jka n määritelty tässä dkumentissa. Tämä dkumentti kuvaa VETUMA-palvelun vaiheen 2 kutsurajapinnan. Vaiheessa 2 n tehty rajapintaan ja itse palveluun timinnallisuuden lisäysten hella seuraavat muutkset (vaiheeseen 1B verrattuna): Kutsun palvelun nnistumisesta kertva STATUS-parametri n nyt myös tunnistus-, hyväksymis- ja allekirjitusvastauksissa. STATUS-parametrilla vi lla myös seuraavat uudet arvt: ERROR ja FAILURE. Kutsuissa ja vastauksissa n uusi valinnainen parametri TRID jta vidaan käyttää yhdistämään tietyn tapahtuman kutsu ja vastaus tisiinsa. Virhe- ja peruutuspaluu suritetaan POST-kmennlla ja vastauksissa käytetään turvakdilaskentaa. Parametri REF n muutettu valinnaiseksi sekä maksatuskutsussa että -vastauksessa. Muita versin muuttumisen yhteydessä humiitavia asiita vat: Yhteenspivuuden vuksi parametri SO säilyy kutsuissa, mutta sillä ei enää le vaikutusta kutsun käsittelyyn. VETUMA-käyttöliittymässä käytetään aina svelluksen LG-parametrissa antamaa kieltä, eli käyttäjä ei vi valita kieltä. 2. VETUMA-RAJAPINNAN YLEISET OMINAISUUDET Tässä luvussa kuvataan VETUMA-rajapinnan yleiset minaisuudet: kutsu- ja vastausviestien välitys, parametrikäytännöt, turvatarkisteiden laskeminen, sekä kutsujen ja vastausten jakaminen timintjen mukaisiin tyyppeihin. Lisäksi tässä kappaleessa kuvataan ne yhteiset parametrit jtka esiintyvät samalla lailla kaikissa VETUMA-palvelun kutsu- ja vastaustyypeissä. 2.1 Kutsu- ja vastausviestien välitys VETUMA-palvelun kutsurajapinta n viestirajapinta missä viestit n tteutettu käyttäen HTTPyhteyskäytännön POST-kmentja. Kun asiintisvellus kutsuu VETUMA-palvelua, se lähettää palvelulle käyttäjän selaimen kautta POST-kmennn jssa VETUMA-kutsun kutsuparametrit n annettu HTML-lmakkeen kenttinä. Kutsuessaan VETUMA-palvelua svellus käytännössä 3 (47)
palauttaa käyttäjän selaimeen HTTP-vastauksen jnka avulla VETUMA-kutsun sisältävä POST-kment lähetetään selaimesta VETUMA-palvelulle. Svellus antaa kutsussa ne sitteet, jihin VETUMA-palvelun tulee palauttaa vastaus eri tilanteissa: nnistunut timint, käyttäjän peruma timint, tai virhetilanne. Kun VETUMA-palvelu palauttaa vastauksen sitä kutsuneelle asiintisvellukselle, se lähettää svellukselle jälleen käyttäjän selaimen kautta POST-kmennn jssa VETUMA-vastauksen parametrit n annettu HTML-lmakkeen kenttinä. Viestinvälityksen luttamuksellisuus (viestien sisällön sujaus paljastumista vastaan) perustuu käytettävien yhteyksien sujaukseen SSL/TLS-yhteyskäytännöllä, eli kutsu- ja vastausviestit välitetään HTTPS-yhteyksiä käyttäen. Ennen kuin svellus palauttaa käyttäjän selaimelle sen HTTP-vastauksen jnka avulla VETUMA-kutsu lähetetään selaimesta VETUMA-palvelulle, svelluksen tulee hulehtia siitä, että sen ja käyttäjän selaimen välillä n HTTPS-yhteys. Kutsusite VETUMA-palveluun (jka n annettava VETUMA-kutsun sisältävän lmakkeen actin-elementissä) n https://-alkuinen, eli POST-kment lähetetään selaimesta VETUMA-palvelulle HTTPS-yhteyttä käyttäen. VETUMA-palvelun palauttaessa selaimelle HTTP-vastauksen jnka avulla VETUMAvastaus lähetetään selaimesta svellukselle tämä tapahtuu HTTPS-yhteyttä käyttäen. VETUMA-kutsussa annettujen paluusitteiden n ltava https://-alkuisia, jtta ne aiheuttaisivat HTTPS-yhteyden mudstamisen vastauksen sisältävän POST-kmennn lähettämiseksi selaimesta svellukselle. VETUMA-palvelu tarkistaa, että näin n, ja js ei le niin se hylkää kutsun. Vaihdettujen viestien eheys ja lähettäjän tunnistaminen taataan käyttämällä viestien turvatarkisteita (Message Authenticatin Cde, MAC). Svellus vi halutessaan antaa VETUMA-kutsulle tapahtumatunnuksen, jnka VETUMApalvelu palauttaa vastatessaan kyseiseen kutsuun. Tapahtumatunnus n tarkitettu helpttamaan tietyn tapahtuman kutsu- ja vastausviestien yhdistämistä tisiinsa. Asiintisvellus vi lähettää kutsun VETUMA-palvelulle käyttäjän selaimen kautta esimerkiksi palauttamalla selaimelle HTML-sivun jssa n: HTML-lmake jssa n VETUMA-kutsuparametrit esitäytettyinä, käyttäjälle näkymättöminä piilkenttinä.... <frm name= VETUMA methd= POST actin=https://tunnistus.sumi.fi/lgin/app > <input type= hidden name= RCVID value= Ankkalinna_S1 > <input type= hidden name= APPID value= Prtaali > <input type= hidden name= TIMESTMP value= 20060211... >... </frm>... Autmaattisesti suritettava skripti jka lähettää lmakkeen VETUMA-palvelulle, esimerkiksi: var frm = dcument.vetuma; 4 (47)
frm.submit(); 2.2 Parametrikäytännöt Käsikäyttöinen submit-timint lmakkeessa VETUMA-palveluun siirtymiseksi, mikäli skriptien surittaminen n estetty selaimessa, esimerkiksi <INPUT type="submit" value="siirry VETUMA-palveluun tunnistautumaan"> Kullakin VETUMA-rajapinnan kutsu- ja vastaustyypillä n ma jukknsa nimettyjä parametreja. Tietyn parametrin nimeä käytetään kutsuissa ja vastauksissa kyseisen parametrin sisältävän lmakkeen kentän nimenä. Osa parametreista n yleisiä parametreja jtka esiintyvät useissa kutsu- ja/tai vastaustyypeissä. Osa parametreista taas n kutsu- tai vastaustyyppikhtaisia. Parametrien nimet ja merkitykset kutsuissa ja vastauksissa n kuvattu tässä dkumentissa. VETUMA-rajapintaparametrien arvissa ist ja pienet kirjaimet tulkitaan eri merkeiksi, paitsi MAC-parametrissa jssa heksadesimaalinumert A..F vidaan esittää jk isilla tai pienillä kirjaimilla. Parametreja sisältävien kenttien nimet lmakkeessa tulee antaa isilla kirjaimilla. VETUMA-rajapinnan kutsu- ja vastausviestien määrittelyissä n niissä esiintyvillä parametreilla määrätty järjestys. Järjestys tulee ttaa humin kutsu- ja vastausviestien turvatarkisteiden mudstamisessa: tietyssä kutsussa mukanalevien parametrien arvt n sisällytettävä ikeassa järjestyksessä siihen merkkijnn jsta turvatarkisteena käytettävä tiiviste lasketaan. Oikean järjestyksen muistamisen helpttamiseksi n VETUMArajapintamäärittelyssä annettu kullekin parametrille järjestysnumer siten, että kussakin kutsuja vastaustyypissä parametrit esiintyvät numeridensa mukaan nusevassa järjestyksessä. Lunnllisestikaan samaa parametria ei saa laittaa useampaan kertaan samaan kutsuun. Osa VETUMA-rajapintakutsujen parametreista n pakllisia ja sa valinnaisia. Pakllinen kutsuparametri n kutsun rakentamisen kannalta parametri jka n ltava mukana kutsussa. Valinnainen parametri n parametri jnka svellus vi jättää pis kutsusta. Tämä n humiitava myös turvatarkisteen mudstamisessa. VETUMA-rajapinnassa käytetään ISO 8859-1 merkistöä. Svelluksen kannalta tämä tarkittaa muun muassa sitä, että VETUMA-kutsujen parametrien arvissa saa esiintyä vain ISO 8859-1 merkistön merkkejä. 2.3 Kutsu- ja vastaustyypit Vetuma-palvelu tarjaa jukn timintja jtka n ryhmitelty palvelutyyppeihin. Kullakin timinnlla n ma kutsu- ja vastaustyyppi. Kutsutyypillä tarkitetaan sellaisen kutsun määrittelyä jlla pyydetään VETUMApalvelua surittamaan tietty timint. Vastaustyypillä tarkitetaan sellaisen vastauksen määrittelyä jnka VETUMA-palvelu palauttaa suritettuaan tietyn timinnn. Tässä dkumentissa n kuvattu eri timintja vastaavat kutsu- ja vastaustyypit: minkä timinnn kutsu aiheuttaa, mitä parametreja timinnn kutsussa n ja mikä n niiden merkitys, sekä mitä parametreja timinnn vastauksessa n ja mikä n niiden merkitys VETUMA-rajapinnan kutsujen ja vastausten parametrit n kuvattu tässä dkumentissa seuraavasti: 5 (47)
Ne parametrit jtka esiintyvät samalla tavalla (samalla nimellä ja merkityksellä) kaikissa kutsutyypeissä n kuvattu tämän luvun kappaleessa VETUMA-kutsujen yleiset parametrit. Ne parametrit jtka esiintyvät samalla tavalla kaikissa vastaustyypeissä n kuvattu tämän luvun kappaleessa VETUMA-vastausten yleiset parametrit. Kutsu- ja vastaustyyppikhtaiset parametrit n kuvattu timintkhtaisten kutsujen ja vastausten kuvauksissa. 2.4 Turvatarkisteen mudstaminen Viestin turvatarkiste (MAC) mudstetaan laskemalla kutsun parametrien arvista ja jaetun salaisuuden arvsta tiiviste. Laskentaan käytetään kyseisen jaetun salaisuuden yhteydessä käytettäväksi knfiguritua tiivistealgritmia. VETUMA:ssa tällä hetkellä tuettuja tiivistealgrimeja vat SHA-256, SHA-1 ja MD5. SHA- 256-algritmin käyttöä susitellaan, kska se n niistä turvallisin. MD5-algritmi n vähiten turvallinen, ja sitä tulee käyttää vain js muut edellämainituista algritmeista eivät le jstain syystä käytettävissä. Jaetun salaisuuden arv mudstetaan sitä lutaessa seuraavalla tavalla: Ohjelmistphjaisella, kryptgrafisesti turvallisella satunnaislukugeneraattrilla sekä symmetrisen avaimen luntifunktilla ludaan salainen avain jnka pituus n 256 bittiä. Salaisuuden arvssa kyseinen avain esitetään heksadesimaalimudssa, jllin sen pituus n 64 merkkiä. Jaetun salaisuuden arvn käsittelyn helpttamiseksi sen alkuun laitetaan vielä kyseisen salaisuuden tunnus, ertettuna avaimesta tavuviivalla. Tunnus esiintyy kutsuissa ja vastauksissa RCVID-nimisen parametrin arvna. Jaetun salaisuuden rakenne n esitetty allalevassa kuvassa. RCVID (5-15 merkkiä) - AVAIN (64 merkkiä) Jaettu salaisuus (70-80 merkkiä) Kuva 1: Jaetun salaisuuden rakenne VETUMA-palvelua kutsuvan asiintisvelluksen tulee laskea kutsuviestin tiiviste kutsun parametrien arvista ja jaetun salaisuuden arvsta mudstetusta merkkijnsta. Mikäli tietty parametri n mukana kutsussa, sen n ltava mukana myös MAClaskennassa (lunnllisestikin lukuun ttamatta itse MAC-parametria jka n laskennan tuls). Parametrien tulee esiintyä tässä merkkijnssa siinä järjestyksessä jka n rajapintamäärittelyssä määrätty kyseiselle kutsulle. Jaetun salaisuuden arvn tulee lla merkkijnn viimeisenä kenttänä. Kentät yhdistetään peräkkäin käyttäen &-merkkiä ertinmerkkinä kenttien välillä, ja &- merkin tulee myös lla merkkijnn viimeisenä merkkinä. Esimerkki MAC-laskentaa varten mudstetusta merkkijnsta: Ankkalinna_S1&Prtaali&2006021514302746254&...... &Ankkalinna_S1-2843AB9FD601235CA09B...4FB352C6& VETUMA-palvelu laskee vastausviestin tiivisteen samalla tavalla. 6 (47)
2.5 Paluu VETUMA-palvelusta svellukseen Kun VETUMA-palvelu käsittelee svellukselta saamaansa kutsua, niin kutsussa pyydetyn timinnn suritus vi nnistua tai timint vi jäädä eri syistä surittamatta. VETUMApalvelu palauttaa vastauksen siihen kutsussa ilmitettuun sitteeseen jka vastaa kutsun käsittelyn jälkeistä tilannetta: Timinnn suritus nnistui. Käyttäjä perui timinnn. Timinnn surittaminen epännistui jstain syystä. Tämän lisäksi VETUMA-palvelu palauttaa aina vastauksessa paluustatusparametrin jlla kerrtaan nnistuik surittaminen vai jäikö timint surittamatta. 2.6 VETUMA-kutsujen yleiset parametrit Allalevassa taulukssa n lueteltu ne VETUMA-rajapinnan parametrit jtka esiintyvät samalla tavalla kaikissa kutsutyypeissä: Nr Nimi Merkitys 1 RCVID Kutsun sujauksessa käytetyn jaetun salaisuuden tunnus 2 APPID VETUMA-palvelua kutsuvan asintisvelluksen tunnus 3 TIMESTMP Kutsun aikaleima 4 SO Oletusmenetelmä 1) 5 SOLIST Käyttäjälle tarjttavat menetelmät 1) 6 TYPE Käytettävän VETUMA-palvelun tyypin tunnus 7 AU Kutsussa pyydettävän timinnn kdi. 9 LG Käyttöliittymäkieli 10 RETURL Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL Virhepaluusite svellukseen 13 AP Kutsun palvelemisessa käytettävän knfiguraatin tunnus 15 MAC Kutsun turvatarkiste (MAC) 20 APPNAME Kutsuvan svelluksen nimi käyttöliittymää varten 34 TRID Tapahtumatunnus 1) Näiden parametrien käytössä n timintkhtaisia vivahde-erja. Ne n kuvattu tarkemmin kunkin timintkhtaisten kutsutyypin yhteydessä. Taulukk 1: VETUMA-kutsujen yleiset parametrit Parametri 1: RCVID Merkitys kutsussa: Kutsun turvatarkisteen (MAC) mudstamisessa käytetyn jaetun salaisuuden tunnus. Yhdellä VETUMA-asiakkaalla vi lla useita salaisuuksia, ja kyseisen asiakkaan svellukset vivat VETUMA-palvelun kannalta käyttää niistä mitä tahansa. 7 (47)
Salaisuuksien tunnukset vat yksilöllisiä (unique) VETUMA-palvelussa. Useilla asiakkailla ei vi lla yhteistä VETUMA-salaisuutta, jten salaisuuden tunnuksesta saadaan selville myös asiakas. VETUMA-palvelun timittaja (Fujitsu Services OY) määrää salaisuuksien arvt ja tunnukset ja antaa ne asiakkaalle. Kukin asiakas vastaa mien salaisuuksiensa säilyttämisestä. Tässä yhteydessä svitaan myös, mitä algritmia käytetään salaisuuden yhteydessä. Esitysmut: Alfanumeerinen merkkijn, pituus 5..15 merkkiä. Esimerkki:...value= VETUM127 > Parametri 2: APPID Merkitys kutsussa: VETUMA-palvelua kutsuvan svelluksen tunnus raprtintia varten. VETUMA-palvelua kutsuva svellus antaa aina kutsun parametrina svellustunnuksen jka talletetaan VETUMA-palvelun raprtintia varten keräämiin tietihin. Kukin asiakas vi valita millä tarkkuustaslla VETUMA-palvelu erittelee asiakkaan svellukset raprtinnissa: tietty svellus, tietty svellusjukk (esimerkiksi tietyn timialan svellukset), tai mikä tahansa tietyn asiakkaan svellus. Asiakas siis antaa tunnukset mille svelluksilleen, ja vastaa niiden keskinäisestä yksilöllisyydestä. Svellustunnuksia ei rekisteröidä VETUMA-palveluun, vaan ne esiintyvät vain käyttöraprteissa. Käyttöraprteissa annettavat tiedt n jateltu asiakaskhtaisesti. Esitysmut: Merkkijn, pituus 5..15 merkkiä, sallittuja merkkejä vat numert 0..9, ist ja pienet kirjaimet, tavuviiva ( - ) ja alaviiva ( _ ) Esimerkki:...value= Prtaali > Parametri 3: TIMESTMP Merkitys kutsussa: Kutsun aikaleima vastauksen tunnistamista varten. Svellus lu haluamallaan tavalla aikaleiman lähettämäänsä kutsuun. Aikaleimalla ei le VETUMA-palvelun kannalta virallisen aikaleiman statusta. VETUMA-palvelu kuitenkin hylkää rajapintakutsut jiden aikaleima n (VETUMApalvelun käyttämään kelln verraten): Yli 10 minuuttia vanhempi kuin kutsun vastaanttamishetki. Yli 10 minuuttia tulevaisuudessa kutsun vastaanttamishetkeen nähden. Esitysmut: Numeerinen merkkijn, 17 merkkiä. Aikaleimaan sisältyvät vusi, kuukausi, päivä, tunti, minuutti, sekunti ja millisekunti. Esitysmut n: YYYYMMDDHHMMSSsss jssa: YYYY = vusiluku MM = kuukausi DD = päivä HH = tunti MM = minuutti SS = sekunti sss = millisekunnit yli tasasekunnin Esimerkki:...value= 20060215193245332 > 8 (47)
Parametri 4: SO Merkitys kutsussa: Kutsussa suritettavaksi pyydetyn timinnn surittamiseen käytettävä letusmenetelmä ja tarvittaessa taustapalvelu. Vaikka tämä parametri nkin pakllinen kutsuissa, niin letusvalintaa ei kuitenkaan tueta vaiheessa 2 vaan menetelmän valinta hjautuu pelkästään SOLIST-parametrin perusteella. VETUMA-palvelu tarjaa useimpien timintjensa surittamiseksi jukn vaihtehtisia menetelmiä. Svellus kert kutsun SOLIST-parametrissa (kats SOLIST-parametrin kuvaus alla) mitä menetelmiä VETUMA-palvelu saa tarjta käyttäjälle valittavaksi svelluksen pyytämän timinnn surittamiseksi. SO-parametri li vaiheessa 1 tarkitettu siihen käyttöön, että svellus visi määrätä letusmenetelmän eli hjata käyttäjän suraan tietyn menetelmän käyttöliittymäsivulle. VETUMA-palvelun vaiheessa 2 tällaista timinnallisuutta ei kuitenkaan tueta. Yhteenspivuuden vuksi SO-parametri n kuitenkin säilytetty rajapinnassa, ja siinä annetun letusmenetelmän tulee aikaisemman määrittelyn mukaisesti sisältyä SOLIST-parametrissa lueteltuihin menetelmiin. SO-nimistä parametria käytetään myös VETUMA-vastauksissa, kertmaan svellukselle millä menetelmällä timint suritettiin (kats yleiset vastausparametrit). Esitysmut: Alfanumeerinen merkkijn, 0..2 merkkiä (menetelmäkdi) Eri palvelutyyppien menetelmävalikimat kdeineen n kuvattu näiden palvelutyyppien kutsujen määrittelyjen yhteydessä. Parametri 5: SOLIST Merkitys kutsussa: Käyttäjän valittavaksi tarjttavat menetelmät timinnn surittamiseksi. VETUMA-palvelu tarjaa useimpien timintjensa surittamiseksi jukn vaihtehtisia menetelmiä. Yleisenä periaatteena n, että käyttäjä vi valita haluamansa menetelmän. VETUMA-palvelu tarjaa tätä varten timintkhtaisen menetelmän valintasivun niille timinnille jtka vidaan surittaa eri menetelmillä. Asiakas vi svellusknfiguraatissaan rajittaa menetelmävalikimaa määräämällä mitä VETUMA-palvelun tarjamista timintkhtaisista menetelmistä saa käyttää kyseisen asiakkaan svelluksissa. VETUMA-palvelua kutsuva svellus määrää knfiguraatin sisältyvän menetelmävalikiman puitteissa kutsun SOLIST-parametrissa (kats SOLIST-kutsun määrittely alla) sen menetelmävalikiman jka tarjtaan käyttäjälle kutsussa pyydetyn timinnn surittamiseen. Jissain timintamenetelmissä käytetään taustapalveluita (esimerkiksi verkkmaksupalvelua Tupas-tunnistukseen ja maksatukseen). Tietyissä tapauksissa (esimerkiksi maksunpalautus) VETUMA-palvelua kutsuva svellus määrää myös mitä menetelmää ja nimenmaista taustapalvelua tulee käyttää timinnn surittamiseen. Mikäli SOLIST-parametrissa n lueteltu useita menetelmiä, VETUMA-palvelu avaa käyttäjälle timintkhtaisen (esimerkiksi tunnistus) menetelmän valintasivun. Käyttäjä valitsee tällöin ensin menetelmän (esimerkikisi pankkitunnistus), ja tekee sen jälkeen mahdllisen menetelmäkhtaisen valinnan (esimerkiksi verkkmaksupalvelu). 9 (47)
Mikäli SOLIST-parametrissa n annettu vain yksi menetelmä, VETUMA-palvelu avaa käyttäjälle kyseisen menetelmän valintasivun. Kska vain yksi menetelmä n sallittu, käyttäjä ei tällöin vi siirtyä menetelmän valintasivulle. SOLIST-parametrissa saa lla lueteltuna vain sellaisia menetelmiä jita vidaan käyttää kutsussa pyydettyyn timintn. SOLIST-parametrissa ei saa lla lueteltuna mitään sellaista menetelmää jka ei sisälly kutsussa viitattuun knfiguraatin. Eräissä tapauksissa (esimerkiksi maksunpalautus) SOLIST-parametrissa määrätään myös mitä menetelmään kuuluvaa taustapalvelua tulee käyttää. Esitysmut: Merkkijn, 1..20 merkkiä Lista menetelmäkdeja, ertettuina pilkulla tisistaan. Parametri 6: TYPE Merkitys kutsussa: Kutsun palvelemiseen käytettävän VETUMA-palvelutyypin tunnus. VETUMA-palvelu tarjaa jukn timintja, jtka n karkealla taslla ryhmitelty palvelutyyppeihin. VETUMA-palvelun tarjamat palvelutyypit ja niiden timinnt tunnuksineen n määritelty allalevassa taulukssa: Palvelutyypin tunnus LOGIN PAYMENT Timinnn tunnus EXTAUTH CONFIRM SIGNATURE PAY RETURN Timint Tunnistus Hyväksyminen Kiistämätön allekirjitus Maksaminen verkkpalvelulla Maksun palautus Taulukk 2: Palvelutyypit tunnuksineen ja timintineen Esitysmut: Kirjaimista kstuva merkkijn, 5..10 merkkiä Esimerkki:...value= LOGIN > Parametri 7: AU Merkitys kutsussa: Kutsussa pyydettävän timinnn kdi. VETUMA-palvelun palvelutyypit tunnuksineen sekä niiden tarjamat timinnt kdeineen n määritelty kutsuparametrin TYPE määrittelyn yhteydessä annetussa taulukssa (Taulukk 2). Esitysmut: Kirjaimista kstuva merkkijn, 3..10 merkkiä Esimerkki:...value= SIGNATURE > 10 (47)
Parametri 9: LG Merkitys kutsussa: Käyttöliittymän kieli. Kutsuessaan VETUMA-palvelua svellus määrää, mitä (VETUMA-palvelussa tuettua) kieltä VETUMA-palvelun käyttöliittymän tulee käyttää. Määräys kskee sekä selainkäyttöliittymää että puhelutunnistuksessa käytettävää äänikäyttöliittymää. Kielen tulee lla mukana kutsussa käytettävässä knfiguraatissa. VETUMA-palvelun versi 2 tarjaa sumen-, rutsin- ja englanninkielisen käyttöliittymän. VETUMA-palvelu pyrkii välittämään kielivalinnan myös kutsumilleen taustapalveluille. Eräissä tapauksissa VETUMA-palvelu ei kuitenkaan vi vaikuttaa kutsumansa taustapalvelun käyttämään käyttöliittymäkieleen, esimerkiksi: Tiettyjen pankkien verkkpalveluissa kieli määrätään kansalaisen pankin kanssa tekemässä verkkpalveluspimuksessa. Vastaavasti tietyillä mbiilikansalaisvarmenteen sisältävillä SIM-krteilla ei tueta kielivalintaa tai ei tueta kaikkia VETUMA-palvelussa tuettuja kieliä. Esitysmut: Merkkijn, 2 merkkiä ISO 639-1-standardin mukainen 2-kirjaiminen kielikdi pienillä kirjaimilla. VETUMA-palvelun versissa 1.5 siis jk fi, sv tai en Esimerkki:...value= fi > Parametri 10: RETURL Merkitys kutsussa: Paluusite svellukseen nnistuneen tapahtuman jälkeen. VETUMA-palvelu hjaa käyttäjän selaimen RETURL-parametrissa annettuun sitteeseen palveltuaan nnistuneesti VETUMA-rajapintakutsun. Paluuyhteyden tulee lla SSL/TLS-sujattu, eli paluusitteen tulee alkaa: https://. Kutsuva svellus n vastuussa paluusitteen ikeellisuudesta, VETUMA-palvelu ei tarkista sitteesta muuta kuin että se alkaa: https:// :llä. RETURL-sitteeseen palataan HTTP:n POST-kutsulla, vastauksen parametrit HTMLlmakkeen kenttinä. Esitysmut: URL-syntaksin mukainen merkkijn, maksimipituus 1000 merkkiä. Esimerkki:...value= https://www.ankkalinna.fi/prtaali/tunnistettu.jsp > Parametri 11: CANURL Merkitys kutsussa: Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen. VETUMA-palvelu hjaa käyttäjän selaimen CANURL-parametrissa annettuun sitteeseen js käyttäjä peruu VETUMA-rajapintakutsussa pyydetyn timinnn. Paluuyhteyden tulee lla SSL/TLS-sujattu, eli paluusitteen tulee alkaa: https://. Kutsuva svellus n vastuussa paluusitteen ikeellisuudesta, VETUMA-palvelu ei tarkista sitteesta muuta kuin että se alkaa: https:// :llä. CANURL-sitteeseen palataan HTTP:n POST-kutsulla, vastauksen parametrit HTMLlmakkeen kenttinä. 11 (47)
Esitysmut: URL-syntaksin mukainen merkkijn, maksimipituus 1000 merkkiä. Esimerkki:...value= https://www.ankkalinna.fi/prtaali/tunn_peruttu.jsp > Parametri 12: ERRURL Merkitys kutsussa: Paluusite svellukseen virhetilanteen jälkeen. VETUMA-palvelu hjaa käyttäjän selaimen ERRURL-parametrissa annettuun sitteeseen virhetilanteessa. Virhepaluu suritetaan js: Kutsussa havaitaan virhe (esimerkiksi syntaksivirhe, spimatn parametrin arv, tai knfiguraatin sisältymättömän piirteen käyttö). Pyydetyn timinnn surituksen aikana tapahtuu virhe (esimerkiksi sallittujen tunnistusyritysten raja ylittyy). Pyydetyn timinnn surituksessa käytettävä taustapalvelu hylkää kutsun (esimerkiksi maksupalvelu hylkää maksutapahtuman kska maksajan tileillä ei le riittävästi katetta maksun surittamiseen). Paluuyhteyden tulee lla SSL/TLS-sujattu, eli paluusitteen tulee alkaa: https://. Js kutsun palveleminen epännistuu ja ERRURL-site puuttuu tai ei ala https:// :lä niin VETUMA-palvelu ei surita lainkaan paluuta. Kutsuva svellus n vastuussa paluusitteen ikeellisuudesta, VETUMA-palvelu ei tarkista sitteesta muuta kuin että se alkaa: https:// :llä. ERRURL-sitteeseen palataan HTTP:n POST-kutsulla, vastauksen parametrit HTMLlmakkeen kenttinä. Esitysmut: URL-syntaksin mukainen merkkijn, maksimipituus 1000 merkkiä. Esimerkki:...value= https://www.ankkalinna.fi/prtaali/tunn_virhe.jsp > Parametri 13: AP Merkitys kutsussa: Kutsun palvelemisessa käytettävän VETUMA-svellusknfiguraatin tunnus. Svellusknfiguraatiilla mukautetaan VETUMA-palvelun timimaan tietyn asiakkaan tietyntyyppisiä asiintisvelluksia varten. Tietyllä asiakkaalla vi lla käytössään useita knfiguraatiita. VETUMA-palvelun timittaja (Fujitsu Services OY) määrää knfiguraatiiden tunnukset ja antaa ne asiakkaille. Esitysmut: Alfanumeerinen merkkijn, pituus 5..15 merkkiä Esimerkki:...value= Ankkalinna_1 > Parametri 15: MAC Merkitys kutsussa: Kutsun turvatarkiste (MAC) Svelluksen tulee laskea kutsun turvartarkiste tämän luvun kappaleessa Turvatarkisteen mudstaminen kuvatulla tavalla. 12 (47)
Esitysmut: Alfanumeerinen merkkijn jssa sallitaan heksadesimaalimerkit (numert 0..9 ja kirjaimet A..F). Pituus riippuu algritmista: SHA-256: 64 merkkiä SHA-1: 40 merkkiä MD5: 32 merkkiä Turvatarkisteena käytettävä tiiviste heksadesimaalimudssa, merkkijnna esitettynä. Heksadesimaalimerkeissä A..F vi käyttää jk pieniä tai isja kirjaimia. Esimerkki:...value= 0D951095739D4D5D4704A0AC1C2299AD >...value= 0d951095739d4d5d4704a0ac1c2299ad > Parametri 20: APPNAME Merkitys kutsussa: VETUMA-palvelua kutsuvan svelluksen nimi näytettäväksi VETUMApalvelun käyttöliittymässä. VETUMA-palvelun käyttöliittymä näyttää svelluksen niin halutessa mistä svelluksesta palvelua kutsuttiin. Mikäli svellus ei halua nimeään näytettäväksi VETUMA-palvelun käyttöliittymässä, tulee sen jättää APPNAME-parametri pis kutsusta. Esitysmut: Merkkijn, pituus enintään 40 merkkiä Sallitut merkit vat: Numert, kirjaimet, välilyönti, tavuviiva, piste, pilkku, kaksispiste ja pulipiste. Esimerkki:...value= Ankkalinnan päivähitpalvelut > Parametri 34: TRID Merkitys kutsussa: Tapahtumatunnus kutsujen ja vastausten yhdistämiseen. Svellus vi halutessaan antaa VETUMA-kutsulle tapahtumatunnuksen, jnka VETUMA-palvelu palauttaa sellaisenaan vastauksessa kyseiseen kutsuun. Tunnus n tarkitettu helpttamaan tietyn kutsun ja siihen tulevan vastauksen yhdistämistä tisiinsa. TRID-parametri n valinnainen kutsuparametri, jllei sitä anneta kutsussa, ei sitä myöskään palauteta vastauksessa. Esitysmut: Merkkijn, pituus enintään 20 merkkiä, sallittuja merkkejä numert ja kirjaimet. 13 (47)
2.7 VETUMA-vastausten yleiset parametrit Allalevassa taulukssa n lueteltu ne VETUMA-rajapinnan parametrit jtka esiintyvät samalla tavalla kaikissa vastaustyypeissä: Nr Nimi Merkitys 1 RCVID Vastauksen sujauksessa käytetyn jaetun salaisuuden tunnus 3 TIMESTMP Vastauksen aikaleima 4 SO Käytetty menetelmä 1) 9 LG Käytetty käyttöliittymäkieli. 10 RETURL Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL Virhepaluusite svellukseen 15 MAC Vastauksen turvatarkiste (MAC) 29 STATUS Tiet timinnn surittamisesta tai surittamatta jättämisestä. 34 TRID Tapahtumatunnus. 1) Parametrin SO tulkinnissa n timintkhtaisia vivahde-erja. SO-parametri timintkhtaisine tulkintineen n kuvattu tarkemmin kunkin timintkhtaisten vastaustyypin yhteydessä. Taulukk 3: VETUMA-vastausten yleiset parametrit Parametri 1: RCVID Merkitys vastauksessa: Vastauksen turvatarkisteen (MAC) laskennassa käytetyn jaetun salaisuuden tunnus. VETUMA-palvelu käyttää vastauksessa samaa jaettua salaisuutta jta asiintisvellus käytti VETUMA-palvelukutsussa. Parametri 3: TIMESTMP Merkitys vastauksessa: Vastauksen aikaleima. VETUMA-palvelu mudstaa aikaleiman jnka se palauttaa vastauksessa. Samin kuin kutsuissa, tällä aikaleimalla ei le virallisen aikaleiman statusta. Aikaleiman esitysmut n kuvattu TIMESTMP-kutsuparametrin yhteydessä. Parametri 4: SO Merkitys vastauksessa: Se timinnn surittamismenetelmä, jlla käyttäjä suritti timinnn. Esitysmut: Merkkijn, pituus 1..2 merkkiä (menetelmäkdi ja tarkenne) Eri palvelutyyppien menetelmävalikimat kdeineen n kuvattu näiden palvelutyyppien kutsujen määrittelyjen yhteydessä. Parametri 9: LG Merkitys vastauksessa: Käytetty käyttöliittymäkieli. VETUMA-palvelu palauttaa sen kielen kielikdin jta svelluksen määräämänä käytettiin VETUMA-käyttöliittymässä. 14 (47)
Parametri 10: RETURL Merkitys vastauksessa: Paluusite svellukseen nnistuneen tapahtuman jälkeen. VETUMApalvelu palauttaa vastauksen RETURL-parametrissa kutsussa saamansa RETURL-parametrin arvn. Parametri 11: CANURL Merkitys vastauksessa: Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen. VETUMA-palvelu palauttaa vastauksen CANURL-parametrissa kutsussa saamansa CANURLparametrin arvn.. Parametri 12: ERRURL Merkitys vastauksessa: Virhepaluusite svellukseen. VETUMA-palvelu palauttaa vastauksen ERRURL-parametrissa kutsussa saamansa ERRURL-parametrin arvn. Parametri 15: MAC Merkitys vastauksessa: Vastauksen turvatarkiste (MAC). VETUMA-palvelu mudstaa vastauksen turvatarkisteen tämän luvun kappaleessa Turvatarkisteen mudstaminen kuvatulla tavalla. Parametri 29: STATUS Merkitys vastauksessa: Tiet kutsun surittamisesta tai surittamatta jättämisestä. Esitysmut: Merkkijn, pituus enintään 50 merkkiä. STATUS-parametrin arv kert miten kutsun käsittely nnistui. Sillä vi lla arvt: SUCCESSFUL = kutsun palveleminen nnistui CANCELLED = käyttäjä keskeytti tai perui kutsussa pyydetyn timinnn surittamisen. REJECTED = Kutsun palveleminen epännistui, kska se käyttäjän valitsema vurvaikutteinen taustapalvelu jhn VETUMA-palvelu hjasi käyttäjän timinta surittamaan hylkäsi timinnn surittaminen. ERROR = kutsu li virheellinen FAILURE = kutsun palveleminen epännistui jstain muusta syystä kuin siitä, että taustapalvelu hylkäsi surittamisen. Parametri 34: TRID Merkitys vastauksessa: Svelluksen kutsussa antama tapahtumatunnus. Ellei tapahtumatunnusta annettu kutsussa, ei sitä myöskään palauteta vastauksessa. 3. TUNNISTUS, HYVÄKSYMINEN JA ALLEKIRJOITUS (LOGIN-PALVELUTYYPPI) VETUMA-palvelun palvelutyyppi LOGIN tarjaa asiintisvelluksille seuraavat timinnt: käyttäjän tunnistaminen, käyttäjän surittama hyväksyminen ja käyttäjän surittama kiistämätön sähköinen allekirjitus. Nämä timinnt n kuvattu dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Tässä luvussa kuvataan näiden timintjen kutsut ja vastaukset parametreineen. 15 (47)
3.1 Menetelmät VETUMA-palvelu tarjaa jukn vaihtehtisia menetelmiä LOGIN-palvelutyypin timintjen surittamiseksi. Nämä menetelmät n kuvattu dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Menetelmien tunnukset sekä kunkin menetelmän yhteydessä käytettävä menetelmäkhtainen käyttäjän tunnisteen tiettyyppi n esitetty allalevassa taulukssa. Kaikissa menetelmissä svellus vi kuitenkin halutessaan saada tunnistusvastauksessa käyttäjän tunnisteena myös HETU:n. Menetelmä Sirukrttiphjainen kansalaisvarmennetunnistus (HST-tunnistus) SIM-krttiphjainen mbiilikansalaisvarmennetunnistus Selainphjainen salasanatunnistus Kdi Käytettävissä timinnissa: Tunn. Hyv. Allekirj. 2 x x x SATU 1 x x x SATU Käyttäjän henkilöllisyyden sittamisessa käytettävä tiettyyppi 3 x x Käyttäjätunnus Puhelutunnistus 0 x x Puhelinnumer Tupas-tunnistus 6 x x HETU Taulukk 4: LOGIN-palvelutyypissä tuetut menetelmät Tupas-menetelmää käytettäessä palautetaan vastauksissa menetelmäkdin 6 lisäksi sen pankin tai pankkiryhmän numer jnka verkkpalvelua käyttäen käyttäjä suritti timinnn. VETUMA-palvelun käyttämät pankkien numert Tupas-menetelmän yhteydessä n kerrttu allalevassa taulukssa: Pankin numer Pankki tai pankkiryhmä 2 Nrdea 3 Tapila 4 Säästöpankkiryhmä 5 OP-ryhmä 6 Ålandsbanken 7 Handelsbanken 8 Samp Taulukk 5: Pankkien ja pankkiryhmien Tupas-numert VETUMA-rajapinnassa Esimerkkejä valitun menetelmän palauttamisesta vastauksessa:...value= 2 > (Timint suritettiin kansalaisvarmenteen sisältävällä sirukrtilla)...value= 21 > (Timint suritettiin matkapuhelimella, kansalaisvarmenteen sisältävällä SIM-krtilla) 16 (47)
...value= 64 > (Timint suritettiin Tupas-menetelmällä käyttäen Säästöpankkiryhmän verkkpalvelua) 3.2 LOGIN-palvelutyypin yleiset kutsu- ja vastausparametrit Kaikissa LOGIN-palvelutyypin timintjen kutsuissa käytetään VETUMA-rajapintakutsuille yhteisiä parametreja, jtka n kuvattu kappaleessa VETUMA-kutsujen yleiset parametrit. Vastaavasti kaikissa LOGIN-palvelutyypin timintjen vastauksissa käytetään VETUMArajapintavastauksille yhteisiä parametreja, jtka n kuvattu kappaleessa VETUMA-vastausten yleiset parametrit. Edellä mainittujen parametrien lisäksi n jukk parametreja jtka esiintyvät kaikissa LOGINpalvelutyypin timintjen kutsuissa, ja jukk parametreja jtka esiintyvät kaikissa LOGINpalvelutyypin timintjen vastauksissa. Ne parametrit n kuvattu tässä kappaleessa. 3.2.1 Yleiset LOGIN-palvelutyypin kutsuparametrit Allalevassa taulukssa n lueteltu ne parametrit jtka esiintyvät kaikille rajapintakutsuille yhteisten parametrien lisäksi kaikissa LOGIN-palvelutyypin timintjen kutsuissa: Nr Nimi Merkitys 19 EXTRADATA VTJ-kyselypyyntö Taulukk 6: LOGIN-palvelutyypin kutsujen yleiset parametrit Parametri19: EXTRADATA Merkitys kutsussa: VTJ-kyselypyyntö. Kun käyttäjä valitsee tunnistautumisen tai hyväksymisen pankkitunnistuksella, saa VETUMA-palvelu pankilta tunnistetun käyttäjän HETU:n ja palauttaa sen aina vastauksen EXTRADATA-parametrissa. Kun käyttäjä valitsee tunnistautumisen tai hyväksymisen käyttäjätunnussalasanatunnistuksella, saa VETUMA-palvelu käyttäjätietkannastaan tunnistetun käyttäjän HETU:n ja palauttaa sen aina vastauksen EXTRADATA-parametrissa. Kun käyttäjä valitsee tunnistautumisen, hyväksymisen tai allekirjituksen kansalaisvarmenteella, saa VETUMA-palvelu tietnsa käyttäjän SATU:n. Vidakseen palauttaa käyttäjän HETU:n n VETUMA-palvelun kysyttävä VTJ:stä SATU:a vastaava HETU. Tällä kyselyllä n VETUMA-palvelun rajapinnassa tunnus VTJ1. Asiintisvellus vi kutsussa valita, suritetaank VTJ-kysely HST-krttia käytettäessä vai ei. Js svellus antaa kutsun EXTRADATA-parametrissa VTJ:stä suritettavan HETUkyselyn tunnuksen ( VTJ1 ), niin: Js kysymyksessä n tunnistus- tai hyväksymiskutsu ja js käyttäjä valitsee jk pankkitunnistuksen tai käyttäjätunnus-salasanatunnistuksen, niin VETUMA-palvelu palauttaa aina HETU:n EXTRADATA-paluuparametrissa riippumatta EXTRADATA-kutsuparametrin arvsta. 17 (47)
Js kysymyksessä n allekirjituskutsu tai tunnistus- tai hyväksymiskutsu jhn käyttäjä valitsee menetelmäksi kansalaisvarmenteen käytön, tutkii VETUMA-palvelu EXTRADATA-parametrin arvn. Mikäli parametrin arvlla n pyydetty HETU:n nutamista VTJ:stä, VETUMA-palvelu nutaa HETU:n ja palauttaa sen vastauksen EXTRADATA-parametrissa. Mikäli parametri puuttuu tai mikäli sen arvlla ei le pyydetty HETU:n nutamista VTJ:stä, palauttaa VETUMA-palvelu EXTRADATAparametrissa tyhjän HETU:n arvn. Parametri EXTRADATA vidaan jättää pis tunnistuskutsusta, jllin sen ei myöskään saa lla mukana MAC-laskennassa. Esitysmut: Merkkijn, enintään 50 merkkiä. Esimerkki:...value= VTJ1 > (Aina vaiheessa 2 tuettu kysely) 3.2.2 Yleiset LOGIN-palvelutyypin vastausparametrit Allalevassa taulukssa n lueteltu ne parametrit jtka esiintyvät kaikille rajapintavastauksille yhteisten parametrien lisäksi kaikissa LOGIN-palvelutyypin timintjen vastauksissa. Nr Nimi Merkitys 8 USERID Timinnn surittaneen käyttäjän henkilöllisyys 18 SUBJECTDATA Käyttäjän nimitiedt 19 EXTRADATA Käyttäjän HETU 1) 1) Paitsi js valittu menetelmä li HST-krtti tai mbiilivarmenne, eikä HETU:n kyselyä VTJ:stä llut pyydetty kutsussa. Taulukk 7: VETUMA-vastausten yleiset parametrit Parametri 8: USERID Merkitys vastauksessa: Timinnn surittaneen käyttäjän henkilöllisyys. VETUMA-palvelun tarjamat LOGIN-palvelutyypin timintjen suritusmenetelmät käyttävät erilaisia tiettyyppejä tunnistettujen käyttäjien henkilöllisyyden sittamiseen. Tunnistusmenetelmien käyttämät henkilöllisyyden sittamien tiettyypit n esitetty tämän luvun Menetelmät-kappaleessa. Esitysmut: Merkkijn, pituus 1..20 merkkiä. Tiettyypin syntaksin mukainen henkilöllisyystiet. Palautettaessa puhelinnumera puhelutunnistuksessa se palautetaan kansainvälisessä mudssa +<maatunnus><suuntanumer><liittymän numer> ilman välilyöntejä, esimerkiksi +35891234567. Esimerkki:...value= 010101-123N > (Tupas-tunnistuksen palauttama HETU) 18 (47)
Parametri 18: SUBJECTDATA Merkitys vastauksessa: Käyttäjän nimitiedt mikäli ne vat tapahtuman surituksen yhteydessä saatavilla. VETUMA-palvelu palauttaa palvellun kutsun surittamisessa käytetyn menetelmän antamat käyttäjän etu- ja sukunimen. Menetelmätyyppien antamien nimitietjen lähteet n kerrttu allalevassa taulukssa. Menetelmätyyppi Kansalaisvarmenteeseen perustuvat menetelmät VETUMA-palvelun käyttäjätietkantaan perustuvat menetelmät Pankkien verkkpalveluihin perustuvat menetelmät Nimitietjen lähde Tunnistetun käyttäjän varmenteen Subject-kentän sisältämät nimitiedt. VETUMA-palvelun käyttäjätietkantaan tunnistetusta käyttäjästä tallennetut nimitiedt. Pankin asiakastietkannassa leva asiakkaan nimi. Taulukk 8: Nimitietjen lähde eri menetelmätyypeissä Esitysmut: Merkkijn, pituus enintään 100 merkkiä. Mut: ETUNIMI=<etunimet>, SUKUNIMI=<sukunimi>, jssa Esimerkkejä: <etunimet> n käytetyn menetelmän antamat etunimet <sukunimi> n käytetyn menetelmän antama sukunimi....value= ETUNIMI=Armas Oskari, SUKUNIMI=Aallntie >...value= ETUNIMI=Maija, SUKUNIMI=Sinisal-Kskinen >...value= ETUNIMI=, SUKUNIMI= > (Tyhjät nimitiedt mikäli niitä ei jstain syystä le tapahtuman surituksen yhteydessä saatavilla). Parametri 19: EXTRADATA Merkitys vastauksessa: Tunnistetun käyttäjän henkilötunnus (HETU), kuitenkin: Tyhjä mikäli valittu menetelmä perustui kanasalaisvarmenteeseen ja VTJ1-kyselyä ei pyydetty kutsussa. VTJ:n palauttama virhekdi mikäli valittu menetelmä perustui kanasalaisvarmenteeseen, VTJ1-kyselyä pyydettiin kutsussa, mutta kysely epännistui. Esitysmut: Merkkijn, pituus enintään 100 merkkiä. Mut n HETU=<henkilötunnus>, jssa <henkilötunnus> n tunnistetun käyttäjän henkilötunnus HETU:n esitysmut n HETU-syntaksin mukainen Esimerkki:...value= HETU=010101-123N >...value= HETU= > (Tyhjä HETU kun käyttäjän valitsema tunnistautumismenetelmä perustui kanasalaisvarmenteeseen eikä VTJ1- kyselyä llut pyydetty tunnistuskutsussa) 19 (47)
3.3 Käyttäjän tunnistus Käyttäjän tunnistus tarkittaa tässä sitä, että asiintisvellus pyytää VETUMA-palvelua tunnistamaan svellusistunnn käyttäjän. Tunnistaminen n kuvattu dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Tämän dkumentin tässä kappaleessa kuvataan tunnistukutsu ja -vastaus parametreineen. 3.3.1 Tunnistuskutsun parametrit Allalevassa taulukssa n lueteltu VETUMA-tunnistuskutsun parametrit. Sarakkeessa P n kerrttu nk parametri pakllinen vai valinnainen. Nr Nimi P Merkitys 1 RCVID 1) p Kutsun sujauksessa käytetyn jaetun salaisuuden tunnus 2 APPID 1) p VETUMA-palvelua kutsuvan asiintisvelluksen tunnus 3 TIMESTMP 1) p Kutsun aikaleima 4 SO 1) p Oletusmenetelmä tunnistautumiseen 5 SOLIST 1) p Käyttäjälle tarjttavat menetelmät tunnistautumiseen 6 TYPE 1) p Käytettävän VETUMA-palvelun tyypin tunnus 3) 7 AU 1) p Pyydettävän timinnn kdi 4) 9 LG 1) p Käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 13 AP 1) p Kutsun palvelemisessa käytettävän knfiguraatin tunnus 15 MAC 1) p Kutsun turvatarkiste (MAC) 19 EXTRADATA 2) v VTJ-kyselypyyntö 20 APPNAME 1) v Kutsuvan svelluksen nimi käyttöliittymää varten 34 TRID 1) v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan kutsuissa. 2) Parametri jka esiintyy kaikissa LOGIN-timinnn kutsuissa 3) Parametrilla TYPE n vakiarv LOGIN tunnistuskutsuissa. 4) Parametrilla AU n vakiarv EXTAUTH tunnistuskutsuissa. Taulukk 9: VETUMA-tunnistuskutsun parametrit 20 (47)
3.3.2 Tunnistusvastauksen parametrit Allalevassa taulukssa n lueteltu ne VETUMA-rajapinnan parametrit jtka esiintyvät tunnistusvastauksissa. Sarakkeessa P n kerrttu nk parametri pakllinen vai valinnainen. Nr Nimi P Merkitys 1 RCVID 1) p Vastauksen sujauksessa käytetyn jaetun salaisuuden tunnus 3 TIMESTMP 1) p Tunnistusvastauksen aikaleima 4 SO 1) p Käytetty menetelmä (ja taustapalvelu) tunnistautumisessa 8 USERID 2) p Tunnistautumisen surittaneen käyttäjän henkilöllisyys 9 LG 1) p Käytetty käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 15 MAC 1) p Vastauksen turvatarkiste (MAC) 18 SUBJECTDATA 2) p Käyttäjän nimitiedt 19 EXTRADATA 2) p Käyttäjän HETU (tai VTJ-virhekdi) 3) 29 STATUS 1) p Tunnistustapahtuman nnistumisen kdi. 34 TRID 1) v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan vastauksissa 2) Parametri jka esiintyy kaikissa LOGIN-timinnn kutsuissa 3) Paitsi js käyttäjän valitsema menetelmä perustui kanasalaisvarmenteeseen, eikä HETU:n kyselyä VTJ:stä llut pyydetty kutsussa. Taulukk 10: VETUMA-tunnistusvastauksen parametrit 3.4 Käyttäjän surittama hyväksyminen Käyttäjän surittama hyväksyminen tarkittaa tässä sitä, että asiintisvellus pyytää svellusistunnn käyttäjää hyväksymään tunnistautumalla sellaisen asiintitimenpiteen jnka hyväksymiseksi riittää käyttäjän tunnistus. Hyväksyminen n kuvattu dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Tämän dkumentin tässä kappaleessa kuvataan hyväksymiskutsu ja -vastaus parametreineen. 21 (47)
3.4.1 Hyväksymiskutsun parametrit Allalevassa taulukssa n lueteltu VETUMA-hyväksymiskutsun parametrit. Nr Nimi P Merkitys 1 RCVID 1) p Kutsun sujauksessa käytetyn jaetun salaisuuden tunnus 2 APPID 1) p VETUMA-palvelua kutsuvan asiintisvelluksen tunnus 3 TIMESTMP 1) p Kutsun aikaleima 4 SO 1) p Oletusmenetelmä hyväksymiseen 5 SOLIST 1) p Käyttäjälle tarjttavat menetelmät hyväksymiseen. 6 TYPE 1) p Käytettävän VETUMA-palvelun tyypin tunnus 3) 7 AU 1) p Pyydettävän timinnn kdi 4) 8 USERID p Hyväksyvän käyttäjän henkilöllisyys 9 LG 1) p Käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 13 AP 1) p Kutsun palvelemisessa käytettävän knfiguraatin tunnus 15 MAC 1) p Kutsun turvatarkiste (MAC) 19 EXTRADATA 2) v VTJ-kyselypyyntö 20 APPNAME 1) v Kutsuvan svelluksen nimi käyttöliittymää varten 34 TRID 1) v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan kutsuissa. 2) Parametri jka esiintyy kaikissa LOGIN-timinnn kutsuissa 3) Parametrilla TYPE n vakiarv LOGIN hyväksymiskutsuissa. 4) Parametrilla AU n vakiarv CONFIRM hyväksymiskutsuissa. Taulukk 11: VETUMA-hyväksymiskutsun parametrit Parametri 4: SO Merkitys hyväksymiskutsussa: Se tunnistusmenetelmä, jnka VETUMA-palvelun käyttöliittymän tulee käynnistyessään tarjta valmiiksi valittuna käyttäjälle hyväksymistä varten. Oletusvalintaa ei kuitenkaan tueta vaiheessa 2 vaan menetelmän valinta hjautuu pelkästään SOLIST-parametrin perusteella. Parametri 5: SOLIST Merkitys hyväksymiskutsussa: Ne tunnistusmenetelmät jtka VETUMA-palvelun käyttöliittymän tulee hyväksymiskutsua palvellessaan tarjta käyttäjälle valittavaksi hyväksymistä (tunnistautumista) varten. Hyväksymiskutsussa annetaan parametrissa USERID sen käyttäjän henkilöllisyys, jlta dtetaan hyväksyntää. 22 (47)
Hyväksymiseen käytettävän tunnistusmenetelmän tulee vastata hyväksymiskutsussa annettavan käyttäjän henkilöllisyyden tiettyyppiä. Js käyttäjä tunnistautui alun perin jllain muulla menetelmällä kuin kansalaisvarmenteeseen perustuvalla menetelmällä, tulee SOLIST-parametrissa yhteenspivuuden vuksi määrätä tarjttavaksi vain kyseinen tunnistusmenetelmä. Js käyttäjä tunnistautui alun perin kansalaisvarmenteeseen perustuvalla menetelmällä, vi SOLIST-parametrissa määrätä tarjttavaksi kansalaisvarmenteeseen perustuvat menetelmät. Käyttäjä vi valita minkä tahansa niistä, kska kaikissa käyttäjän tunniste n SATU. Tunnistusmenetelmien käyttämät henkilöllisyyden situksen tiettyypit n esitetty tämän luvun Menetelmät-kappaleessa. SOLIST-parametrissa vi lla lueteltuna vain sellaisia tunnistusmenetelmiä jtka sisältyvät hyväksymiskutsussa viitattuun knfiguraatin. Parametri 8: USERID Merkitys hyväksymiskutsussa: Hyväksyvän käyttäjän henkilöllisyys (eli sen käyttäjän henkilöllisyys, jta pyydetään surittamaan hyväksyntä tunnistautumalla). Käyttäjän henkilöllisyys n sitettava sellaisella tiettyypillä, jta käyttää ainakin yksi VETUMA-palvelun tunnistusmenetelmistä. Henkilöllisyyden sittamiseen käytettävän tiettyypin n myös vastattava SOLISTparametrissa annettujen menetelmien käyttämää henkilöllisyyden tunnisteen tiettyyppiä.. Esitysmut: Merkkijn jssa vi lla numerita ja kirjaimia sekä HETU:ssa ja puhelinnumerssa esiintyviä erikismerkkejä ( + ja - ), pituus 1..20 merkkiä Tunnistusmenetelmien käyttämät henkilöllisyyden situksen tiettyypit n esitetty SOkutsuparametrin kuvauksessa (Taulukk 4). Henkilöllisyys n annettava tarkalleen samassa esitysmudssa kuin se palautetaan tunnistusvastauksessa. Esimerkiksi puhelinnumer n annettava kansainvälisessä mudssa +<maatunnus><suuntanumer><liittymän numer> ilman välilyöntejä. Esimerkki:...value= 010101-123N > 23 (47)
3.4.2 Hyväksymisvastauksen parametrit Allalevassa taulukssa n lueteltu ne VETUMA-rajapinnan parametrit jtka esiintyvät hyväksymisvastauksissa. Nr Nimi P Merkitys 1 RCVID 1) p Vastauksen sujauksessa käytetyn jaetun salaisuuden tunnus 3 TIMESTMP 1) p Hyväksymisvastauksen aikaleima 4 SO 1) p Käytetty menetelmä (ja taustapalvelu) hyväksymisessä 8 USERID 2) p Hyväksymisen surittaneen käyttäjän henkilöllisyys 9 LG 1) p Käytetty käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 15 MAC 1) p Vastauksen turvatarkiste (MAC) 18 SUBJECTDATA 1) p Käyttäjän nimitiedt 19 EXTRADATA 2) p Käyttäjän HETU 3) 29 STATUS 1) p Hyväksymistapahtuman nnistumisen kdi. 34 TRID 1) v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan vastauksissa. 2) Parametri jka esiintyy kaikissa LOGIN-timinnn vastauksissa 3) Paitsi js käyttäjän valitsema menetelmä li HST-krtti, eikä HETU:n kyselyä VTJ:stä llut pyydetty kutsussa. Taulukk 12: VETUMA-hyväksymisvastauksen parametrit 3.5 Käyttäjän surittama kiistämätön sähköinen allekirjitus Käyttäjän surittama kiistämätön sähköinen allekirjitus tarkittaa tässä sitä, että asiintisvellus pyytää svellusistunnn käyttäjää allekirjittamaan kansalaisvarmenteeseensa liittyvällä salaisella avaimella svelluksen antaman tekstin. Kiistämättömän allekirjituksen surittaminen VETUMA-palvelua käyttäen n kuvattu dkumentissa Sumalaisen julkishallinnn VETUMA-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Tässä kappaleessa kuvataan allekirjituskutsu ja -vastaus parametreineen. 24 (47)
3.5.1 Allekirjituskutsun parametrit Allalevassa taulukssa n lueteltu VETUMA-allekirjituskutsun parametrit. Nr Nimi P Merkitys 1 RCVID 1) p Kutsun sujauksessa käytetyn jaetun salaisuuden tunnus 2 APPID 1) p VETUMA-palvelua kutsuvan asiintisvelluksen tunnus 3 TIMESTMP 1) p Kutsun aikaleima 4 SO 1) p Oletusmenetelmä allekirjitukseen 5 SOLIST 1) p Käyttäjälle tarjttavat menetelmät allekirjitukseen 6 TYPE 1) p Käytettävän VETUMA-palvelun tyypin tunnus 3) 7 AU 1) p Pyydettävän timinnn kdi 4) 9 LG 1) p Käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 13 AP 1) p Kutsun palvelemisessa käytettävän knfiguraatin tunnus 14 TTS p Allekirjitettava teksti 15 MAC 1) p Kutsun turvatarkiste (MAC) 19 EXTRADATA 2) v VTJ-kyselypyyntö 20 APPNAME 1) v Kutsuvan svelluksen nimi käyttöliittymää varten 34 TRID 1) v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan kutsuissa. 2) Parametri jka esiintyy kaikissa LOGIN-timinnn kutsuissa 3) Parametrilla TYPE n vakiarv LOGIN allekirjituskutsuissa. 4) Parametrilla AU n vakiarv SIGNATURE allekirjituskutsuissa. Taulukk 13: VETUMA-allekirjituskutsun parametrit Parametri 14: TTS Merkitys allekirjituskutsussa: Allekirjitettava teksti. VETUMA-palvelu välittää allekirjitettavan tekstin sellaisenaan allekirjituksen tteuttavalle kmpnentille. Allekirjituksen tteuttava kmpnentti käyttäjän työasemassa tai mbiililaitteessa näyttää allekirjitettavan tekstin käyttäjälle. Käyttäjän työasemaan asennettu allekirjituskmpnentti saattaa asettaa rajituksia allekirjitettavassa tekstissä esiintyvien merkkien suhteen, sekä sille, miten pitkä teksti n helpsti luettavissa esimerkiksi ilman runsasta vierittämistä. Ymmärrettävyys- ja sitvuusnäkökhtien lisäksi asiintisvelluksen tulee siis myös hulehtia tekstin luettavuudesta allekirjitusta suritettaessa. 25 (47)
Esitysmut: Merkkijn, sallittuja merkkejä vat abcdefghijklmnpqrstuvwxyzåäö ABCDEFGHIJKLMNOPQRSTUVWXYZÅÄÖ 01234567890 +,-_/*.;:()!? @$. Mikäli SOLIST-parametrissa n sallittu allekirjitus vain sirukrtilla levalla kansalaisvarmentella, enimmäispituus n 2000 merkkiä. Mikäli SOLIST-parametrissa n sallittu allekirjitus mbiilivarmenteella, enimmäispituus n 160 merkkiä. Esimerkki:...value= Varaan Ankkalinnan kaupungin venepaikan H-35 vudeksi 2006 > 3.5.2 Allekirjitusvastauksen parametrit Allalevassa taulukssa n lueteltu ne VETUMA-rajapinnan parametrit jtka esiintyvät allekirjitusvastauksissa. Nr Nimi P Merkitys 1 RCVID 1) p Vastauksen sujauksessa käytetyn jaetun salaisuuden tunnus 3 TIMESTMP 1) p Allekirjitusvastauksen aikaleima 4 SO 1) p Käytetty menetelmä allekirjituksessa 8 USERID 2) p Allekirjittaneen käyttäjän henkilöllisyys 9 LG 1) p Käytetty käyttöliittymäkieli 10 RETURL 1) p Paluusite svellukseen nnistuneen tapahtuman jälkeen 11 CANURL 1) p Paluusite svellukseen käyttäjän peruman tapahtuman jälkeen 12 ERRURL 1) p Virhepaluusite svellukseen 14 TTS p Allekirjitettu teksti 15 MAC 1) p Vastauksen turvatarkiste (MAC) 16 SIGNATURE p Allekirjitus 17 SIGNATURESTATUS p Allekirjituksen tarkistuksen tuls 18 SUBJECTDATA 2) p Käyttäjän nimitiedt 19 EXTRADATA 2) p Käyttäjän HETU 3) 29 STATUS 1) p Allekirjitustapahtuman nnistumisen kdi. 34 TRID v Tapahtumatunnus 1) Yleinen parametri jka esiintyy kaikissa VETUMA-rajapinnan vastauksissa 2) Parametri jka esiintyy kaikissa LOGIN-timinnn vastauksissa 3) Paitsi js valittu menetelmä li HST-krtti, eikä HETU:n kyselyä VTJ:stä llut pyydetty kutsussa. Taulukk 14: VETUMA-allekirjitusvastauksen parametrit Parametri 14: TTS Merkitys allekirjitusvastauksessa: Allekirjitettu teksti sellaisena kuin svellus lähetti sen allekirjituskutsussa. 26 (47)