Varmenne

Tämä ohje käsittelee varmennetta, jota käytetään positiivisen luottotietorekisterin tiedon ilmoittamiseen sekä tiedon hyödyntämiseen. Tuotannossa käytetään eri varmennetta kuin testauksessa. Tutustu sidosryhmätestauksessa käytettävän testivarmenteen ohjeeseen.

Keskeiset termit ja niiden selitteet

Hanke
Positiivisen luottotietorekisterin perustaminen -hanke vastaa rekisterin toteuttamisesta.

Varmenteen allekirjoituspyyntö, Certificate Signing Request (CSR)
Varmenteen allekirjoituspyyntö (PKCS#10 muotoinen) lähetetään varmennepalvelun rajapintaan. Allekirjoituspyynnön jälkeen varmennepalvelu muodostaa varmenteen, jonka voi noutaa varmennepalvelun rajapinnan kautta.

Varmenne
Tulorekisteriyksikön myöntämä sähköinen tunniste, jolla käyttäjä tunnistetaan.

Organisaatio

Positiivisen luottotietorekisterin rajapintoja käyttävä yritys tai organisaatio.

Varmenteen tekninen yhteyshenkilö
Henkilö, jonka organisaatio on ilmoittanut ilmoittautumisen yhteydessä tai tietolupahakemuksella ja jolle toimitetaan tiedot varmenteen noutamista varten.

Ilmoittautuminen tietojen ilmoittajaksi
Positiivisesta luottotietorekisteristä annetussa laissa on määritelty ilmoitusvelvollinen, jonka on ilmoittauduttava Tulorekisteriyksikölle sähköisessä asiointipalvelussa, ennen kuin tietojen ilmoittaminen aloitetaan.

Jos organisaatio ei pysty käyttämään organisaatioiden sähköistä asiointipalvelua, ilmoittautuminen tehdään muussa asiointikanavassa. Tällaisessa tilanteessa voi olla puhelimitse yhteydessä positiivisen luottotietorekisterin asiakaspalveluun.

Tutustu ohjeeseen: Ilmoittautuminen tietojen ilmoittajaksi positiiviseen luottotietorekisteriin

Tietolupa
Positiivisesta luottotietorekisteristä annetussa laissa on määritelty oikeus saada tietoja rekisteristä. Tietolupaa varten tarvitaan hyväksytty tietolupapäätös, joka perustuu sähköisessä asiointipalvelussa jätettyyn tietolupahakemukseen.

Jos organisaatio ei pysty käyttämään organisaatioiden sähköistä asiointipalvelua, tietolupahakemus tehdään muussa asiointikanavassa. Tällaisessa tilanteessa voi olla puhelimitse yhteydessä positiivisen luottotietorekisterin asiakaspalveluun.

Tutustu luotonantajien tietoluvan hakemisen ohjeeseen

Viranomaiset ja luottotietoyhtiöt saavat erilliset ohjeet tietoluvan hakemiseen.

Lisää termejä positiivisen luottotietorekisterin sanastossa (suomi.fi).

1 Johdanto

Tämä ohje käsittelee varmennetta, jota käytetään positiivisen luottotietorekisterin tiedon ilmoittamiseen sekä tiedon hyödyntämiseen. Tuotannossa käytetään eri varmennetta kuin testauksessa. Tutustu sidosryhmätestauksessa käytettävän testivarmenteen ohjeeseen.

Positiivisen luottotietorekisterin rajapintojen käyttö vaatii, että rajapintaa kutsuva taho tunnistetaan kutsun yhteydessä. Rajapinnan käyttäjä tunnistetaan varmenteen avulla, ja palvelussa hyväksyttävät varmenteet ovat Verohallinnon julkaisemia varmenteita.

2 Varmennepalvelu

Positiivisessa luottotietorekisterissä käytetään Tulorekisteriyksikön varmennepalvelua. Varmennepalvelu perustuu PKI-ratkaisuun (Public Key Infrastructure).

Asiakas tunnistetaan ja rajapintojen käyttöoikeus varmistetaan varmenteen avulla. Tulorekisteriyksikkö myöntää varmenteet tiettyyn käyttötarkoitukseen tietylle organisaatiolle, eikä niitä voi käyttää alkuperäisestä poikkeavaan tarkoitukseen.

2.1 Varmennetyypit

Varmenteita on kahta tyyppiä: luoton tietojen ilmoittajan ja luottotiedon hyödyntäjän varmenne. Tiedon ilmoittamisen ja tiedon kyselyn rajapinnoissa käytetään siis erityyppisiä varmenteita. Jos palveluiden käyttäjä toimii sekä tiedon ilmoittajana että tiedon hyödyntäjänä, pitää näihin eri käyttötarkoituksiin käyttää eri varmennetyyppejä. Yhdellä toimijalla voi olla useita varmenteita. Ne voivat olla joko samantyyppisiä tai erityyppisiä.

Tulorekisteriyksikkö toimii itse myöntämiensä varmenteiden julkaisijana. Tämän vuoksi näiden varmenteiden julkaisijatietoja ei löydy markkinoilla olevien valmisohjelmistojen jakelusta. Organisaatio varmistaa varmenteiden teknisen luotettavuuden omassa järjestelmässään lataamalla verkkosivuilta Verohallinnon myöntämien varmenteiden juurivarmenteet ja julkaisijavarmenteet. Kun organisaatio on asentanut nämä omaan järjestelmäänsä, muodostuu varmenteiden kautta luottosuhde Verohallinnon varmenteisiin ja rajapintoja voi käyttää tietoturvallisesti.

Varmenteiden juuri- ja julkaisijavarmenteet voi ladata alla olevista linkeistä:

Luoton tietojen ilmoittajan varmenne: Data Providers Issuing CA v1

Luottotiedon hyödyntäjän varmenne: PCR Credit Data Users Issuing CA v1

Lue lisää varmennepalvelun rajapintakuvauksesta.

3 Uuden varmenteen muodostaminen

Organisaatio saa varmenteen ilmoittautumalla luoton tietojen ilmoittajaksi tai hakemalla tietolupaa rekisteriin. Kun organisaatio on saanut myönteisen päätöksen, varmenteen tekniselle yhteyshenkilölle lähetetään tarvittavat tiedot varmenteen noutamista varten.

Varmenteen tekninen yhteyshenkilö voi noutaa varmenteen Tulorekisteriyksikön varmennepalvelusta sen jälkeen, kun on vastaanottanut varmennepyyntöä varten turvasähköpostilla lähetetyn siirtotunnuksen ja kertakäyttösalasanan. Kertakäyttösalasana on voimassa 14 vuorokautta. Jos varmennetta ei noudeta tämän ajan kuluessa, kertakäyttösalasana vanhenee. Organisaation on tällöin pyydettävä uusi varmenne positiivisen luottotietorekisterin asiakaspalvelusta.

Varmenteen tekninen yhteyshenkilö noutaa varmenteen varmennepalvelun Web Service -rajapinnan kautta. Varmenne noudetaan käyttämällä kahta eri rajapintakutsua, jotka ovat varmennepyyntö ja -haku. Kun rajapinta on vastaanottanut varmennepyynnön, se vastaa kutsuun palauttamalla varmenteen noutotunnuksen. Varmenteen tekninen yhteyshenkilö ottaa noutotunnuksen talteen ja lähettää sen avulla varmennehaun. Lopuksi varmennepalvelu palauttaa varmenteen vastauksena varmennehakuun.

Seuraavassa kaaviossa kuvataan teknisen prosessin vaiheet, ja kaavion jälkeen kerrotaan kunkin toiminnon sisällöstä.

Kuva 1. Varmenteen noudon prosessikaavio.

Seuraavaksi selitetään kaaviossa kuvattu varmenteen noudon prosessi. Numerojärjestys noudattaa kuvassa olevaa numerointia. Kohdissa 2–7 viitataan varmennepalvelun rajapintakuvauksessa mainittuihin rajapintoihin ja niiden elementteihin.

1. Organisaatio saa varmenteen ilmoittautumalla luoton tietojen ilmoittajaksi tai hakemalla tietolupaa rekisteriin. Tässä yhteydessä organisaatio ilmoittaa myös varmenteen teknisen yhteyshenkilön, joka noutaa varmenteen. Varmenteen teknisellä yhteyshenkilöllä pitää olla riittävästi teknistä taitoa varmenteen noutamiseen.

Varmenteen teknisen yhteyshenkilön yhteystiedoiksi pitää ilmoittaa sähköpostiosoite, joka ei ole jakelulista tai jaettu sähköpostilaatikko. Lisäksi pitää ilmoittaa puhelinnumero, joka voi vastaanottaa tekstiviestejä. Puhelinnumerossa pitää olla myös maakoodi.

Jos organisaatio on jo noutanut yhden varmenteen ja haluaa pyytää lisävarmenteita, sen pitää ottaa yhteyttä positiivisen luottotietorekisterin asiakaspalveluun. Lisävarmenteet noudetaan samalla tavalla kuin ensimmäinen varmenne.

2. Kun Tulorekisteriyksikkö on antanut myönteisen päätöksen ilmoittautumiseen tai tietolupahakemukseen, varmennepalvelu lähettää organisaation ilmoittamalle varmenteen tekniselle yhteyshenkilölle turvasähköpostiviestin. Turvasähköpostiviesti sisältää kaksi yksilöivää tunnusta: siirtotunnuksen (TransferId) ja kertakäyttöisen salasanan (TransferPassword). Kyseisen sähköpostiviestin voi avata vain PIN-koodilla. Varmenteen tekniselle yhteyshenkilölle lähetetään ensin sähköpostiviesti, joka sisältää linkin turvasähköpostiviestin avaamiseksi. Kun varmenteen tekninen yhteyshenkilö on avannut linkin, viestin avaamiseksi tarvittava PIN-koodi lähetetään yhteyshenkilön matkapuhelimeen tekstiviestinä.

Varmennetilaukseen liittyvä siirtotunnus ja kertakäyttöinen salasana ovat voimassa viestien lähettämisestä alkaen 14 vuorokautta, ja varmenne pitää noutaa tänä aikana. Jos varmennetta ei noudeta tämän ajan kuluessa, varmennetilaus vanhenee ja organisaation pitää tilata uusi varmenne ottamalla yhteyttä positiivisen luottotietorekisterin asiakaspalveluun.

3. Varmenteen tekninen yhteyshenkilö muodostaa varmennepyyntöä varten RSA-algoritmilla muodostetun 2048-bittisen avainparin. Lisäksi yhteyshenkilö muodostaa yksityisellä avaimella allekirjoitetun, PKCS#10-määrityksen mukaisen varmenteen allekirjoituspyynnön (Certificate Signing Request, CSR). Kappaleessa 5.3 kuvataan allekirjoituspyyntöön täytettävät tiedot.

4. Varmenteen tekninen yhteyshenkilö lähettää varmennepyynnön varmennepalvelun Web Service -rajapintaan. Kun käytetään rajapintaa varmenteen hakuun, palvelukutsut pitää lähettää osoitteeseen https://pkiws.vero.fi/2017/10/CertificateServices. Varmennepyyntöön käytetään SignNewCertificateRequest-sanomaa. Sanoman sisältönä on äsken muodostetun CSR:n lisäksi turvasähköpostilla saatu siirtotunnus (TransferId) ja kertakäyttöinen salasana (TransferPassword). Lisäksi sanomaan liitetään ilmoitusvelvollisen tai tietoluvan haltijan Y-tunnus (CustomerId) ja nimi (CustomerName).

Varmennepalvelu vastaanottaa allekirjoituspyynnön ja palauttaa vastaussanoman.

5. Varmenteen tekninen yhteyshenkilö saa SignNewCertificateResponse-vastaussanomassa varmenteen noutotunnuksen (RetrievalId). On tärkeää ottaa noutotunnus talteen ennen seuraavaa vaihetta.

Varmenteen muodostaminen kestää joitakin sekunteja, joten ennen varmennehaun lähettämistä pitää odottaa 30–60 sekuntia. Jos varmennehaku yritetään lähettää liian nopeasti ennen varmenteen muodostumista, varmennehaku epäonnistuu. Tällöin on tärkeää, että noutotunnus on otettu talteen, jotta varmennehakua voidaan yrittää uudelleen. Jos noutotunnusta ei ole otettu talteen ja varmennehaku epäonnistuu, organisaation pitää pyytää uutta varmennetta.

6. Varmenteen tekninen yhteyshenkilö lähettää varmennehaun eli GetCertificateRequest-sanoman varmennepalvelun rajapintaan. Sanomaan on liitettävä edellisen kutsun vastaussanomasta saatu varmenteen noutotunnus (RetrievalId). Lisäksi sanoman pitää sisältää sama Y-tunnus ja nimi, jotka ovat edellisessä sanomassa ja joille varmenne on myönnetty.

Varmennepalvelu palauttaa vastaussanomassa varmenteen.

7. Varmenteen tekninen yhteyshenkilö saa GetCertificateResponse-vastaussanomassa varmenteen (Certificate), jonka varmennepalvelu on muodostanut organisaatiolle. Tämän jälkeen organisaatio voi käyttää varmennetta rajapintakutsuissa liittämällä varmenteen muodostamaansa yksityiseen avaimeen.

Varmennehaun voi toistaa uudelleen käyttämällä samaa RetrievalId-tunnistetta.

Varmennepalvelun rajapintakuvauksessa on tarkemmat tekniset ohjeet varmenteen noutoon.

4 Muut tilanteet

4.1 Lisävarmenteiden pyytäminen

Jos organisaatio tarvitsee useita varmenteita, se voi pyytää lisävarmenteen.

Varmenne on toimijakohtainen, joten luotonantaja ja mahdollinen lukuun toimija eivät voi molemmat käyttää samaa varmennetta. Jos organisaatio käyttää itse varmennettaan, mutta lisäksi osan sen rajapinta-asioinnista hoitaa jokin lukuun toimija, on lukuun toimivalle tilattava lisävarmenne. Lisävarmennetta pyydettäessä organisaatiota pyydetään kertomaan sen organisaation nimi ja y-tunnus, jonka käyttöön lisävarmenne annetaan. Jos lukuun toimija (esim. järjestelmätoimittaja) hoitaa organisaation kaiken rajapinta-asioinnin, voi lukuun toimijalle antaa käyttöön organisaation ainoan varmenteen. Varmennetta käyttävän lukuun toimijan tiedot tulee ilmoittaa rekisterille. 

Jos organisaatio tarvitsee lisävarmenteita, sen on otettava yhteyttä positiiviseen luottotietorekisteriin joko yhteydenottolomakkeella tai soittamalla puhelinasiakaspalveluun.

4.2 Varmenteen sulkeminen

Varmenteen haltijan on pyydettävä varmenteen sulkemista, jos yksityinen avain on kadonnut tai mahdollisesti joutunut sivullisen tietoon. Varmenne on suljettava myös silloin, jos se on tarpeeton.

Tulorekisteriyksikkö 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.

Pyydä varmenteen sulkemista puhelimitse:

Virka-aikana
Positiivisen luottotietorekisterin asiakaspalvelu: 029 497 570
arkisin kello 9–16.

Virka-ajan ulkopuolella
Vain varmenteiden kiireelliset sulkemiset: +358 9 427 34 834

5 Usein kysytyt kysymykset

Seuraavaksi joitakin varmenteen noutamiseen liittyviä usein kysyttyjä kysymyksiä.

5.1 Mikä on varmennepalvelun osoite ja mihin palvelukutsut toimitetaan?

• Dynaamisen WSDL-kuvauksen voi noutaa osoitteesta https://pkiws.vero.fi/2017/10/CertificateServices.wsdl. 
• WSDL-kuvauksen ja XML-skeemat voi ladata myös tulorekisterin verkkosivustolta.
• Kun käytetään rajapintaa varmenteen hakuun, palvelukutsut pitää lähettää osoitteeseen https://pkiws.vero.fi/2017/10/CertificateServices.
  • Palvelukutsu pitää tehdä HTTP POST -metodia käyttäen ja lisäksi pitää asettaa seuraavat HTTP-otsakkeet (headers):

Content-Type: "text/xml;charset=UTF-8"
Content-Length: "VALUE"
SOAPAction: "getCertificate"

Content-Length otsakkeen arvon pitää olla kyseisen viestin pituus eli "calculated value". Viestin pituus pitää laskea sitä lähetettäessä.
SOAPActionin arvon pitää olla kyseisen rajapintaoperaation arvo. Nämä arvot löytyvät WSDL-kuvauksesta.

• • SOAP-viestejä ei voi lähettää verkkoselaimella, ainakaan ilman selaimen lisäosia (extensions ja plugins), vaan viesti on lähetettävä ohjelmalla, joka pystyy lähettämään SOAP-viestejä.

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

Ohessa esimerkki kohdasta GetCertificateRequest ja käytettävästä Y-tunnuksesta ja asiakasnimestä.

<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>PRODUCTION</Environment>
<CustomerId> Y-tunnus</CustomerId>
<!--Optional:-->
<CustomerName>Organisaation nimi</CustomerName>

<RetrievalId>SignNewCertificateResponse-vastaussanomassa saatu varmenteen noutotunnus eli RetrievalId</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>

5.3 Mitkä ovat varmenteen allekirjoituspyynnön tiedot?

Varmenteen allekirjoituspyynnön (CSR) muodostamisvaiheessa varmenteen tekninen yhteyshenkilö antaa sen organisaation (Subject) tiedot, jolle varmenne on myönnetty. Näistä tiedoista pitää allekirjoituspyyntöön täyttää seuraavat organisaation tiedot:

Common Name (CN), kirjoita Y-tunnus tai ulkomainen organisaatiotunniste.
Organization (O), kirjoita organisaation nimi.
Country (C), kirjoita organisaation kaksikirjaiminen maakoodi (ISO 3166).

5.4 Miten CSR-tieto liitetään signNewCertificate-operaatioon?

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

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

5.5 Miten getCertificate-operaatiosta saatu varmenne tallennetaan tiedostoon?

Jos vastaussanomassa saatava varmenne tallennetaan manuaalisesti tiedostoon, on Certificate-elementissä olevaan base64-enkoodattuun tietoon lisättävä alku- ja lopputagit omille riveilleen siten, että varmenteen tieto jää niiden väliin:

-----BEGIN CERTIFICATE-----
base64-enkoodattu varmenne
-----END CERTIFICATE-----

6 Virhetilanteet

Pääsääntöisesti varmennepalvelu palauttaa tiedot virheistä välittömästi rajapintakutsun vastauksen yhteydessä. Osan virheistä varmennepalvelu havaitsee kuitenkin vasta varmennepyynnön käsittelyssä, jolloin varmennepalvelu palauttaa varmennehaun rajapintakutsuun varmenteen sijaan virheilmoituksen.

Välittömästi palvelukutsun vastaanottokuittauksessa palautetaan tieto virheestä silloin, kun

• palvelukutsu ei ole palvelun skeeman mukainen
• siirtotunnukset ovat virheellisiä
• pyyntöön mahdollisesti liitetty varmenteen allekirjoituspyyntö on virheellisesti muodostettu
• ilmenee jokin muu poikkeustilanteen aiheuttama tekninen virhe.

Palautettavat virhekoodit ja selitteet kuvataan varmennepalvelun rajapintakuvauksessa.

Organisaatio voi tarvittaessa virhetilanteessa olla yhteydessä positiivisen luottotietorekisterin asiakaspalveluun.

6.1 Virhe varmennehakua lähetettäessä

Jos varmenteen luonti epäonnistuu, pitää mahdollinen virhetilanne (esimerkiksi virheelliset tunnisteet) korjata. Tämän jälkeen varmennepyynnön rajapintakutsu pitää tehdä uudelleen. Poikkeuksena on kuitenkin tilanne, jossa järjestelmä ei ole ehtinyt käsitellä varmennepyyntöä, ennen kuin varmennetta yritetään noutaa. Jos varmennehaku on lähetetty liian nopeasti varmennepyynnön jälkeen, se voi epäonnistua. Ota aina talteen noutoavain (RetrievalId) ja yritä hetken kuluttua uudestaan. Varmennehakua voi yrittää uudelleen samalla noutotunnuksella 30–60 sekunnin käsittelyajan jälkeen.

Palautettavat virhekoodit ja selitteet kuvataan varmennepalvelun rajapintakuvauksessa.

Useimmiten virheet varmenteen noudossa tapahtuvat kuvan 1 vaiheissa 4–6. Ennen varmenteen noutamista on hyvä tutustua ohjeisiin huolellisesti.

6.2 Varmennetta ei ole noudettu ajoissa

Varmenteen teknisen yhteyshenkilön pitää noutaa varmenne 14 vuorokauden kuluessa siitä, kun hänelle on lähetetty turvasähköpostiviesti, joka sisältää tiedot varmenteen noutoa varten. Jos varmennetta ei noudeta tämän ajan kuluessa, pitää organisaation tehdä pyyntö uudesta varmenteesta ottamalla yhteyttä positiivisen luottotietorekisterin asiakaspalveluun.

7 Lisätietoa ja tuki

Tutustu varmennepalvelun rajapintakuvaukseen.

Positiivisen luottotietorekisterin rajapintoja koskeva tekninen dokumentaatio on julkaistu Dokumentaatio-sivulla.

Varmennetta ja sen noutoa koskevat tukipyynnöt voi välittää rekisterin verkkosivuilla olevalla havaintolomakkeella tai ottamalla yhteyttä positiivisen luottotietorekisterin asiakaspalveluun 029 497 570.