Rajapintakäyttö ja varmenne Vyvi-klinikka 11.10.
Tiedon tuottaja
Sisältö Yleistä varmenteista Miten tiedon tuottajan hakemus tulorekisterin teknisen rajapinnan käyttöönottamiseksi tapahtuu? Millainen varmenne? Väärinkäytösepäily varmenteen käytössä Verohallinnon ja tulorekisterin rajapintapalveluiden käyttöehdot
Mistä on kyse? Tulorekisterin teknisiä rajapintoja käyttävien organisaatioiden tunnistaminen toteutetaan käyttämällä tulorekisterin varmennepalvelua. ratkaisu pohjautuu digitaalisiin varmenteisiin Varmennepalvelussa toteutetaan toiminnallisuus, jonka avulla sidosryhmät voivat muodostaa varmenteita. varmenteella tunnistetaan tietoja tuottava/käyttävä organisaatio varmenteella varmistetaan aineiston muuttumattomuus Varmenteet myönnetään käyttötarkoituksen mukaan. jos tulorekisterin käyttäjä toimii sekä tiedon tuottajana että tiedon käyttäjänä, tulee käyttäjän muodostaa varmenteet kumpaankin käyttötarkoitukseen. 17.1.2018
Varmennepalvelun käyttö Käyttökohteet Kenelle Viivästetty ja reaaliaikainen WebService - palvelut Tiedon tuottaminen Puolesta asioija (esim. tilitoimisto) ei käytetä varmennetta Latauspalvelu Varmennepalvelu Yritys itse SFTP-käyttö Tiedon käyttäminen Tiedon käyttäjäorganisaatio Käyttäjätunnus ja yksityinen avain (PKI-autentikointi) Toimija voi muodostaa useamman kuin yhden varmenteen per varmennetyyppi perustelut yksi kerrallaan useamman varmennetyypin 17.1.2018
Varmenne Varmenne: Tietorakenne, joka liittää julkisen avaimen haltijan tietoihin ja joka on allekirjoitettu varmenteen myöntäjän (CA) yksityisellä avaimella. Varmenteen hakija: Taho, joka hakee varmennetta ja jonka vastuulla myönnetty varmenne on. Organisaatiotapauksessa, organisaatiolla on yleensä edustaja, joka toimii organisaation nimissä / lukuun varmennetta haettaessa. Varmenteen haltija: Taho, joka käyttää myönnettyä varmennetta. Varmenteen subject - kenttä viittaa yksilöivästi varmenteen haltijaan. Varmenteen hakijan sopimus (Subscriber Agreement, PKI:ssa): Varmentajan ja varmenteen hakijan välinen sopimus, joka kattaa osapuolten oikeudet ja vastuut varmenteen myöntämisen ja hallinnoinnin osalta. Yksityinen avain: Julkisen avaimen järjestelmässä epäsymmetrisessä salauksessa käytettävän avainparin yksityinen osa. Tämä avain on yksikäsitteisesti määritetty tietylle taholle ja siksi sitä käytetään mm. sähköisessä allekirjoituksen luomisessa. Yksityisellä avaimella voidaan purkaa avainparin julkisella avaimella salattua tietoa.
Millainen varmenne? Tilitoimiston tai yrityksen eri ohjelmistot voivat käyttää samaa varmennetta eri ohjelmistoissaan, jos tyypiltään samanlainen varmenne soveltuu eri ohjelmistojen tarpeisiin. Yhtä varmennetta voi käyttää kaikkien asiakkaidensa puolesta asiointiin. Jokaiselle ohjelmistolle voi hakea oman varmenteen. Varmenteen tarvitsee se yritys tai tilitoimisto, joka käyttää palkkahallinnon ohjelmistoa, josta on rakennettu tekninen rajapinta tulorekisterin ja järjestelmän välille.
Tulorekisterin teknisen rajapinnan käyttöönottamisen prosessi Kirjaudu tulorekisterin sähköiseen asiointipalveluun www.vero.fi/tulorekisteri Tulorekisterin sähköinen asiointipalvelu Ensimmäisen varmenteen varmennepyyntö ja nouto https://www.vero.fi/tuloreki steri/ohjelmistokehittäjät/va rmennepalvelu/ Etusivu Hakemus Varmenteen uusiminen, 2 vuoden kuluttua ensimmäisen varmenteen aktivoinnista. Vahvistus Hakemus tulorekisterin teknisen rajapinnan käyttöönottamiseksi (YouTube)
Kuka voi tehdä hakemuksen rajapinnan käyttöön? Hakemuksen teknisen rajapinnan käyttöönottamiseksi voi tehdä ainoastaan hakijaorganisaation nimenkirjoitusoikeudellinen henkilö eli toimitusjohtaja toimitusjohtajan sijainen toimihenkilö, jolla on yksinedustamisoikeus Katso-pääkäyttäjä tai elinkeinonharjoittaja. Jos hakemuksen tekee tilitoimisto tai muu palkkahallinnon ulkoistuskumppani, sillä pitää olla voimassa oleva toimeksiantosopimus ja valtuudet toimia asiakasyrityksensä puolesta. Lisätietoa:Varmennepalvelu yrityksille ja organisaatioille
Kuka voi noutaa varmenteita? 1. Tilitoimisto Mikäli tilitoimisto hoitaa asiakkaidensa ilmoituksia voi tilitoimisto olla se, joka tekee hakemuksen tulorekisterin teknisestä rajapintakäytöstä, jos sillä on puolesta asioinnin oikeudet ja toimeksiantosopimukset kunnossa. Tilitoimisto muodostaa varmenteen (tai nimeämä taho) ja yhdellä varmenteella hoitaa kaikkien asiakkaiden puolesta ilmoittamisen. 2. Yritys itse Jos yritys itse on hakemuksen tekijä niin se voi ulkoistaa varmenteen teknisen noutamisen esim. ohjelmistotalon edustajalle tai jollekin muulle valitsemalleen taholle. 3. Ohjelmistotalo Voi olla hakemuksen tekijä ja varmenteen muodostaja siinä tapauksessa, jos ohjelmistotalo täyttää Verohallinnon ja tulorekisterin määrittelemien käyttöehtojen vaatimukset. On saanut valtuudet loppuasiakkailta eli suorituksen maksajilta. Verohallinnon ja tulorekisterin rajapintapalveluiden käyttöehdoissa määritellään tarkasti millainen toimija voi saada varmenteen.
Turvasähköpostiviestin sisältö Ohjeistusta päivitetään Oikea havaintolomakkeen osoite päivitetään
Varmennepyyntö ja nouto Tiedon käyttäjän on saanut haltuunsa TransferID:n ja TransferPasswordin
Esimerkki avainparin ja varmenteen allekirjoituspyynnön tekemisestä OpenSSL komennot avainparin ja varmennepyynnön tekemiseksi Muodosta avainpari openssl genrsa -aes256 -out testiyritys.key 2048 Muodosta varmennepyyntö openssl req -new -key testiyritys.key -out testiyritys.csr Toteutus voidaan tehdä monella teknisellä tavalla, jokainen sidosryhmä valitsee toteutustavan itse.
SFTP-käyttäjätunnus Hei, tulorekisteri on muodostanut organisaatiollenne SFTP-käyttäjätunnuksen. Organisaation nimi: xxxxxxxx SFTP-tunnus: xxxxxxxxxxxxx_xx SFTP-kanavassa tunnistautuminen tapahtuu SSH-autentikoinnilla siten, että käytetään käyttäjätunnusta sekä yksityistä avainta siitä avainparista, jota organisaatio on käyttänyt varmenteen allekirjoituspyynnön (CSR) allekirjoittamisessa. Varmenteen tyyppi: xxxxxxxxxx Varmenteen kuvaus: xxxxxxxxxx Ystävällisin terveisin Tulorekisteri
Varmenteen listaus ja kuvaus * *pakollinen
Varmenteen tilat Tilattu (ordered) Voimassa (active) Päättynyt (expired) Suljettu (revoked) Väliaikainen käyttökielto (hold) Tieto tilasta tulee tulorekisterin sähköiseen asiointipalveluun varmennepalvelulta
Tuotannon varmenteiden CA IR Income Data Users Issuing CAv1 IR Income Data Users SFTP Issuing CAv1 Data Providers Issuing CAv1 Data Providers SFTP Issuing CAv1 IR External Data Providers Issuing CAv1 IR External Data Providers SFTP Issuing CAv1 IR Services Issuing CAv1
Domain-nimet - Varmennepalvelun osoitteet https://pkiws.vero.fi (varmennepalvelun osoite) https://crl.vero.fi (sulkulistan osoite) 17.1.2018
Varmennetilaukseen liittyviä rajauksia
Tuotannon varmennepalvelun sivu Varmennepalvelun tekniset kuvaukset Yleiskuvaus Dokumentti on yleisesitys tulorekisterin varmennepalvelusta, Varmennepalvelu Yleiskuvaus (15.12.2017, versio 1.01). -> 15.10.2018 versio 1.02 Rajapintakuvaus Dokumentissa kuvataan varmennepalvelun Web Service -rajapinnan toteutus järjestelmäintegraation toteuttajan näkökulmasta, Varmennepalvelu Rajapintakuvaus (15.12.2017, versio 1.01), -> 15.10.2018 versio 1.02 esim. url -tietoja päivitetty Tekninen rajapinta Palveluiden WSDL-kuvaus ja tietosisällöt XML-skeema -muodossa. Varmennepalvelun tekninen rajapinta ZIP Sovelluskehittäjille (15.12.2017, versio 1.01) -> 15.10.2018 esim. url -tietoja päivitetty Varmennepalvelun tuotannon osoitteet Varmennepalvelun tuotannon CA-paketit Testipenkkiaineisto pystyy samana Lisätään linkkejä: varmennepalvelun ei tekniselle tilannesivulle Verohallinnon ja tulorekisterin teknisen rajapinnan käyttöehtoihin.
Väärinkäytösepäily varmenteen käytössä Käyttäjän yksityisen avaimen katoamisesta tai joutumisesta sivullisen tietoon tai käyttäjän epäillessä sen joutuneen sivullisen tietoon on välittömästi ilmoitettava Verohallinnolle palvelun asiattoman käytön estämiseksi ohjeissa ilmoitettavalla tavalla. Ilmoita mahdollisesta väärinkäytöstilanteesta / epäilystä tulorekisterille yhteydenottokanavasta lisätietoa 29.10. mennessä. lomake puhelinsoitto yhteydenottopuhelinnumerosta tiedotetaan tulorekisteri.fi sivulla
Varmistuskysymykset Varmenteen sarjanumero (Serial number) Kohde (Subject ) Tekninen kontakti puhelinnumero sähköpostiosoite Jokin muu tieto?
Palvelun esittelyvideot Katsele teknisen rajapinnan käyttöoikeuksia ja varmenteita https://dreambroker.com/channel/i8kxf400/kyywg4ap Hae uutta varmennetta https://dreambroker.com/channel/i8kxf400/z2q7zvr3 Tee uusi korvaava hakemus teknisen rajapinnan käyttöönottamiseksi https://dreambroker.com/channel/i8kxf400/chtl7m38
Verohallinnon ja Tulorekisterin rajapintapalveluiden käyttöehdot
Käyttöehdot Tutustu huolellisesti Verohallinnon ja Tulorekisterin rajapintapalveluiden käyttöehtoihin. Hyväksymällä käyttöehdot sitoudut noudattamaan niitä. Ilman käyttöehtojen hyväksymistä et voi ottaa tulorekisterin teknistä rajapintaa käyttöön. Käyttöehdoissa on määritelty seuraavat asiat rajapinta-asiointiin ja varmenteeseen liittyen käyttäjän vastuu asiakkaan puolesta toimiminen valtuus ja asiakkaan tunteminen asiakkaan tahdon mukainen asiointi puolesta asioinnin valvonta Verohallinnon oikeus keskeyttää palvelun käyttäminen tulorekisterin toiminnallisuuksien ehdot
Varmenteeseen liittyen: Valtuutus ja asiakkaan tunteminen Määritelmiä Asiakas on esimerkiksi verovelvollinen, suorituksen maksaja, ilmoitusvelvollinen, rekisteröity tai muu taho, jonka velvoitteita palvelussa hoidetaan ja jonka nimissä palveluiden käyttö tapahtuu. Asiakas voi olla käyttäjä tai käyttäjän päämies. Käyttäjä on elinkeinonharjoittaja tai oikeushenkilö, joka hyväksyy nämä käyttöehdot. Käyttäjä saa varmenteen ja käyttää palvelua asiakkaana tai asiakkaan valtuuttamana. --------------------------------------------------------------------------------------------------------------------- Asiakas voi valtuuttaa käyttäjän käyttämään palvelua puolestaan. Käyttäjän on tunnettava asiakas, eli varmistettava asiakkaan ja asiakkaan edustajan identiteetti sekä edustusoikeus valtuutuksen yhteydessä ja tarpeellisin väliajoin asioinnin yhteydessä. Verohallinto antaa tarkempia ohjeita asiakkaan tuntemiseen liittyen erilaisissa toimintatilanteissa.
Varmenteeseen liittyen: Valtuutus ja asiakkaan tunteminen Valtuutus on tehtävä kirjallisesti ja valtuutusasiakirjasta tai siihen liittyvistä merkinnöistä on käytävä ilmi: valtuutuksen antopäivä; valtuutuksen kesto tai toistaiseksi voimassa olevan valtuutuksen tapauksessa päättymispäivä, kun valtuutus on päättynyt; asiakkaan ja asiakkaan edustajan identiteetti; asiakkaan tai asiakkaan edustajan tunnistustapa; asiakkaan edustajan asiointivaltuuden tarkistustapa ja käyttäjän oikeus käyttää palvelua asiakkaan puolesta.
Varmenteeseen liittyen: Valtuutus ja asiakkaan tunteminen Käyttäjän on säilytettävä valtuutusasiakirja valtuutuksen keston ajan sekä kaksi vuotta valtuutuksen päättymisen jälkeen. Osa palvelun kautta tarjottavista asiointipalveluista edellyttää edellä kuvatun menettelyn sijaan, että asiakas on valtuuttanut käyttäjän Suomi.fivaltuudet palvelussa (suomi.fi) tai muulla Verohallinnon erikseen määrittämällä tavalla. Asiointipalvelukohtainen valtuutuskäytäntö ilmoitetaan palvelukohtaisissa ohjeissa.
Varmenteen haltijan vastuu Käyttäjä vastaa palvelun kautta lähettämistään viesteistä (esim. ilmoitukset). Käyttäjän tulee noudattaa Verohallinnon tarkentavia ohjeita palvelun ja asiointipalveluiden käytöstä. Käyttäjän tulee noudattaa huolellisuutta yksityisen avaimensa käsittelyssä väärinkäytösten ehkäisemiseksi. Järjestelmään liittyvän päätelaitteiden tapauksessa huolellisuus tulee kirjata päätelaitteiden käyttöpolitiikkaan. Käyttäjän yksityisen avaimen katoamisesta tai joutumisesta sivullisen tietoon tai käyttäjän epäillessä sen joutuneen sivullisen tietoon on välittömästi ilmoitettava Verohallinnolle palvelun asiattoman käytön estämiseksi ohjeissa ilmoitettavalla tavalla.
Varmenteen hakijan velvollisuudet Virheettömät ja täydelliset tiedot: Varmentajalle toimitetaan virheettömät ja täydelliset tiedot, kuten tässä varmennepolitiikassa on määritetty. Avainparin käyttö: Avainparin käytössä huomioidaan varmenteen hakijalle tiedoksi annetut rajoitteet. Huolellisuus: Varmenteen haltijan tulee noudattaa huolellisuutta yksityisen avaimensa käsittelyssä väärinkäytösten ehkäisemiseksi. Järjestelmään liittyvän päätelaitteiden tapauksessa huolellisuus tulee kirjata päätelaitteiden käyttöpolitiikkaan. Avainten luonti: Varmenteen haltijan avainpari luodaan algoritmilla, jonka yleisesti katsotaan olevan riittävän vahva tässä varmennepolitiikassa määriteltyihin varmenteen käyttötarkoituksiin ja jonka Viestintäviraston NCSA-FI -yksikkö hyväksyy. Järjestelmän tulee toteuttaa tämä ennalta määriteltyjen varmenneprofiilien kautta. Varmenteen haltijan avainten pituus: Avainten pituuden tulee täyttää vahvan avaimen edellytykset tässä varmennepolitiikassa määriteltyihin varmenteen käyttötarkoituksiin sen määriteltynä voimassaoloaikana. Avainten pääsynhallinta: Koska varmenteen yksityistä avainta käytetään tai voidaan käyttää sähköisen allekirjoituksen luomisessa ja tunnistamisessa, tulee sen käyttö olla rajoitettu vain varmenteen haltijaan. Tämä koskee Verohallinto / Tulorekisteri Varmennepalvelu -hierarkiassa niitä varmenteita, joita käytetään edellisissä mainituissa käyttötarkoituksissa.
Varmenteen hakijan velvollisuudet Vaatimus tiedoksiannosta: Varmenteen hakijan tulee ilmoittaa varmentajalle viipymättä, jos jokin seuraavista tapahtuu ennen varmenteen vanhenemista: Varmenteen haltijan yksityinen avain katoaa, varastetaan tai sen luotettavuus vaarantuu. Kontrolli varmenteen haltijan yksityisestä avaimesta menetetään esim. jaetun salaisuuden paljastuttua (rekisteröintiavain tms.). havaitaan epätarkkuus tai muutoksia varmenteen sisällössä havaitaan epäkohtia, tai sitä muutetaan. Olosuhteet, jotka ovat vaikuttaneen varmenteen myöntämiseen muuttuvat (Esim. varmenteen hakijan sopimus puretaan) Varmenteen haltijan avaimen vaarantuminen: Vaarantunut varmenteen haltijan yksityisavain tulee välittömästi ja pysyvästi poistaa käytöstä. Varmentajan avaimen vaarantuminen: Välittömästi saatuaan tiedon varmentajan avaimen vaarantumisesta, tulee varmenteen hakijan varmistaa, että kaikki siihen pohjautuvat varmenteet poistetaan käytöstä.
HUOM! Teknisen rajapinnan hakemus!
Sidosryhmien kysymyksiä varmenteesta
Kysymyksiä? Varmenne vanhenee saako siitä viestin? Varmenteen uusiminen voidaan aloittaa vasta 60 vrk:ta aikaisemmin Tekninen yhteyshenkilö saa varmenteen vanhenemisesta sähköpostiviestin 60 vuorokautta ennen varmenteen vanhenemista. Sähköisestä asiointipalvelusta voi seurata varmenteen tiloja ja vanhenemista Varmenne on jo ehtinyt vanhenemaan, mitä tapahtuu? Mikäli varmenne on jo ehtinyt vanhenemaan niin siinä tapauksessa tiedon tuottajan tulee hankkia uusi varmenne -> uusi varmenne toiminnallisuudella. Kuinka pitkään edellinen varmenne on voimassa? Vanha varmenne on voimassa siihen saakka kunnes 2 vuotta on kulunut loppuun, vaikka uusi olisi jo voimassa. Kaksi varmennetta voi olla yhtä aikaa voimassa vaihdon aikana
Tulorekisterin YouTube -kanava Tulorekisterillä on nyt tilit sekä Facebookissa (Tulorekisteri) että Twitterissä (@Tulorekisteri) Molemmissa kanavissa viestimme tulorekisterin ajankohtaisista asioista ja ohjaamme tulorekisterin käyttäjiä toimimaan oikein. Kiitos!