Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part 2013-11-17 BISP - Beskrivning till förlitande part Version: 3.1 Datum: 2013-11-17 Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part 2013-11-17 Innehållsförteckning 1 2 Introduktion .................................................................................................................................. 1 1.1 Revisionshistorik ................................................................................................................................1 1.2 Översikt...............................................................................................................................................1 1.3 Vart kan jag vända mig med frågor? ...............................................................................................1 1.4 Plattformsstöd ....................................................................................................................................1 Kontroller innan inloggning görs med BISP .............................................................................. 1 2.1 Installationsverifiering ......................................................................................................................2 2.1.1 2.1.2 2.1.3 2.2 3 Versionspluginen ........................................................................................................................................ 2 Exempel på installations- och versionskontroll .......................................................................................... 3 Hänvisning till install.bankid.com .............................................................................................................. 6 Automatisk versionskontroll .............................................................................................................6 Legitimering och underskrift ....................................................................................................... 6 3.1 Teknisk översikt .................................................................................................................................7 3.2 Aktivering ...........................................................................................................................................7 3.2.1 3.2.2 Legitimering ............................................................................................................................................... 7 Underskrift .................................................................................................................................................. 7 3.3 Parametrar .........................................................................................................................................7 3.4 Funktioner ..........................................................................................................................................9 3.4.1 3.4.2 3.4.3 3.4.4 3.4.5 SetParam ................................................................................................................................................... 10 GetParam .................................................................................................................................................. 10 PerformAction .......................................................................................................................................... 10 GetLastError ............................................................................................................................................. 10 Reset ......................................................................................................................................................... 10 3.5 Returkoder........................................................................................................................................10 3.6 Filtrering ...........................................................................................................................................11 3.6.1 3.6.2 3.6.3 3.6.4 Filtrering för att endast visa BankID ........................................................................................................ 11 Filtrering för att vid underskrift endast visa BankID för den person som loggade in ............................... 12 Kombinationer av filter ............................................................................................................................ 12 BankID för test och utveckling ................................................................................................................. 12 3.7 Validering med BankID Control Server (BICS) ...........................................................................12 3.8 Beskrivning av filunderskrift ..........................................................................................................12 3.9 Exempel på legitimering, underskrift och filunderskrift .............................................................13 3.9.1 3.9.2 3.9.3 3.10 Legitimering ............................................................................................................................................. 13 Underskrift ................................................................................................................................................ 15 Filunderskrift ............................................................................................................................................ 18 Vanliga misstag.............................................................................................................................23 4 Appendix 1: Rekommenderade feltexter för returkoder från BISP ......................................... 23 5 Appendix 2: Rekommenderade feltexter för returkoder från BICS ......................................... 24 6 Appendix 3: Windows 8 och BankID på fil eller BankID på kort............................................ 25 6.1 Varianter av Windows 8 ..................................................................................................................25 6.2 Windows 8 använder växelvis två ”vyer” eller användargränssnitt för olika tillfällen: ...........25 6.3 Konsekvenser....................................................................................................................................25 Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part 6.4 2013-11-17 Anpassning av webbsidor: Meta-tag ..............................................................................................26 Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part 1 Sida 1 2013-11-17 Introduktion 1.1 Revisionshistorik Version 1.8 Datum 2010-12-22 Kommentar Uppdaterad för version 4.17. Lagt till filunderskrift och ändringar i Token Removal samt rekommenderade feltexter för returkoder från BISP och BICS. 2.0 2010-05-09 Uppdaterad för version 4.18. 2.1 2012-05-24 Rättat ett skrivfel i exempelkod för filunderskrift. 2.2 2012-10-30 Anvisningar för Windows 8 tillagda i Appendix. 3.0 2013-10-20 Uppdaterat för BISP 5.0.1. Inaktuella avsnitt borttagna. Notera: Kodexemplen är oförändrade. 3.1 2013-11-17 Uppdaterat för BISP 5.0.2. Tillägg för å, ä och ö i parametern ”FileName” i avsnitt 3.3 för kompatibilitet. Avsnitt om detektering av webbläsare i Windows 8-läge med Javascript struket, eftersom det sättet att detektera inte längre fungerar i Chrome. 1.2 Översikt Den här informationen riktar sig till er som använder BankID på fil eller BankID på kort för inloggning och underskrift i era webbtjänster (vi kallar er nedan förlitande part). Mobilt BankID beskrivs i ett separat dokument. BankID säkerhetsprogram (BISP) används vid utgivning av BankID på fil och inloggning på webbplatser. Dokumentet är uppdaterat för BankID säkerhetsprogram version 5.0. I version 5.0 av BISP är de äldre pluginerna ”Websigner” och ”Logout” borttagna. De pluginerna har dock aldrig haft någon funktion vid användning av BankID. Dokumentet innehåller kodexempel, felkoder, instruktioner och tips, t.ex. förslag på flöde för att hantera BankID-användare innan en inloggning eller underskrift påbörjas. 1.3 Vart kan jag vända mig med frågor? För tekniska frågor ska ni i första hand vända er till er leverantör av BankID Control Server (BICS). I övriga frågor hänvisas till den bank som ni har avtal med om användandet av BankID. 1.4 Plattformsstöd För aktuell lista över vilka operativsystem och webbläsare som officiellt stöds för BankID-användning, se http://support.bankid.com/syskrav Gamla versioner av operativsystem och webbläsare stöds inte, eftersom inte leverantörerna längre ger ut säkerhetsuppdateringar till dem. Det innebär att de inte uppfyller de krav som finns för säker användning. Tester har utförts med aktuella versioner av webbläsare och OS enligt listan. 2 Kontroller innan inloggning görs med BISP Innan en användare kan logga in på förlitande parts webbplats ska några kontroller genomföras för att garantera att den BISP som används inte är för gammal. Vad förlitande part behöver göra är: 1. Kontrollera att användaren har BISP installerad (se kapitel 2.1 Installationsverifiering) 2. Kontrollera att parametern best_before finns med i versionssträngen från Versionspluginen (se kapitel 2.1.1) 3. Kontrollera att värdet på parametern best_before, som är en datum- och tidsangivelse uttryckt i UNIX DateTime format, ligger i framtiden När de här kontrollerna är klara kan användaren gå vidare till inloggningen. Finansiell ID-Teknik BID AB Sida 2 2013-11-17 BISP - Beskrivning till förlitande part 2.1 Installationsverifiering I normalfallet sköts kontrollen att BISP har rätt version automatiskt. Användaren får i god tid automatiskt reda på om en ny version av BISP finns, och får på BankIDs webbplats vägledning i hur en uppgradering ska göras. Trots detta måste man komplettera den automatiska versionskontrollen med ytterligare en kontroll vid inloggningen till en förlitande part. Den versionskontrollen görs med hjälp av den så kallade versionspluginen som beskrivs närmare i avsnitt 2.1.1. Följande bild visar ett förslag på ett flöde över hur installationsverifieringen ska genomföras före inloggning till webbtjänster där BankID används. Start Är BISP installerad? A Ja Finns parametern ”best_before” och är värdet på parametern OK? C Nej Nej Visa lämplig text och hänvisa till install.bankid.com/rp B Ja E D Visa lämplig text och hänvisa till install.bankid.com om parametern saknas, annars install.bankid.com/vk Anropa BISP för inloggning eller underskrift A: Genom att anropa den versionsplugin som installeras tillsammans med BISP kan man avgöra om säkerhetsprogrammet finns installerat. Exempel på hur detta kan göras finns i avsnitt 2.1.2.1. B: Om användaren behöver installera BISP ska hon hänvisas till webbplatsen install.bankid.com. Förslag på text som kan visas för användaren i samband med hänvisningen och information om vilken URL som ska användas finns i avsnitt 2.1.3. C: Även om BISP är installerat kan det behöva uppgraderas eller versionskontrolleras. Med hjälp av den versionssträng som returneras från anropet till versionspluginen kan man avgöra om allt är OK eller om användaren ska hänvisas till install.bankid.com för uppgradering eller versionskontroll. Exempel på hur man får ut versionssträngen från versionspluginen och sedan kan använda denna för att säkerställa att rätt version finns installerad hos användaren finns i avsnitt 2.1.2.2 och 2.1.2.3. D: Förslag på text som kan visas för användaren om hon behöver hänvisas till install.bankid.com för uppgradering eller versionskontroll, samt information om vilken URL som ska användas, finns i avsnitt 2.1.3. E: Om de tidigare beskrivna kontrollerna visar att en godkänd version av BISP finns installerad kan säkerhetsprogrammet anropas för att logga in användaren. Exempel på hur detta kan göras finns i avsnitt 3.7. 2.1.1 Versionspluginen 2.1.1.1 Beskrivning Versionspluginen kan kontrollera vilken version av BISP som finns installerad på användarens dator. Dessutom får man information om eventuella kortläsare anslutna till datorn, vilket operativsystem som används samt om BISP har versionskontrollerats. Pluginen finns tillgänglig dels som en ActiveX-kontroll (Internet Explorer), dels som en NPAPI-plugin (Mozilla-baserade webbläsare som Firefox och Safari). Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 3 2013-11-17 2.1.1.2 Aktivering För att aktivera pluginen i webbläsaren ska följande identifierare användas: CLSID: E5C324CC-4029-43CA-8D57-4A10480B9016 (Internet Explorer) ProgID: Nexus.VersionCtl (Internet Explorer) MIME-typ: application/x-personal-version (Mozilla-baserade webbläsare) 2.1.1.3 Funktioner Detta avsnitt beskriver de funktioner med vilka man kan anropa versionspluginen. 2.1.1.3.1 GetVersion GetVersion() returns String Denna funktion returnerar versionssträngen som en lång sträng där de ingående elementen är separerade med ett &. Nedan följer ett exempel på hur en versionssträng kan se ut: Personal=5.0.1.87&BankID_exe=5.0.1.87&BISP=5.0.1.87&platform=win64&os_version=win7&uhi=zc16w F1bUxeqNdf+iTEE6Edjzys=&best_before=1382110669&docSign=1&SmartCard_Reader=Alcor Micro USB Smart Card Reader 0& Följande element ingår i versionssträngen: BISP=<versionsnummer>: Version av BISP Personal=<versionsnummer> : Version av BISP för bakåtkompatibilitet <filnamn>_<filändelse>=<versionsnummer> : Version på enskilda komponenter. SmartCard_Reader=<reader name> : Informerar om tillgängliga kortläsare, ett entry för varje kortläsare. Platform={win32, win64, macosx, linux} : Användardatorns plattform. os_version : o Windows: { winxp, winvista, win7, win8, unknown } o Mac OS X: os_version=<majorversion>.<minorversion>, dvs 10.8, 10.9 etc. eller unknown. o Linux: os_version=<majorversion>.<minorversion> (version av Ubuntus distribution), dvs 11.10, 12.04 etc. eller unknown. distribution=ubuntu : Informerar om distribution av operativsystemet. Endast Linux. best_before=<värdet av bäst-före-datumet> : Tidpunkt i Unix Time-format då BISP senast måste göra en versionskontroll för att kontrollera att den installerade versionen av BISP fortfarande är giltig. docSign=1 : Om denna parameter finns med så innebär det att BISP har stöd för filsignaturer (se 3). uhi=<Base64 kodat värde> : Ett värde unikt för användarens dator. 2.1.1.4 Returkoder Inga returkoder finns definierade för denna plugin. 2.1.2 Exempel på installations- och versionskontroll Detta avsnitt beskriver hur man ska anropa versionspluginen för att ta reda på om BISP är installerad och om rätt version är installerad. Normalt ska en förlitande part gå igenom alla tre stegen nedan. 2.1.2.1 Är BISP installerad? För att kontrollera om BISP är installerad ska man försöka skapa en instans av versionspluginen. Om det går bra, är BISP installerad. 2.1.2.2 Är rätt version av BISP installerad? När man vet att BISP är installerad måste man också kontrollera att en tillräckligt ny version av BISP är installerad samt ev. att den stödjer filsignering om det är en fil man vill få signerad. Detta görs med hjälp av versionssträngen som fås via versionspluginen. Om versionssträngen innehåller parametern best_before så kan man gå vidare. För detaljerad information om formatet på versionssträngen, se avsnitt 2.1.1.3.1. Förlitande parter som vill använda filsignering bör även kontrollera att versionen stödjer filsignering. Se avsnitt 3.8. Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 4 2013-11-17 2.1.2.3 Är installationen versionskontrollerad? Parametern best_before i versionssträngen innehåller en tidsangivelse uttryckt i antal sekunder sedan klockan 00.00 den 1/1 1970 (UNIX DateTime format). Värdet uppdateras varje gång BISP genomfört en lyckad versionskontroll. I en godkänd version av BISP innehåller best_before en tidpunkt i framtiden. Om versionen inte är godkänd så innehåller parametern en gammal tidpunkt. Om användaren då inte uppgraderar sin programvara, kommer BISP inte gå att använda eftersom BankID Control Server (BICS) kontrollerar att transaktionen är skapad av en godkänd version av BISP. 2.1.2.4 Exempelkod för installations- och versionskontroll Här kommer ett exempel på kod för installations- och versionskontroll. Den är utformad för att fungera i både Internet Explorer och Mozilla-baserade webbläsare. <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "version"); objHldr.setAttribute("type", "application/xpersonal-version"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "version"); objHldr.setAttribute("classid", "CLSID:E5C324CC-4029-43CA-8D57-4A10480B9016"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } } // Kontrollerar om BISP är installerad samt vilken typ av // plugin/ActiveX som stöds function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.SignerV2Ctl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { //BankID säkerhetsprogram är inte installerat return false; } return false; } } //Kontrollera att klienten är uppdaterad function versionVerified(verStr) { var ct = new Date(); var currentUsrTime = Math.round(ct.getTime()/1000); Finansiell ID-Teknik BID AB Sida 5 2013-11-17 BISP - Beskrivning till förlitande part var index = verStr.search("best_before"); if (index < 0) { // Syntax error in the version // string, return false. return false; } var subStr = verStr.substring(index+12); index = subStr.search("&"); if (index < 0) { // Syntax error in the version // string, return false. return false; } var bfdStr = subStr.substring(0,index); // The bfdStr should now hold the value // we are looking for. // Compare it with current time. // If best_before is greater than // current time the control passes. return (bfdStr > currentUsrTime); } function startCheck(){ var typePlugin = isInstalled(); if (typePlugin != false) { // pluginerna bör laddas enl. funktionen initPlugin() // p.g.a. kompabilitet med t.ex. Chrome. // Det bör också ske efter att hela DOM-trädet är laddat // därav anropet via body onload. initPlugin(typePlugin); var retVal; var Plugin = document.getElementById('pluginId'); // Hämta versionssträngen retVal = Plugin.GetVersion(); // Kontrollera bestbeforedate if(versionVerified(retVal)) { alert("Klienten är installerad och Bäst föredatum är OK\n" + retVal) } else { alert("Klienten har fel version eller har inte versionskontrollerats. Gå till https://install.bankid.com/vk\n" + retVal); } } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") } } </script> <BODY onLoad="startCheck()"> Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 6 2013-11-17 <a href=./login_exempel.html>Vidare till Inloggningsexempel</a> </body> </html> 2.1.3 Hänvisning till install.bankid.com Den webbplats dit användaren hänvisas för att få hjälp att installera BISP är install.bankid.com. a. När användaren behöver installera eller uppgradera BISP ska URL:en https://install.bankid.com/rp användas. b. När användaren behöver versionskontrollera BISP ska URL:en https://install.bankid.com/vk användas. Vi föreslår att installationsplatsen öppnas i ett nytt fönster. Följande texter bör visas för användaren om: Användaren inte har BISP installerat ”Innan du kan använda ditt BankID behöver du installera BankID säkerhetsprogram. Det gör du i det nya fönster som öppnas när du klickar på länken …” URL:en https://install.bankid.com/rp öppnas. Användaren har en för gammal version av BISP ”Din version av BankID säkerhetsprogram behöver uppgraderas innan du kan logga in. Det gör du i det nya fönster som öppnas när du klickar på länken…” URL:en https://install.bankid.com/rp öppnas. Användaren behöver versionskontrollera sin installation av BISP ”BankID säkerhetsprogram i din dator behöver versionskontrolleras. Det gör i det nya fönster som öppnas när du klickar på länken…” URL:en https://install.bankid.com/vk öppnas. 2.2 Automatisk versionskontroll Detta avsnitt beskriver i korthet den funktion för automatisk versionskontroll som finns i aktuell version av BISP. För att användarna alltid ska ha en fungerande och godkänd version av BISP finns en funktion i programmet som innebär att det med jämna mellanrum automatiskt kontrollerar om installerad version fortfarande är godkänd för användning. Detta görs genom att en versionskontrollfråga ställs till versionskontrollservern (VKS) för BankID. Om användarens version är för gammal, kommer programmet i normalfallet att i bakgrunden hämta och validera en installationsfil för uppdatering. När filen är hämtad kommer användaren att meddelas att en uppdatering av BISP görs, varpå uppdateringen startas. Om hämtningen misslyckas upprepade gånger så kommer programmet att öppna en webbläsare mot https://install.bankid.com. Från denna webbplats kan användaren själv hämta och installera den senaste versionen. Om den installerade versionen är alltför gammal kommer till sist inte webbplatserna att godkänna användning av BankID med mindre än att användaren uppdaterar. BISP använder standardfunktioner i operativsystemet för att upprätta förbindelsen mot versionskontrollservern och servern där installationsfilen finns. Detta innebär att inställningar som gjorts i t.ex. Internet Explorer (på Windows) avseende anslutning mot Internet via proxy kommer att användas. I vissa fall fungerar inte den automatiska versionskontrollen som avsett. Det kan t ex bero på att nätverksinställningarna hos vissa användare inte tillåter BISP att kommunicera med versionskontrollservern. I dessa fall kommer BISP med jämna mellanrum att hänvisa användaren till install.bankid.com för att göra en webb-baserad versionskontroll. 3 Legitimering och underskrift BISP innehåller funktionalitet för legitimering och underskrift via två pluginer som aktiveras i webbläsaren. Dessa två pluginer är väldigt lika i både funktionalitet och anrop och beskrivs därför i ett och samma avsnitt. Pluginerna finns dels som ActiveX-kontroller (endast Internet Explorer), dels som Mozilla-pluginer, och laddas i webbläsaren via en html-sida. När pluginen aktiveras i webbsidan visas en dialog där användaren får välja BankID och därefter ange lösenord för att skapa den signatur som används i transaktionen för legitimering eller underskrift. Finansiell ID-Teknik BID AB Sida 7 2013-11-17 BISP - Beskrivning till förlitande part 3.1 Teknisk översikt Funktionerna för legitimering och underskrift är implementerade som två pluginer som laddas i webbläsaren. Pluginstödet i Internet Explorer utgörs av ActiveX medan stödet i Mozilla-baserade webbläsare utgörs av NPAPI pluginer. Vid en legitimering eller underskrift anropas respektive plugin med ett antal parametrar. Vissa parametrar styr funktionen av pluginen medan andra används för att bygga upp det data som ska signeras och skickas tillbaka till servern för validering. Vid legitimering eller underskrift anropar pluginen BISPs huvudprogram som i sin tur visar legitimerings/underskriftsdialogen för användaren. När användaren har valt BankID och angivit lösenord skapas den signatur som används vid legitimerings-/underskriftstransaktionen. När signaturen är genererad i huvudprogrammet skickas den över till pluginen för att sedan kunna skickas över till servern för validering. I aktuella versioner av BISP finns funktionaliteten filunderskrift av filtyperna text och pdf. Förutsättningarna är att förlitande part har en BICS som stödjer version 1.4 av signaturformatet för BankID och att användarens dator har programvara för att visa filtyperna. Filunderskrift aktiveras med hjälp av parametrar i anropet till pluginen för underskrift (se 3.3). Användaren kan normalt välja vilket BankID som ska användas. Via filtreringsfunktionen (se 3.6) kan förlitande part dock styra vilket/vilka BankID som ska vara valbara för användaren. De signaturer som skapas följer BankIDs XML-baserade signaturformat. För mer information om detta format, kontakta er leverantör av BICS. 3.2 Aktivering Den sida som aktiverar pluginen måste vara skyddad med SSL för att funktionerna för legitimering och underskrift ska fungera. Det betyder att pluginen ska aktiveras i en sida med en URL som börjar med https://. Om SSL inte används kommer en felkod, 8015, att returneras. För att pluginen ska aktiveras på ett korrekt sätt måste också vissa parametrar vara satta. För mer information om vilka parametrar som är obligatoriska hänvisas till avsnitt 3.3. 3.2.1 Legitimering För att aktivera pluginen i webbläsaren ska följande identifierare användas: CLSID: DD137900-E4D7-4b86-92CC-2E968F846047 (Internet Explorer) ProgID: Nexus.AuthenticationCtl (Internet Explorer) MIME-typ: application/x-personal-authentication (Mozilla-baserade webbläsare) 3.2.2 Underskrift För att aktivera pluginen i webbläsaren ska följande identifierare användas: CLSID: FB25B6FD-2119-4CEF-A915-A056184C565E (Internet Explorer) ProgID: Nexus.SignerV2Ctl (Internet Explorer) MIME-typ: application/x-personal-signer2 (Mozilla-baserade webbläsare) 3.3 Parametrar Vid anropet av pluginen definierar förlitande part ett antal parametrar som styr funktionaliteten av pluginen samt bygger upp det data som ska signeras. De flesta parametrar är frivilliga men det finns ett antal obligatoriska parametrar som alltid måste sättas. Dessa obligatoriska parametrar beskrivs först i listan nedan. Parameter TextToBeSigned Beskrivning Den text som användaren ser och ska skriva under. Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8 strängen är 100 kB. Kontrolltecknen TAB samt CR och LF kan användas för att indentera respektive radbryta den text som ska skriva under. Icke-utskrivbara tecken accepteras inte. Av BankID föreskrivet värde Ska sättas i pluginen för underskrift. Challenge Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8-strängen är 4 kB. Ska sättas i legitimeringspluginen. Finansiell ID-Teknik BID AB Sida 8 2013-11-17 BISP - Beskrivning till förlitande part Nonce Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8-strängen är 4 kB. Ska sättas i pluginen för underskrift. Issuers En filterparameter som används för att reducera antalet valbara certifikat till dem som är utgivna av en viss certifikatutgivare. Filtersträngen byggs upp av ett eller flera certifikatattribut. Attributen ska vara separerade med "," eller ";", där "," tolkas som logiskt AND och ";" tolkas som logiskt OR. Följande X.500 attribut finns tillgängliga: "cn", "g", "s", "t", "ou", "o", "email", "i", "sn", "street", "l", "st", "c", "d", and "dc". Dessutom kan OID:s användas. Reguljära uttryck som använder sig av jokertecken såsom ’*’ och ’?’ kan också användas. ’*’ matchar godtyckligt antal tecken. ’?’ matchar exakt ett tecken (endast ett ’?’ kan användas). För att matcha en sträng som innehåller en asterisk, bakstreck eller frågetecken måste tecknet föregås av ’\’. Så för att matcha en asterisk skriv ’\*’. Frivillig. Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8-strängen är 4 kB. Subjects En filterparameter som används för att reducera antalet valbara certifikat till dem som är utgivna till en viss person (filtreringen görs på Subjectfältet i certifikatet). Se Issuers för formatet på parametern. Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8-strängen är 4 kB. Frivillig. Policys En filterparameter som används för att endast göra certifikat av en viss typ valbara. De typer man kan filtrera på är typiskt BankID på kort och BankID på fil. Se Issuers för formatet på parametern. Notera att logiskt OR, dvs ”,”, ej är applicerbart för den här parametern. Teckenkodning ska vara UTF-8, innehållet ska base64-kodas och maxlängd på UTF-8-strängen är 4 kB. För att inga andra certifikat ska visas sätts denna parameter att filtrera ut enbart BankID på fil och BankID på kort, se avsnitt 3.6.1 Signature Innehåller den signatur som skapades i anropet till funktionen PerformAction. Denna parameter kan endast användas i funktionen GetParam. Den returnerade signaturen är Base64-kodad. SupportedFileTypes Innehåller information om vilka filtyper som BISP stödjer för filsignatur. Varje returnerad filtyp innehåller en flagga som indikerar om användaren har ett program installerat som kan användas för att förhandsgranska dokumentet innan det signeras. Denna parameter kan endast användas med funktionen GetParam. Endast pluginen för underskrift och när filunderskrift ska användas. Endast vid ”GetParam”. Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 9 2013-11-17 Exempel 1: 'txt=1&pdf=0&' Exemplet ovan motsvarar svaret från en version av BISP som stödjer både .txt och .pdf, men det finns inget program installerat för att visa filer av typen .pdf. Exempel 2: 'txt=1&' Exemplet ovan motsvarar svaret från en version av BISP som endast stödjer .txt och har program installerat för att visa filer av denna typ. FileContent Fildata Base64 kodat. Kan vara max. 10MB data. Om man överskrider detta kommer en felkod returneras. Endast pluginen för underskrift och när filunderskrift ska användas. Endast i kombination med parametern ”FileName”. Endast vid ”SetParam” FileName Filnamn inklusive filändelse. Skall vara UTF-8 och max. 255 tecken innan Base64 kodning. Endast utskrivbara ASCII-tecken (32-127 samt å, ä, ö, Å, Ä, Ö) och förutom de tecken som inte är tillåtna i filnamn: '”' (34 citat) '%' (37) '*' (42 asterisk) ',' (44 komma) '/' (47) ':' (58) '<' (60) '>' (62) '?' (63) '\' (92) '|' (124) 'DEL' (127 delete) Endast pluginen för underskrift och när filunderskrift ska användas. Endast i kombination med parametern ”FileContent” OnlyAcceptMRU Om den här är satt visas endast senast använt BankID i signeringsdialogen. Endast pluginen för underskrift. Frivillig NonVisibleData Information som kommer med i signaturen, men som användaren inte har möjlighet att se. Används för att i signaturen kunna lägga med information som avses hanteras maskinellt, men som inte kan anses ha någon juridisk funktion (eftersom användaren inte kunnat se denna information i samband med underskriften). Detta data ska vara Base64-kodat och får vara max 5Mb efter Base64-kodning. Frivillig parameter. Endast pluginen för underskrift accepterar denna parameter. 3.4 Funktioner Pluginen tillhandahåller ett antal scriptbara funktioner. Dessa används för att sätta och hämta parametrar, styra funktionaliteten för hanteringen av frånkoppling av BankID samt för att skapa själva signaturen. Följande funktioner finns tillgängliga: SetParam GetParam Finansiell ID-Teknik BID AB Sida 10 2013-11-17 BISP - Beskrivning till förlitande part PerformAction GetLastError Reset 3.4.1 SetParam SetParam(String ParamType, String ParamValue) returns Integer ErrorCode Sätter värdet på en given parameter. Vid fel returneras en felkod som ger mer information om vilket fel som inträffat. 3.4.2 GetParam GetParam(String ParamType) returns String ParamValue Returnerar värdet på en parameter. Om en tom sträng returneras har ett fel inträffat. Felkoden hämtas med ett anrop till funktionen GetLastError. 3.4.3 PerformAction PerformAction(String Action) returns Integer ErrorCode Utför en aktivitet i pluginen. För att kunna anropa den här funktionen måste man ladda pluginen i en sida skyddad med SSL. Vid fel returneras en felkod som ger mer information om vilket fel som inträffat. Följande aktiviteter finns tillgängliga: Aktivitet Legitimering Authenticate Underskrift Sign Beskrivning Genererar signaturen för legitimeringen. I detta anrop öppnas en legitimeringsdialog där användaren får välja BankID och sedan ange dess lösenord för att generera signaturen. Genererar signaturen för underskriften. I detta anrop öppnas en underskriftsdialog där användaren får välja BankID och sedan ange dess lösenord för att generera signaturen. 3.4.4 GetLastError GetLastError() returns Integer ErrorCode Om ett fel har inträffat ska denna funktion anropas för att få en felkod som beskriver felet. Det kan vara användbart t ex då man har anropat GetParam men får en tom sträng tillbaka. En beskrivning av de felkoder som kan returneras finns i avsnitt 3.5. 3.4.5 Reset Reset() returns Integer ErrorCode Då denna funktion anropas sätts alla parametrar i pluginen till dess standardvärden. Vid fel returneras en felkod som ger mer information om vilket fel som inträffat. 3.5 Returkoder Returkoderna nedan finns definierade. Se avsnitt 4 för rekommenderade feltexter att visa för användaren. Returkod 0 Beskrivning OK 8001 Ett generellt fel har inträffat. 8002 Användaren avbröt. 8003 Minnesfel, dvs programmet har inte lyckats allokera det minne det behöver för att kunna exekvera. 8004 Ogiltig parameter, dvs funktionen SetParam eller GetParam har anropats med ett ogiltigt parameternamn. 8005 Internt fel i BISP: programmet misslyckades med en intern avkodning av data. Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 11 2013-11-17 8006 Internt fel i BISP: programmet misslyckades med en intern kodning av data. 8007 Konvertering av en parameter till/från Unicode misslyckades. 8008 Ogiltig aktivitet har angivits i funktionen PerformAction. 8009 Inget BankID finns tillgängligt. I vissa fall returneras detta om man använder filtreringsfunktionen och ingen elegitimation som finns tillgänglig uppfyller filterinställningarna. 8010 Pluginen misslyckades med att bestämma sidans URL. 8011 Anropande server är inte betrodd att exekvera pluginen. För att få exekvera pluginen måste servern finnas med i listan över betrodda servrar som installeras med programmet. Endast Webadmin. 8012 Värdet av den angivna parametern måste vara Boolean. 8013 Felaktig PIN-kod/lösenord. 8014 Värdet av den angivna parametern måste vara numeriskt. 8015 Pluginen kräver att sidan den laddas ifrån är skyddad med SSL, dvs att sidans URL börjar med https://. 8016 Alla obligatoriska parametrar är inte satta. Det måste de vara för att PerformAction ska kunna anropas. 8017 Parametern måste vara Base64-kodad. 8018 Ogiltigt parametervärde, dvs funktionen SetParam har anropats med ett felaktigt värde på en given parameter. 8019 Pluginen får inte anropas med en IP-adress. 8020 Funktionen inte tillåten 8022 Webbläsarpluginen kan inte kommunicera med BISPs huvudprogram. Detta kan hända om Internet Explorer körs som administratör och BISP körs som vanlig användare (eller tvärtom) i Windows Vista och senare. 8102 PIN-koden är blockerad. Användaren har angett en felaktig PIN-kod för många gånger och PIN-koden är nu blockerad. PIN-koden kan låsas upp med hjälp av en PUK-kod. 8551 Endast underskrift Filtypen som skickas med stöds inte för underskrift. 8552 Datorn har inget program för att visa filtypen som skickas med 3.6 Filtrering I funktionerna för legitimering och underskrift kan man styra vilka BankID som användaren ska kunna välja mellan. Detta görs med hjälp av de filtreringsparametrar som finns definierade för pluginen. För att förlitande parter ska ha möjlighet att filtrera ut både BankID och Nordea e-legitimation på ett ställe krävs en genomtänkt kombination av filter, i synnerhet om man vill filtrera ut endast e-legitimation på kort: BankID använder policy för att skilja på BankID på kort och BankID på fil. Nordea använder olika cn för att skilja ut e-legitimation på fil och e-legitimation på kort åt. Se avsnitt 3.6.3. 3.6.1 Filtrering för att endast visa BankID Genom att filtrera på följande sätt kommer endast BankID att presenteras för användaren, även om användaren också skulle ha andra typer av e-legitimationer. Filtret aktiveras genom att i värdet för parametern Policys inkludera både den policy som används för BankID på fil (1.2.752.78.1.1) och den som används för BankID på kort (1.2.752.78.1.2) separerade med ett semikolon (1.2.752.78.1.1;1.2.752.78.1.2). Notera att värdet ska base64-kodas. Exemplet nedan filtrerar bort alla e-legitimationer utom de som följer policy 1.2.752.78.1.1 eller 1.2.752.78.1.2 (policy för BankID på fil och BankID på kort): plugin.SetParam('Policys', 'MS4yLjc1Mi43OC4xLjE7MS4yLjc1Mi43OC4xLjI='); Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 12 2013-11-17 3.6.2 Filtrering för att vid underskrift endast visa BankID för den person som loggade in Det rekommenderade sättet att endast visa BankID som användes för inloggning är att sätta parametern ”OnlyAcceptMRU”, som alltid har företräde vid underskrift. Alternativa lösningar som även fungerar, är att filtrera på Subject i certifikatet, så filtrerar BISP bort BankID för andra personer. I detta exempel används fältet som innehåller personnummer för denna filtrering, men man kan även använda exempelvis Common Name. Anta att en person med personnummer 188803099368 har loggat in. För att endast BankID för denna person ska presenteras i dialogen för underskrift sätts parametern Subjects till värdet ”2.5.4.5=188803099368” (2.5.4.5 är objektidentifieraren för Serial Number dvs. användarens personnummer). Notera att innehåll ska base64-kodas. För att dessutom filtrera bort eventuella andra e-legitimationer för denna person så bör filtreringen ovan kombineras med filtret för BankID enligt avsnitt 3.6.1. Exempel: // Filtrerar bort alla e-legitimationer utom de som tillhör användaren med serienummer (personnummer) 188803099368 plugin.SetParam('Subjects', 'Mi41LjQuNT0xODg4MDMwOTkzNjg='); // Filtrerar bort alla e-legitimationer utom de som följer policy 1.2.752.78.1.1 eller 1.2.752.78.1.2 (policy för BankID på fil och BankID på kort) plugin.SetParam('Policys', 'MS4yLjc1Mi43OC4xLjE7MS4yLjc1Mi43OC4xLjI='); 3.6.3 Kombinationer av filter Parametern "OnlyAcceptMRU" har företräde (gäller endast vid underskrift). Om ”Issuers” och ”Subjects” används, så gäller logiskt OCH mellan de två filtreringarna Om ”Issuers” och ”Policys” används, så gäller logiskt ELLER mellan de två filtreringarna Om ”Subjects” och ”Policys” används, så gäller logiskt OCH mellan de två filtreringarna Om alla tre parametrarna används, så gäller först logiskt OCH mellan ”Issuers” och ”Subjects”, och därefter gäller logiskt ELLER mot filtreringen på ”Policys” 3.6.3.1 Förlitande part filtrerar ut både BankID på kort och Nordea e-leg på kort I detta anrop sätter förlitande part parametern ”Issuers” till strängen ”cn=Nordea CA for Smartcard users 08” och parametern ”Policys” till ” 1.2.752.78.1.2” (BankID på kort). Förhållandet mellan de båda parametrarna ”Issuers” och ”Policys” är logiskt ELLER. 3.6.3.2 Förlitande part filtrerar ut både BankID och Nordea e-leg I detta anrop sätter förlitande part parametern ”Issuers” till strängen ”cn=Nordea CA for Smartcard users 08; cn=Nordea CA for users 03” samt parametern ”Policys” till ”1.2.752.78.1.1;1.2.752.78.1.2” (BankID på fil eller BankID på kort). 3.6.4 BankID för test och utveckling Då man utvecklar och testar applikationer som använder BankID för legitimering och underskrift tillhandahålls speciella BankID avsedda för test. De har andra Policy-värden än skarpa BankID: BankID på fil för test har policy 1.2.3.4.5. BankID på kort för test har policy 1.2.3.4.10. 3.7 Validering med BankID Control Server (BICS) Den resulterande transaktionen som BISP postar in till servern ska vidareförmedlas till BICS för validering. BICS returnerar bland annat status av valideringen samt personuppgifter för aktuell användare i de fall valideringen lyckades. 3.8 Beskrivning av filunderskrift Förutsättningar: Förlitande part har implementerat ett flöde för filunderskrift, inklusive en BICS som stödjer version 1.4 av signaturformatet för BankID. Kontakta er leverantör av BICS för mer information. Filsignering görs i följande steg 1. Kontrollera att BISP kan hantera filsignering Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 13 2013-11-17 Kontrollera om BISP har stöd för filsignering genom att leta efter parametern docSign i versionssträngen. Från och med ver. 4.17 finns parametern docSign=1 med i versionssträngen. Den visar att BISP kan hantera filsignering. 2. Kontrollera vilka filtyper som kan användas Om BISP, enligt kontrollen i avsnitt 1, kan signera filer behöver man kontrollera vilka filtyper som användarens dator kan hantera (vilka filtyper som är associerade med program). I aktuell version av BISP kan två typer av filer undertecknas: pdf-filer och textfiler med filändelserna ”pdf” respektive ”txt”. Kontrollen görs med ett anrop till BISP: SignerV2.GetParam(”SupportedFileTypes”) Svaret från BISP är en textsträng med formatet (extName=[1|0]&)+ som till exempel kan se ut så här: pdf=0&txt=1& om det finns ett program associerat med textfiler men användaren inte har något program associerat med pdf-filer. 3. Initiera filunderskrift Nu kan servern göra anropet till SignerV2 med bl.a. de två nya parametrarna för filsignering: FileName och FileContent (se 3.3). Notera: Den underskrivna filen skickas inte tillbaka till servern. Servern ska spara hela anropet till BISP och efter underskriften använda det vid verifiering i BICSen. I parametern TextToBeSigned ska finnas en sammanfattning eller beskrivning av innehållet i filen som användaren ska skriva under samt ett referensnummer och datum. 4. När användaren har skrivit under BISP returnerar en signatur. Om det är en filsignering som har gjorts så ingår ett nytt element under SignedInfo: ett Reference-element som refererar till den underskrivna filen. Elementet börjar alltid med file:/// till exempel: <Reference URI="file:///QXZ0YWxfNDU2NzgxMjM0NS5wZGY"> Servern ska då skicka signaturen till BICSen för validering, inklusive filen som signerades. 5. Kvitto till användaren Efter en godkänd filsignering bör användaren få ett kvitto på webbplatsen, med bl.a. referensnummer och datum. 3.9 Exempel på legitimering, underskrift och filunderskrift 3.9.1 Legitimering Nedanstående exempel visar hur man kontrollerar att BISP är installerad och hur inloggningsfunktionen i BISP aktiveras i Internet Explorer och Mozilla-baserade webbläsare. <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "auth"); objHldr.setAttribute("type", "application/xpersonal-authentication"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "auth"); objHldr.setAttribute("classid", "CLSID:DD137900E4D7-4b86-92CC-2E968F846047"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); Finansiell ID-Teknik BID AB Sida 14 2013-11-17 BISP - Beskrivning till förlitande part } } //Kontrollerar om BISP är installerad function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.AuthenticationCtl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { // BankID säkerhetsprogram är // inte installerat return false; } return false; } } function Checkerror(paramName, errorMsg) { if (errorMsg) { if ( errorMsg == 8002 ) { // Om användaren avbryter bör han få ett nytt // försök och inte hamna i normal felhantering. alert ("Du valde att avbryta."); return false } else if (errorMsg == 8015) { // Sidan måste köras över SSL alert ("Pluginen kräver att sidan den laddas ifrån är skyddad med SSL, dvs att sidans URL börjar med https://."); } else { // Lägg din kod för felhantering här... Se stycke // 3.5 i dokumentet "BISP - Beskrivning till // förlitande part" alert("Tekniskt fel: " + errorMsg + " vid " + paramName); return false } } else { return true } } function startLogin(){ var typePlugin = isInstalled(); if (typePlugin != false) { // // // // pluginerna bör laddas enl. funktionen initPlugin() p.g.a. kompabilitet med t.ex. Chrome. Det bör också ske efter att hela DOM-trädet är laddat, därav anropet via body onload. initPlugin(typePlugin); Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 15 2013-11-17 var retVal; var Plugin = document.getElementById('pluginId'); var signature = "Not Present"; // // // // Sätt parametrarna till klienten och kolla om det gick bra. SetParam returnerar felkoden direkt så ni behöver inte gå omvägen via GetLastError t.ex.: Checkerror("Challenge",Plugin.SetParam('Challenge','MTIzNDU2Nzg5MGFiYw==')); alert("OBS!! Challenge ska genereras av er BICS och vara Base64 kodad! \n Se stycke 3.5 i dokumentet BISP - Beskrivning till förlitande part"); //OBS!! Ni får ej använda detta värde!! Plugin.SetParam('Challenge','MTIzNDU2Nzg5MGFiYw=='); Checkerror("Challenge",Plugin.GetLastError()); // Nedan filtrerar bort alla e-legitimationer utom de som följer policy // 1.2.752.78.1.1 eller 1.2.752.78.1.2 (policy för BankID på fil och // BankID på kort) // Plugin.SetParam('Policys', 'MS4yLjc1Mi43OC4xLjE7MS4yLjc1Mi43OC4xLjI='); // Checkerror("Policy filter", Plugin.GetLastError()); // Filter för test certifikat på kort och fil nedan Plugin.SetParam('Policys', 'MS4yLjMuNC41OzEuMi4zLjQuMTA='); Checkerror("Policy filter", Plugin.GetLastError()); // Starta legitimeringen retVal = Plugin.PerformAction('Authenticate'); if (!retVal) { signature = Plugin.GetParam('Signature'); if (Checkerror("hämtning av signatur", Plugin.GetLastError())){ // Lägg in din kod för att skicka transaktionen // till din BICS här. alert('Signatur skapad OK\n'); } } else { Checkerror("performAction", Plugin.GetLastError()); } } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") } } </script> <BODY onLoad="startLogin()"> <a href=./sign_exempel.html>Vidare till Signeringsexempel</a> </body> </html> 3.9.2 Underskrift Nedanstående exempel visar hur man kontrollerar att BISP är installerad och hur underskriftsfunktionen i BISP aktiveras för Internet Explorer och Mozilla-baserade webbläsare. <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); Finansiell ID-Teknik BID AB Sida 16 2013-11-17 BISP - Beskrivning till förlitande part objHldr.setAttribute("type", "application/xpersonal-signer2"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); objHldr.setAttribute("classid", "CLSID:FB25B6FD2119-4CEF-A915-A056184C565E"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } } // Kontrollerar om BISP är installerad genom att försöka så undviker man // beroende till webbläsarnamn o.s.v. function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.SignerV2Ctl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { // BankID säkerhetsprogram är // inte installerat return false; } return false; } } function Checkerror(paramName, errorMsg) { if (errorMsg) { if ( errorMsg == 8002 ) { // Om användaren avbryter bör han få ett nytt // försök och inte hamna i normal felhantering. alert ("Du valde att avbryta."); return false } else if (errorMsg == 8015) { // Sidan måste köras över SSL alert ("Pluginen kräver att sidan den laddas ifrån är skyddad med SSL, dvs att sidans URL börjar med https://."); } else { // Lägg din kod för felhantering här. Se avsnitt 3.5 // i dokumentet "BISP - Beskrivning till // förlitande part" alert("Tekniskt fel: " + errorMsg + " vid " + paramName); return false } } else { return true } Finansiell ID-Teknik BID AB Sida 17 2013-11-17 BISP - Beskrivning till förlitande part } function startSign(){ var typePlugin = isInstalled(); if (typePlugin != false) { // // // // pluginerna bör laddas enl. funktionen initPlugin() p.g.a. kompabilitet med t.ex. Chrome. Det bör också ske efter att hela DOM-trädet är laddat, därav anropet via body onload. initPlugin(typePlugin); var retVal; var Plugin = document.getElementById('pluginId'); var signature = "Not Present"; // Sätt parametrarna till klienten och kolla om det gick bra. // SetParam returnerar felkoden direkt så ni behöver inte gå // omvägen via GetLastError t.ex.: // Checkerror("Nonce",Plugin.SetParam('Nonce','MTIzNDU2Nzg5MGFiYw==')); // true betyder att signeringscertifikatet som är kopplat till // det certifikat användaren loggat in med används. Plugin.SetParam('OnlyAcceptMRU','true'); Checkerror("MRU", Plugin.GetLastError()); alert("OBS!! NONCE ska genereras av er BICS och vara Base64 kodad! \n Se stycke 3.5 i dokumentet BISP - Beskrivning till förlitande part"); //OBS!! Ni får ej använda detta värde!! Plugin.SetParam('Nonce','MTIzNDU2Nzg5MGFiYw=='); Checkerror("Nonce", Plugin.GetLastError()); // Texten som visas för användaren. "Vänligen överför 1000 // kronor till konto 123456-7" Plugin.SetParam('TextToBeSigned','VsOkbmxpZ2VuIMO2dmVyZsO2ciAxMDAwIGtyb25vci B0aWxsIGtvbnRvIDEyMzQ1Ni03'); Checkerror("TBS", Plugin.GetLastError()); // Text som signeras men inte visas för användaren t.ex. XML-data. // <xml><test>test</test></xml> Plugin.SetParam('NonVisibleData','PHhtbD48dGVzdD50ZXN0PC90ZXN0PjwveG1sPg==') ; Checkerror("NVD", Plugin.GetLastError()); // Starta signeringen retVal = Plugin.PerformAction('Sign'); if (!retVal) { signature = Plugin.GetParam('Signature'); if (Checkerror("hämtning av signatur", Plugin.GetLastError())) { // Lägg in din kod för att skicka // transaktionen till din BICS här. alert('Signatur skapad OK\n'); } } else { Checkerror("performAction", Plugin.GetLastError()); } } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 18 2013-11-17 } } </script> <BODY onLoad="startSign()"> Signering </body> </html> 3.9.3 Filunderskrift Nedanstående exempel visar hur man kontrollerar att BISP klarar filunderskrift: <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "version"); objHldr.setAttribute("type", "application/x-personal-version"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "version"); objHldr.setAttribute("classid","CLSID:E5C324CC-4029-43CA-8D57-4A10480B9016"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } } // Kontrollerar om BISP är installerad samt vilken typ av // plugin/ActiveX som stöds function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.SignerV2Ctl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { //BankID säkerhetsprogram är inte installerat return false; } return false; } } //Kontrollera att klienten är uppdaterad function versionVerified(verStr) { var index = verStr.search("docSign=1"); if (index < 0) { // Version doesn't support docSigning, return false. return false; } return true; } function startCheck(){ var typePlugin = isInstalled(); if (typePlugin != false) { // pluginerna bör laddas enl. funktionen initPlugin() // p.g.a. kompabilitet med t.ex. Chrome. Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 19 2013-11-17 // Det bör också ske efter att hela DOM-trädet är laddat // därav anropet via body onload. initPlugin(typePlugin); var retVal; var Plugin = document.getElementById('pluginId'); // Hämta versionssträngen retVal = Plugin.GetVersion(); // Kontrollera funktionen för filsignering if(versionVerified(retVal)) { alert("Klienten är installerad och filsignering är OK\n" + retVal); } else { alert("Klienten har fel version. Gå till https://install.bankid.com/rp\n" + retVal); } } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") } } </script> </head> <body onLoad="startCheck()"> <a href=./filecheck.aspx>Vidare till filtypskontroll</a> </body> </html> Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 20 2013-11-17 Nedanstående exempel visar hur man kontrollerar vilka filtyper BISP kan hantera för filunderskrift: <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); objHldr.setAttribute("type", "application/x-personal-signer2"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); objHldr.setAttribute("classid", "CLSID:FB25B6FD-2119-4CEF-A915-A056184C565E"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } } // Kontrollerar om BISP är installerad genom att försöka så undviker man // beroende till webbläsarnamn o.s.v. function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.SignerV2Ctl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { // BankID säkerhetsprogram är // inte installerat return false; } return false; } } function Checkerror(paramName, errorMsg) { if (errorMsg) { if ( errorMsg == 8002 ) { // Om användaren avbryter bör han få ett nytt // försök och inte hamna i normal felhantering. alert ("Du valde att avbryta."); return false } else if (errorMsg == 8015) { // Sidan måste köras över SSL alert ("Pluginen kräver att sidan den laddas ifrån är skyddad med SSL, dvs att sidans URL börjar med https://."); } else { // Lägg din kod för felhantering här. Se avsnitt 3.5 // i dokumentet "BISP - Beskrivning till // förlitande part" alert("Tekniskt fel: " + errorMsg + " vid " + paramName); return false } } else { return true } } function startFilecheck(){ var typePlugin = isInstalled(); if (typePlugin != false) { // pluginerna bör laddas enl. funktionen initPlugin() Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 21 2013-11-17 // p.g.a. kompabilitet med t.ex. Chrome. // Det bör också ske efter att hela DOM-trädet är laddat, // därav anropet via body onload. initPlugin(typePlugin); var retVal; var Plugin = document.getElementById('pluginId'); var supportedTypes = Plugin.GetParam('SupportedFileTypes'); if (supportedTypes.search("txt=1") > -1) alert("textfiler kan signeras"); if (supportedTypes.search("pdf=1") > -1) alert("Acrobat pdf-filer kan signeras"); } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") } } </script> </head> <body onLoad="startFilecheck()"> <a href=./filesigning.aspx>Vidare till filsignering</a> </body> </html> Nedanstående exempel visar hur man aktiverar en underskrift av en textfil i BISP: <html> <head> <script language="JavaScript"> // Hantera olika browsers. function initPlugin(typePlug){ if( typePlug == "Plugin" ) { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); objHldr.setAttribute("type", "application/x-personal-signer2"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } else { var objHldr = document.createElement("object"); objHldr.setAttribute("id", "pluginId"); objHldr.setAttribute("name", "signer2"); objHldr.setAttribute("classid", "CLSID:FB25B6FD-2119-4CEF-A915-A056184C565E"); objHldr.setAttribute("width", "0"); objHldr.setAttribute("height", "0"); document.body.appendChild(objHldr); } } // Kontrollerar om BISP är installerad genom att försöka så undviker man // beroende till webbläsarnamn o.s.v. function isInstalled (){ try{ var myObj = new ActiveXObject("Nexus.SignerV2Ctl"); if (myObj){ return "ActiveX"; } } catch(e){ if (navigator.plugins['Nexus Personal']){ return "Plugin"; } else { // BankID säkerhetsprogram är // inte installerat return false; } return false; } } function Checkerror(paramName, errorMsg) { if (errorMsg) { if ( errorMsg == 8002 ) { // Om användaren avbryter bör han få ett nytt Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 22 2013-11-17 // försök och inte hamna i normal felhantering. alert ("Du valde att avbryta."); return false } else if (errorMsg == 8015) { // Sidan måste köras över SSL alert ("Pluginen kräver att sidan den laddas ifrån är skyddad med SSL, dvs att sidans URL börjar med https://."); } else { // Lägg din kod för felhantering här. Se avsnitt 3.5 // i dokumentet "BISP - Beskrivning till // förlitande part" alert("Tekniskt fel: " + errorMsg + " vid " + paramName); return false } } else { return true } } function startSign(){ var typePlugin = isInstalled(); if (typePlugin != false) { // pluginerna bör laddas enl. funktionen initPlugin() // p.g.a. kompabilitet med t.ex. Chrome. // Det bör också ske efter att hela DOM-trädet är laddat, // därav anropet via body onload. initPlugin(typePlugin); var retVal; var Plugin = document.getElementById('pluginId'); var signature = "Not Present"; // Sätt parametrarna till klienten och kolla om det gick bra. // SetParam returnerar felkoden direkt så ni behöver inte gå // omvägen via GetLastError t.ex.: // Checkerror("Nonce",Plugin.SetParam('Nonce','MTIzNDU2Nzg5MGFiYw==')); // true betyder att signeringscertifikatet som är kopplat till // det certifikat användaren loggat in med används. //Plugin.SetParam('OnlyAcceptMRU','true'); //Checkerror("MRU", Plugin.GetLastError()); alert("OBS!! NONCE ska genereras av er BICS och vara Base64 kodad! \nSe stycke 3.5 i dokumentet BISP - Beskrivning till förlitande part"); //OBS!! Ni får ej använda detta värde!! Plugin.SetParam('Nonce','MTIzNDU2Nzg5MGFiYw=='); Checkerror("Nonce", Plugin.GetLastError()); if (!Checkerror("TextToBeSigned", Plugin.SetParam('TextToBeSigned',' SmFnIHNrcml2ZXIgdW5kZXIgZGVuIGJpZm9nYWRlIGZpbGVuIA0KDQpEYXR1bSB4eHh4eHggeHg6eHgNCg0KUmVmZXJlb nNudW1tZXI='))) return; if (!Checkerror("Policys", Plugin.SetParam('Policys', 'MS4yLjMuNC4xMDsxLjIuMy40LjU7MS4yLjMuNC42MDsxLjIuMy40LjUw'))) return; if (!Checkerror("FileName", Plugin.SetParam('FileName', 'dGVzdC50eHQ='))) return; if (!Checkerror("FileContent", Plugin.SetParam('FileContent', 'SmFnIHZpbGwgbMOlbmEgMTAgdGtyIHV0YW4gcsOkbnRhIGkgMjAgw6VyIHRpbGwgYXR0IGvDtnBhIGVuIHNrw6RyZ8Ol cmRzw7Ygb2NoIMOkdGEgZW4gUsOES1NNw5ZSR8OFUy4NCg=='))) return; var retVal = Plugin.PerformAction('Sign'); if (!retVal) { var signature = Plugin.GetParam('Signature'); if (Checkerror("hämtning av signatur", Plugin.GetLastError())){ // Lägg in din kod för att skicka transaktionen till din BICS här. alert('Signatur skapad OK\n' +signature); } } else { Checkerror("performAction", Plugin.GetLastError()); } } else { alert("BankID säkerhetsprogram är inte installerat. Gå till https://install.bankid.com/rp") } Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 23 2013-11-17 } </script> </head> <body onLoad="startSign()"> Signering </body> </html> 3.10 Vanliga misstag I detta avsnitt listas de vanligaste misstagen som man kan göra när man skapar sidorna som hanterar legitimering och underskrift: 4 Anrop till pluginerna görs inte över SSL, resulterar i felkod 8015. Olika stavfel, resulterar i felkod 8020 eller 8004. Exemplen i detta dokument används utan anpassning, till exempel med Challenge eller Nonce satt till exemplets värde. Det innebär en säkerhetsrisk att använda ett statiskt värde som nonce/challenge eftersom dessa transaktioner då kan återanvändas (återuppspelningsattack). Parametrar base64-kodas inte, trots att detta krävs, till exemepl TextToBeSigned, Nonce och Challenge. Detta fel resulterar i felkod 8017. Pluginerna anropas innan hela sidan laddats i användarens webbläsare. Om webbläsaren inte är klar med uppbyggnaden av DOM-trädet över sidan innan pluginerna anropas kan olika typer av fel uppstå, bland annat att pluginerna inte kan ta reda på vilken sida de anropas från (felkod 8010 eller 8015). Returkoder från anrop till SetParam fångas inte. Om ett anrop till SetParam misslyckas och ett anrop sedan görs till PerformAction kan till exempel felkod 8016 returneras (parameter saknas). Felet kan dock ha berott på att värdet på parametern som skulle sättas med SetParam inte var base64-kodad eller på annat sätt ogiltig. Appendix 1: Rekommenderade feltexter för returkoder från BISP Allmänt: Användaren ska kunna minnas och förstå meddelandet. Meddelandet ska innehålla returkoden och ska hänvisa användaren till rätt supportkontakt, beroende på vad som gått fel. 8001 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8001 8002 Du har avbrutit med Avbryt-knappen eller stängt dialogen. Returkod: 8002 8003 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8003 8004 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8004 8005 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8005 8006 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8006 8007 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8007 8008 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8008 8009 Programmet hittar inte rätt BankID. Felkod: 8009 8010 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8010 8011 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8011 8012 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8012 8013 Du har skrivit fel lösenord/PIN-kod. Felkod: 8013 8014 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8014 8015 Webbplatsens adress måste börja med https. Felkod: 8015 8016 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8016 8017 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8017 8018 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8018 8019 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8019 8020 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8020 Finansiell ID-Teknik BID AB Sida 24 2013-11-17 BISP - Beskrivning till förlitande part 5 8022 Säkerhetsprogrammet kan vara fel installerat. Kontakta support hos utgivaren av ditt BankID. Felkod: 8022 8102 Din PIN-kod är låst eftersom du har skrivit fel PIN-kod för många gånger. Du kan låsa upp PIN-koden med hjälp av din PUK-kod. Felkod: 8102 8551 Endast underskrift Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8551 8552 Ett fel har inträffat. Kontakta webbplatsen du besöker. Felkod: 8552 Appendix 2: Rekommenderade feltexter för returkoder från BICS Utdrag ur Appendix F i “Functional Requirements BankID-Control Server (BICS)”, Version: 6.7. Denna information finns med som referens. Specifika felkoder för er BICS får ni av er BICS-leverantör. Error Example Suggestion for error messages, Swedish BankID Error Group A BankID User certificate expired The validity period for the BankID User certificate has expired. The transaction is not accepted. Ditt BankID är inte längre giltigt och behöver förnyas. Kontakta din bank för att skaffa ett nytt (Fel-ID) BankID User certificate revoked The BankID User certificate is revoked. The OCSP response says that the certificate has been revoked by the CA. The transaction is not accepted. Ditt BankID är spärrat och kan B inte användas. Kontakta din bank för att skaffa ett nytt (Fel-ID) Error concerning the BankID User certificate Some error has occurred Ditt BankID är felaktigt och kan C concerning the certificate of the inte användas. Kontakta din bank BankID User. Possible reasons för att skaffa ett nytt (Fel-ID) may be not a trusted issuer, not a valid key usage, not a valid signature in the certificate. BankID User certificate soon to be expired The validity period of the BankID User certificate will soon expire. This is used as an information message in order to inform the BankID User to order a new certificate. Ditt BankID upphör snart att gälla. Kontakta din bank för att skaffa ett nytt (Fel-ID) alt Ditt BankID upphör att gälla ÅÅÅÅ-MM-DD. Kontakta din bank för att hämta ut ett nytt (Fel-ID) D Technical errors Communication errors, errors in the CBT, not a valid signature, not a valid XML transaction, signed value does not correspond to the value to be signed. Not a valid OCSP signing certificate, internal errors in the BICS, OCSP responder does not respond. DSEARCH responder does not respond. RPSI does not respond. Tekniskt fel. Var god försök senare. (Fel-ID) alt Eller hänvisa kunden till alternativ metod att genomföra ärendet NOT: I detta fall får Förlitande Part inte hänvisa kunden till banken. E Long response times Timeouts, long response times, overload in different parts of the infrastructure. Technical Just nu är tjänsten inte tillgänglig. Var god försök senare. (Fel-ID) F Finansiell ID-Teknik BID AB Sida 25 2013-11-17 BISP - Beskrivning till förlitande part errors that will be NOT: I detta fall får Förlitande automatically resolved within a Part inte hänvisa kunden till short period of time. banken. Client Version Errors 6 The client version has not been controlled within the stipulated timeframe, the client version is wrong, not possible to control client version, enhanced version control failed, genuine software control failed, G [Rekommenderade texter finns i avsnitt 2.1.3.] NOT: I detta fall skall förlitande part presentera en länk till korrekt installationswebbplats för kunden. Appendix 3: Windows 8 och BankID på fil eller BankID på kort 6.1 Varianter av Windows 8 1) Windows 8 Version av Windows för vanlig PC, alltså dator med processor av typen Intel/AMD, x86/x64 2) Windows RT 8 En variant för en typ av surfplatta med ARM-processor. BankID säkerhetsprogram stödjer inte denna processor/plattform. Datortyper som är nya på marknaden tillsammans med Windows 8 är: - PC med pekskärm men helt utan tangentbord – med Intel-processor och som kör Windows 8 för vanlig PC. - Surfplatta utan tangentbord med ARM-processor som kör Windows RT 8. 6.2 Windows 8 använder växelvis två ”vyer” eller användargränssnitt för olika tillfällen: - Det vanliga skrivbordet, som det har sett ut i de senaste versionerna av Windows. - Ett pekskärmsanpassat användargränssnitt som kallas ”Windows 8-gränssnitt”eller ”Modern UI”, som även har benämnts ”Metro”. Dels erbjuder det gränssnittet en startskärm/startmeny, dels används det till appar anpassade för Windows 8. Båda gränssnitten fungerar både med pekskärm och tangentbord/mus, och används både på skrivbords-PC och på surfplattor. 6.3 Konsekvenser BankID kommer att fungera för de flesta med Windows 8 för vanlig PC men inte med Windows RT 8. BankID fungerar på Windows 8 för PC med följande undantag: 1) Om webbläsaren (Internet Explorer eller andra webbläsare) startas i ”Windows 8-gränssnittet”/Metro kommer BankID säkerhetsprogram inte att fungera, eftersom webbläsaren normalt inte kan använda pluginer i det gränssnittet. Om användaren i stället öppnar webbläsaren på skrivbordet kommer BankID att fungera. Webbplatsen kan inte utan anpassning avgöra om användaren kör en webbläsare på skrivbordet eller i ”Windows 8-gränssnittet”/Metro. Microsoft rekommenderar att en meta-tag ska läggas till på alla webbsidor som behöver pluginer för sitt innehåll. Denna meta-tag har endast funktion i Internet Explorer. Se avsnitt 6.4. 2) Om användaren har en PC utan fysiskt tangentbord (en vanlig PC men med endast pekskärm) så kommer inte BankID på fil eller BankID på kort i kortläsare utan knappsats (transparent kortläsare) att fungera, eftersom Finansiell ID-Teknik BID AB BISP - Beskrivning till förlitande part Sida 26 2013-11-17 skärmtangentbordet inte kan användas tillsammans med BankID säkerhetsprograms säkra inmatning/visning. BankID på kort i kortläsare med knappsats kommer däremot att fungera. BankID på kort eller BankID på fil kommer inte att fungera i surfplattor med Windows RT 8. Dessa surfplattor har en helt annan arkitektur och därför går det inte att installera eller använda BankID säkerhetsprogram. 6.4 Anpassning av webbsidor: Meta-tag Microsoft rekommenderar att följande meta-tag läggs till på alla webbsidor som kräver pluginer för sin funktion. <head> <meta http-equiv="X-UA-Compatible" content="requiresActiveX=true"/> </head> En användare som har Internet Explorer i ”Windows 8-gränssnittet”/Metro och som visar en webbsida som har denna meta-tag kommer att få se följande dialog i webbsidans nederkant: Alla förlitande parter med stöd för BankID på fil och/eller BankID på kort rekommenderas att lägga till denna meta-tag eller som alternativ implementerar en kontroll i javascript enligt förslaget i avsnitt Fel! Hittar inte referenskälla.. Fundera noga på var i flödet denna meta-tag läggs till, eftersom en session inte nödvändigtvis följer med till webbläsaren på skrivbordet. Notera: Den meta-tag som rekommenderas har inte funktion i andra webbläsare än Internet Explorer.