Versio 1.0 Varmennepalvelu Yleiskuvaus Kansallisen tulorekisterin perustamishanke
Varmennepalvelu Yleiskuvaus 2 (8) Versiohistoria Versio Päivämäärä Kuvaus 1.0 Dokumentti julkaistu.
Varmennepalvelu Yleiskuvaus 3 (8) SISÄLLYS 1 Johdanto... 4 2 Sanasto ja lyhenteet... 4 3 Palvelun käyttöoikeus ja käytöstä sopiminen... 5 4 Varmennepalvelu... 5 4.1 Uuden varmenteen pyytäminen... 5 4.2 Varmenteiden sulkeminen... 6 4.3 Varmenteiden elinkaari ja uusiminen... 6 4.4 Virhetilanteet... 7 5 Varmennepalvelu käytettäessä SFTP-rajapintaa... 8 6 Palvelun testaus... 8
Varmennepalvelu Yleiskuvaus 4 (8) 1 JOHDANTO Varmennepalvelua hyödyntävät kaikki tulorekisteriin aineistoja tuottavat ja sieltä noutavat organisaatiot. Varmenne myönnetään organisaatiolle, joka vastaa tietojen toimittamisesta tulorekisteriin tai jolla on oikeus saada tietoja tulorekisteristä. Tulorekisterin varmennepalvelu myöntää varmenteet. Dokumentin tarkoituksena on kuvata tulorekisterin varmennepalvelu yleisellä tasolla. Varmenteen pyytämiseen, noutoon ja uusimiseen käytettävät tekniset toiminnallisuudet ja skeemat on kuvattu erillisessä dokumentissa. 2 SANASTO JA LYHENTEET Palvelukuvauksessa käytetyt lyhenteet ja tärkeimmät termit on esitetty taulukossa 1. Lyhenne tai termi CSR (Certificate Signing Request) varmenteen allekirjoituspyyntö PKCS#10 (Public Key Cryptography Standards # 10) PKI (Public Key Infrastructure) Private key (Yksityinen avain) Public Key (Julkinen avain) Rajapinta SFTP (Secure File Transfer Protocol) SGML (Standard Generalized Markup Language) Tiedon käyttäjät Selite Varmennepalvelun käyttäjän tekemä varmennepyyntö. Varmennepyyntö on PKCS#10- muotoinen Base64-koodattu merkkijono. Standardi, joka määrittää varmenteen allekirjoituspyynnön muodon ja sisällön. Julkisen avaimen menetelmää hyödyntävä järjestelmä, jolla varmentaja tarjoaa ja ylläpitää varmenteita. Salassa pidettävä osa epäsymmetrisestä avainparista, jota käytetään julkisen avaimen salauksessa. Yksityistä avainta käytetään tyypillisesti sähköiseen allekirjoittamiseen tai julkisella avaimella salatun viestin avaamiseen. Julkinen osa epäsymmetrisestä avainparista. Julkista avainta käytetään tyypillisesti viestin salaamiseen ja yksityisellä avaimella suoritetun allekirjoituksen todentamiseen. Standardin mukainen käytäntö tai yhtymäkohta, joka mahdollistaa tietojen siirron laitteiden, ohjelmien tai käyttäjän välillä. Tiedonsiirtoprotokolla, joka mahdollistaa salatun tiedonsiirtoyhteyden kahden järjestelmän välillä. Merkintäkieli, jota käytetään aineiston eri osien ja niiden välisten suhteiden merkitsemiseen. Sellaiset toimijat, joilla on lainsäädäntöön perustuva oikeus saada tulorekisteristä tulotai muita tietoja oman tehtävänsä hoitamiseen. Ensimmäisessä vaiheessa 1.1.2019 lähtien tiedon käyttäjiä ovat Verohallinto, Kela, Työttömyysvakuutusrahasto (TVR) sekä työeläkelaitokset ja ETK. Tiedon tuottajat WS (Web Service) XML (Extensible Markup Language) Toisessa vaiheessa 1.1.2020 lähtien tiedon käyttäjiä ovat lisäksi mm. Tilastokeskus, Koulutusrahasto, vahinkovakuuttajat, työttömyyskassat, TEMin hallinnonala, kunnat ja työsuojeluviranomainen. Kaikki yritykset ja muut toimijat, joilla on palkka-, eläke- tai etuustietojen ilmoitusvelvollisuuksia Suomeen jollekin tulorekisterin tiedon käyttäjälle. Verkkopalvelimessa toimiva ohjelmisto, joka tarjoaa standardoitujen internetyhteyskäytäntöjen avulla palveluja sovellusten käytettäväksi. Varmennepalvelun tarjoamia palveluja ovat varmenteen pyyntö, nouto ja uusiminen. SGML-kielestä erityisesti internetkäyttöä varten rajattu merkintäkieli, joka on helposti laajennettavissa. XML Signature (allekirjoitus) Asiakkaan voimassaolevalla varmenteella muodostama XML-allekirjoitus. X.509 Varmenteen rakenteen määrittelevä standardi. Taulukko 1. Käytetyt lyhenteet ja tärkeimmät termit.
Varmennepalvelu Yleiskuvaus 5 (8) 3 PALVELUN KÄYTTÖOIKEUS JA KÄYTÖSTÄ SOPIMINEN Tulorekisterin teknisen rajapinnan käyttöoikeudesta on sovittava tulorekisterin kanssa. Käyttöoikeudesta ja rajapinnan testauksesta sopimisen yksityiskohdat täsmennetään myöhemmin. 4 VARMENNEPALVELU Tulorekisterin varmennepalvelu perustuu PKI-ratkaisuun (Public Key Infrastructure). Varmennepalvelussa asiakkaalla on yksi tai useampi avainpari (yksityinen ja julkinen avain) ja avainpariin liittyvä varmenne, joka on X.509-standardin mukainen. Varmennepalvelusta pyydettyä tulorekisterin myöntämää varmennetta käytetään asiakkaan tunnistamiseen ja tulorekisteriin toimitettavan aineiston allekirjoittamiseen sähköisellä allekirjoituksella (XML Signature). Varmenteet myönnetään tiettyyn käyttötarkoitukseen, eikä niitä voi käyttää alkuperäisestä poikkeavaan tarkoitukseen. Jos tulorekisterin palveluiden käyttäjä toimii sekä tiedon tuottajana että tiedon käyttäjänä, tulee palvelun käyttäjän tilata varmenteet kumpaankin käyttötarkoitukseen. 4.1 Uuden varmenteen pyytäminen Uuden varmenteen pyytäminen ja varmenteen noutaminen on esitetty kuvassa 1. Kuva 1. Uuden varmenteen pyytäminen ja noutaminen.
Varmennepalvelu Yleiskuvaus 6 (8) Asiakas sopii tulorekisterin kanssa palvelujen käytöstä. Varmennepalvelu lähettää varmennepyynnön tekoa varten tarvittavat tiedot: siirtotunnuksen ja kertakäyttösalasanan. Asiakas voi tehdä varmennepyynnön sen jälkeen, kun on vastaanottanut varmennepyyntöä varten lähetetyn siirtotunnuksen ja kertakäyttösalasanan. Varmennepyyntö tulee tehdä tietyn ajan kuluessa. Aika tarkennetaan myöhemmin. Siirtotunnuksen ja kertakäyttösalasanan toimitustapa täsmennetään myöhemmin. Asiakas muodostaa varmennepyyntöä varten avainparin, sekä PKCS#10-määrityksen mukaisen varmenteen allekirjoituspyynnön (Certificate Signing Request, CSR), joka sisältää asiakkaan julkisen avaimen. Varmennepyynnön palvelukutsuun liitetään muodostettu allekirjoituspyyntö. Lisäksi pyynnön yksilöimiseksi ja suojaamiseksi palvelukutsuun liitetään asiakkaalle erikseen toimitettu siirtotunnus ja kertakäyttösalasana. Varmennepyynnön palvelukutsu palauttaa vastaanottokuittauksessa noutotunnuksen, jolla yksilöidään luotava varmenne hakua varten. Varmenne saadaan palautteena varmenteen haun palvelukutsulle johon liitetään noutotunnus. Tämän jälkeen asiakkaalla on tulorekisterin palveluiden käyttöön tarvittava varmenne. 4.2 Varmenteiden sulkeminen Varmenne on suljettava, jos tiedetään tai epäillään, että varmenteen haltijan yksityinen avain on kadonnut tai päätynyt vääriin käsiin. Varmenne on suljettava myös silloin, jos se on tarpeeton. Tulorekisteri voi sulkea varmenteen esimerkiksi silloin, kun palvelun käyttöön oikeuttava sopimus päättyy tai on ilmeistä, että myönnettyä varmennetta on käytetty väärin. Varmenne suljetaan ottamalla yhteyttä tulorekisteriin. Yhteystiedot varmenteen sulkemista varten täsmennetään myöhemmin. Asiakkaan pyytäessä varmenteen sulkemista varmenne suljetaan ensin tilapäisesti (varmenne asetetaan "pitoon", Certificate Hold). Tällöin varmenteen käyttö on estetty, mutta varmenne on mahdollista aktivoida uudelleen. Tulorekisteri käsittelee sulkemispyynnön virka-aikana. Mikäli sulkemispyyntö vahvistetaan, varmenne suljetaan lopullisesti. Virheelliseksi tai aiheettomaksi todettu varmenteen sulkemispyyntö on mahdollista perua ja aktivoida varmenne uudelleen käyttöön. Lopullisesti suljettua varmennetta ei voi palauttaa käyttöön, eikä sitä voi uusia, vaan asiakkaan on tilattava uusi varmenne. Tällöin uuden varmenteen pyytäminen ja noutaminen tehdään samalla tavalla kuin tilattaessa varmenne ensimmäisen kerran. 4.3 Varmenteiden elinkaari ja uusiminen Asiakkaan varmenteilla on tietty käyttöikä. Varmenteen haltijan tulee tarkistaa varmenteiden voimassaolo säännöllisesti. Vanhenemassa olevat varmenteet voidaan uusia varmennepalvelun varmenteen uusiminen -toiminnolla. Kun varmenteen uusii olemassaolevan varmenteen voimassaoloaikana, ei tarvitse tilata uutta siirtotunnusta ja kertakäyttösalasanaa. Jos varmenne ehtii vanheta, asiakkaan pitää ottaa yhteys tulorekisteriin ja tilata uusi varmenne. Tällöin uuden varmenteen pyytäminen ja noutaminen tehdään samalla tavalla kuin tilattaessa varmenne ensimmäisen kerran. Varmenteen uusiminen on esitetty kuvassa 2.
Varmennepalvelu Yleiskuvaus 7 (8) Palvelun käyttäjä Varmennepalvelu Lähettää uusimispyynnön 1 Varmenteen uusimispyyntö RenewCertificateRequest Vastaanottaa varmenteen uusimispyynnön Vastaanottaa noutotunnuksen Noutotunnus käsittelyaika 2 Vastaanottokuittaus (noutotunnus) RenewCertificateResponse Muodostaa noutotunnuksen Muodostaa varmenteen Lähettää varmennehaun 3 Varmenteen haku (noutotunnus) GetCertificateRequest Vastaanottaa varmennehaun Vastaanottaa varmenteen 4 Varmenne GetCertificateResponse Palauttaa varmenteen Kuva 2. Varmenteen uusiminen. Varmenteen uusimista varten asiakkaan tulee luoda uusi avainpari sekä varmenteen allekirjoituspyyntö (CSR) samalla tavalla kuin pyydettäessä uusi varmenne. Palvelun käyttäjä liittää muodostamansa allekirjoituspyynnön varmenteen uusimisen palvelukutsuun. Palvelukutsu allekirjoitetaan sähköisesti käyttäen aikaisempaan, edelleen voimassaolevaan varmenteeseen liittyvää yksityistä avainta. Varmenteen allekirjoituksessa käytetään samaa muotoa kuin silloin, kun tulorekisteriin toimitetaan aineistoja voimassaolevalla varmenteella. Varmenteen uusiminen -toiminto palauttaa varmenteen noutotunnuksen, jota käyttämällä uusi varmenne haetaan varmenteen haun palvelukutsulla samalla tavalla kuin haettaessa varmennetta ensimmäistä kertaa. Aikaisempi varmenne tulee korvata uudella varmenteella viipymättä. Mikäli samaa varmennetta on käytetty useammassa kuin yhdessä paikassa, tulee kaikki vanhan varmenteen kopiot korvata uudella, jotta vältytään vanhentuneen varmenteen aiheuttamilta virhetilanteilta. 4.4 Virhetilanteet Pääsääntöisesti varmennepalvelu palauttaa tiedot virheistä välittömästi palvelun vastauksen yhteydessä. Osa virheistä havaitaan kuitenkin vasta varmennepyynnön käsittelyssä, ja virhe palautetaan varmenteen noudon yhteydessä. Välittömästi palvelukutsun vastaanottokuittauksessa palautetaan tieto virheestä silloin, kun palvelukutsu ei ole palvelun skeeman mukainen käytetyt tunnisteet ovat virheelliset pyyntöön mahdollisesti liitetty varmenteen allekirjoituspyyntö on virheellisesti muodostettu varmenteen uusimisessa käytettävän sähköisen allekirjoituksen tarkistus epäonnistuu ilmenee jokin muu poikkeustilanteen aiheuttama tekninen virhe.
Varmennepalvelu Yleiskuvaus 8 (8) Mikäli varmenteen luonti epäonnistuu, tulee mahdollisen virhetilanteen korjauksen jälkeen suorittaa virheeseen päättynyt palvelukutsu uudelleen. Palautettavat virhekoodit ja selitteet on kuvattu varmennepalvelun rajapintakuvauksessa. 5 VARMENNEPALVELU KÄYTETTÄESSÄ SFTP-RAJAPINTAA Tulorekisterin SFTP-rajapinnassa yhteyden muodostamiseen käytetään asiakkaan varmennetta varten luotua avainparia. Tulorekisteri saa tarvitsemansa julkisen avaimen noutamalla asiakkaalle luodun varmenteen varmennepalvelulta. Asiakas käyttää yhteyden muodostamiseen omaa yksityistä avaintaan. 6 PALVELUN TESTAUS Teknisen rajapinnan testauksesta sovitaan tulorekisterin kanssa. Testaus tapahtuu varmennepalvelun testiympäristössä, josta asiakkaalle myönnetään myös testivarmenne tulorekisterin teknisen rajapinnan testausta varten. Testauksen ja testauksesta sopimisen yksityiskohdat täsmennetään myöhemmin.