Teknisk handledning för Dator-Dator kommunikation

Transkript

1 Skatteverket IT Teknisk handledning för Dator-Dator kommunikation Dokumentversion: 2.0

2 Skatteverket IT Innehållsförteckning Innehållsförteckning 1 Inledning Syfte Målgrupp Introduktion Säkerhetsfunktioner Nyckelgenerering och certifikatbildning Autenticering och kryptering Fysisk uppkoppling Beskrivning av Dator-Dator miljön X.509 Certifikat Beställning av certifikat (automatisk uppkoppling) Dataformat Utformning av indata Paketering av datafiler i MIME-paket Klientprogramvara Parametrar till klientprogramvaran Exempel template Infil Felsituationer Fel hos Skatteverket HTTP-fel SSL-fel Fel hos Klient HTTP-fel SSL-fel...12 BILAGA Konfigurering av ISDN-förbindelse till Skatteverkets Elektroniska BrevLåda EBL.

3 1 Inledning 1.1 Syfte Dokumentet är en teknisk handledning för användare av NAVET:s tjänst Dator-Dator kommunikation. Här beskrivs uppkoppling mot och användning av denna tjänst. 1.2 Målgrupp Kommunikations- och applikationsansvariga hos de kunder till Skatteverket som skall använda Dator-Dator kommunikation för att ställa frågor mot folkbokföringsregistret. Tekniskhandledning 1

4 2 Introduktion Detta dokument beskriver uppkoppling mot och användning av tjänsten Dator-Dator kommunikation. Dator-Dator (DD) är en tjänst för automatiserat informationsutbyte mellan system hos Skatteverket och andra myndigheter eller företag. Det är upp till kunden att integrera tjänsten i sina applikationer. Skatteverket har tagit fram två exempelapplikationer, en C- och en Java-variant, som visar ett exempel på hur man skulle kunna lösa fråga/svar mot folkbokföringsregistret. Mer om detta senare i detta dokument. En förutsättning för användning av DD är att användaren har tecknat avtal med Skatteverket. Vid avtalstecknandet får kunden ett kundnummer. Detta används senare för att identifiera kunden i olika sammanhang. Principerna för säkerhetslösningen för DD beskrivs i kapitel 3. De förberedelser som krävs för att använda DD beskrivs i kapitel 4 och 5. Dessa rör bland annat: Fysisk uppkoppling mot Skatteverket. Beställning, hämtning och installation av X.509 certifikat Formatet på datat behandlas i kapitel 6. Exempelprogramvaran som Skatteverket IT tagit fram för DD-kommunikation behandlas i kapitel 7. En beskrivning av de olika felsituationerna och även troliga felorsaker beskrivs i kapitel 8. Tekniskhandledning 2

