Transcript BISP - beskrivning till förlitande part 3.1

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.