Miten viestit liikkuvat Suomi.fi-palveluväylässä?

Suomi.fi-palveluväylän tuotantokäyttö alkaa tänään. Vaikka palveluväylästä onkin jo julkaistu paljon hyvää dokumentaatiota, ainakin itselläni kesti melko pitkään sisäistää miten palveluväylä teknisesti toimii. Tämän on tarkoitus olla kohtalaisen tiivis kuvaus siitä, miten viestinvälitys palveluväylällä vaihe vaiheelta tapahtuu.
Kuvitteellisena esimerkkinä tarinassa on jokin avustusjärjestelmä, josta jaetaan rahaa yrityksille. Osana järjestelmän toimintaa halutaan tarkistaa että rahoituksen saaja on maksanut veronsa säntillisesti. Tästä syystä tehdään palveluväylää pitkin verovelkakysely Verohallinnon tarjoamaan rajapintaan.

Tukijärjestelmä kysyy kysymyksen verottajalta

Palveluväylän viestinvälitys perustuu sille että melko itsenäiset liityntäpalvelimet lähettävät viestejä toisilleen. Keskuspalvelimella hallitaan väyläkokonaisuuden konfiguraatiota. Tätä konfiguraatiota jaellaan liityntäpalvelimille joko suoraan tai erillisen konfiguraatiopalvelimen kautta. Liityntäpalvelimet käyttävät aikaleima- ja varmennepalveluita tietoturvan varmistamiseen. Väylään liittyviä käsitteitä on avattu laajemmin sanastossa.
Esimerkissämme tukihakemusjärjestelmä lähettää palvelukutsun eteenpäin oman liityntäpalvelimensa kautta. Tukijärjestelmän liityntäpalvelin salaa ja allekirjoittaa kutsun ja lähettää sen vastapuolen, eli Verohallinnon, liityntäpalvelimelle julkisen internetin yli. Verohallinnon liityntäpalvelin purkaa salauksen, tarkistaa allekirjoituksen ja välittää varsinaisen palvelukutsun verovelkapalvelulle. Vastaus siirtyy takaisin samaa reittiä pitkin.

Vaihe 1

Tukihakemusjärjestelmä lähettää palvelukutsun liityntäpalvelimelleen. Palvelukutsu on X-Road viestiprotokollan mukainen, eli käytännössä SOAP-kutsu, jossa on mukana X-Roadin omat elementit ja joka noudattaa tiettyjä sovittuja käytäntöjä.

• client -elementti kertoo mistä kutsu lähetettiin
• service -elementti kertoo mihin palveluun kutsu välitetään
• itse palvelukutsu on SOAP-viestin bodyssä

Esimerkkiviestistä nähdään miten väylän keskustelukumppanit tunnistetaan koordinaateilla xRoadInstance – memberClass – memberCode – subsystemCode. Kun viesti lähetetään verovelkapalveluun, koordinaateiksi asetetaan kohdejärjestelmä FI – GOV – 0245458-3 – VeroSS2.

Avain	Arvo	Tulkinta
xRoadInstance	FI	Kutsu kohdistuu Suomen palveluväylään. Käytetty teknologia tukee federointia, eli olisi mahdollista kutsua esimerkiksi Virossa olevaa palvelua (ei käytössä kuitenkaan tällä hetkellä)
memberClass	GOV	Palveluntarjoajan luokittelukategoria. Tässä tapauksessa GOV eli valtionhallinnon organisaatio (Taulukko 3).
memberCode	0245458-3	Kohdeorganisaation yksilöivä tunnus, joihin käytetään Suomessa aina Y-tunnusta. Esimerkissä käytetään Verohallinnon Y-tunnusta.
subsystemCode	VeroSS2	Alijärjestelmä, joka on kohdeorganisaatiossa kutsun kohteena. Esimerkissä verovelkapalvelu on päätetty julkaista alijärjestelmässä ”VeroSS2”.

