Kysymyksiä ja vastauksia varmennepalvelusta

Tekniset kysymykset varmenteesta

Miten varmenne suljetaan?

Pyyntö varmenteen sulkemisesta tehdään virka-aikana tulorekisteriyksikölle ja virka-ajan ulkopuolella Helpdeskille.

Lue lisää: Varmenteen sulkeminen

Testausympäristön varmenteen sulkemispyyntö osoitetaan tulorekisterin sidosryhmätestauksen organisaatiolle.

Voiko tekninen yhteyshenkilömme saada varmenteiden hakemiseen liittyvät viestit englanninkielisinä?

Teknisille yhteyshenkilöille lähetettävät varmennepalvelun viestit ovat kolmikielisiä (suomi, ruotsi ja englanti).

Voiko asiakkaalla olla useita varmenteita käytössä samaan aikaan? Asiakkaalla on käytössä useita ohjelmistoja.

Asiakkailla voi olla samaan aikaan useita varmenteita käytössä. Asiakas voi myös käyttää samaa varmennetta eri ohjelmistoissa.

Voiko varmenteita hallinnoida tulorekisterin sähköisessä asiointipalvelussa, esimerkiksi ladata varmennetiedoston?

Organisaation nimenkirjoitusoikeudellinen näkee tulorekisterin sähköisessä asiointipalvelussa listan niistä varmenteista, jotka ovat organisaation käytössä. Hän voi lisäksi tilata sen kautta uusia varmenteita.

Varmenteiden tekninen hakuprosessi ja niiden noutaminen tapahtuvat varmennepalvelun ohjeiden mukaisesti. Yksityiskohtaiset ohjeet lähetetään tekniselle yhteyshenkilölle turvasähköpostiviestin välityksellä.

Jos ohjelmistotoimittaja X hakee oman varmenteen, voivatko tämän jälkeen kaikki ohjelmistoa käyttävät tilitoimistot käyttää ohjelmiston X varmennetta?

Ohjelmistotoimittaja X toimii ohjelmistotalona. Jokaisen ohjelmisto X:ää käyttävän asiakkaan, kuten tilitoimiston tai yrityksen, on haettava oma varmenne tulorekisterin tuotantokäyttöä varten.

Pitääkö jokaisen ohjelmistotalon, joka toteuttaa teknisen rajapinnan tulorekisteriin, toteuttaa tekninen rajapinta myös varmennepalveluun?

Tuotannon aikaisen varmenteen hakee ohjelmistotalon asiakasyritys (tilitoimisto tai yritys). Käytännössä ohjelmistoon on kuitenkin toteutettava ratkaisu, jolla varmenne haetaan ja talletetaan ohjelmiston käytettäväksi.

Mikä on SFTP-kanavan osoite?

Tulorekisterin tuotantokäytössä osoite on sftp.tulorekisteri.fi.

Tulorekisterin sidosryhmätestauksessa on kaksi osoitetta eri testausympäristöihin:

EXT1 – Palkkojen ensisijainen testausympäristö: sftp-testi.tulorekisteri.fi

EXT2 – Etuuksien ensisijainen testausympäristö (palkkojen toissijainen testausympäristö): sftp-testi-2.tulorekisteri.fi

Miten tunnistaudun SFTP-kanavassa?

SFTP-käyttäjätunnuksen muoto on esimerkiksi 0ac1ee931da7cf1ce_PW. Käyttäjätunnus lähetetään testauksen yhteyshenkilölle ja tekniselle yhteyshenkilölle sähköpostilla, kun testaava taho on noutanut testivarmenteen. SFTP-kanavassa tunnistautuminen tapahtuu SSH-autentikoinnilla siten, että käytetään käyttäjätunnusta sekä yksityistä avainta siitä avainparista, jota sidosryhmä on käyttänyt varmenteen allekirjoituspyynnön (CSR) allekirjoittamisessa. Salasanaa ei siis käytetä.

Miksi Web Service -palveluita käytettäessä tulee SSLHandshakeException-poikkeus (tulorekisterin ja varmennepalvelun rajapinta)?

