Gebruikshandleiding eid middleware v2.6 pagina 1 van 17
Inhoudsopgave Inleiding...3 Installatie...4 Installatie vanaf broncode...4 Installatie van distributiespecifieke pakketten...5 Systeemvereisten na installatie...5 De onderdelen van de eid software...6 De Privacy Filter...7 De PKCS#11 module...9 Toepassing om de kaart te lezen en te beheren...10 Command Line Tools...15 pagina 2 van 17
INLEIDING Midden 2006 stond de teller voor electronische identiteitskaarten of eid al op tweeëneenhalfmiljoen en jaarlijks komen er daar nog eens evenveel bij. Meer en meer overheidsdiensten en bedrijven bieden nieuwe internetdiensten en programma's aan die van de eid gebruik maken. Om de eid te gebruiken met die diensten en programma's heb je een kaartlezer nodig en speciale software - de eid middleware -om de kaart uit te lezen. De kaartlezers zijn verkrijgbaar in de gewone computerwinkels en grootwarenhuizen. De eid middleware wordt door de federale overheid gratis ter beschikking gesteld op de federake portaalsite http://www.eid.belgium.be. Met de eid middleware kan je de inhoud van de identiteitskaart uitlezen en bewaren en je identiteitskaart gebruiken met populaire programma's zoals OpenOffice, Firefox, Thunderbird, Adobe Reader, enz. De electronische chip op de kaart bevat naast je identiteit, adres en foto ook cryptografische sleutels die door deze programma's gebruikt worden om je identiteit te bewijzen of een electronische handtekening op een computerdocument te zetten. Voor meer informatie over LSB zie http://www.freestandard s.org/en/specifications De software is geschikt voor de volgende versies van Linux: kernel v2.6 PC/SC Lite 1.2 of 1.3 bij voorkeur voldoen aan Linux Standards Base v3.1 Deze handleiding is bedoeld voor gewone gebruikers en bevat een overzicht van de verschillende onderdelen en hun functie en legt uit hoe je de software kan installeren en gebruiken. De informatie in dit document is van toepassing op v2.6 van de eid middleware. Bijkomende informatie voor professionele gebruikers, systeembeheerders en programmeurs is beschikbaar in aparte technische nota's. Programmeurs doen er bovendien goed aan naast deze handleiding en de technische nota's ook de documentatie van de eid Software Development Kit door te nemen. pagina 3 van 17
INSTALLATIE INSTALLATIE VANAF BRONCODE Om te installeren vanaf de broncode moet de volgende software reeds geïnstalleerd zijn: Qt 3.3.x libraries + header files OpenSSL 0.9.x libraries + header files gcc Python pkgconfig LSB core package PC/SC Lite 1.2.x of 1.3.x daemon, libraries en header files Scons (optioneel) Java2 SDK v1.4 of 1.5 (optioneel) wxgtk 2.6 libraries + header files (optioneel) Een typische installatiesequentie op een moderne Linux distributie met LSB core package is als volgt: #./configure # make # su enter your password: # make install # ldconfig /usr/local/lib # /usr/lib/lsb/install_initd /etc/init.d/belgium.bebeidpcscd # /usr/lib/lsb/install_initd /etc/init.d/belgium.bebeidcrld Indien de distributie geen LSB core package bevat moet je de twee laatste stappen (de registratie van de init scripts) doen volgens de voorschriften van jouw distributie. Extra informatie vind je in de README en INSTALL bestanden die samen met de broncode verdeeld worden. In INSTALL staan ook algemene richtlijnen voor het correct installeren van de init scripts voor de twee daemons (beidpcscd en beidcrld). pagina 4 van 17
De tarball met de broncode bevat ook een ikoon dat kan gebruikt worden voor het Start menu van de desktop manager (KDE, Gnome,...). INSTALLATIE VAN DISTRIBUTIESPECIFIEKE PAKKETTEN Sommige Linux distributies bieden gebruiksklare pakketten aan van de eid software in het standaard pakketformaat (rpm, dev,...) voor die distributie. Gebruik de pakketbeheerder van je distributie en installeer de volgende pakketten: eid middleware (zoek onder "beid", "Belgium", "eid",...) PC/SC Lite LSB Core wxwidgets (wxgtk) 2.6 OpenSSL Qt 3.3.x Java Runtime environment (optioneel) Het is mogelijk dat de eid middleware in meerdere pakketten is opgesplitst door de verantwoordelijken van de distributie. Dit kan voor elke distributie verschillend zijn. SYSTEEMVEREISTEN NA INSTALLATIE De pcscd daemon van het PC/SC Lite pakket moet opgestart zijn via een init script in /etc/init.d. Zonder deze daemon kan de eid middleware geen gebruik maken van de kaartlezer voor de eid kaart. pagina 5 van 17
DE ONDERDELEN VAN DE EID SOFTWARE Nu de installatie voltooid is, is het tijd om kennis te maken met de essentiële onderdelen van de eid middleware. een PKCS#11 plugin module (libbeidpkcs11.so) om de identiteitskaart te gebruiken voor authenticatie of electronische handtekening een toepassing (beidgui) om de inhoud van de identiteitskaart uit te lezen, te controleren, af te drukken en te bewaren in een bestand enkele command line tools (beid-tool en beid-pkcs11-tool) Daarnaast zijn er nog 2 onzichtbare onderdelen of daemons (beidpcscd en beidcrld) die enkele achtergrondtaken verzorgen zoals het controleren van applicaties die de eid kaart proberen uit te lezen. pagina 6 van 17
DE PRIVACY FILTER Deze optie is enkel beschikbaar als de init script en runlevel configuratie correct is. De privacy filter is een onzichtbare component (een daemon) die als een soort waakhond alle communicatie met de eid-kaart onderzoekt. Als de privacy filter actief is kunnen enkel programma's die met de officiële software van de overheid ontwikkeld werden, gebruik maken van de eid-kaart. Bovendien zal de privacy filter een waarschuwing tonen telkens een onbekend programma probeert gegevens van een eid-kaart te lezen. De privacy filter verstrekt de volgende informatie: naam van het programma dat de kaart probeert uit te lezen het bestand dat gelezen wordt (adres, identiteit of foto) De gebruiker kan zelf beslissen of dit programma de eid-kaart mag uitlezen: ja (eenmalig) nee altijd (voor dit programma) altijd op alles (voor alle programma's) Nota: de privacy filter is een daemon (beidpcscd) die opgestart wordt via een runlevel init script in /etc/init.d. CONFLICT MET PERSONAL FIREWALL SOFTWARE Om de verschillende onderdelen van de eid middleware toe te laten pagina 7 van 17
met de eid privacy filter te communiceren is het soms nodig om de personal firewall zo in te stellen dat communicatie via IP adres 127.0.0.1 of hostname "localhost" en TCP poortnummer 2500 toegelaten is. Dit adres is overigens geen echt internet adres maar een virtueel adres dat "de lokale computer" betekent. pagina 8 van 17
DE PKCS#11 MODULE Dit is geen zelfstandig programma dat je zelf kan opstarten maar een module die door andere programma's gebruikt worden om met de eid kaart te communiceren. Deze module blijft onzichtbaar behalve wanneer je de PIN code moet ingeven bijv. om aan te melden op een web site of om een document te ondertekenen. Enkele toepassingen die de PKCS#11 module gebruiken: OpenOffice.org Firefox, Thunderbird, Mozilla en Netscape Evolution Lotus Notes De PKCS#11 module is een shared library met de naam libbeidpkcs11.so. De directory waarin deze library geïnstalleerd wordt is afhankelijk van distributie tot distributie en van de build options indien je van broncode geïnstalleerd hebt. Meestal staat dit bestand in /usr/local/lib of in /usr/lib. De configuratie en het gebruik van deze toepassingen met de eidkaart is beschreven in aparte handleidingen. pagina 9 van 17
TOEPASSING OM DE KAART TE LEZEN EN TE BEHEREN Deze toepassing is enkel beschikbaar als wxwidgets (wxgtk) geïnstalleerd is. De toepassing kan opgestart worden via een ikoon op het bureaublad, via het Start menu of via de commandolijn (beidgui): # beid-gui & In de knoppenbalk bovenaan staan ikonen voor het uitlezen, afdrukken en bewaren van gegevens van de eid-kaart. De toepassing biedt 4 informatieschermen voor resp. de identiteitsgegevens, de certificaten, de kaart & PIN status en de opties van het programma. SCHERM "IDENTITEIT" Naast de identiteitsgegevens, het adres en de foto bevat dit scherm ook informatie over de geldigheidsduur van de kaart, het serienummer van de chip en de speciale status van de kaarthouder. pagina 10 van 17
SCHERM "CERTIFICATEN" Een eid-kaart kan perfect geldig zijn ook al zijn een of meerdere certificaten ingetrokken. De status van een certificaat wordt onafhankelijk van de status van de kaart beheerd. Dit scherm toont in de linkerhelft de certificaten die op de kaart staan. Elke certificaat kan apart geselecteerd worden om in de rechterhelft de status van het certificaat te bekijken. De status van de certificaten kan de volgende waarden aannemen: geldig vervallen tijdelijk ingetrokken definitief ingetrokken pagina 11 van 17
SCHERM "KAART EN PIN" Dit scherm toont informatie over de chip en biedt de mogelijkheid de PIN te wijzigen. pagina 12 van 17
SCHERM "OPTIES" Dit scherm bevat de algemene opties voor het programma. Taal: De taalkeuze is enkel van toepassing op dit programma zelf en heeft geen invloed op de taal die gebruikt wordt in andere applicaties. Certificaatvalidatie: Zoals eerder aangegeven kunnen de certificaten op de kaart geldig, vervallen of ingetrokken zijn. Om de actuele status te controleren zal het programma de status van de certificaten geval per geval online controleren (optie OCSP of Online Certificate Status Protocol) of regelmatig een nieuwe lijst van ingetrokken certificaten downloaden (optie CRL of Certificate Revocation List). Voor elk van beide controlemechanismes kan men het gebruik aangeven: Niet gebruikt: Deze controle wordt nooit uitgevoerd pagina 13 van 17
Optioneel: De methode wordt gebruikt indien de omstandigheden dit toelaten. Voor controle d.m.v. OCSP moet er een werkende internetconnectie zijn op het moment dat de certificaten gecontroleerd worden. Voor controle d.m.v. CRL moet er een actuele versie van de CRL op de computer staan of - indien de lokale lijst vervallen is - moet er een werkende internetconnectie zijn om een nieuwe lijst te downloaden. Verplicht: Indien een controlemethode verplicht is maar niet kan uitgevoerd worden (bijv. doordat er geen internetconnectie is) verschijnt een foutmelding en worden de gegevens van de kaart niet getoond. Kaartlezer: Indien geen kaartlezer is opgegeven zal het programma alle beschikbare kaartlezers aflopen en de eerstgevonden eid-kaart uitlezen. Indien gewenst kan hier een specifieke kaartlezer geselecteerd worden. De aangeboden lijst bevat alle op dat moment aangesloten kaartlezers. pagina 14 van 17
COMMAND LINE TOOLS BEID-TOOL Het commando beid-tool toont alle aangesloten kaartlezers en de respons code van de kaarten in die kaartlezers. Detectie van de kaartlezer: # beid-tool -l Readers known about: Nr. Driver Name 0 pcsc ACS ACR38U 00 00 Detectie van de eid kaart: # beid-tool -a Connecting to card in reader ACS ACR38 00 00 Using card driver: BE eid card Card ATR: 3B 98 94 40 0A A5 03 01 01 01 AD 13 10 ;..@... BEID-PKCS11-TOOL Het commando beid-tool test de cryptografische functies van Testen van de eid kaart: # beid-pkcs11-tool -t -l --module /usr/local/lib/libbeidpkcs11.so pagina 15 van 17
DAEMONS EN INIT SCRIPTS De eid middleware bevat twee daemons: 1. de beidpcscd daemon voor de privacy filter 2. de beidcrld daemon voor de periodieke dowload van CRLs De directory waarin deze daemons geïnstalleerd worden is afhankelijk van distributie tot distributie en van de build options indien van broncode geïnstalleerd werd. Meestal staan deze bestanden in /usr/local/bin of in /usr/bin. De daemons worden opgestart via init scripts in /etc/init.d: belgium.be-beidpcscd voor beidpcscd belgium.be-beidcrld voor beidcrld Op de meeste distributies is de LSB core package wel beschikbaar maar niet geïnstalleerd. De scripts die met de broncode meegeleverd worden, voldoen aan de standaard "Linux Standard Base" v3.1. Voor de correcte werking van de scripts moet dan ook de LSB core package voor uw distributie geïnstalleerd zijn. Tip: Als de LSB core package voor uw distributie geïnstalleerd is, zijn de volgende drie bestanden beschikbaar: /lib/lsb/init-functions /usr/lib/lsb/install_initd /usr/lib/lsb/remove_initd. Registratie van de init scripts na installatie d.m.v. de standaard broncode: Na de installatie d.m.v. make install moeten de init scripts nog geregistreerd worden zodat de daemons in de juiste runlevels opgestart worden. Dit kan door als root met het install_initd commando de scripts te registreren: Op sommige distributies kan het nodig zijn om een distributiespecifiek commando te gebruiken i.p.v. het LSB commando install_initd. Het is mogelijk dat bepaalde distributies deze scripts aangepast hebben en dat de LSB core package niet vereist is. pagina 16 van 17
------------------------ dit is de laatste pagina van dit document ------------------------ pagina 17 van 17