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. 

Anvisningen har uppdaterats 8.10.2024. Uppdateringen gäller den nya e-tjänsten i Skatteförvaltningens certifikattjänst.

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 certifikattjänstens gränssnitt eller begäran matas in i gränssnittet för Skatteförvaltningens certifikattjänst beroende på hur certifikatet hämtas.

I samband med hämtning via gränssnittet skapar certifikattjänsten efter signaturbegäran ett certifikat som kan hämtas via certifikattjänstens gränssnitt. När certifikattjänstens gränssnitt används laddas certifikatfilen ner direkt till den enhet som personen använder enligt filhanteringen.

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 positiva kreditupplysningsregistret används certifikattjänsten för Inkomstregisterenheten. 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:

• Certifikat för anmälare av kreditens uppgifter: Data Providers Issuing CA v1
• Certifikat för användare av kreditens uppgifter: PCR Credit Data Users Issuing CA v1

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 från kundtjänsten för det positiva kreditupplysningsregistret.

Den tekniska kontaktpersonen för certifikatet hämtar certifikatet via Web Service-gränssnittet eller via gränssnittet för Skatteförvaltningens certifikattjänst.

Via gränssnittet hämtas certifikatet genom att använda två olika gränssnittsanrop, som är en certifikatbegäran och -sökning. När gränssnittet har tagit emot certifikatbegäran svarar det på anropet genom att returnera certifikatets hämtkod. Den tekniska kontaktpersonen för certifikatet sparar hämtkoden och skickar certifikatsökningen med hjälp av den. Slutligen returnerar certifikattjänsten certifikatet som svar på certifikatsökningen.

I samband med att certifikatet hämtas via gränssnittet för Skatteförvaltningens certifikattjänst ombeds certifikatets tekniska kontaktperson av den överföringskod, det lösenord och den signaturbegäran (CSR) som den tekniska kontaktpersonen har tagit emot med en separat säker e-post. När personen har skickat hämtningsuppgifter via gränssnittet laddas certifikatfilen upp på personens enhet enligt filhanteringen.

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

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 ut ett certifikat och vill begära tilläggscertifikat, kan organisationen beställa tilläggscertifikat via Skatteförvaltningens certifikattjänst. Beställning av tilläggscertifikat ska anmälas till Inkomstregisterenheten med kontaktblanketten för det positiva kreditupplysningsregistret eller genom att ringa kundtjänsten för det positiva kreditupplysningsregistret. Tilläggscertifikat hämtas på samma sätt som det första certifikatet. Om organisationen inte kan använda Skatteförvaltningens certifikattjänst till exempel av orsaker som gäller identifiering, kan organisationen beställa tilläggscertifikat via kontaktblanketten för det positiva kreditupplysningsregistret eller genom att ringa kundtjänsten för det positiva kreditupplysningsregistret.

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.

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 en certifikatbegäran till certifikattjänstens Web Service-gränssnitt eller hämtar certifikatet via funktionen Hämta certifikat i Skatteförvaltningens certifikattjänst.

Följande punkter i detta kapitel behandlar hämtning av certifikat via gränssnittet.

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 flera certifikat kan den beställa tilläggscertifikat via Skatteförvaltningens certifikattjänst.

Certifikatet är aktörsspecifikt, så kreditgivaren och någon som eventuellt agerar för dennes räkning kan inte båda använda samma certifikat. Om organisationen själv använder sitt certifikat, men någon som agerar för dess räkning dessutom sköter en del av dess gränssnittsärenden, ska ett tilläggscertifikat beställas för den som agerar för dess räkning.

Tilläggscertifikat som beställts av en organisation för någon som agerar för dess räkning ska anmälas till Inkomstregisterenheten med hjälp av kontaktblanketten för det positiva kreditupplysningsregistret, med vilken organisationen meddelar namnet och affärsverksamhetskoden för den organisation till vars förfogande tilläggscertifikatet ges.

Om organisationen inte kan använda Skatteförvaltningens certifikattjänst och behöver tilläggscertifikat, ska den kontakta det positiva kreditupplysningsregistret antingen med kontaktblanketten eller genom att ringa till telefonkundtjänsten.

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?

• Den dynamiska WSDL-beskrivningen kan hämtas på adressen https://pkiws.vero.fi/2017/10/CertificateServices.wsdl.
• WSDL-beskrivningen och XML-scheman kan också laddas ner från inkomstregistrets webbplats.
• 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.
  • Tjänsteanropet ska göras med HTTP POST-metoden och dessutom ska följande HTTP-rubriker (headers) ställas in:

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>Certifikatets hämtningskod (RetrievalId) frän svarsmeddelandet SignNewCertificateResponse</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 kundtjänsten för det positiva kreditupplysningsregistret.

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 från kundtjänsten för det positiva kreditupplysningsregistret.

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.

Stödbegäranden som gäller certifikatet och hämtningen av det kan skickas med observationsblanketten, eller genom att kontakta kundtjänsten för det positiva kreditupplysningsregistret på nummer 029 497 570.