Ongelma liittyy todennäköisesti asiakasohjelmiston käyttämään TLS/SSL-versioon ja niihin liittyviin kryptokirjastoihin. Tulorekisterin ja varmennepalvelun Web Service -rajapinnat käyttävät TLSv1.2:n mukaista protokollaa ja asiakasohjelmiston tulee käyttää samaa versiota. Tiedossa olevat ongelmat: 

Java 7 ja sitä vanhemmat versiot → Päivitä käyttöön Java 8 tai uudempi.

SoapUI OpenSource, versio 5.3.0 ja sitä vanhemmat käyttävät vanhentunutta Java-versiota. → Päivitä SoapUI versioon 5.4.0 tai päivitä/korvaa SoapUI:n paketoima Java versioon 8.

Varmenne ja sidosryhmätestaus

Miten voin saada toisen henkilön varmenteen tekniseksi yhteyshenkilöksi? Onko tarpeen tehdä uusi sopimus?

Uutta sopimusta ei tarvita, alkuperäisen sopimuksen allekirjoittanut henkilö voi vaihtaa varmenteen teknisen yhteyshenkilön päivittämällä varmenteen tiedot tulorekisterin sähköisessä asiointipalvelussa.

Kuinka varmenteen uusimista testataan?

Varmenteen uusimista on mahdollista testata varmennepalvelun testipenkissä. Lue lisää varmennepalvelun testipenkin ohjeesta.

Miten varmenne suljetaan?

Sidosryhmätestauksen aikana sulkemispyyntö tehdään tulorekisterin testausorganisaatiolle, jos on kyse testausta varten myönnetystä varmenteesta.

Mihin Y-tunnuksia pdf-listalla tarvitaan sidosryhmätestauksessa, jos niitä vasten ei voi hakea varmennetta?

Jokaiselle testaavalle organisaatiolle toimitetaan 40 Y-tunnusta ja 200 henkilötunnusta. Sidosryhmät voivat itse valita, kuinka monta palkansaajaa kullakin Y-tunnuksellisella maksajalla on palkkatietoaineistossa. Myös henkilötunnukset voi liittää Y-tunnukseen omavalintaisesti. Testiasiakkaita saa tulorekisterihankkeelta tarvittaessa lisää. 

Liite 1: Teknisten rajapintojen testausohje (pdf)

Voitte lisäksi ilmoittaa tulorekisterille rajatun määrän omia testitunnisteitanne, jotka haluatte lisättävän tulorekisterin sidosryhmätestaukseen.

Liite 7: Ohje testiaineiston anonymisoinnista (pdf)

Kun varmenne haetaan testiympäristössä, kuinka kauan varmenteen hakemisen kertakäyttösalasana (OTP, TransferPassword) on voimassa?

Varmenteen hakemiseen tarvittavat siirtotunnukset ovat voimassa 14 vuorokautta.

Mikä on varmennepalvelun osoite sidosryhmätestiympäristössä ja mihin palvelukutsut toimitetaan?

Tämä palvelun kutsu tulee tehdä HTTP POST -metodia käyttäen ja lisäksi tulee asettaa seuraavat HTTP-otsakkeet (headers)

Content-Type: text/xml;charset=UTF-8

SOAPAction: "getCertificate"

  • SOAPAction tulee olla kyseisen operaation action ja ne löytyvät WSDL-kuvauksesta.
    - SOAP-viestejä ei tyypillisesti voi lähettää nettiselaimella, ainakaan ilman lisäkkeitä (extensions ja plugins) vaan siihen tulee käyttää jotain SOAP-viestien lähettämiseen kykenevää ohjelmaa.

Mitä Y-tunnusta ja asiakasnimeä käytetään kohdassa GetCertificateRequest?

Ohessa esimerkki tästä kohdasta ja vastaus CustomerID:n kohdalla:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices">

<soapenv:Header/>

<soapenv:Body>

<cer:GetCertificateRequest>

<Environment>TEST</Environment>

<CustomerId>Tulorekisterin testaussopimus käsitelty viestin keinotekoinen y-tunnus</CustomerId>

<!--Optional:-->