5 3 Säkerhetsfunktioner Vid kommunikation med Skatteverket krävs att: uppkoppling från kunden sker på ett sådant sätt att Skatteverket säkert kan identifiera avsändaren (autenticering) överföring av information mellan Skatteverket och kund sker krypterat eftersom viss information kan vara sekretessbelagd. Skatteverket har valt att implementera lösningar, baserade på standardiserade verktyg tillgängliga på den öppna marknaden. Med begreppet klient avses i den följande texten kundens dator. Den hemliga och den öppna nyckeln som beskrivs nedan lagras på datorns hårddisk, vilket medför att all kommunikation med Skatteverket måste ske från den dator där nycklarna finns. Dessutom krävs en PIN-kod, som bör memoreras eller på annat sätt förvaras med hög säkerhet. 3.1 Nyckelgenerering och certifikatbildning Varje klient skall förses med en hemlig och en öppen RSA-nyckel. Denna nyckelgenerering sker hos klienten själv med lämplig programvara. Det krävs att klientens identitet med full säkerhet kan kopplas ihop med den öppna nyckeln. Denna hopkoppling verifieras av en CA-funktion (Certification Authority) som med hjälp av sin hemliga RSA-nyckel bildar det certifikat (enligt X.509-standard) som i fortsättningen används för klientens säkra identifiering. Skatteverket agerar (tills en riksgemensam godkänd CA-funktion skapats) som CA och skapar de certifikat som säkerställer att man kan garantera identiteten hos de kommunicerande parterna. Skatteverket kommer också att förse klienterna med utställarens, d.v.s Skatteverkets öppna nyckel, vilket erfordras för att klienten skall kunna verifiera uppkopplingen till Skatteverkets server. Då avtal mellan Skatteverket och kund upprättats får kunden per brev en PIN kod. Denna används tillsammans med kundnummer som identifikation vid beställning av X.509 certifikat. Beställning av certifikat görs genom att först skapa en certifikatbegäran enligt PKCS#10 (ex. med programmet ssleay eller numera openssl) och sända in denna via mail till Skatteverkets certifikattjänst. Certifikatbegäran behandlas av Skatteverkets CA-funktion, och om lämnade uppgifter accepteras, skapas ett certifikat, vanligen inom en arbetsdag från det att begäran inkommit. Skatteverket skickar med mail efter någon dag tillbaka certifikatet till kunden. Det skall påpekas att certifikatet i sig inte är känslig information. Det är endast tilsammans med den privata RSAnyckeln det är användbart. 3.2 Autenticering och kryptering För att säkerställa autenticeringen skall protokollet SSL (Secure Sockets Layer) användas över TCP/IP-protokollet Vid överföringen krypteras informationen med en för sessionen tillfälligt skapad sessionsnyckel. Denna tillfälliga sessionsnyckel genereras från data skapat hos både klient och server och utbytet skyddas genom att det är krypterad med mottagarens öppna RSA-nyckel. Tjänsten DDkommunikation använder minst 128 bitar långa sessionsnycklar. För SSL gäller att autenticeringen kommer att utföras med RSA key exchange algorithm medan krypteringen använder den starkaste kryptering som är tillgänglig hos både klient och server. Tekniskhandledning 3

6 4 Fysisk uppkoppling Figuren nedan beskriver den fysiska kopplingen mellan Skatteverket och kund. Anslutning kan ske antingen via fast linje eller via ISDN. På sikt är intentionen att använda sig av Internet för kommunikationen mellan Skatteverket och kund. Skatteverket Kunder R Win/ Unix Navet INIT m fl R Firewall R ISDN Win/ Unix WEB X-Line R Win/ Unix Om anslutning via fast linje önskas skall kontakt först tas med Skatteverket. Se vidare bilaga konfigurering av ISDN-förbindelse till Skatteverkets elektroniska brevlåda. Kundens ISDN-router konfigureras med följande parametrar: IP-adress till Skatteverket-router: Nätmask: ISDN-nummer: CHAP password: kontakta Skatteverket Via Skatteverkets brandvägg kan tre webservrar nås. Den ena är öppen (kräver inget certifikat) och används för öppen information samt för beställning och utlämning av X.509 certifikat för konceptet Elektronisk Brevlåda, EBL. Det är på denna port program för att skapa certifikat för DD samt även exempelapplikationerna för DD finns för nedladdning. Den andra servern hanterar den elektroniska brevlådan och för att koppla sig mot denna krävs att man har ett certifikat. Den tredje servern hanterar Dator-Dator tjänsten och för att nå denna krävs ett certifikat. För anslutning mot DD-tjänsten används följande parametrar: IP-adress Portnummer öppen web 80 Portnummer DD (produktion) 8443 URL för DD: /servlets/ddservlet Tekniskhandledning 4

7 4.1 Beskrivning av Dator-Dator miljön Nedan visas DD-systemets uppbyggnad. NAVET Tuxedo- Server Folkbokförings - register Skatteverket Kundens maskin Applikation Dator - Dator Tuxedo- Server Dator - Dator Servlet Webb- Server DD-tjänst Tekniskhandledning 5

8 5 X.509 Certifikat För att kunna använda DD-tjänsten måste varje användare ha ett X.509 certifikat. Certifikatet används vid kommunikationen, dels för autenticering, dels för utbyte av sessionsnycklar för kryptering av data under överföringen mellan Skatteverket och kund. Certifikatet innehåller uppgifter om kunden (organisationsnummer, namn, mm), uppgifter om utställaren (Skatteverket) samt giltighetstid. Det innehåller dessutom kundens öppna RSA-nyckel. All denna information är skyddad av ett elektroniskt sigill vilket innebär att ingen del av certifikatet kan förändras utan att det upptäcks. Till kundens öppna nyckel hör också en hemlig nyckel. Denna skapas hos kunden och lämnar aldrig kundens system. 5.1 Beställning av certifikat (automatisk uppkoppling) Beroende på vilken programvara som används kan kunden behöva ett certifikat på ett annat format än det som används av webläsare. I den exempel-programvara Skatteverket tillhandahåller för automatisk uppkoppling mot brevlådan finns stöd för att skapa certifikatbegäran enligt PKCS#10 Mer information om specifika detaljer finns i programvarudokumentationen som finns att hämta från brevlådans öppna webserver. Tekniskhandledning 6

