Hur man skapar certifikat för Swish

Marcus Olsson,

Jag implementerade nyligen Swish-betalningar på esignering.se och medan själva implementationen var tämligen simpel (flödet påminner något om PayPals) så kan certifikaten ställa till det lite.

Medan det är egentligen en ganska snabb process så är det lite klurigt att hitta bra och relevant information om vilka nycklar som hör ihop – så en liten snabbguide är på sin plats.

Denna guiden är för macOS specifikt. I Swish-portalen tillhandahåller de ett flöde för Windows, dock så kan jag inte svara på hur SSL och annat funkar på den plattformen och/eller om det är någon skillnad på metoderna för macOS.

Sedan detta inlägget skrev så har jag publicerat ett ett komplett paket för att snabbt och enkelt börja ta betalt med Swish i PHP (och Laravel), läs mer om det här. Fortsätt gärna och läs denna artikeln om hur man skapar certifikaten (som då är kompatibla med t.ex. min open source-lösning.)
OBS! Nycklar och annan output i denna guiden eller ifrån Swish skall aldrig delas med någon utanför din organisation, med dessa nycklar man kan utföra återbetalningar, betalningsförfrågningar m.m. i ditt företagsnamn. De ska givetvis aldrig heller commitas till exempelvis Github – förvara dem säkert.

Steg 1 – Skaffa Swish Handel

Ett steg innan vi kommer till certifikaten dock: det första man kanske stöter på är skillnaden mellan Swish Handel och Swish Företag.

För båda varianterna får man ett Swish-nummer man kan använda, dock är det med Swish Handel man får tillgång till Swish-portalen för att hämta ut certifikat som man kan använda i sina integrationer. Notera också att bankerna tar premium för Handeln, antingen genom dyrare månadskostnader eller högre transaktionsavgift – men det är en artikel en annan dag.

Så kontakta din bank, säg att det är Swish Handel du är ute efter, fyll i blanketten "Ansökan om certifikatansvarig" och så hjälper de dig vidare.

Steg 2 – Generera Swish-certifikat

När du äntligen har fått tillgång till Swish-portalen så är det dags att börja jobba med certifikaten.

På macOS, börja med att skapa en CSR (Certificate Signing Request) genom appen Certificate Assistant (Keychain -> Certificate Assistant -> Create a Certificate From a Certificate Authority).

macOS Keychain Assistant .p12

Ange din e-postadress och sedan ditt Swish-nummer som "Common Name".

Gå vidare till Swish-portalen – portal.swish.nu/company – välj att skapa nytt certifikat och ladda upp din CSR. Där efter spottas det ut en .pem-fil med dina unika certifikat som du ska ladda ner.

Swish Certificate Portal

Steg 3 – Extrahera .key

Vi börjar med att exportera vår privata nyckel ifrån steg 2 – den skapades i samband med vår CSR och ska finnas i Keychain (se efter under Login -> Keys, där ska det finnas en "private key" med ditt Swish-nummer). Välj exportera och sätt ett lösenord.

Export private key Keychain Access

Ut kommer en p12-fil, ifrån denna extraherar vi vår privata nyckel;

1openssl pkcs12 -nocerts -in 123xxxxxxx.p12 -out private.key
1openssl pkcs12 -nocerts -in 123xxxxxxx.p12 -out private.key

Där 123xxxxxxx.p12 är namnet på din nyss exporterade nyckel ur keychain. Du kommer att bli ombed att ange ditt lösenord ett par gånger.

Du har nu ännu en fil – private.key som innehåller din krypterade nyckel:

1-----BEGIN ENCRYPTED PRIVATE KEY-----
2MbyPnwyOhRF23b9AENfJokVFBbFBzZLWRQOwbfS1CwAKWI9DS2zcjN3lwwxcyU8O
3[...]
4KWI9DS2zcjN3FBzZLWRQOwbfS1CwAlwwxcyU8OMbyPnwyOhRF23b9AENfJokVFBb
5-----END ENCRYPTED PRIVATE KEY-----
1-----BEGIN ENCRYPTED PRIVATE KEY-----
2MbyPnwyOhRF23b9AENfJokVFBbFBzZLWRQOwbfS1CwAKWI9DS2zcjN3lwwxcyU8O
3[...]
4KWI9DS2zcjN3FBzZLWRQOwbfS1CwAlwwxcyU8OMbyPnwyOhRF23b9AENfJokVFBb
5-----END ENCRYPTED PRIVATE KEY-----

