Anvisningar för testcertifikat
- Har getts
- 27.2.2023
- Giltighet
- 27.2.2023 - Tills vidare
Centrala termer
Projektet
Projektet Inrättandet av det positiva kreditupplysningsregistret ansvarar för utvecklingen av registret. Projektet stöder intressentgrupperna vid testningen.
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.
Testcertifikatet är avsett för testmiljön för intressentgrupper. Behörigheten och certifikatet för gränssnittet för produktionsanvändningen av det positiva kreditupplysningsregistret, vilken inleds år 2024, hämtas separat före ibruktagandet.
Organisation som genomför testningen
Företag eller organisation som deltar i intressentgruppstestningen för det positiva kreditupplysningsregistret.
Teknisk kontaktperson
Person som organisationen namnger på anmälan om inledning av test-ning och till vilken informationen om hämtningen av testcertifikatet skickas.
Anmälan om inledning av testning
Anmälan om inledning av testning görs på webblanketten. Intressentgruppen uppger i anmälan om inledning av testning till det positiva kreditupplysningsregistret de uppgifter som behövs för att testningen kan inledas och de tjänster som testas samt godkänner användarvillkoren för testmiljön.
Fler termer finns i anvisningarna för testning för intressentgrupper och i ordlistan för det positiva kredit-upplysningsregistret (Suomi.fi).
1 Inledning
I denna anvisning behandlas testcertifikatet som används vid intressentgruppstestningen för det positiva kreditupplysningsregistret. Verkställandet av intressentgruppstestningen beskrivs på ett allmänt plan i anvisningarna för testning för intressentgrupper.
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.
Olika certifikat används under produktionsfasen och i testningen. Intressentgrupperna har fått separata anvisningar om produktionscertifikatet. Bekanta dig med anvisningarna för användning av produktionscertifikatet.
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. Användaren av certifikatet måste godkänna användarvillkoren för intressentgruppstestning och följa dem.
2.1 Typer av certifikat
Olika typer av certifikat används för gränssnitten för anmälan av uppgifter och förfrågan av uppgifter. Om den som använder tjänsten verkar både som 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.
Om organisationen som genomför testningen testar både anmälan och förfrågan av uppgifter behöver organisationen olika typer av certifikat för dessa båda ändamål.
- I det positiva kreditupplysningsregistret används två olika typer av certifikat: en för anmälan av uppgifter och en för förfrågan av uppgifter.
- Ett konstgjort FO-nummer och ett konstgjort organisationsnamn bifogas alltid till testcertifikatet. Dessa uppgifter skickas till den person som har fyllt i anmälan om inledning av intressentgruppstestning. Om organisationen som genomför testningen endast testar anmälan av uppgifter eller endast testar förfrågan av uppgifter behöver organisationen ett certifikat och ett konstgjort FO-nummer.
- Om organisationen som genomför testningen testar både anmälan och användning av uppgifter behöver organisationen två olika typer av certifikat, minst ett av vardera typen. Organisationen behöver alltså ett certifikat för anmälan av uppgifter och ett certifikat för förfrågan av uppgifter. Det konstgjorda FO-numret är detsamma för båda certifikaten. Vid behov kan det dock finnas flera konstgjorda FO-nummer och certifikat som lagts till dem till exempel när organisationen som genomför testningen testar anmälan av uppgifter för flera intressentgruppers räkning. Organisationen som genomför testningen kan begära fler certifikat eller konstgjorda FO-nummer med kontaktblanketten för intressentgruppstestningen.
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 som genomför testningen 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 datasä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 Test Issuing CA v1 (ZIP)
Certifikat för användare av kreditens uppgifter: PCR Credit Data Users Test Issuing CA v2 (ZIP)
Läs mer i beskrivningen av gränssnittet för certifikattjänsten.
3 Skapa ett nytt testcertifikat
För att organisationen som genomför testningen ska kunna hämta ett nytt testcertifikat måste organisationen först anmäla sig till intressentgruppstestningen. Anvisningarna för anmälan till intressentgruppstestningen finns i anvisningarna för testning för intressentgrupper.
När organisationens anmälan som testare har behandlats skickar certifikattjänsten behövlig information för hämtning av certifikatet till den tekniska kontaktpersonen. Denna information förmedlas till den tekniska kontaktpersonen med ett säkert e-postmeddelande. Kontaktpersonen får per sms en kod för att öppna meddelandet. Därför ska man som den tekniska kontaktpersonens kontaktuppgifter ange en e-postadress som inte är en sändlista eller en delad e-postlåda samt ett telefonnummer som kan ta emot ett sms. Telefonnumret ska också innehålla en landskod.
Den tekniska kontaktpersonen 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 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 som genomför testningen ska i så fall begära ett nytt certifikat med kontaktblanketten för intressentgruppstestningen.
Den tekniska kontaktpersonen 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 kontaktpersonen 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.
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. Anvisningarna för anmälan till testning och begäran av tilläggscertifikat finns i anvisningarna för testning för intressentgrupper.
1. För att organisationen som genomför testningen ska få ett nytt testcertifikat ska organisationen göra anmälan om inledning av testning. Med anmälan om inledning av testning namnges den tekniska kontaktpersonen som hämtar certifikatet. Den tekniska kontaktpersonen måste ha tillräcklig teknisk expertis för att kunna hämta certifikatet.
Om organisationen redan har hämtat ett testcertifikat och vill begära tilläggscertifikat måste organisationen fylla i en kontaktblankett för intressentgruppstestnignen. Tilläggscertifikaten hämtas på samma sätt som det första certifikatet.
2. När anmälan om inledning av testning har hanterats i projektet skickar certifikattjänsten ett säkert e-postmeddelande till den tekniska kontaktperson som namngetts på anmälan om inledning av testning. Meddelandet innehåller två identifieringskoder: en överföringskod (TransferId) och ett engångslösenord (TransferPassword). Detta e-postmeddelande kan bara öppnas med en PIN-kod. Den tekniska kontaktpersonen 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 har öppnat länken skickas den PIN-kod som behövs för att öppna meddelandet till den tekniska 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 som genomför testningen beställa ett nytt testcertifikat.
3. Den tekniska kontaktpersonen skapar för begäran om certifikat ett nyckelpar på 2048 bitar som skapats med RSA-algoritmen. Dessutom skapar den tekniska 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 skickar certifikatbegäran till certifikattjänstens Web Service-gränssnitt. Tjänsteanropen skickas till adressen https://pkiws-testi.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 det konstgjorda FO-nummer (CustomerId) och namn (CustomerName) som har getts till organisationens bruk i samband med behandlingen av anmälan om inledning av testning.
Tjänsteanropen skickas till adressen https://pkiws-testi.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: "signNewCertificate"
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. Den dynamiska WSDL-beskrivningen kan hämtas på adressen https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl. WSDL-beskrivningen och XML-scheman kan också laddas ner från inkomstregistrets webbplats.
-
- 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.
Certifikattjänsten tar emot signaturbegäran och returnerar ett svarsmeddelande.
5. Den tekniska kontaktpersonen 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.
6. Den tekniska kontaktpersonen gör certifikathämtningen, det vill säga skickar 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 konstgjorda FO-nummer och namn som har funnits i det föregående meddelandet.
Certifikattjänsten returnerar certifikatet i svarsmeddelandet.
7. Den tekniska kontaktpersonen 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 fler testcertifikat
Om organisationen som genomför testningen behöver fler testcertifikat för ett sådant gränssnitt som organisationen testar kan man begära ett nytt certifikat med kontaktblanketten för intressentgruppstestningen. På blanketten ska man ange om certifikatet gäller anmälan eller förfrågan av uppgifter och om samma konstgjorda FO-nummer som använts i de tidigare certifikaten bifogas till certifikatet. Samma konstgjorda FO-nummer kan han flera certifikat av samma typ, till exempel flera certifikat för anmälan av uppgifter.
4.2 Testning för en intressentgrupps räkning
Om någon annan än intressentgruppen själv genomför intressentgruppstestningen kan certifikatet ansökas för den aktör som genomför testningen. Innan anmälan om inledning av testning görs ska man utreda vem i organisationen som utför testningen som verkar som teknisk kontaktperson och hämtar certifikatet. Kontaktuppgifterna för denna person ska meddelas med anmälan om inledning av testning så att den information som behövs för att hämta certifikatet förmedlas till rätt person.
Om intressentgruppen samtidigt också vill testa själv kan intressentgruppen ansöka om ett separat certifikat för sig själv med kontaktblanketten. Intressentgruppen kan också komma överens med aktören som genomför testningen om att samanvända ett testcertifikat.
4.2.1 Certifikatförfarandet är olika i testningen och i produktionsfasen
I det positiva kreditupplysningsregistret kan bara en anmälningsskyldig eller en aktör som har rätt att använda uppgifterna anmäla sig som anmälare av uppgifter eller ansöka om dataanvändningstillstånd för förfrågan av uppgifter. Endast dessa aktörer kan ansöka om och beviljas det produktionscertifikat som behövs för anmälan eller förfrågan av uppgifter.
Läs mer om detta:
Förfaranden vid användning av certifikat för det positiva kreditupplysningsregistret
Anvisning om certifikatet som används under produktionsfasen
Denna anvisning gäller endast användningen av testcertifikatet.
4.3 Förnyande av testcertifikatet
Testcertifikatet gäller i två år. Giltighetstiden kan kontrolleras i certifikatet. Certifikatet förnyas i certifikattjänstens gränssnitt. Det finns en egen tjänst i gränssnittet för förnyelsen (RenewCertificate).
Förnyelsen kan göras tidigast 60 dygn före giltighetstiden för certifikatet går ut. Om giltighetstiden för certifikatet hinner gå ut måste organisationen som genomför testningen begära ett helt nytt certifikat och hämta det nya certifikatet. Då begärs och hämtas det nya certifikatet på samma sätt som när man beställer ett certifikat för första gången.
Läs mer om hur certifikatet förnyas i beskrivningen av gränssnittet för certifikattjänsten.
4.4 Spärrande av ett testcertifikat
När organisationen som genomför testningen inte längre behöver ett testcertifikat eller om organisationen av annan orsak vill spärra ett certifikat ska organisationen fylla i kontaktblanketten för intressentgruppstestningen. Som orsaken till kontakten väljs beställning av testcertifikat, övriga ärenden som gäller testcertifikat. På blanketten meddelas serienumret för certifikatet som ska spärras.
5 Vanliga frågor
Nedan några vanliga frågor som anknyter till hämtningen av certifikatet.
5.1 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="https://pkiws-testi.vero.fi/2017/10/certificateservices">
<soapenv:Header/>
<soapenv:Body>
<cer:GetCertificateRequest>
<Environment>TEST</Environment>
<CustomerId>Konstgjort FO-nummer som erhållits av det positiva kreditupplysningsregistret</CustomerId>
<!--Optional:-->
<CustomerName>Konstgjort organisationsnamn som erhållits av det positiva kreditupplysningsregistret</CustomerName>
<RetrievalId>Certifikatets hämtningskod (RetrievalId) frän svarsmeddelandet SignNewCertificateResponse</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>
5.2 Vilka är uppgifterna i signaturbegäran för certifikatet?
När signaturbegäran för certifikatet (CSR) skapas anger organisationen som genomför testningen uppgifter som gäller den konstgjorda organisationen (Subject) som ansöker om certifikatet. Av dessa ska man i signaturbegäran fylla i följande uppgifter om den konstgjorda organisationen:
Common Name (CN), ange det konstgjorda FO-nummer som erhållits av det positiva kreditupplysningsregistret.
Organization (O), ange det konstgjorda organisationsnamn som erhållits av det positiva kreditupplysningsregistret.
Country (C), ange FI.
I testmiljön används de konstgjorda uppgifter om testorganisationen som gett till organisationen. Organisationens egna uppgifter använda endast under produktionsfasen.
5.3 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.4 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-----
5.5 Kan hämtningen av testcertifikatet testas separat?
Det är möjligt att testa hämtningen av certifikatet i testbädden för inkomstregistrets certifikattjänst. Certifikattjänstens testbädd är en separat tjänst med separata adresser och som endast är avsedd för testningen av certifikatet.
I testbädden kan den tekniska kontaktpersonen testa riktigheten i de meddelanden som skickas till gränssnittet för certifikattjänsten utan att det bildas något certifikat av dem. Intressentgruppen som testar kan också använda testbädden för att utveckla programmet som anropar gränssnittet för certifikattjänsten.
Observera att testcertifikatet som används vid intressentgruppstestningen inte kan hämtas från testbädden. De adresser och uppgifter som används i testbädden ska inte användas när testcertifikatet hämtas.
Läs mer i anvisningen för certifikattjänstens testbädd (pdf)
Ladda ner certifikattjänstens testmaterial (zip)
6 Felsituationer
I regel returnerar certifikattjänsten uppgifter om fel omedelbart i samband med 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.
Tekniska problem vid hämtningen av certifikatet kan meddelas med observationsblanketten för testning. För andra kontakter, såsom beställningar av tilläggscertifikat, kan man fylla i kontaktblanketten för testning.
7.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.
7.2 Certifikatet har inte hämtats i tid
Den tekniska kontaktpersonen 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 som genomför testningen göra en begäran om ett nytt testcertifikat med kontaktblanketten för intressentgruppstestningen.
8 Ytterligare information och stöd
Den tekniska dokumentation som används vid intressentgruppstestningen har publicerats på sidan Dokumentation.
Certifikattjänsten – Beskrivning av gränssnittet (pdf)
Anvisningar för programutvecklare (pdf)
Anvisningar för testning för intressentgrupper
Om ditt ärende gäller observationer om tekniska fel kan du meddela om detta på observationsblanketten för intressentgruppstestningen. Ta kontakt med kontaktblanketten om du behöver ett nytt testcertifikat.