<CustomerName>Tulorekisterin testaussopimus käsitelty viestin keinotekoinen asiakasnimi</CustomerName>

<RetrievalId>varmennepalvelusta saatu RetrivalId</RetrievalId>

</cer:GetCertificateRequest>

</soapenv:Body>

</soapenv:Envelope>

Organisaatiomme haluaa käyttää useita eri varmenteita tulorekisterin sidosryhmätestauksessa. Tehdäänkö sidosryhmätestausta varten yksi testaussopimus jokaiselle varmenteelle?

Ei, jokainen organisaatio tekee yhden testaussopimuksen sidosryhmätestausta varten. Jos organisaatio tietää tarvitsevansa testauksessa useita varmenteita, tästä laitetaan pyyntö sen sähköpostin liitteeksi, jolla Verohallinnon tulorekisterihankkeelle lähetetään allekirjoitettu ja skannattu testaussopimus ja testausympäristön käyttöehdot. Liitteessä pitää yksilöidä tarvittavien varmenteiden lukumäärä ja varmenteiden käyttötarkoitukset. Jos eri varmenteilla on eri tekniset yhteyshenkilöt, myös näiden tiedot on kerrottava.

Jos testaussopimus on jo hyväksytty tai testaus on jo meneillään, ohjelmistotalo voi pyytää useampia varmenteita havaintolomakkeella. Linkki havaintolomakkeeseen toimitetaan testaavalle organisaatiolle testaussopimuksen käsittelyn jälkeen. Havaintolomakkeella lähetetyssä pyynnössä pitää olla teknisen yhteyshenkilön tiedot, tarvittavan varmenteen tyyppi, keinotekoinen Y-tunnus (CustomerID) ja Y-tunnukseen liittyvä keinotekoinen organisaation nimi (CustomerName), jotka on toimitettu testaavalle organisaatiolle aikaisemmin.

Pitääkö myös matkalaskujärjestelmästä toteuttaa tekninen rajapinta varmennepalveluun, eli onko niin, että varmennetta ei toimiteta testausta varten muilla keinoilla kuin varmennepalvelun rajapinnan kautta?

Testauksen varmenne toimitetaan vain varmennepalvelun rajapinnan kautta.

Varmenteeseen liittyvä yksityinen avain on vain tulorekisteriin liittyvän ohjelmiston hallussa, joten asiakkaan on muodostettava se. Varmennepalvelun rajapinta on Web Service -rajapinta, joten varmenteen haku voidaan integroida tiiviisti osaksi asiakasohjelmistoa tai varmenteen nouto voidaan tehdä erillisillä Web Service -ohjelmistoilla kuten SoapUI tai Postman.

Varmenteen allekirjoittaminen

Mitkä ovat varmenteen allekirjoituspyynnön tiedot?

Varmenteen allekirjoituspyynnön (CSR) muodostamisvaiheessa kysytään varmennetta hakevan organisaation (Subject) tietoja. Näistä tiedoista kannattaa allekirjoituspyyntöön täyttää seuraavat organisaation tiedot:

Common Name (CN), merkitse Y-tunnus

Organization (O), merkitse asiakasyrityksen nimi

Country (C), merkitse FI

Tuotannossa käytetään yrityksen omia tietoja, testiympäristössä käytetään yritykselle annetun testiorganisaation tietoja.

Mitkä ovat oikeat attribuutit Signature-noodin käyttämisessä?

Allekirjoituksessa käytettävä tekninen määritys on tulorekisterin dokumentaatiossa: Tekninen rajapinta – Soveltamisohje 2020 (pdf).

<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />

<Reference URI="">

<Transforms>

<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />

</Transforms>

<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />

Miten avainpari muodostetaan? Miten PKCS#10-varmennetiedosto luodaan ja kuinka siihen liitetään julkinen avain?

Ratkaisut riippuvat osapuolen käyttämästä teknologiasta. Yksi mahdollinen tapa PKCS#10-muotoisen varmenteen allekirjoituspyynnön (CSR) tekemiseen varmennepalvelun testiympäristössä esitetään varmennepalvelun testipenkin ohjeen luvussa 5.

