Varmenteet rajapintojen käytössä

Vero API-rajapintapalvelujen käyttö edellyttää Verohallinnon varmennepalvelun myöntämää asiakasvarmennetta (client certificate). Autentikaatiotapana käytetään client certificate authentication -tapaa, mikä on yksi vahvan autentikaation muoto. Tämä tarkoittaa, että suojatun yhteyden muodostumisessa SSL- tai TLS-kättelyssä tarkistetaan client-varmenteen olemassaolo. Kättelyn yhteydessä palvelin tarkistaa, että kutsujalla on varmenteeseen liittyvä yksityinen avain. Varmenteella tunnistetaan ja auktorisoidaan rajapintaa käyttävä organisaatio.

Verohallinto ei voi antaa ratkaisukohtaisia ohjeita, miten varmenne liitetään kutsuun, koska tapa riippuu asiakkaan järjestelmäratkaisuista. Lisätietoja autentikaatiotavasta ja sen käyttämisestä löytyy useimmilla hakukoneilla avainsanoilla ”client certificate authentication.”. Koodiesimerkit -sivulle on julkaistu yksi tapa lisätä varmenne kutsuun, esimerkistä voi ottaa mallia omaan toteutukseen.

Lisätietoa varmenteista löytyy Testaus ja Tuotanto -välilehdiltä.

Ohjelmistotalon tulee testata integraatio Vero API testirajapintoihin käyttäen testivarmennetta. Testiskenaarioiden tulee sisältää mm. tyypillisimmät käyttötilanteet, rajapinnan palauttaman hyväksytyn syötteen sekä virheilmoitusten käsittelyn, varautuminen käyttökatkotilanteisiin sekä odottamattomiin virheisiin.

Rajapintakohtainen tuotantolupa edellyttää testiskenaarioiden suorittamista API-portaalissa. Testiskenaarioiden suorittaminen tapahtuu kutsumalla rajapintoja integraation verifiointiympäristössä tuotantovarmenteella.

Avainpari ja varmenne

Avainpari ja varmenne ovat keskeisiä käsitteitä PKI-teknologiassa. Avainpari koostuu yksityisestä ja julkisesta avaimesta. Asiakas muodostaa avainparin itse varmenteen myöntäjän (CA) ohjeiden mukaisesti.

Yksityinen avain on salainen ja sitä käytetään viestien allekirjoittamiseen ja salattujen viestien purkamiseen. Yksityinen avain on pidettävä suojattuna ja sitä ei koskaan lähetetä kenellekään. Julkista avainta käytetään viestien salaamiseen.

Varmenne sisältää asiakkaan julkisen avaimen, jonka varmenteen myöntäjä (CA) on allekirjoittanut. Allekirjoitettu varmenne todistaa, että julkinen avain kuuluu tietylle entiteetille. Vero API-rajapintoja käytettäessä palvelin lisäksi varmistaa kättelyssä, että rajapinnan käyttäjällä on hallussaan asiakasvarmenteeseen liittyvä yksityinen avain. Tällä varmistetaan, että varmennetta käyttää sen oikea omistaja.

SSL-kättely ja client certificate authentication

Asiakkaan järjestelmän ja Vero APIn välisen yhteyden muodostamisessa eli SSL/TLS-kättelyssä tapahtuu seuraavaa, kun suoritetaan client certificate authentication -menettely, yksinkertaistettu kuvaus:

 

  • 1

    Client Hello

  • Asiakas aloittaa kättelyn lähettämällä palvelimelle viestin, joka sisältää mm. tuetut TLS-versiot, salausalgoritmit (cipher suitet) ja satunnaisen numeron.
  • 2

    Server Hello

  • Palvelin vastaa "Server Hello"-viestillä ja valitsemalla TLS-version ja salausalgoritmin. Palvelin lähettää varmenteensa asiakkaalle, joka tarkistaa sen luotettavuuden varmentajan (CA) avulla. Palvelin lähettää myös oman satunnaisen numeronsa.
  • 3

    Asiakkaan varmenne

  • Palvelin pyytää, että asiakas lähettää oman varmenteensa palvelimelle. Asiakas lähettää varmenteensa (julkisen osan) sekä yksityisellä avaimella allekirjoitetun satunnaisen tiedon palvelimelle. Palvelin tarkistaa asiakkaan varmenteella, että se voi purkaa allekirjoitetun tiedon, eli varmistaa, että asiakkaalla on varmenteen yksityinen avain hallussaan.
  • 4

    Avainten vaihto

  • Asiakas ja palvelin vaihtavat yhteyden salaukseen liittyviä avaimia, jotka on johdettu satunnaisista numeroista ja julkisista avaimista. Näitä salausavaimia käytetään varsinaisen tiedon salaamiseen ja purkamiseen koko yhteysistunnon ajan.
  • 5

    Viimeistely

  • Asiakas ja palvelin lähettävät toisilleen viestin, joka vahvistaa, että kättely on onnistunut ja salattu yhteys on muodostettu.

    Tässä prosessissa asiakas todistaa identiteettinsä palvelimelle lähettämällä varmenteensa, ja palvelin varmistaa sen luotettavuuden. Tämä varmistaa, että yhteys on turvallinen ja että molemmat osapuolet ovat luotettavia.

Yleisiä ohjeita PKI-teknologiasta, ohjeita avainparin muodostamisesta, varmenteen allekirjoituspyynnöstä löydät seuraavilta vero.fi- sivuilta ja hakukoneiden avulla:

  • Verohallinnon varmennepalvelun ohjeet: Tekniset ohjeet - vero.fi
  • Varmenteen käyttäminen yhteyden muodostamisessa omassa ohjelmakoodissa: Koodiesimerkit - vero.fi
  • Hakukoneilla voit etsiä ohjeita hakusanalla "Mikä on julkisen avaimen infrastruktuuri (PKI)?"
Sivu on viimeksi päivitetty 7.1.2025