Steg 4 - Skapa en bundle

Det finns lite olika standarder för att hantera certifikat. Det enklaste och det som fungerar i de flesta systemen är vanliga .pem-certifikat med inkluderad nyckel. Det andra är en så kallad .p12-bundle.

Alternativ 1 – .pem och .key

Nu ska vi äntligen slå ihop nyckeln med certifikaten ifrån Swish. Det görs enklast med cat kommandot:

1cat private.key swish_certificate_202203011000.pem \
2> swish_123xxxxxxx.pem
1cat private.key swish_certificate_202203011000.pem \
2> swish_123xxxxxxx.pem

Där swish_123xxxxxxx.pem är vad du vill att din färdiga nyckel ska heta, swish_certificate_202203011000.pem är certifikaten ifrån Swish och private.key din nyss extraherade private nyckel.

swish_123xxxxxxx.pem är den enda filen du behöver ha kvar. Notera då att det är lösenordet för din privata nyckel (ifrån steg 3) som används för certifikatet.

Alternativ 2 - .p12

Även i detta alternativet ska vi slå ihop nyckeln med certifikaten från Swish, men på ett litet annat vis. Du blir även här tillfrågad om ett skapa ett lösenord, se till att spara det på en säker plats, du behöver den sedan när du ska använda din bundle;

1openssl pkcs12 -export -out swish_123xxxxxxx.p12 \
2-in swish_certificate_202203011000.pem -inkey private.key
1openssl pkcs12 -export -out swish_123xxxxxxx.p12 \
2-in swish_certificate_202203011000.pem -inkey private.key

Där swish_123xxxxxxx.p12 är vad du vill att din färdiga nyckel ska heta, swish_certificate_202203011000.pem är certifikaten ifrån Swish och private.key din nyss extraherade private nyckel.

Har du gjort rätt har du nu alltså en slutgiltig fil swish_123xxxxxxx.p12, som kombinerar din privata nyckel med certifikaten ifrån Swish. Det fina med detta tillvägagångssättet är att Root/CA (Certificate Authority)-certifikaten är inkluderade, du behöver alltså endast använda denna filen för distribution och i dina anrop emot Swish via exempelvis cURL.

Övriga filer (private.key, .p12-filen som exporterades ifrån Keychain samt .pem-filerna ifrån Swish) behövs inte längre och kan säkert raderas ifrån disk.

Steg 5 – Testa

Då det endast är certifikaten vi vill testa kan vi skicka skräpdata via cURL och se så att certifikatet kan parse:as korrekt. Då bör du få tillbaka en HTTP 422 i stil med:

1[
2    {
3        "errorCode":"PA01",
4        "errorMessage":"Parameter is not correct.",
5        "additionalInformation":null
6    }
7]
1[
2    {
3        "errorCode":"PA01",
4        "errorMessage":"Parameter is not correct.",
5        "additionalInformation":null
6    }
7]

Alltså att anropet gick fram, men 123 inte är ett giltigt betalnings-ID.

Om du har gjort något fel på vägen kommer du istället få ett cURL och/eller SSL-fel i stil med curl: (56) LibreSSL SSL_read: error:06FFF064, curl: (58) could not parse PKCS12 file, curl: (58) unable to set private key file eller liknande.

Kika på cURL-exemplena här nedanför och välj beroende på vilken typ av certifikat du använder (byt ut password och swish_123xxxxxxx till dina egna uppgifter):

.pem

1curl -s -S -i --cert ./swish_123xxxxxxx.pem:password --cert-type pem \
2--header "Content-Type:application/json" \
3https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/123
1curl -s -S -i --cert ./swish_123xxxxxxx.pem:password --cert-type pem \
2--header "Content-Type:application/json" \
3https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/123

.p12

1curl -s -S -i --cert ./swish_123xxxxxxx.p12:password --cert-type p12 \
2--header "Content-Type:application/json" \
3https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/123
1curl -s -S -i --cert ./swish_123xxxxxxx.p12:password --cert-type p12 \
2--header "Content-Type:application/json" \
3https://cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/123

Hoppas att denna lilla guiden har varit till nytta. Frågor eller kommentarer? @olssonm är jag på Twitter.

⋯