Miten tehdään CSR tiedon liittäminen signNewCertificate-operaatioon?

CertificateRequest-elementissä oleva base64-enkoodattu varmenteen allekirjoituspyyntö (CSR) syötettävä ilman alku- ja lopputageja:

-----BEGIN CERTIFICATE REQUEST-----
base64 enkoodattu CSR-----
END CERTIFICATE REQUEST-----

Suoritetaanko CSR:n (varmenteen allekirjoituspyynnön) sisältämille arvoille kuten Common namelle tarkistuksia? Onko niille asetettu rajoitteita, esimerkiksi pitääkö CSR:n sisältämien tietojen olla varmennetta uusittaessa samat kuin alkuperäisessä varmenteessa, tai tuleeko näiden tietojen jollain tapaa vastata varmennetta hakevan yrityksen tietoja?

CSR:ää käytetään teknisesti vain julkisen avaimen toimittamiseen. Sen eheys tarkistetaan, mutta varsinaisia tietokenttiä ei hyödynnetä varmenteella. Tietojen käyttö muussa yhteydessä, kuten vianselvityksessä ei ole suljettu pois, joten olisi hyvä täyttää oikeat tiedot.

Varmenteen nouto

Milloin varmenne pitää noutaa?

Varmenne pitää noutaa 14 vuorokauden kuluessa sen muodostamisesta. Hakuaikaa ei voi jatkaa. Jos hakuaika menee umpeen, organisaation pitää tehdä uusi varmennetilaus, ja noutaa varmenne ajoissa.

Miksi varmenteen nouto epäonnistuu?

Varmenteen nouto voi epäonnistua esimerkiksi väärän noutotunnuksen vuoksi (RetrievalId).

Varmenteen hakemisessa on otettava huomioon, että allekirjoituspyynnön (SignNewCertificate) saa tehdä siirtotunnuksilla (TransferId ja TransferPassword) vain yhden kerran. Varmenteen noudon (GetCertificate) voi tehdä samalla noutotunnuksella (RetrievalId) useita kertoja. Allekirjoituspyynnön ja noudon välillä on viive eli kannattaa odottaa jonkin aikaa.

GetCertificateRequest-pyynnöllä noudettavan varmenteen luontipyyntö on vielä käsiteltävänä. Onko tilanteelle oma virhekoodi?

Erillistä virhekoodia ei ole. Varmenteen haun aikaviivettä on pidennetty GetCerfiticateRequest-pyynnössä, joten entistä harvemmin pitäisi tulla vastaan tilanteita, jossa käsittely on edelleen kesken.

Mikä on käsittelyaika, kun noudetaan pyydettyä tai uusittua varmennetta GetCertificateRequest-pyynnöllä?

Dokumentaatiossa on määritelty varoaika 5 minuutiksi, mutta käytännössä aika on alle 30 sekuntia. Usein aika on selkeästi lyhyempi.

Miten tilitoimisto saa kertakäyttösalasanan ja siirtotunnuksen, kun käytössä on tekninen rajapinta? Tarvitseeko loppuasiakkaan valtuuttaa tilitoimistoa laisinkaan?

Tilitoimisto tekee hakemuksen rajapinnan käyttämisestä tulorekisterin sähköisessä asiointipalvelussa ja ilmoittaa varmenteen yhteyshenkilön sopimusta tehtäessä.

Varmenteen yhteyshenkilö saa ilmoitettuun sähköpostiosoitteeseen turvasähköpostiviestin ja puhelimeensa PIN-koodin, jolla yhteyshenkilö avaa turvasähköpostiviestin mikä sisältää varmennepyyntöön liittyvät siirtotunnukset (TransferID ja TransferPassword). 

Tilitoimistolla tulee olla voimassa oleva toimeksiantosopimus ja valtuudet toimia asiakkaansa puolesta.  