X-Road viestiprotokollan vaatima kuorrutus voidaan lisätä viesteihin eri tavoin. Tietojärjestelmä voi kirjoittaa tarvittavat SOAP-headerit itse, tai niiden lisäyksestä voi vastata jokin yleiskäyttöinen komponentti. Aiheesta lisää muualla. On myös olemassa komponentti, joka välittää REST kutsuja X-Road viestiprotokollan yli.
Tässä vaiheessa on syytä huomata, että kutsuvan organisaation täytyy varmistaa että liityntäpalvelimen paikalliseen kutsurajapintaan pääsee lähettämään viestejä vain luotettu toimija (tyypillisesti omasta sisäverkosta). Mikäli ei-toivottu taho pääsee lähettämään viestejä tähän rajapintaan, se voi tehdä vapaasti palvelukutsuja kaikkien tämän liityntäpalvelimen käyttäjiksi konfiguroitujen organisaatioiden ja alijärjestelmien nimissä. Pääsy liityntäpalvelimen paikalliseen rajapintaan voi olla rajattu palomuurilla, ja liityntäpalvelin voidaan säätää hyväksymään kutsuja vain tunnettujen varmenteiden käyttäjiltä.

Vaihe 2

Saatuaan palvelukutsun liityntäpalvelin alkaa käsittelemään sitä tietoturvamielessä. Ensimmäiseksi viesti allekirjoitetaan kutsujan allekirjoitusavainta käyttäen. Käytettävät avaimet on luotu liityntäpalvelimella, ja ne on rekisteröity keskitettyyn varmennepalveluun (CA, käytännössä VRK). Vastaavasti liityntäpalvelimella on luotu autentikointiavain (ja sitä vastaava varmenne), jota käytetään myöhemmin vaiheessa 4.
Seuraavaksi viesti leimataan aikaleimapalvelussa (TSA, Time Stamping Authority). TSA tuottaa sille lähetetylle tiedolle allekirjoituksen, joka todistaa tiedon olleen olemassa tietyllä ajanhetkellä. Käytännössä väylässä välitettävän viestin allekirjoituksesta lasketaan tiiviste, joka TSA aikaleimaa ja allekirjoittaa.
Liityntäpalvelin tallettaa aikaleimatun ja allekirjoitetun viestin omaan tietokantaansa. Tätä tietoa voidaan jälkikäteen käyttää sen todistamiseen, että tukijärjestelmällä on ollut hallussaan verovelkakysely X ajanhetkellä Y₁.

Vaihe 3

Liityntäpalvelin valmistelee datapaketin, joka lähetetään vastaanottavalle liityntäpalvelimelle. Pakettiin laitetaan

• alkuperäinen palvelukutsu
• palvelukutsun aikaleimattu allekirjoitus
• OCSP-vastaukset tukijärjestelmän liityntäpalvelimen käyttämille allekirjoitus- ja autentikointivarmenteille

OCSP (Online Certificate Status Protocol) on työkalu varmenteiden voimassaolon hallintaan. OCSP -palvelimelta voidaan kysyä onko jokin varmenne edelleen voimassa. Palveluväylän voimassaolokyselyt toimivat samalla periaatteella kuin OCSP stapling, eli varmenteen käyttäjä huolehtii voimassaolon kyselystä, ja pakkaa voimassaolotiedot mukaan viestiin. Koska voimassaolotieto on allekirjoitettu luotetun tahon (CA) toimesta, vastaanottaja voi tarkistaa allekirjoituksen ja luottaa siihen että häntä ei yritetty huijata varmenteella joka ei olekaan voimassa.

Muutamia yksityiskohtia on lakaistu maton alle: viestien aikaleimaus ja OCSP kyselyt eivät välttämättä tapahdu joka kyselylle erikseen ja / tai reaaliaikaisesti jos viestissä on attachmenteja, yhden allekirjoituksen sijaan käsitellään useita, ja niistä muodostettua Merkle-puuta

Vaihe 4

