Certifikat

I denna anvisning behandlas det certifikat som används när uppgifter anmäls till och används från det positiva kreditupplysningsregistret. Olika certifikat används under produktionsfasen och i testningen. Bekanta dig med anvisningen för testcertifikatet som används vid intressentgruppstestningen. 

Centrala termer och förklaringar till dem

Projektet
Projektet Inrättandet av det positiva kreditupplysningsregistret ansvarar för implementeringen av registret.

Signaturbegäran för certifikatet, Certificate Signing Request (CSR)
Signaturbegäran för certifikatet (i formatet PKCS#10) skickas till gränssnittet för certifikattjänsten. Efter signaturbegäran skapar certifikattjänsten ett certifikat som det går att hämta via gränssnittet för certifikattjänsten.

Certifikat
En elektronisk kod som används för att identifiera användaren och som utfärdas av Inkomstregisterenheten.

Organisation
Företag eller organisation som använder det positiva kreditupplysningsregistrets gränssnitt.

Teknisk kontaktperson för certifikatet
Person som organisationen har angett i samband med anmälan eller på ansökan om dataanvändningstillstånd och till vilken informationen om hämtningen av certifikatet skickas.

Anmälan som lämnare av uppgifter
Anmälningsskyldigheten har specificerats i lagen om ett positivt kreditupplysningsregister och de anmälningsskyldiga måste anmäla sig till Inkomstregisterenheten i e-tjänsten före anmälan av uppgifter inleds.

Om organisationen inte kan använda e-tjänsten för organisationer görs anmälan i en annan ärendehanteringskanal. I en sådan situation går det att kontakta kundtjänsten för det positiva kreditupplysningsregistret per telefon.

Bekanta dig med anvisningen: Anmälan som lämnare av uppgifter i det positiva kreditupplysningsregistret

Dataanvändningstillstånd
I lagen om ett positivt kreditupplysningsregister finns det bestämmelser om rätten att få uppgifter ur registret. För dataanvändningstillståndet behövs ett godkänt beslut om dataanvändningstillstånd, som baserar sig på den ansökan om dataanvändningstillstånd som har lämnats i e-tjänsten.

Om organisationen inte kan använda e-tjänsten för organisationer görs ansökan om dataanvändningstillstånd i en annan ärendehanteringskanal. I en sådan situation går det att kontakta kundtjänsten för det positiva kreditupplysningsregistret per telefon.

Bekanta dig med anvisningen för ansökan om dataanvändningstillstånd för kreditgivare

Myndigheter och kreditupplysningsföretag får separata anvisningar för ansökan om dataanvändningstillstånd.

Fler termer finns i ordlistan för det positiva kreditupplysningsregistret (suomi.fi).

1 Inledning

I denna anvisning behandlas det certifikat som används när uppgifter anmäls till och används från det positiva kreditupplysningsregistret. Olika certifikat används under produktionsfasen och i testningen. Bekanta dig med anvisningen för testcertifikatet som används vid intressentgruppstestningen.

Användningen av gränssnitten för det positiva kreditupplysningsregistret kräver att aktören som anropar gränssnittet identifieras i samband med anropet. Användaren av gränssnittet identifieras med hjälp av att certifikat. Certifikaten som godkänns i tjänsten har publicerats av Skatteförvaltningen.

2 Certifikattjänsten

Vid intressentgruppstestningen för det positiva kreditupplysningsregistret används certifikattjänsten för inkomstregistret. Certifikattjänsten grundar sig på en PKI-lösning (Public Key Infrastructure).

Kunden identifieras och behörigheten att använda gränssnitten säkerställs med hjälp av ett certifikat. Inkomstregisterenheten utfärdar certifikaten för ett visst användningsändamål och för en viss organisation. De kan inte användas för ett ändamål som avviker från det ursprungliga.

2.1 Typer av certifikat

Det finns två typer av certifikat: certifikat för lämnare av kredituppgifter och certifikat för användare av kredituppgifter. Olika typer av certifikat används alltså i gränssnitten för anmälan av uppgifter och för förfrågan av uppgifter. Om den som använder tjänsten är både en anmälare och användare av uppgifter måste olika typer av certifikat användas för dessa olika användningsändamål. En aktör kan ha flera certifikat. De kan antingen vara av samma eller av olika typ.

Inkomstregisterenheten fungerar själv som utfärdare för sina certifikat. Därför går utfärdaruppgifterna för dessa certifikat inte att hitta i distributionen för färdigprogram på marknaden. Organisationen kontrollerar själv den tekniska tillförlitligheten för certifikaten i det egna systemet genom att från webbplatsen ladda ner rotcertifikaten och utfärdarcertifikaten för de certifikat som Skatteförvaltningen har utfärdat. När organisationen har installerat dessa i sitt eget system skapas det genom certifikaten ett förtroendeförhållande med Skatteförvaltningens certifikat, varefter gränssnitten kan användas på ett informationssäkert sätt.

Det går att ladda ner rot- och utfärdarcertifikaten via länkarna nedan:

Läs mer i beskrivningen av gränssnittet för certifikattjänsten.

3 Skapa ett nytt certifikat

Organisationen får certifikatet genom att anmäla sig som lämnare av kredituppgifter eller genom att ansöka om dataanvändningstillstånd till registret. När organisationen har fått ett positivt beslut skickas den nödvändiga informationen för att hämta certifikatet till den tekniska kontaktpersonen för certifikatet.

Den tekniska kontaktpersonen för certifikatet kan hämta certifikaten från Inkomstregisterenhetens certifikattjänst efter att hen har mottagit den överföringskod och det engångslösenord som har sänts med säker e-post som en följd av certifikatbegäran. Engångslösenordet är giltigt i 14 dygn. Engångslösenordets giltighetstid går ut om certifikatet inte hämtas inom den här tiden. Organisationen ska i så fall begära ett nytt certifikat antingen från kundtjänsten för det positiva kreditupplysningsregistret eller med observationsblanketten.

Den tekniska kontaktpersonen för certifikatet hämtar certifikatet via certifikattjänstens Web Service-gränssnitt. Certifikatet hämtas med två olika gränssnittsanrop, det vill säga certifikatbegäran och certifikathämtning. När gränssnittet har tagit emot certifikatbegäran svarar gränssnittet på anropet genom att returnera certifikatets hämtningskod. Den tekniska kontaktperson för certifikatet tar vara på hämtningskoden och skickar med hjälp av den en certifikathämtning. Till slut returnerar certifikattjänsten certifikatet som ett svar på certifikathämtningen.

I följande diagram beskrivs faserna i den tekniska processen och nedanför diagrammet beskrivs innehållet i varje funktion.

Faserna för processen för hämtning av certifikatet. Faserna beskrivs närmare senare i texten.

Bild 1. Processdiagram för hämtning av certifikatet.

Nedan beskrivs den i diagrammet presenterade processen för hämtning av certifikatet. Numreringen följer numreringen på bilden. I punkterna 2–7 hänvisas det till gränssnitten och deras element i beskrivningen av gränssnittet för certifikattjänsten.

1. Organisationen får certifikatet genom att anmäla sig som lämnare av kredituppgifter eller genom att ansöka om dataanvändningstillstånd till registret. I samband med detta meddelar organisationen också den tekniska kontaktpersonen för certifikatet. Denna person hämtar certifikatet. Den tekniska kontaktpersonen för certifikatet måste ha tillräcklig teknisk expertis för att kunna hämta certifikatet.

Som kontaktuppgifter för den tekniska kontaktpersonen för certifikatet måste man ange en e-postadress som inte är en sändlista eller en delad e-postlåda. Dessutom ska man ange ett telefonnummer som kan ta emot ett sms. Telefonnumret ska också innehålla en landskod.

Om organisationen redan har hämtat ett certifikat och vill begära tilläggscertifikat måste organisationen kontakta kundtjänsten för det positiva kreditupplysningsregistret eller fylla i observationsblanketten. Tilläggscertifikaten hämtas på samma sätt som det första certifikatet.

2. När Inkomstregisterenheten har fattat ett positivt beslut om anmälan eller om ansökan om dataanvändningstillstånd skickar certifikattjänsten ett säkert e-postmeddelande till den tekniska kontaktpersonen för certifikatet som organisationen har meddelat. Det säkra e-postmeddelandet innehåller två specificerande koder: en överföringskod (TransferId) och ett engångslösenord (TransferPassword). E-postmeddelandet kan bara öppnas med en PIN-kod. Den tekniska kontaktpersonen för certifikatet får först ett e-postmeddelande som innehåller en länk för att öppna det säkra e-postmeddelandet. När den tekniska kontaktpersonen för certifikatet har öppnat länken skickas den PIN-kod som behövs för att öppna meddelandet till kontaktpersonens mobiltelefon som ett sms.

Överföringskoden och engångslösenordet som anknyter till beställningen av certifikatet är giltiga i 14 dygn efter att meddelandena har skickats och certifikatet måste hämtas under den här tiden. Giltighetstiden för beställningen av certifikatet går ut om certifikatet inte hämtas inom den här tiden. I så fall måste organisationen beställa ett nytt certifikat genom att kontakta kundtjänsten för det positiva kreditupplysningsregistret eller fylla i observationsblanketten.

3. Den tekniska kontaktpersonen för certifikatet skapar för begäran om certifikat ett nyckelpar på 2048 bitar som skapats med RSA-algoritmen. Dessutom skapar kontaktpersonen en signaturbegäran för certifikatet (Certificate Signing Request, CSR) som följer PKCS#10-specifikationen och som undertecknats med en privat nyckel. I kapitel 5.3 beskrivs de uppgifter som ges i signaturbegäran.

4. Den tekniska kontaktpersonen för certifikatet skickar certifikatbegäran till certifikattjänstens Web Service-gränssnitt. När gränssnittet används för hämtning av certifikat ska tjänsteanropen skickas till adressen https://pkiws.vero.fi/2017/10/CertificateServices. Meddelandet SignNewCertificateRequest används för certifikatbegäran. Meddelandet innehållet förutom det nyss skapade CSR:et den överföringskod (TransferId) och det engångslösenord (TransferPassword) som erhållits per säker e-post. Till meddelandet bifogas dessutom FO-numret (CustomerId) och namnet (CustomerName) för den anmälningsskyldiga eller innehavaren av dataanvändningstillståndet.

Certifikattjänsten tar emot signaturbegäran och returnerar ett svarsmeddelande.

5. Den tekniska kontaktpersonen för certifikatet får certifikatets hämtningskod (RetrievalId) i svarsmeddelandet SignNewCertificateResponse. Det är viktigt att ta vara på hämtningskoden före nästa fas.

Det räcker några sekunder att skapa certifikatet och därför ska man vänta 30–60 sekunder innan certifikathämtningen skickas. Om man försöker skicka certifikathämtningen för snabbt innan certifikatet har skapats misslyckas certifikathämtningen. Då är det viktigt att man har tagit vara på hämtningskoden så att man kan försöka utföra certifikathämtningen på nytt. Om hämtningskoden inte har tagits till vara och certifikathämtningen misslyckas måste organisationen begära ett nytt certifikat.

6. Den tekniska kontaktpersonen för certifikatet skickar certifikathämtningen, det vill säga meddelandet GetCertificateRequest, till gränssnittet för certifikattjänsten. Hämtningskoden för certifikatet (RetrievalId), vilken har erhållits från svarsmeddelandet för det tidigare anropet, ska bifogas till meddelandet. Dessutom ska det alltid i meddelandet ingå samma FO-nummer och namn som har funnits i det föregående meddelandet och till vilka certifikatet har beviljats.

Certifikattjänsten returnerar certifikatet i svarsmeddelandet.

7. Den tekniska kontaktpersonen för certifikatet får i svarsmeddelandet GetCertificateResponse det certifikat (Certificate) som certifikattjänsten har skapat för organisationen. Efter det kan organisationen använda certifikatet i gränssnittsanrop genom att bifoga certifikatet till den privata nyckel som organisationen har skapat.

Certifikathämtningen kan upprepas genom att använda samma RetrievalId-kod.

I beskrivningen av gränssnittet för certifikattjänsten finns närmare tekniska anvisningar för att hämta certifikatet.

4 Övriga situationer

4.1 Begäran om tilläggscertifikat

Om organisationen behöver ett nytt certifikat eller nya tilläggscertifikat ska organisationen kontakta kundtjänsten för det positiva kreditupplysningsregistret eller fylla i observationsblanketten.

4.2 Att spärra ett certifikat

Om användarens privata nyckel försvunnit eller hamnat i fel händer, ska certifikatet spärras. Ett certifikat måste också spärras om det är onödigt.

Inkomstregisterenheten kan spärra ett certifikat till exempel när ett avtal som berättigar till användning av tjänsten upphör eller då det är uppenbart att certifikatet missbrukats.

Begär spärrning av certifikatet per telefon:

Under tjänstetiden
Det positiva kreditupplysningsregistrets kundtjänst: 029 497 570
vardagar kl. 9–16.

Utanför tjänstetiden
Endast brådskande spärrning av certifikat: +358 9 427 34 834

5 Vanliga frågor

Nedan några vanliga frågor som anknyter till hämtningen av certifikatet.

5.1 Vilken är certifikattjänstens adress och vart ska tjänsteanropen skickas?

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

Värdet för rubriken Content-Length ska vara längden på meddelandet i fråga, det vill säga "calculated value". Längden på meddelandet ska räknas i samband med sändningen.
Värdet för SOAPAction ska vara värdet för gränssnittsoperationen i fråga. Dessa värden hittas i WSDL-beskrivningen.

    • Det går inte att skicka SOAP-meddelanden med webbläsaren, åtminstone inte utan att tilläggsdelar (extensions och plugins) har lagts till webbläsaren. Meddelandet ska i stället skickas med ett program som kan skicka SOAP-meddelanden.

5.2 Vilket FO-nummer och kundnamn används i punkten GetCertificateRequest?

Nedan ett exempel som gäller punkten GetCertificateRequest och det FO-nummer och kundnamn som ska användas.

<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> FO-nummer</CustomerId>
<!--Optional:-->
<CustomerName>Organisationens namn</CustomerName>

<RetrievalId>RetrievalId från det säkra e-postmeddelande som certifikattjänsten har skickat</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>

5.3 Vilka är uppgifterna i signaturbegäran för certifikatet?

När signaturbegäran för certifikatet (CSR) skapas ger den tekniska kontaktpersonen för certifikatet uppgifterna för den organisation (Subject) till vilken certifikatet har beviljats. Av dessa ska man i signaturbegäran fylla i följande uppgifter om organisationen:

Common Name (CN), ange ett FO-nummer eller ett utländskt organisationsnummer.
Organization (O), ange organisationens namn.
Country (C), ange organisationens landskod som består av två bokstäver (ISO 3166).

5.4 Hur bifogas CSR-uppgiften till operationen signNewCertificate?

Den base64-kodade signaturbegäran för certifikatet (CSR), vilken finns i elementet CertificateRequest, ska anges utan start- och sluttaggar:

-----BEGIN CERTIFICATE REQUEST-----
base64-kodad CSR-----
END CERTIFICATE REQUEST-----

5.5 Hur sparas certifikatet som fås i operationen getCertificate i filen?

Om det certifikat som fås i svarsmeddelandet sparas manuellt i en fil, ska man i den base64-kodade uppgiften i Certificate-elementet lägga till start- och sluttaggar på egna rader så att certifikatets uppgift är mellan dem:

-----BEGIN CERTIFICATE-----
base64-kodat certifikat
-----END CERTIFICATE-----

6 Felsituationer

I regel returnerar certifikattjänsten uppgifter om fel omedelbart i samband med svaret på gränssnittsanropet. Certifikattjänsten upptäcker dock en del av felen först vid behandlingen av certifikatbegäran. I så fall returnerar certifikattjänsten ett felmeddelande i stället för certifikatet som svar på gränssnittsanropet för certifikathämtningen.

I mottagningskvitteringen för tjänsteanropet returneras information om ett fel omedelbart när

  • tjänsteanropet inte följer schemat för tjänsten
  • överföringskoderna är felaktiga
  • den signaturbegäran för certifikatet som eventuellt har bifogats till begäran har skapats på ett felaktigt sätt
  • det uppstår något annat tekniskt fel som orsakats av en avvikande situation.

Felkoderna och förklaringarna som returneras beskrivs i beskrivningen av gränssnittet för certifikattjänsten.

Organisationen kan vid behov i felsituationer kontakta Inkomstregisterenheten med observationsblanketten.

6.1 Fel vid skickande av certifikathämtning

Om skapandet av certifikatet misslyckas ska en eventuell felsituation (till exempel felaktiga koder) korrigeras. Efter det ska gränssnittsanropet för certifikatbegäran göras på nytt. Ett undantag är dock en situation då systemet inte har hunnit behandla certifikatbegäran innan man försöker hämta certifikatet. Certifikathämtningen kan misslyckas om den skickas för snabbt efter certifikatbegäran. Ta alltid vara på hämtningsnyckeln (RetrievalId) och försök på nytt om en stund. Man kan försöka göra certifikathämtningen på nytt med samma hämtningskod efter att man gett 30–60 sekunder behandlingstid.

Felkoderna och förklaringarna som returneras beskrivs i beskrivningen av gränssnittet för certifikattjänsten.

För det mesta sker felen vid hämtningen av certifikatet i skedena 4–6 på bild 1. Innan certifikatet hämtas är det bra att noggrant bekanta sig med anvisningarna.

6.2 Certifikatet har inte hämtats i tid

Den tekniska kontaktpersonen för certifikatet ska hämta certifikatet inom 14 dygn från att ett säkert e-postmeddelande med information om hur certifikatet ska hämtas har skickats till denne. Om certifikatet inte hämtas inom den här tiden ska organisationen göra en begäran om ett nytt certifikat med observationsblanketten.

7 Ytterligare information och stöd

Bekanta dig med gränssnittsbeskrivningen för certifikattjänsten.

Den tekniska dokumentationen som gäller gränssnitten för det positiva kreditupplysningsregistret har publicerats på sidan Dokumentation.

Certifikat — andra sidor

Sidan har senast uppdaterats 13.9.2023