Pitääkö uuden sertifikaatin luontia varten muodostaa jokaiselle asiakkaalle oma julkinen avain, yksityinen avain sekä PKCS#10-varmennepyyntö erikseen? Eikö riitä, että olisi vain yksi yhteinen julkinen/yksityinen avain sekä PKCS#10-varmennepyyntötiedosto, jota käytettäisiin kaikille asiakkuuksille? Tällöin asiakkaalle toimittamanne siirtotunnus ja kertakäyttösalasana riittäisivät asiakkuuden yksilöimiseen uuden varmenteen noutotunnuksen ja XML-allekirjoituksenne muodostamiseksi.

Jos kyseessä on tilitoimisto, niin tilitoimisto voi toimia omalla varmenteellaan ja muodostaa aineistot sekä ilmoittaa tiedot asiakkaiden puolesta. Jos kyse on puhtaasti aineistojen välittämisestä, niin kullekin asiakkaalle tulee muodostaa oma avainpari sekä varmenteen allekirjoituspyyntö, joista sitten muodostetaan varmenteet.

Miten tallennetaan getCertificate-operaatiosta saatu varmenne tiedostoon?

Mikäli vastaussanomassa saatava varmenne talletetaan manuaalisesti tiedostoon, tulee Certificate-elementissä oleva base64-enkoodattuun tietoon lisätä alku- ja lopputagit omille riveilleen, siten että varmenteen tieto jää niiden väliin:

-----BEGIN CERTIFICATE-----
base64 encoodattu varmenne
-----END CERTIFICATE-----

Varmenteen uusiminen

Miten ja milloin varmenne uusitaan? Voiko varmenteen uusia automaattisesti?

Organisaatio näkee varmenteen voimassaoloajan tulorekisterin sähköisestä asiointipalvelusta, tai itse varmenteesta. Organisaatio lähettää varmenteen uusimispyynnön aikaisintaan 60 päivää ennen sen viimeistä voimassaolopäivää tulorekisterin teknisen rajapinnan kautta. Jos varmenne ehtii vanhentua ennen uusimista, organisaation on tehtävä uusi varmennehakemus tulorekisterin sähköisessä asiointipalvelussa.

Mahdollisuus varmenteen uusimiseen automaattisesti riippuu ohjelmistotalon käytännöistä.

Kun varmennetta uusitaan, korvaako uusi varmenne vanhan heti, vai onko vanha voimassa sen alkuperäiseen voimassaolopäivään asti?

Vanha varmenne jää voimaan, kunnes se vanhenee tai se pyydetään erikseen sulkemaan. Uusi varmenne on siinä mielessä korvaava, että sillä on sama DN kuin vanhalla, mutta itse varmenne on uusi.

Täytyykö uusi avainpari generoida?

Kyllä. Avaimen uusimisella halutaan vähentää riskiä avaimen joutumisesta vääriin käsiin.

Miten XML-allekirjoitus muodostetaan yksityisellä avaimella?

XML-allekirjoituksen määrittelyt on julkaistu tulorekisterin rajapintadokumentaatiossa.

https://www.vero.fi/globalassets/tulorekisteri/tekninen-rajapinta---soveltamisohje-2020.pdf

Mitä merkistöä rajapinnan palveluissa käytetään?

Rajapinnan palvelussa tulee käyttää UTF-8-merkistöä.

Miksi varmenteen uusimispyyntö (RenewCertificate) päätyy Signature verification failed -virheeseen? Lokin perusteella uusintapyynnöt menevät virheeseen virhekoodilla PKI010.

Tarkistakaa, että lähtevässä uusimispyynnössä namespace on määritelty Soap-bodyn RenewCertificateRequest-elementtiin, eikä Soap-envelopeen.

Varmenteet ja SaaS-palvelu

Miten toimitaan silloin, jos yritys on ostanut palkat ohjelmistotoimittajalta SaaS-palveluna? Voiko samalla palvelimella olla monen yrityksen varmenne tulorekisteriä varten?

Tulorekisteri ei ota kantaa siihen, kuinka monta varmennetta on samalla palvelimella. Määrää ei siis ole rajoitettu.

SaaS-palvelussakin kukin tietoja ilmoittava yritys hankkii oman varmenteen. Varmenteen tekniseksi yhteyshenkilöksi voidaan nimetä SaaS-palveluntarjoajan edustaja, jolloin hän voivat yrityksen puolesta hakea varmenteen ja asentaa sen.