Tukijärjestelmän liityntäpalvelin lähettää edelliskohdassa valmistellun datapaketin Verohallinnon liityntäpalvelimelle. Tiedonsiirto salataan TLS -salausprotokollaa käyttämällä.
Yhteyden salaamiseen käytetään liityntäpalvelinten autentikointiavaimia. Yhteyttä avattaessa asiakaspään liityntäpalvelin pyytää vastapuolelta sen autentikointivarmenteen OCSP-vastaukset.  Vastaavasti palvelupään liityntäpalvelin saa kutsujan autentikointivarmenteiden OCSP-vastaukset vastaanotetusta datapaketista.
Tämän jälkeen liityntäpalvelimet voivat luottaa siihen, että tiedonsiirto on salattua, ja vastapuoli on se kuka väittää olevansa.

Palvelukutsun SOAP-headereista tiedetään siis koordinaatit ”FI/GOV/0245458-3/VeroSS2” jonne datapaketti pitäisi lähettää. Mutta mistä tukijärjestelmän liityntäpalvelin tietää missä osoitteessa niitä vastaava palvelin sijaitsee? Tämä tieto löytyy kaikille liityntäpalvelimille yhteisestä konfiguraatiosta, jonka liityntäpalvelimet hakevat keskuspalvelimelta ajastetusti. Liityntäpalvelinten osoitteiden lisäksi jaetussa konfiguraatiossa on muunmuassa tiedot luotetuista aikaleima- ja OCSP palveluista.
Tiedonsiirto liityntäpalvelinten välillä voi jatkua häiriöittä (asetusparametreista riippuvan pituisen) tietyn ajan vaikka joku räjäyttäisi OCSP, aikaleima- ja keskuspalvelimet tuusan nuuskaksi.
Palveluväylän toteutuksessa on sisäänrakennettuna (erittäin yksinkertainen) tuki kuormanjaolle liityntäpalvelinten kesken. Samoin DOS-hyökkäysten estolle on jonkinlainen tuki.

Vaihe 5

Kun palveluntarjoajan liityntäpalvelin on purkanut vastaanotetun datapaketin salauksen, se alkaa käsitellä sen sisältöä. Myös palvelun tarjoajan päässä aikaleimataan saapunut palvelukutsu (sen allekirjoituksen tiiviste). Viesti allekirjoituksineen talletetaan täälläkin kantaan. Tallennettua viestiä voidaan jälkikäteen käyttää sen todistamiseen, että Verohallinnon liityntäpalvelimella on ollut hallussaan tukijärjestelmästä tullut verovelkakysely X ajanhetkellä Y₂.

Liityntäpalvelin tarkastaa saapuneeseen viestiin liittyen että:

• autentikointivarmenne ja sen varmenneketju ovat voimassa pakettiin liitettyjen OCSP-vastausten mukaan
• autentikointivarmenteen tiiviste vastaa sitä, joka on saatu keskuspalvelimelta jaettujen konfiguraatiotietojen mukana
• allekirjoitusvarmenne on voimassa pakettiin liitetyn OCSP-vastauksen mukaan
• allekirjoitusvarmenne vastaa kutsujan identiteettiä (varmenteen distinguished name sisältää tahon memberCoden)
• allekirjoitus vastaa SOAP-palvelukutsua (eli voidaan luottaa siihen että palvelukutsua ei ole muutettu)
• kutsu on tullut oikeaan osoitteeseen ja haluttu palvelu löytyy valikoimasta
• kutsujalla on lupa käyttää kyseistä palvelua (konfiguroidaan paikallisesti liityntäpalvelimella).

Vaihe 6

Nyt Verohallinnon liityntäpalvelin on valmis kutsumaan varsinaista SOAP-palvelua, eli tässä tapauksessa tekemään verovelkakyselyn.

Liityntäpalvelin löytää varsinaisen palvelun sijainnin oman paikallisen konfiguraationsa perusteella. Kuten kutsuvassa päässä, tässä välissä voi olla vielä erillinen sovitinpalvelu, tai vaikkapa ESB, joka tulkkaa X-Road viestiprotokollaa kohdejärjestelmän käyttämään muotoon.
Verovelkapalvelun vastaus matkaa sitten takaisin tukijärjestelmään marssien samaa polkua takaperin, pääpiirteissään samoja periaatteita noudattaen.