9 6 Dataformat 6.1 Utformning av indata Etiketter (metadata) som skickas in till DD ska vara formatterade enligt XML-format (extensible Markup Language). MIME-standarden som används för infilerna (frågorna) är text/xml. Exempel: <?xml version="1.0"?> <!DOCTYPE DD_REQUEST SYSTEM "DD_REQUEST.dtd"> <DD_REQUEST version="1.0"> <service name="na_grundpost"> <param name="kundnr"> </param> <param name="id_pers"> </param> <param name="best_id"> fo </param> </service> </DD_REQUEST> 6.2 Paketering av datafiler i MIME-paket Utdata från DD-tjänsten är ett MIME-paket av typen multipart/ mixed. MIME-paketet innehåller en etikettfil ( text/xml ) och en datafil (text/plain) Exempel: HTTP/ OK Date: Mon, 08 Nov :20:31 GMT Server: Apache/1.3.9 (Unix) ApacheJServ/1.0 mod_ssl/2.4.1 SSLeay/0.9.4 Content-Length: 968 Content-Type: multipart/mixed; boundary="bound bound" --BOUND BOUND Content-Type: text/xml Content-Disposition: attachment; filename="label.xml" <?xml version="1.0"?> <!DOCTYPE DD_RESPONSE SYSTEM "DD_RESPONSE.dtd"> <DD_RESPONSE version="1.0"> <status> 0 </status> <message> OK </message> </DD_RESPONSE> --BOUND BOUND Content-Type: text/plain Content-Disposition: attachment; filename="data.txt" #DATA_START Tekniskhandledning 7

10 #POST_START #UP #UP #UP Lars #UP Burman #UP #UP #UP #UP FLÄDERN 2 #UP FB #UP #POST_SLUT #DATA_SLUT --BOUND BOUND-- Tekniskhandledning 8