Varmenteet ja tilitoimistot

Miten varmenteet haetaan ja miten niitä käytetään tilitoimistoissa? Onko tilitoimistolla yksi varmenne, jota käytetään kaikilla asiakkailla?

Esimerkki: Tilitoimisto A, jolla on asiakkaat:
Asiakas 1 Oy
Asiakas 2 Oy
Asiakas 3 Oy

Tilitoimisto B, jolla on asiakkaat:
Asiakas 2 Oy
Asiakas 4 Oy, haluaa tehdä itse aineistotilauksia

Tilitoimiston nimenkirjoitusoikeudellinen henkilö tekee palvelusopimuksen tulorekisterin kanssa ja hakee yhden varmenteen.

Varmenteen hakemisen yhteydessä tekniseksi yhteyshenkilöksi voi nimetä esimerkiksi ohjelmistotalon edustajan, joka käytännössä hoitaa varmenteen hakemisen tilitoimistolle. Varmenteen voi käytännössä muodostaa tilitoimistolle se taho, jonka tilitoimiston nimenkirjoittaja on merkinnyt tekniseksi yhteyshenkilöksi.

Miten toimitaan Asiakas 2 Oy kohdalla, jonka palkkoja hoitavat Tilitoimisto A ja Tilitoimisto B?

Molemmilla tilitoimistoilla on omat varmenteet ja ne hoitavat asiakkaansa puolesta asiointia normaalisti, kuten asioinnista on sovittu Asiakas 2 Oy:n kanssa.

Miten toimitaan Asiakas 4 Oy kohdalla, joka haluaa tehdä itse aineistotilauksia, mutta Tilitoimisto B tekee ilmoitukset?

Asiakas 4 Oy voi käyttää sähköistä asiointipalvelua aineistotilauksiin tai hankkia oman varmenteen. Tilitoimisto B:llä on oma varmenne, jota käytetään ilmoittamisessa.

Tarvitseeko palkanlaskentaohjelmaa käyttävien tilitoimistojen ja yritysten hakea varmenne? Tarvitseeko yrityksen tai tilitoimiston valtuuttaa ohjelmisto X lähettämään aineistoja heidän puolestaan?

Taloushallinnon ohjelmaa käyttävät yritykset ja tilitoimistot tarvitsevat jokainen oman varmenteen. Jos yrityksen asioita hoitaa tilitoimisto, tilitoimisto tarvitsee varmenteen, jota se käyttää kaikkien asiakkaidensa puolesta asiointiin. Tilitoimiston asiakkaana oleva yritys ei siis tarvitse omaa varmennetta, ellei se ilmoita palkkoja itse rajapinnan kautta.

Kun tilitoimisto on sitoutunut tulorekisterin käyttöehtoihin, se voi ilmoittaa tietoja rajapinnan kautta edustamansa asiakasyrityksen puolesta. Kaikissa tapauksissa varmenteen tarvitsee siis se yritys tai tilitoimisto, joka taloushallinnon ohjelmaa käyttää.

Teknisen rajapinnan käyttöön ei tarvita Suomi.fi-valtuutuksia. Sen sijaan tulorekisterin sähköisessä asiointipalvelussa käytetään Suomi.fi-tunnistautumista, ja yrityksen pitää valtuuttaa tarvittavat henkilöt ja tahot Suomi.fi-valtuutuksilla asioimaan sen puolesta.

Miten toimitaan, jos tilitoimistolla tai yrityksellä on useita ohjelmistoja, joista tuotetaan ilmoituksia suoraan tulorekisteriin (esimerkiksi palkka- ja matkalaskujärjestelmä)?

Samaa varmennetta voi käyttää saman tilitoimiston/asiakasyrityksen eri ohjelmistoissa. Tilitoimiston tai yrityksen eri ohjelmistot voivat käyttää samaa varmennetta, jos saman tyyppinen varmenne soveltuu eri ohjelmistojen tarpeisiin. Vaihtoehtoisesti jokaiselle ohjelmistolle voi hakea oman varmenteen.