Sumalaisen julkishallinnn VETUMA-palvelu versi 2.1 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...4 2.3 Kutsu- ja vastaustyypit...5 2.4 Turvatarkisteen mudstaminen...6 2.5 Paluu VETUMA-palvelusta svellukseen...6 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... 21 3.3.2 Tunnistusvastauksen parametrit... 22 3.4 Käyttäjän surittama hyväksyminen...22 3.4.1 Hyväksymiskutsun parametrit... 23 3.4.2 Hyväksymisvastauksen parametrit... 25 3.5 Käyttäjän surittama kiistämätön sähköinen allekirjitus...25 3.5.1 Allekirjituskutsun parametrit... 26 3.5.2 Allekirjitusvastauksen parametrit... 28 4. Verkkmaksaminen ja maksunpalautus (PAYMENT-palvelutyyppi)...29 4.1 Menetelmät...29 4.2 Maksatus...30 4.2.1 Maksatuskutsun parametrit... 31 4.2.2 Maksatusvastauksen parametrit... 38 4.3 Maksun palautus...40 4.3.1 Tuki verkkmaksupalveluissa... 41 4.3.2 Maksunpalautuskutsun parametrit... 42 4.3.3 Maksunpalautusvastauksen parametrit... 45 5. Yleinen pikkeustilanteiden käsittely...47 5.1 VETUMA-palvelun havaitsemat pikkeustilanteet...47 5.1.1 Paluu svellukseen pikkeustilanteissa... 47 5.1.2 Testiympäristön tuki kutsuvirheiden tutkimiselle... 48 5.2 Virhetilanteet kutsu- ja vastausviestien välityksessä...48 5.2.1 VETUMA-istunnn vanhentuminen... 48 5.2.2 Tistuvat kutsut... 49 6. Liitteet...49 2 (49)
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 versin 2.1 kutsurajapinnan. Versissa 2.1 n versin 2.0 rajapintaan ja itse palveluun lisätty perustietjen hakeminen VTJstä tunnistuksen yhteydessä ja kasvatettu sirukrtilla allekirjitettavan tekstin maksimipituutta sekä lisätty mahdllisuus sisällyttää rivinvaihtja allekirjitettavaan tekstiin. 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ä 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. 3 (49)
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; 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. 4 (49)
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 kstuu kahdesta palvelutyypistä: Tunnistus-, hyväksymis- ja allekirjitustiminnt. Maksatukseen liittyvät timinnt. VETUMA-palvelun tarjamista timinnista jkaisella n ma kutsu- ja vastaustyyppinsä. 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: 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. Timintkhtaiset parametrit n kuvattu timintkhtaisten kutsu- ja ja vastaustyyppien määrittelyissä. 5 (49)
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 asiakkaan svellukset eivät jstain syystä pysty käyttämään muita edellämainittuja algritmeja. 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). Mikäli jku parametri n annettu mutta sillä n tyhjä arv, n sen siis kuitenkin ltava mukana tiivisteen laskennassa. 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. 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. 6 (49)
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. 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. Tässä yhteydessä svitaan myös, mitä algritmia käytetään salaisuuden yhteydessä. Kukin asiakas vastaa mien salaisuuksiensa säilyttämisestä. Esitysmut: Alfanumeerinen merkkijn, pituus 5..15 merkkiä. 7 (49)
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 asiakas-, timint- ja svellustunnuskhtaisesti. 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 karkean tasn valvntaa varten. 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. Svellus lu haluamallaan tavalla aikaleiman lähettämäänsä kutsuun siten, että se vastaa kutsun tdellista lähettämisaikaa. 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 > Parametri 4: SO Merkitys kutsussa: Kutsussa suritettavaksi pyydetyn timinnn surittamiseen käytettävä letusmenetelmä ja tarvittaessa taustapalvelu. Tätä parametria käytettiin vaiheissa 1.0 ja 1.5 letusmenetelmän määräämiseen. Vaikka letusmenetelmän määräämistä kutsussa ei tuetakaan vaiheessa 2 (vaan menetelmän 8 (49)
valinta hjautuu pelkästään SOLIST-parametrin perusteella), n SO-parametri säilytetty yhteenspivuuden vuksi. SO-parametri nkin pakllinen kutsuissa. 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 enää 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 asiakasknfiguraatissaan 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). Tietyissä tapauksissa (esimerkiksi maksunpalautus) VETUMApalvelua kutsuva svellus määrää myös mitä 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). Mikäli SOLIST-parametrissa n annettu vain yksi menetelmä, VETUMA-palvelu avaa käyttäjälle vastaavan menetelmäkhtaisen suritus- tai valintasivun. Kska vain yksi menetelmä n sallittu, käyttäjä ei tällöin vi siirtyä menetelmän valintasivulle. 9 (49)
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 > 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ää. 10 (49)
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. 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ä. 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. 11 (49)
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-asiakasknfiguraatin tunnus. Asiakasknfiguraatiilla 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. 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ä 12 (49)
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 (49)
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 vastauksen lähettämisajankhdan kertvan 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. Jissain tapauksissa myös taustapalvelu jlla timint suritettiin. 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 (49)
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 (49)
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= 1 > (Timint suritettiin matkapuhelimella, kansalaisvarmenteen sisältävällä SIM-krtilla) 16 (49)
...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ö. EXTRADATA-parametrin arvlla VTJ1 vidaan pyytää HETUn nutamista VTJ:stä js käyttäjä surittaa timinnn kansalaisvarmenteeseen perustuvalla menetelmällä jsta saadaan käyttäjän tunnisteeksi SATU. 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 riippumatta kutsun EXTRADATA-parametrin arvsta. 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 riippumatta kutsun EXTRADATA-parametrin arvsta. 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. Asiintisvellus vi kutsussa määrätä, että HETU-kysely tehdään käyttäjän valittua menetelmäksi HST-krtin antamalla kutsun EXTRADATAparametrissa arvn VTJ1. Js käyttäjä valitsee menetelmäksi kansalaisvarmenteen, mutta EXTRADATAparametrin arvlla ei le pyydetty HETU:n nutamista VTJ:stä, palauttaa VETUMApalvelu EXTRADATA-parametrissa tyhjän HETU:n arvn. Parametri EXTRADATA vidaan jättää pis tunnistuskutsusta, jllin se ei myöskään saa lla mukana MAC-laskennassa. 17 (49)
Tunnistuskutsuissa EXTRADATA-parametrin arvlla VTJTT=<tutetunnus> vidaan pyytää VTJ-kyselytutteessa <tutetunnus> määriteltyjen tietjen nutamista VTJ:stä käyttäjän tunnistamisen jälkeen. Js EXTRADATA-parametrin arvna n VTJTT=<tutetunnus>, saa SOLISTparametrissa määrätä tarjttavaksi vain Tupas-tunnistuksen, HST-krttitunnistuksen, ja/tai mbiilikansalaisvarmennetunnistuksen. Muutin kutsu tulkitaan virheelliseksi. Tutetunnuksella VTJ-VETUMA-Perus pyydetään kaikille VETUMA-asiakkaille tarjlla leva vakikyselytute jssa n seuraavat tiedt: henkilötunnus, nimitiedt, ktikunta, sitetiedt, äidinkieli, kulinaika sekä tiet siitä, nk käyttäjä Sumen kansalainen. Kyselyllä VTJstä saadut tiedt palautetaan valinnaisessa VTJDATA-parametrissa. Käyttäjän tunnistauduttua pankkitunnistuksella palauttaa VETUMA-palvelu käyttäjän HETU:n vastauksen EXTRADATA-parametrissa riippumatta kutsun EXTRADATAparametrin arvsta. Käyttäjän tunnistauduttua kansalaisvarmenteeseen perustuvalla menetelmällä palauttaa VETUMA-palvelu käyttäjän HETU:n vastauksen EXTRADATAparametrissa mikäli kutsussa llut EXTRADATA-parametrin arv li VTJ1 tai VTJTT=<tutetunnus>. Esitysmut: Merkkijn, enintään 50 merkkiä. Esimerkki:...value= VTJ1 > (HETUn haku SATUlla)...value= VTJTT=T1 > (VTJ-tutteessa T1 määrättyjen tietjen haku) 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) 35 VTJDATA Käyttäjän perustiedt VTJstä 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. 18 (49)
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) 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 kansalaisvarmenteeseen ja VTJ-kyselyä ei pyydetty kutsussa. VTJ:n palauttama virhekdi mikäli valittu menetelmä perustui kanasalaisvarmenteeseen, VTJ-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 19 (49)
Esimerkki:...value= HETU=010101-123N >...value= HETU= > (Tyhjä HETU kun käyttäjän valitsema tunnistautumismenetelmä perustui kansalaisvarmenteeseen eikä VTJ1- kyselyä llut pyydetty tunnistuskutsussa) Parametri 35: VTJDATA Merkitys vastauksessa: Kutsussa annetun VTJ-kyselytutteen mukaiset käyttäjän perustiedt VTJstä. Kuitenkin: Parametria ei palauteta vastauksessa mikäli kutsussa ei ltu pyydetty VTJTT=<tutetunnus> -kyselyä. Mikäli VTJTT=<tutetunnus> -kyselyä pyydettiin kutsussa, mutta kysely epännistui, ei VTJDATA-parametria palauteta, vaan haun palauttama virhekdi ja virheteksti palautetaan SATU/HETU-kyselyn tavin EXTRADATA-paluuparametrissa. Esitysmut: Merkkijn, pituus enintään 3000 merkkiä. Esitysmut n sama XML-mut kuin kuin VTJ SS-kyselyiden vastauksissa. XMLdata n kuitenkin VETUMAn paluusanmassa URL encdattuna. Tietyn tietluvan sisältämien VTJ-kyselytutteiden vastaustiedt määritellään tietluvan yhteydessä, ja kunkin tutteen vastauksen tarkka esitysmut kuvataan XML Schema-määrittelynä. VRK n myös julkaissut XML Scheman jssa määritellään vastausten XML-schemissa esiintyvät VTJ-tietjen tiettyypit. Esimerkki VTJDATA-parametrin arvsta löytyy dkumentista: VETUMA Sanmaesimerkit. 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 tunnistuskutsu ja -vastaus parametreineen. 20 (49)