11 7 Klientprogramvara Skatteverket IT har tagit fram två exempelapplikationer (C, Java) som visar hur man skulle kunna lösa fråga/svar mot tjänsten DD-kommunikation. Dessa finns att hämta hem från den öppna webservern ( :80). Observera dock att detta inte är någon produkt som Skatteverket IT tar ansvar för, utan att de endast tagits fram för att visa hur man skulle kunna lösa kommunikationen. C-variant som bygger på fri programvara, openssl, som är ett SSL-paket för certifikathantering och kryptering/dekryptering. Java-variant som bygger på det kommersiella SSL-paketet isasilk. ( 7.1 Parametrar till klientprogramvaran Alla argument anges i form av par där en flagga följs av ett värde. Nedan visas de argument som kan användas till exempelprogramvaran. -Cafile Identifierar en PEM-formaterad fil som innehåller Skatteverkets CA certifikat. -cert Identifierar en PEM-formaterad fil som innehåller användarens certifikat. -key Identifierar en fil som innehåller användarens privata nyckel -template Identifierar en fil innehållande en mall för frågorna, med variabler för de värden som skiljer sig mellan frågorna. -host Identifierar den värd som man ska koppla upp sig mot. -port Identifierar den port på värden som man ska koppla upp sig emot. -log Identifierar en fil där applikationen ska skriva logginformation. -count Ett heltal som anger max antal omsändningsförsök mot värden. -in Identifierar en fil innehållande de värden som skiljer sig mellan frågorna. -out Identifierar en fil där applikationen skriver svaren på frågorna Exempel template Nedan visas hur mallen som används av klientapplikationen ser ut. Applikationen läser filen som är specifierad av in parametern och ersätter variablerna $ med värden från infilen. <?xml version="1.0"?> <!DOCTYPE DD_REQUEST SYSTEM "DD_REQUEST.dtd"> <DD_REQUEST version="1.0"> <service name="na_grundpost"> <param name="kundnr"> $1 </param> <param name="id_pers"> $2 </param> <param name="best_id"> $3 </param> </service> </DD_REQUEST> Tekniskhandledning 9

12 7.1.2 Infil Kommentarer (inleds med # ) och tomrader ignoreras av exempelapplikationerna. Applikationerna ersätter varaiblerna $ med värdena från infilen. Värdena i infilen måste därför vara i samma ordning som variablerna. Exempel på infil: #Kundnr hos Skatteverket Personnr för frågan BeställningsId hos NAVET # 8 siffror 12 siffror 18 valfria tecken FO FO Tekniskhandledning 10

13 8 Felsituationer Nedan beskrivs de kända felsituationer som kan uppkomma från DD-tjänsten eller från klientsidan. Generellt gäller att om ett HTTP-fel uppkommer så skriver exempelapplikationerna felmeddelandet till loggfilen och avslutar applikationen. 8.1 Fel hos Skatteverket HTTP-fel Här beskrivs de HTTP-fel som kan uppstå hos Skatteverket och även trolig felorsak: 403 Forbidden - Kunden är inte behörig att köra DD-tjänsten. 404 Not Found - DDServlet är nere hos Skatteverket. 500 Internal Server Error - Internt fel hos Skatteverket 503 Service Temporarily Unavailable - DD-tjänsten är nere hos Skatteverket SSL-fel Här beskrivs de SSL-fel som kan uppstå och även trolig felorsak. Detta gäller Java-klienten eftersom exempelklienten för C skriver alla SSL-fel (från SSL-paketet) direkt till loggfilen. Connection refused - Web servern är nere hos Skatteverket 8.2 Fel hos Klient HTTP-fel Här beskrivs de HTTP-fel som kan uppstå på klientsidan och även trolig felorsak: 400 Bad Request Meddelandets kropp innehåller en beskrivning av vad som orsakat fel. Troliga orsaker är: - Syntaxfel i anropsdata (XML) - Någon av indataparametrarna har felaktigt format - Fel vid läsning av anropsdata (Förmodligen tillfälligt, försök igen) 411 Length Required - Content-Length har inte angivits i datat 413 Request Entity Too Large - Längden på indata överstiger 1024 tecken 415 Unsupported Media Type - Content-type är inte text/xml Tekniskhandledning 11

14 8.2.2 SSL-fel Här beskrivs de SSL-fel som kan uppstå och även trolig felorsak. Detta gäller Java-klienten eftersom exempelklienten för C skriver alla SSL-fel (från SSL-paketet) direkt till loggfilen. Alert Fatal: bad certificate - Ogiltigt eller icke godkänt certifikat Alert Fatal: certificate expired - Certifikatet är utgånget. BILAGA Tekniskhandledning 12

15 Konfigurering av ISDN-förbindelse till Skatteverkets Elektroniska BrevLåda EBL. Skatteverkets miljö Server IP-adress Tillåtna TCP-sockets: 80, 443(prod), 444(test), 8443(Dator-Dator) Skatteverkets router host name: r30024 Linkprotocol: Multilink Authentication Protocol CHAP-password ISDN-nummer ISDN IP-adress Subnätsmask KLIENT miljö Fyll i klientuppgifter och returnera till Skatteverket IT Produktion Nätövervakningen Solna Fax: Mail: ebl@rsv.se PPP Enabled CHAP Fås av Skatteverket IT/P:s repr. (svarar på ping från klients router) (8 bitar) Klient (browser:s) IP-adress Router host name Eget ISDN-nummer "ISDN" IP adress (Fås av Skatteverket IT/P:s rep.) Subnätmask (8bitar) Organisation (För utskick av PIN-kod) Organisationsnummer Kontaktperson(Drift) (För utskick av PIN-kod) Kontaktperson(datakommunikation) Avdelning (För utskick av PIN-kod) Utdelningsadress (För utskick av PIN-kod) Postnummer (För utskick av PIN-kod) Postort (För utskick av PIN-kod) Telefon, Fax adress Kundnummer (Fås av Skatteverket IT/P:s rep. För NAVET-kunder har detta redan tilldelats) Tekniskhandledning 13