Erinevus lehekülje "Uute eID rakenduste loomine" redaktsioonide vahel

Allikas: eid.eesti.ee
Jump to navigation Jump to search
(→‎Isikuandmete faili kasutamine: digi-id-l on isikuandmete fail peaaegu tühi)
 
(ei näidata 4 kasutaja 31 vahepealset redaktsiooni)
1. rida: 1. rida:
 
= Uute eID rakenduste loomine =
 
= Uute eID rakenduste loomine =
'' Uute rakenduste loomise osas vajavad käsitlemist: digiallkirjastamine, krüpteerimine (piirame end CDOC-iga), isikutuvastamine veebis (siia alla ka OCSP, CRL, LDAP), isikuandmete faili kasutamine, DigidocService kasutamine. ''
+
Järgnev osa räägib uute eID rakenduste loomisest. Enne seda tasub kindlasti tutvuda ka [[Üldteavet_arendajatele|üldteabega arendajatele]].
 
 
== DigiDoc tarkvara ==
 
AS Sertifitseerimiskeskus pakub veebiteenust ning mitmeid teeke nimega DigiDoc, mis on loodud eID dokumentide kasutamise lihtsustamiseks.
 
 
 
=== Teegid ===
 
Töölauarakendustes eID funktsionaalsuse kasutamiseks on loodud neli erinevat teeki:<ref name="digidoc-teegid">http://id.ee/index.php?id=30290</ref>
 
* '''jdigidoc''' -  Java teek, mis on ühtlasi ka esmane soovitus uute arenduste tegemisel.<br />Toetatud vormingud: '''DDOC''', '''BDOC''', '''CDOC'''.
 
* '''libdigidoc''' - C teek, millelt on plaan tugi asenduse tekkimisel ära kaotada. Ei ole soovitatud uute arenduste tegemisel.<br />Toetatud vormingud: '''DDOC''', '''CDOC'''.
 
* '''libdigidocpp''' - C++ teek, mis on kasutuses DigiDoc3 kliendi koosseisus. Eraldiseisvana teda arendajatele ei pakuta, ent on kättesaadav koos kliendiga.<br />Toetatud vormingud: '''BDOC'''.
 
* '''libdigidoccom''' - <abbr title="Component Object Model">COM</abbr> liides libdigidoc teegile.<br />Toetatud vormingud: '''DDOC'''.
 
* '''ndigidoc''' - .NET teek krüpteerimiseks ja dekrüpteerimiseks. Hetkel toetab ainult tarkvaralisi võtmepaare, s.t ID-kaarti kasutada ei saa; saaja salajane võti peab olema kõvakettal [http://www.rsa.com/rsalabs/node.asp?id=2138 PKCS#12]-tüüpi konteineris.<br />Toetatud vormingud: '''CDOC'''.
 
 
 
Tulevikus on plaanis luua ka .NET teek, mis asendaks COM teegi.<ref name="digidoc-teegid" />
 
 
 
=== DigiDocService ===
 
Alternatiiviks teekide kasutamisele on olemas ka DigiDocService, mis on <abbr title="Simple Object Access Protocol">SOAP</abbr>-põhine tasuline veebiteenus. See võimaldab isikutuvastuse, digitaalallkirjastamise ja allkirjade kontrollimise funktsionaalsust siduda teiste infosüsteemidega. Teenust on võimalik kasutada erinevatelt arenduskeskkondadelt/platvormidelt, millel on SOAP 1.0 <abbr title="Remote Procedure Call">RPC</abbr>-encoded tugi.
 
 
 
Teenuse poolt pakutav funktsionaalsus:
 
* Isikusamasuse kontroll Mobiil-ID'ga
 
* Sertifikaatide kehtivuse kontroll (võimaldab isikusamasuse kontrolli ID-kaardi ja muu kiipkaardiga)
 
* DigiDoc failide moodustamine
 
* Digitaalallkirjastamine Mobiil-ID'ga
 
* Digitaalallkirjastamine ID-kaardi (ja muu kiipkaardiga)
 
* Digitaalallkirjastatud failide (DigiDoc) sisu ja allkirjade kehtivuse kontroll.
 
 
 
DigiDocService toetab ainult DDOC formaadis allkirjastatud dokumente - BDOC tugi hetkel puudub.
 
 
 
Teenusele ligipääsu võimaldatakse IP aadressi põhiselt, selle kasutamiseks tuleb rakenduse pakkujal sõlmida leping AS Sertifitseerimiskeskusega. Teenuse kasutamise maksumus sõltub allkirjastamise ja autentimise päringute arvust kuus ja ühelt rakenduselt tulevatest üheaegsete päringute arvust.<ref name="digidocservice">http://id.ee/index.php?id=30291</ref>
 
 
 
==== Testteenus ====
 
Testimiseks ja arendamiseks on olemas ka tasuta [https://www.openxades.org/ OpenXAdES] testkeskkond.<ref name="digidocservice-test">http://id.ee/index.php?id=30340</ref>
 
 
 
Testkeskkonnas on võimalik kasutada Mobiil-ID [http://www.openxades.org/dds_test_phone_numbers.html testtelefoninumbreid], et vältida mobiilivõrkude kasutamist arendamisel. Kasutades testteenust, peab rakenduse nimeks (meetodite parameeter <tt>ServiceName</tt>) alati panema "Testimine".<ref>http://www.openxades.org/dds_test_phone_numbers.html</ref> Alternatiivina võib enda Mobiil-ID-d toetava telefoninumbri [http://www.openxades.org/ddsregisteruser/ OpenXAdES-es registreerida] ning testimisel seda kasutada.
 
 
 
== Sertifikaatide kehtivuse kontroll ==
 
Sertifikaadi kehtivust tuleb eraldi kontrollida ka väljaandja käest; ei piisa vaid sertifikaadil oleva kehtivuse algus- ja lõppkuupäeva kontrollist, kuna sertifikaadi väljaandja võib selle teatud põhjustel varem kehtetuks tunnistada, peatada või peatamist lõpetada.
 
 
 
''Märkus:'' Järgnev jutt kehtib vaid ID-kaardi ning Digi-ID puhul: Mobiil-ID sertifikaati kontrollib DigiDocService ning SSL/TLS seansis isikutuvastamine käib rakenduse tasemel.
 
 
 
Kehtivuse kontrolliks on kaks valikut:
 
* Tühistusnimekiri (''Certificate Revocation List'') ehk '''CRL''', mis on perioodiliselt allalaetav nimekiri kõikidest kehtetuks tunnistatud sertifikaatidest. AS Sertifitseerimiskeskuse tühistusnimekirjade kasutamine on tasuta.
 
* Kehtivuskinnitus (''Online Certificate Status Protocol'') ehk '''OCSP''', mis esitab päringu sertifikaadi kehtivuse kohta OCSP-serverile (edaspidi responder), mis annab vastuse reaalajas. AS Sertifitseerimiskeskuse kehtivuskinnituse teenuse kasutamine on '''tasuline'''.<ref>http://www.sk.ee/teenused/kehtivuskinnituse-teenus/</ref>
 
** Autentimise OCSP on piloteerimisfaasis tasuta, edaspidi tasuline ja IP-põhine ning eeldab lepingu sõlmimist SK-ga. Vt http://www.sk.ee/teenused/kehtivuskinnituse-teenus/autentimise-ocsp/
 
 
 
Kuigi tühistusnimekirjade kasutamine on tasuta ning neil on eelis käideldavuse osas (kui CRL-serverid muutuvad kättesaadamatuks, siis on ikkagi teada viimane kord allalaetud seis), ei ole nendes olev info reaalajaline esitus sertifikaatide kehtivusest. Värskeima kehtivusinfo saamiseks tuleb kasutada kehtivuskinnituse teenust, mis aga on tasuline ning responderi mitte-kättesaadavuse korral puudub igasugune info sertifikaatide kohta (ka mitte mõni hetk tagasi kehtinud). Iga veebiteenuse korral on vaja eraldi uurida nõudeid ning otsustada, kumb sobib paremini.
 
 
 
'''Tähelepanu:''' Tarkvaraarendajad on mõnikord kasutanud isikutuvastamise juures LDAP-teenust sertifikaatide kehtivuskontrolli vahendina. '''See on teenuse väärkasutus ja sellisena keelatud,''' isegi kui see (mõnikord) annab korrektseid tulemusi. LDAP-andmeedastus ei ole turvatud, mistõttu saab vastuseid võltsida või muuta, ning LDAP kataloog võib sisaldada ka kehtetuid sertifikaate.
 
 
 
=== SSL/TLS seansis ===
 
Eraldi teema on SSL/TLS seansi alguses kliendi antud ID-kaardi või Digi-ID sertifikaadi kehtivuse kontrollimine, kuna selle peaks läbi viima veebiserver, mitte -rakendus. Käesolev juhend käsitleb vaid [http://httpd.apache.org/ Apache httpd] ning [http://www.iis.net/ Microsoft IIS] servereid, kuigi see jutt võib rakenduda ka teistele.
 
 
 
Tühistusnimekirjade kasutamise korral töötab kõik hästi ning veebiserverid on suutelised neid iseseisvalt kasutama. Serveri konfigureerimiseks vaata [[#Veebiserver|näiteseadistust]].
 
 
 
Kehtivuskinnituse kasutamisel on aga mõned lisatingimused, mida käsitlevad järgmised peatükid.
 
 
 
==== OCSP rakenduse tasemel ====
 
Kuigi nii Apache-l kui ka IIS-il on sisseehitatud vahendid OCSP kehtivuskinnituse küsimiseks, soovivad need, et vastuses oleks kaasas ka OCSP responderi sertifikaat. Viimast on vaja selleks, et saaks kontrollida vastusel olevat allkirja.  Sertifikaadi lisamine on aga valikuline ning Sertifitseerimiskeskuse OCSP teenus seda ei tee. Seetõttu ei ole võimalik OCSP kehtivuskinnitust küsida vaikimisi vahenditega. Olemasolevatele seansihaldusvahenditele tuleb lisada tugi OCSP kehtivuskinnituse küsimiseks, et uue seansi alustades saaks veenduda, et kasutaja antud sertifikaat ikkagi kehtib.
 
 
 
Üks võimalus kehtivuse kontrolliks on kasutada [[#DigiDocService|DigiDocService]] meetodit <tt>CheckCertificate</tt>, mis tagastab parameetriks antud sertifikaadi OCSP staatuse. See on üks lihtsamaid lahendusi, ent nõuab ligipääsu DigiDocService-le (mis on tasuline) ning et veebirakenduses on vahendid SOAP-serveriga suhtlemiseks.
 
 
 
Alati on ka võimalik kasutada alternatiivseid vahendeid, mis suudavad suhelda Sertifitseerimiskeskuse OCSP-teenusega ning ei vaja selleks DigiDocService-i abi; neile tuleb aga responderi sertifikaat vastuse verifitseerimiseks käsitsi ette anda.
 
 
 
'''NB!''' Oma rakendustes '''peab alati''' OCSP-teenuse vastust verifitseerima, muidu on ründajal lihtne kehtivuskinnitust võltsida! Kui kasutada DigiDocService-teenust, siis see tehakse päringu käigus; alternatiivsete vahendite puhul peab seda suure tõenäosusega käsitsi tegema.
 
 
 
Näitekoodi DigiDocService-ga sertifikaadi kehtivuse kontrolliks leiab [[#Veebivorm|veebivormist]] ja OpenSSL-i kasutavaks alternatiiviks [http://id.ee/index.php?id=30338 ID.ee näiterakendusest].
 
 
 
==== Autentimise OCSP ====
 
Sertifitseerimiskeskus pakub lisaks "tavalisele" OCSP teenusele ka autentimise OCSP teenust: see on mõeldud kasutamiseks süsteemidesse sisselogimisel. Autentimise OCSP ei kanna kehtivuskinnituse päringuid turvalogisse, mistõttu puudub hilisem tõestus sel hetkel kehtivuse kohta. Samuti on hinnakiri teistsuguse ülesehitusega: tasuma peab erinevate sertifikaatide eest, mille olekut päritakse, mitte päringute hulga eest. Tänu selle on ta sobilik väikese hulga kasutajatega süsteemide jaoks, ent mitte avalike veebiteenuste jaoks.<ref>https://www.sk.ee/teenused/kehtivuskinnituse-teenus/autentimise-ocsp/</ref>
 
 
 
Autentimise OCSP tagastab oma vastustes ka responderi sertifikaadi, nii et seda saab kasutada Apache ja IIS-i sisseehitatud OCSP-kehtivuskontrolli vahenditega. Seda tasub teha aga vaid tingimusel, kui eelmises lõigus mainitud hinnakirja eripärad on vastuvõetavad, kuna mitme unikaalse kasutaja korral võib teenus osutuda kallimaks tavalisest OCSP-st.
 
 
 
Autentimise OCSP-l puudub ka test-teenus, mistõttu tuleb arendamisel/testimisel saata päringuid ''live''-responderile.
 
  
 
== Isikutuvastamine ==
 
== Isikutuvastamine ==
79. rida: 7. rida:
 
Isiku tuvastamine toimub vastavalt allolevale (lihtsustatud) protokollile:
 
Isiku tuvastamine toimub vastavalt allolevale (lihtsustatud) protokollile:
 
# Kasutaja esitab süsteemile mingi sertifikaadi ning väidab, et ta on selle omanik.
 
# Kasutaja esitab süsteemile mingi sertifikaadi ning väidab, et ta on selle omanik.
# Süsteem genereerib juhusliku, ühekordse arvu ehk nonsi (''nonce''), mis antakse kasutajale allkirjastamiseks.
+
# Süsteem genereerib juhusliku, ühekordse arvu ehk nonsi (''nonce''), mis antakse kasutajale isikutuvastusvõtmega allkirjastamiseks.
# Kasutaja lukustab lahti kaardil oleva salajase võtme, kasutades selleks PIN1-koodi.
+
# Kasutaja lukustab lahti kaardil oleva isikutuvastuseks mõeldud salajase võtme, kasutades selleks PIN1-koodi.
 
# Kaardile antakse nonss, mille see allkirjastab, ning kaardilt loetakse tulemus, mis edastatakse süsteemile.
 
# Kaardile antakse nonss, mille see allkirjastab, ning kaardilt loetakse tulemus, mis edastatakse süsteemile.
 
# Süsteem kontrollib, kas antud allkiri verifitseerub sertifikaadil oleva avaliku võtmega.
 
# Süsteem kontrollib, kas antud allkiri verifitseerub sertifikaadil oleva avaliku võtmega.
# Süsteem küsib sertifikaadi kohta kehtivuskinnitust.
+
# Süsteem kontrollib sertifikaadi kehtivust (vt [[#Sertifikaatide_kehtivuse_kontroll|Sertifikaatide kehtivuse kontroll]]).
  
 
Kui kõik õnnestus, siis võib eeldada, et kasutaja on tõesti sertifikaadi omanik -- ja kuna sertifikaadil on isiku nimi ning isikukood, siis on ka teada omaniku identiteet. Kuigi tegelikult võib olla kasutaja lihtsalt keegi, kellel on sertifikaadi omaniku kaart ning teab selle PIN1, ei saa seda enam kuidagi kontrollida.
 
Kui kõik õnnestus, siis võib eeldada, et kasutaja on tõesti sertifikaadi omanik -- ja kuna sertifikaadil on isiku nimi ning isikukood, siis on ka teada omaniku identiteet. Kuigi tegelikult võib olla kasutaja lihtsalt keegi, kellel on sertifikaadi omaniku kaart ning teab selle PIN1, ei saa seda enam kuidagi kontrollida.
  
Isikutuvastamise näitekoodi näeb [[#Isikutuvastuse_rakendus|eraldiseisva rakendusena]] ning ka [[#Avalduste_rakendus|avalduste kasutusmalli]] koosseisus.
+
Isikutuvastamise näitekoodi näeb [[Näiterakendused#Isikutuvastuse_rakendus|eraldiseisva rakendusena]] ning ka [[Näiterakendused#Avalduste_rakendus|avalduste kasutusmalli]] koosseisus.
  
=== Veebis ===
+
==== Veebis ====
 
Veebis toimub isiku tuvastamine SSL/TLS käepigistuse (''handshake'') käigus, kus kontrollitakse ka kliendi sertifikaati. Protokolli põhjalik kirjeldus on kättesaadav [http://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake Wikipediast], ent lühidalt kokkuvõetuna tehakse sama, mis eelnevalt kirjeldatud, kuid nonsi asemel antakse allkiri kõigi eelnevate sõnumite räsile. Kuna sõnumid sisaldavad endas juhuarve, siis on ka nende räsi juhuslik.
 
Veebis toimub isiku tuvastamine SSL/TLS käepigistuse (''handshake'') käigus, kus kontrollitakse ka kliendi sertifikaati. Protokolli põhjalik kirjeldus on kättesaadav [http://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake Wikipediast], ent lühidalt kokkuvõetuna tehakse sama, mis eelnevalt kirjeldatud, kuid nonsi asemel antakse allkiri kõigi eelnevate sõnumite räsile. Kuna sõnumid sisaldavad endas juhuarve, siis on ka nende räsi juhuslik.
  
Veebis isiku tuvastamist tehakse näitekoodis [[#Veebivorm|veebivormil]].
+
Siin tuleb arvestada ka [[#SSL.2FTLS_seansis|sertifikaatide kehtivuse kontrolli SSL/TLS seansis]].
 +
 
 +
Veebis isiku tuvastamist tehakse näitekoodis [[Näiterakendused#Veebivorm|veebivormil]].
  
 
==== SSL/TLS taasläbirääkimise viga ====
 
==== SSL/TLS taasläbirääkimise viga ====
102. rida: 32. rida:
  
 
Eraldi ühenduspunktid peaksid olema erinevate IP-aadresside peal või vähemalt kasutama erinevat porti. Eraldi virtuaalhostidest ei piisa, kuna enne luuakse SSL/TLS seanss ning alles siis vaadatakse, millist virtuaalhosti kasutada.
 
Eraldi ühenduspunktid peaksid olema erinevate IP-aadresside peal või vähemalt kasutama erinevat porti. Eraldi virtuaalhostidest ei piisa, kuna enne luuakse SSL/TLS seanss ning alles siis vaadatakse, millist virtuaalhosti kasutada.
 +
 +
==== Mobiil-ID-ga ====
 +
Isikutuvastamine Mobiil-ID abil toimub järgmiselt:<ref name="mobiil-id">http://www.id.ee/index.php?id=30389</ref><ref name="digidocservice-spec-est">http://www.sk.ee/upload/files/DigiDocService_spec_est.pdf</ref><ref name="digidocservice-spec-eng">http://www.sk.ee/upload/files/DigiDocService_spec_eng.pdf</ref>
 +
# Luuakse tavaline SSL/TLS seanss ilma kliendisertifikaati küsimata.
 +
# Kasutaja sisestab oma telefoninumbri ja/või isikukoodi ning viimase välja andnud riigi koodi. Need andmed edastatakse teenusele DigiDocService <tt>MobileAuthenticate</tt> päringuga.
 +
# DigiDocService kontrollib OCSP-protokolli vahendusel, et kasutaja Mobiil-ID isikutuvastuse sertifikaat kehtib.
 +
# DigiDocService teeb samaaegselt järgmist:
 +
#* Saadab mobiiloperaatorile isikutuvastuse päringu (mis edastab selle kasutaja telefonile);
 +
#* Tagastab kontrollkoodi ja kasutaja sertifikaadi.
 +
#** '''NB!''' Teenus tagastab kõigest tuvastamisel oleva isiku sertifikaadi -- see ei tähenda veel, et kasutaja oleks autenditud!
 +
# Rakendus kuvab kasutajale neljakohalise isikutuvastuspäringu kontrollkoodi.
 +
# Rakendus hakkab perioodiliselt käima DigiDocService'i käest isikutuvastuse olekut küsimas <tt>GetMobileAuthenticateStatus</tt> päringuga.
 +
#* Olekupäring on võimalik teha ka sünkroonselt, s.t DigiDocService hoiab ühendust avatuna ning ei tagasta midagi enne, kui mobiiltelefonilt on tulnud vastus.
 +
# Kasutaja telefonil kuvatakse teade isikutuvastuspäringu kohta
 +
# Kasutaja veendub, et telefonil kuvatav kontrollkood langeb kokku rakenduse poolt kuvatavaga ning sisestab Mobiil-ID PIN1.
 +
# Teenuse poolt saadetud väljakutse (''challenge'') allkirjastatakse SIM-kaardil oleva salajase võtmega ning tulemus saadetakse mobiiloperaatorile, mis edastab selle DigiDocService'ile.
 +
# Järgmine kord, kui rakendus tuleb teenuselt päringu olekut küsima, vastab teenus, et kasutaja on autenditud ning tagastab allkirja.
 +
 +
Kasutamise näiteid näeb [[Näiterakendused#Mobiil-ID|avalduste kasutusmallis]] ning SK näiterakenduse leiab [http://id.ee/index.php?id=30388 siit].
  
 
== Digitaalne allkirjastamine ==
 
== Digitaalne allkirjastamine ==
Uusi digitaalseid allkirju luuakse kahes erinevas vormingus: [[#DDOC|DIGIDOC-XML]] ja [[#BDOC|BDOC]]. Esimest neist toetavad jdigidoc, libdigidoc, libdigidoccom; teist jdigidoc ja libdigidocpp (plaanitavalt ka .NET teek). Siit on näha, et ainus teek, mis mõlemat formaati toetab on jdigidoc, mistõttu soovitatakse seda kasutada ka uute arenduste tegemisel.<ref name="digidoc-teegid" /> Ka DigiDocService toetab vaid DDOC vorminguid.<ref name="digidocservice" />
+
Alates 2015. aastast luuakse digitaalseid allkirju [[Üldteavet_arendajatele#BDOC|BDOC]] vormingus. Kuni 2014. aasta lõpuni oli kasutusel [[Üldteavet_arendajatele#DDOC|DDOC]] formaat . [http://id.ee/index.php?id=30290 Siit] on näha, millised teegid, milliseid formaate toetavad. DigiDocService toetab nii BDOC kui DDOC vormingut.<ref>http://id.ee/index.php?id=30291</ref>
  
 +
==== Allkirjastatud faili loomine ====
 
Sõltumata allkirja vormingust on nii teekide kui ka DigiDocService puhul lähenemine sama:
 
Sõltumata allkirja vormingust on nii teekide kui ka DigiDocService puhul lähenemine sama:
 
# luuakse konteiner,
 
# luuakse konteiner,
111. rida: 61. rida:
 
# üle andmete genereeritakse räsi,
 
# üle andmete genereeritakse räsi,
 
# räsi allkirjastatakse osapoolte salajaste võtmetega,
 
# räsi allkirjastatakse osapoolte salajaste võtmetega,
# allkirjastaja sertifikaadile küsitakse kehtivuskinnitus ning
+
# allkirjastaja sertifikaadile küsitakse '''kehtivuskinnitus''' (tühistusnimekirja kontrollimisest on vähe, vt [[EID_lühitutvustus#Digiallkirjade_andmine|Digiallkirjade andmine]] ja [[#Sertifikaatide_kehtivuse_kontroll|Sertifikaatide kehtivuse kontroll]]) ning
 
# allkiri ja kinnitus lisatakse konteinerisse.
 
# allkiri ja kinnitus lisatakse konteinerisse.
  
 
Veebirakendustes allkirjastades toimub kõik allkirjastamise-eelne ning -järgne tegevus samamoodi nagu kohaliku allkirjastamise korral, ent räsi allkirjastamine (samm 4) toimub kliendi veebibrauseris. Selle jaoks on loodud JavaScripti teek, mille programmeerimisliides (API) on ühtne ning võimaldab erinevaid allkirjastamispluginaid – sõltumata kasutaja operatsioonisüsteemist ja brauserist – ühte moodi kasutada. Täpsem info [http://id.ee/index.php?id=30279 siit].
 
Veebirakendustes allkirjastades toimub kõik allkirjastamise-eelne ning -järgne tegevus samamoodi nagu kohaliku allkirjastamise korral, ent räsi allkirjastamine (samm 4) toimub kliendi veebibrauseris. Selle jaoks on loodud JavaScripti teek, mille programmeerimisliides (API) on ühtne ning võimaldab erinevaid allkirjastamispluginaid – sõltumata kasutaja operatsioonisüsteemist ja brauserist – ühte moodi kasutada. Täpsem info [http://id.ee/index.php?id=30279 siit].
  
Selguse ja turvalisuse tagamiseks peab iga rakendus, kus on digiallkirjastamise funktsioon, vastama kahele nõudmisele:<ref>http://id.ee/index.php?id=31039</ref>
+
Hiljem allkirja kontrollides tuleb veenduda, et konteineris olevate dokumentide räsid langevad kokku allkirjastatud räsidega ning allkirjad räsidel ja kehtivuskinnitustel on korrektsed (selleks kasutatakse allkirjastaja ning kehtivuskinnituse väljastaja sertifikaatidel olevaid avalikke võtmeid).
 +
 
 +
Selguse ja turvalisuse tagamiseks peab iga rakendus, kus on digiallkirjastamise funktsioon, vastama kahele nõudele:<ref>http://id.ee/index.php?id=31039</ref>
 
# Enne allkirjastamist peab kasutaja saama mõistlikul moel andmetega tutvuda.
 
# Enne allkirjastamist peab kasutaja saama mõistlikul moel andmetega tutvuda.
 
# Pärast allkirjastamist saab kasutaja kontrollida, millele tema allkiri anti, ehk tal on ligipääs DigiDoc-konteinerile koos esialgsete allkirjastatud andmete ja allkirjadega.
 
# Pärast allkirjastamist saab kasutaja kontrollida, millele tema allkiri anti, ehk tal on ligipääs DigiDoc-konteinerile koos esialgsete allkirjastatud andmete ja allkirjadega.
  
Dokumentide digitaalset allkirjastamist on demonstreeritud nii [[#Allkirjastamise_rakendus|eraldiseisva utiliidina]] kui ka [[#Avalduste_esitamise_kasutusmall|avalduste esitamise kasutusmallis]] - nii veebis, kasutades [[#Veebivorm|DigiDocService-teenust]] või [[#Avaldusi_t.C3.B6.C3.B6tlev_teenus|SWIG mähkurit]], kui ka [[#Avalduste_rakendus|töölauarakenduses]].
+
==== Kasutajatoe abi ====
 +
* Sagedane on veebilehitsejates allkirjastamise ebaõnnestumine mille peamiseks põhjuseks on veebilehitseja lisamooduli (plugina) keelatud olek. E-teenuste pakkujatel on soovitatav lisada allkirjastamise lisamooduli staatuse kontroll enne kui kasutaja alustab e-vormi täitmist. Näidisena on GitHubi (https://github.com/open-eid/hwcrypto.js/wiki/FAQ) lisatud skript mis teostab kontrolli allkirjastamise plugina kohta.
 +
 
 +
Juhul kui plugin ei ole aktiivne siis teavitada sellest kasutajat õige sõnumiga. Selliselt on võimalus tõsta teenuse kasutamiskogemust.
 +
:'''Veateate näidis:'''
 +
::''Allkirjastamine ebaõnnestus!''
 +
::''Kontrolli kas allkirjastamise plugin on lubatud.''
 +
::''Juhised leiate veebist http://www.id.ee/index.php?id=36636''
 +
 
 +
 
 +
Dokumentide digitaalset allkirjastamist on demonstreeritud nii [[Näiterakendused#Allkirjastamise_rakendus|eraldiseisva utiliidina]] kui ka [[Näiterakendused#Avalduste_esitamise_kasutusmall|avalduste esitamise kasutusmallis]] - nii veebis, kasutades [[Näiterakendused#Veebivorm|DigiDocService-teenust]] või [[Näiterakendused#Avaldusi_t.C3.B6.C3.B6tlev_teenus|SWIG mähkurit]], kui ka [[Näiterakendused#Avalduste_rakendus|töölauarakenduses]].
 +
 
 +
Allkirja kontrollimist on demonstreeritud [[Näiterakendused#Allkirja_kontrollimise_rakendus|eraldiseisvas rakenduses]], [[Näiterakendused#Avalduste_rakendus|avalduste rakenduses]] ja [[Näiterakendused#Avaldusi_t.C3.B6.C3.B6tlev_teenus|avaldusi töötlevas teenuses]].
 +
 
 +
=== Mobiil-ID-ga ===
 +
Mobiil-ID-ga saab allkirjastada dokumente kahte moodi:<ref name="mobiil-id" /><ref name="digidocservice-spec-est" /><ref name="digidocservice-spec-eng" />
 +
# Saadame DigiDocService-teenusele dokumendi, mispeale alustatakse uus seanss, kus luuakse ainult seda dokumenti sisaldav allkirjastatud konteiner, mis tagastatakse päringu esitajale. Selle jaoks tuleb kasutada päringuid <tt>MobileCreateSignature</tt> ja <tt>GetMobileCreateSignatureStatus</tt>. See on hea olukorras, kus meil ei ole DigiDocService vaja muuks kui dokumendi allkirjastamiseks.
 +
# Allkirjastame olemasolevas seansis loodud konteineri päringutega <tt>MobileSign</tt> ja <tt>GetStatusInfo</tt>. Seda lähenemist tasub kasutada siis, kui DigiDocService seanssi kasutatakse ka muude operatsioonide tegemiseks ning konteineri Mobiil-ID-ga allkirjastamine on vaid üks osa sellest.
 +
 
 +
Üldiselt toimub Mobiil-ID-ga allkirjastamine samamoodi nagu [[#Mobiil-ID-ga|isikutuvastamine]], järgmiste erinevustega:
 +
* Teenusele ei saadeta <tt>MobileAuthenticate</tt> ja <tt>GetMobileAuthenticateStatus</tt>, vaid ülaltoodud päringud.
 +
* Teenusele saadetakse allkirjastatavad dokumendid või nende räsid ning Mobiil-ID allkirja küsitakse hoopis nende räsile, mitte väljakutsele.
 +
* Allkiri antakse digitaalallkirjastamise salajase võtmega, mitte isikutuvastamise omaga. Sellest tulenevalt kontrollib ning tagastab DigiDocService allkirjastamisertifikaadi ning kasutaja peab sisestama PIN2, mitte PIN1.
 +
 
 +
Nende toimingute tulemusel moodustab DigidocService-teenus allkirjastatud konteineri, mille rakendus saab alla laadida. Kui alguses saadeti teenusele vaid allkirjastatavate dokumentide räsid, siis lisasammuna peab konteineris asendama räsid dokumentide endiga.
 +
 
 +
Kasutamise näiteid näeb [[Näiterakendused#Mobiil-ID|avalduste kasutusmallis]] ning SK näiterakenduse leiab [http://id.ee/index.php?id=30388 siit].
  
 
== Krüpteerimine ==
 
== Krüpteerimine ==
131. rida: 109. rida:
 
Sellist krüpteerimist saab kasutada vaid lühiajaliselt, näiteks andmete transportimiseks. Kuna krüpteeritud andmeid saavad avada ainult saajateks märgitud isikud oma krüpteerimise ajahetkel kehtivate sertifikaatidega, siis ei sobi see lahendus pikaajaliseks arhiveerimiseks -- sertifikaatide aegumisel asendatakse need kasutaja kaardil uutega ning vana salajast võtit pole enam võimalik kasutada.<ref>http://id.ee/index.php?id=30264</ref> See aga muudab konteineri jäädavalt suletuks. Samuti tuleb meeles pidada, et ID-kaardi jaoks krüpteeritud konteinerit ei saa avada sama isik oma Digi-ID-ga.
 
Sellist krüpteerimist saab kasutada vaid lühiajaliselt, näiteks andmete transportimiseks. Kuna krüpteeritud andmeid saavad avada ainult saajateks märgitud isikud oma krüpteerimise ajahetkel kehtivate sertifikaatidega, siis ei sobi see lahendus pikaajaliseks arhiveerimiseks -- sertifikaatide aegumisel asendatakse need kasutaja kaardil uutega ning vana salajast võtit pole enam võimalik kasutada.<ref>http://id.ee/index.php?id=30264</ref> See aga muudab konteineri jäädavalt suletuks. Samuti tuleb meeles pidada, et ID-kaardi jaoks krüpteeritud konteinerit ei saa avada sama isik oma Digi-ID-ga.
  
Krüpteerimist toetavad teegid libdigidoc (ja seega ka libdigidoccom) ning jdigidoc. DigiDocService-teenust pole võimalik krüpteerimiseks kasutada, aga see poleks ka mõistlik, sest sel juhul tuleks salastatavad andmed enne saata SK-le. Krüpteerimist demonstreeritakse [[#Avaldusi_t.C3.B6.C3.B6tlev_teenus|avaldusi töötlevas teenuses]] ning dekrüpteerimist [[#Avalduste_rakendus|avalduste rakenduses]].
+
Krüpteerimist toetavad teegid libdigidoc (ja seega ka libdigidoccom) ning jdigidoc. DigiDocService-teenust pole võimalik krüpteerimiseks kasutada, aga see poleks ka mõistlik, sest sel juhul tuleks salastatavad andmed enne saata SK-le. Krüpteerimist demonstreeritakse [[Näiterakendused#Avaldusi_t.C3.B6.C3.B6tlev_teenus|avaldusi töötlevas teenuses]] ning dekrüpteerimist [[Näiterakendused#Avalduste_rakendus|avalduste rakenduses]].
  
'''Tähelepanu:''' luues tarkvara, mis tegeleb andmete lahti krüpteerimisega, tuleb kindlasti silmas pidada [[#R.C3.BCnne_t.C3.A4idistusoraaklile|rünnet täidistusoraaklile]].
+
'''Tähelepanu:''' luues tarkvara, mis tegeleb andmete lahti krüpteerimisega, tuleb kindlasti silmas pidada [[Üldteavet_arendajatele#R.C3.BCnne_t.C3.A4idistusoraaklile|rünnet täidistusoraaklile]].
  
 
=== Sertifikaatide pärimine LDAP-ist ===
 
=== Sertifikaatide pärimine LDAP-ist ===
155. rida: 133. rida:
 
</pre>
 
</pre>
  
Päringut esitades tuleb silmas pidada, et ühel isikul võib LDAP-is olla mitu erinevat sertifikaati (nt ID-kaart ja Digi-ID). Täpne kataloogistruktuur on nähtav [https://www.sk.ee/repositoorium/ldap/ldap-kataloogi-kasutamine/ SK repositooriumis].
+
Täpne kataloogistruktuur on nähtav [https://www.sk.ee/repositoorium/ldap/ldap-kataloogi-kasutamine/ SK repositooriumis].
 +
 
 +
Päringut esitades tuleb silmas pidada, et ühel isikul võib LDAP-is olla mitu erinevat sertifikaati (nt ID-kaart ja Digi-ID). Samuti tuleb silmas pidada, et LDAP pole turvaline, mistõttu on võimalik ründajal sertifikaat välja vahetada enda omaga ning alati tuleb tagastatud sertifikaat üle kontrollida: kellele see on väljastatud, kelle poolt jne.
 +
 
 +
== Sertifikaatide kehtivuse kontroll ==
 +
Sertifikaadi kehtivust tuleb eraldi kontrollida ka väljaandja käest; ei piisa vaid sertifikaadil oleva kehtivuse algus- ja lõppkuupäeva kontrollist, kuna sertifikaadi väljaandja võib selle teatud põhjustel varem kehtetuks tunnistada, peatada või peatamist lõpetada.
 +
 
 +
''Märkus:'' Järgnev jutt kehtib vaid ID-kaardi ning Digi-ID puhul: Mobiil-ID sertifikaati kontrollib DigiDocService ning SSL/TLS seansis isikutuvastamine käib rakenduse tasemel.
 +
 
 +
Kehtivuse kontrolliks on kaks valikut:
 +
* Tühistusnimekiri (''Certificate Revocation List'') ehk '''CRL''', mis on perioodiliselt allalaetav nimekiri kõikidest kehtetuks tunnistatud sertifikaatidest. AS Sertifitseerimiskeskuse tühistusnimekirjade kasutamine on tasuta.
 +
* Kehtivuskinnitus (''Online Certificate Status Protocol'') ehk '''OCSP''', mis esitab päringu sertifikaadi kehtivuse kohta OCSP-serverile (edaspidi responder), mis annab vastuse reaalajas. AS Sertifitseerimiskeskuse kehtivuskinnituse teenuse kasutamine on '''tasuline'''.<ref>http://www.sk.ee/teenused/kehtivuskinnituse-teenus/</ref>
 +
** Autentimise OCSP on piloteerimisfaasis tasuta, edaspidi tasuline ja IP-põhine ning eeldab lepingu sõlmimist SK-ga. Vt http://www.sk.ee/teenused/kehtivuskinnituse-teenus/autentimise-ocsp/
 +
 
 +
Kuigi tühistusnimekirjade kasutamine on tasuta ning neil on eelis käideldavuse osas (kui CRL-serverid muutuvad kättesaadamatuks, siis on ikkagi teada viimane kord allalaetud seis), ei ole nendes olev info reaalajaline esitus sertifikaatide kehtivusest. Värskeima kehtivusinfo saamiseks tuleb kasutada kehtivuskinnituse teenust, mis aga on tasuline ning responderi mitte-kättesaadavuse korral puudub igasugune info sertifikaatide kohta (ka mitte mõni hetk tagasi kehtinud). Iga veebiteenuse korral on vaja eraldi uurida nõudeid ning otsustada, kumb sobib paremini.
 +
 
 +
'''Tähelepanu:''' Tarkvaraarendajad on mõnikord kasutanud isikutuvastamise juures LDAP-teenust sertifikaatide kehtivuskontrolli vahendina. '''See on teenuse väärkasutus ja sellisena keelatud,''' isegi kui see (mõnikord) annab korrektseid tulemusi. LDAP-andmeedastus ei ole turvatud, mistõttu saab vastuseid võltsida või muuta, ning LDAP kataloog võib sisaldada ka kehtetuid sertifikaate.
 +
 
 +
=== SSL/TLS seansis ===
 +
Eraldi teema on SSL/TLS seansi alguses kliendi antud ID-kaardi või Digi-ID sertifikaadi kehtivuse kontrollimine, kuna selle peaks läbi viima veebiserver, mitte -rakendus. Käesolev juhend käsitleb vaid [http://httpd.apache.org/ Apache httpd] ning [http://www.iis.net/ Microsoft IIS] servereid, kuigi see jutt võib rakenduda ka teistele.
 +
 
 +
Tühistusnimekirjade kasutamise korral töötab kõik hästi ning veebiserverid on suutelised neid iseseisvalt kasutama. Serveri konfigureerimiseks vaata [[Näiterakendused#Veebiserver|näiteseadistust]].
 +
 
 +
Kehtivuskinnituse kasutamisel on aga mõned lisatingimused, mida käsitlevad järgmised peatükid.
  
== Mobiil-ID ==
+
==== OCSP rakenduse tasemel ====
[[#Isikutuvastamine|Isikutuvastamise]] ja [[#Digitaalne_allkirjastamine|digitaalse allkirjastamise]] korral on võimalik kasutada ka [[#Mobiil-ID|Mobiil-ID]] abi. Protsessid on samad nagu kirjeldatud vastavates peatükkides, ent allkiri räsile või nonsile antakse läbi Mobiil-ID.
+
Kuigi nii Apache-l kui ka IIS-il on sisseehitatud vahendid OCSP kehtivuskinnituse küsimiseks, soovivad need, et vastuses oleks kaasas ka OCSP responderi sertifikaat. Viimast on vaja selleks, et saaks kontrollida vastusel olevat allkirja. Sertifikaadi lisamine on aga valikuline ning Sertifitseerimiskeskuse OCSP teenus seda ei tee. Seetõttu ei ole võimalik OCSP kehtivuskinnitust küsida vaikimisi vahenditega. Olemasolevatele seansihaldusvahenditele tuleb lisada tugi OCSP kehtivuskinnituse küsimiseks, et uue seansi alustades saaks veenduda, et kasutaja antud sertifikaat ikkagi kehtib.
  
Mobiil-ID on kasutatav ainult läbi [[#DigiDocService|DigiDocService]]'i—seega võib tekkida vajadus seni sellest sõltumatule teenusele DigiDocService tugi lisada. Samuti ollakse sellega kaasnevalt sunnitud usaldama teenusepakkujat. Vastutasuks on arendamise lihtsus—implementatsiooni detailid ning mobiilioperaatoritega suhtlemine on arendaja eest peidetud ning Mobiil-ID kasutamiseks piisab mõne parameetri andmisest vastavale teenusele.
+
Üks võimalus kehtivuse kontrolliks on kasutada [[Üldteavet_arendajatele#DigiDocService|DigiDocService]] meetodit <tt>CheckCertificate</tt>, mis tagastab parameetriks antud sertifikaadi OCSP staatuse. See on üks lihtsamaid lahendusi, ent nõuab ligipääsu DigiDocService-le (mis on tasuline) ning et veebirakenduses on vahendid SOAP-serveriga suhtlemiseks.
  
Mobiil-ID protokoll on asünkroonne, s.t esitatud päringule ei tule kohe vastus, vaid seda on vaja käia hiljem eraldi küsimas; kuna Mobiil-ID päringute käigus peavad kasutajad koode verifitseerima ning PIN-e sisestama, mis võib võtta omajagu aega, siis on otstarbekas võrguühenduse ressursid vahepeal vabastada. Seega kutsutakse esiteks välja päringumeetod ning seejärel käiakse perioodiliselt olekut kontrollimas.<ref name="digidocservice-spec-est">http://www.sk.ee/upload/files/DigiDocService_spec_est.pdf</ref><ref name="digidocservice-spec-eng">http://www.sk.ee/upload/files/DigiDocService_spec_eng.pdf</ref>
+
Alati on ka võimalik kasutada alternatiivseid vahendeid, mis suudavad suhelda Sertifitseerimiskeskuse OCSP-teenusega ning ei vaja selleks DigiDocService-i abi; neile tuleb aga responderi sertifikaat vastuse verifitseerimiseks käsitsi ette anda.
  
Vajalikud DigiDocService meetodid on:<ref name="digidocservice-spec-est" /><ref name="digidocservice-spec-eng" />
+
'''NB!''' Oma rakendustes '''peab alati''' OCSP-teenuse vastust verifitseerima, muidu on ründajal lihtne kehtivuskinnitust võltsida! Kui kasutada DigiDocService-teenust, siis see tehakse päringu käigus; alternatiivsete vahendite puhul peab seda suure tõenäosusega käsitsi tegema.
* <tt>MobileAuthenticate/GetMobileAuthenticateStatus</tt> - Mobiil-ID abil autentimiseks.
 
* <tt>MobileCreateSignature/GetMobileCreateSignatureStatus</tt> - Loob allkirjastatud dokumendi uues sessioonis.
 
* <tt>MobileSign/GetStatusInfo</tt> - Allkirjastab olemasoleva sessiooni dokumendid.
 
* <tt>GetMobileCertificate</tt> - Mobiil-ID teenuse olemasolu ja sertifikaatide pärimiseks. Kuna siin ei ole vaja kasutaja sekkumist, siis see operatsioon tehakse sünkroonselt.
 
  
Mobiil-ID ülevaadet näeb [[#Mobiil-ID|eID lühitutvustuses]] ning kasutamise näiteid [[#Mobiil-ID_3|avalduste kasutusmallis]]. Sertifitseerimiskeskuse näiterakendused Mobiil-ID jaoks on kättesaadavad [http://id.ee/index.php?id=30388 siit].
+
Näitekoodi DigiDocService-ga sertifikaadi kehtivuse kontrolliks leiab [[Näiterakendused#Veebivorm|veebivormist]] ja OpenSSL-i kasutavaks alternatiiviks [http://id.ee/index.php?id=30338 ID.ee näiterakendusest].
 +
 
 +
==== Autentimise OCSP ====
 +
Sertifitseerimiskeskus pakub lisaks "tavalisele" OCSP teenusele ka autentimise OCSP teenust: see on mõeldud kasutamiseks süsteemidesse sisselogimisel. Autentimise OCSP ei kanna kehtivuskinnituse päringuid turvalogisse, mistõttu puudub hilisem tõestus sel hetkel kehtivuse kohta. Samuti on hinnakiri teistsuguse ülesehitusega: tasuma peab erinevate sertifikaatide eest, mille olekut päritakse, mitte päringute hulga eest. Seetõttu on ta sobilik väikese hulga kasutajatega süsteemide jaoks, ent mitte avalike veebiteenuste jaoks.<ref>https://www.sk.ee/teenused/kehtivuskinnituse-teenus/autentimise-ocsp/</ref>
 +
 
 +
Autentimise OCSP tagastab oma vastustes ka responderi sertifikaadi, nii et seda saab kasutada Apache ja IIS-i sisseehitatud OCSP-kehtivuskontrolli vahenditega. Seda tasub teha aga vaid tingimusel, kui eelmises lõigus mainitud hinnakirja eripärad on vastuvõetavad, kuna mitme unikaalse kasutaja korral võib teenus osutuda kallimaks tavalisest OCSP-st.
 +
 
 +
Autentimise OCSP-l puudub ka test-teenus, mistõttu tuleb arendamisel/testimisel saata päringuid ''live''-responderile.
  
 
== Isikuandmete faili kasutamine ==
 
== Isikuandmete faili kasutamine ==
ID-kaardile talletatud [[%C3%9Cldteavet_arendajatele#Isikuandmete_faili_kasutamine|isikuandmete faili]] ei oska ükski DigiDoc teekidest lugeda. Sellepärast on tegu võrdlemisi madala taseme operatsiooniga, mida peab iga arendaja käsitsi tegema. Kuna olulisemad väljad isikuandmete failist (nimi, isikukood ning viimasest tuletatav info) on olemas ka sertifikaadi peal, siis ehk piisab rakenduse jaoks sertifikaadi lugemisest, mida toetavad mitmed DigiDoc teegid.
+
ID-kaardile talletatud [[%C3%9Cldteavet_arendajatele#Isikuandmete_faili_kasutamine|isikuandmete faili]] ei oska ükski DigiDoc teekidest lugeda. Sellepärast on tegu võrdlemisi madala taseme operatsiooniga, mida peab iga arendaja käsitsi tegema. Kuna olulisemad väljad isikuandmete failist (nimi, isikukood ning viimasest tuletatav info) on olemas ka sertifikaadi peal, siis üldjuhul piisab rakenduse jaoks sertifikaadi lugemisest, mida toetavad mitmed DigiDoc teegid.
  
 
''Märkus:'' Digi-ID-l on küll isikuandmete fail olemas, et täidetud on vaid dokumendi number; isikukood koosneb tühikutest ning kõikidel teistel väljadel on üks 0-bait.
 
''Märkus:'' Digi-ID-l on küll isikuandmete fail olemas, et täidetud on vaid dokumendi number; isikukood koosneb tühikutest ning kõikidel teistel väljadel on üks 0-bait.
179. rida: 183. rida:
 
Kui aga siiski on vajadus isikuandmete faili lugeda, siis selle jaoks on vähe võimalusi. Tuleb kas kaardiga otse suhelda või kasutada mõnda teeki, mis seda minimaalsel määral abstraheerib (näiteks [http://www.opensc-project.org/opensc OpenSC]). Viimasega on aga see probleem, et sellised teegid on enamasti vaid C jaoks ning nende kasutamine näiteks Javas või .NET-is on keerulisem kui kaardiga otse suhtlemine.
 
Kui aga siiski on vajadus isikuandmete faili lugeda, siis selle jaoks on vähe võimalusi. Tuleb kas kaardiga otse suhelda või kasutada mõnda teeki, mis seda minimaalsel määral abstraheerib (näiteks [http://www.opensc-project.org/opensc OpenSC]). Viimasega on aga see probleem, et sellised teegid on enamasti vaid C jaoks ning nende kasutamine näiteks Javas või .NET-is on keerulisem kui kaardiga otse suhtlemine.
  
Mõnes kindlas olukorras võib piisata ka [[#eidenv|eidenv]] rakenduse kasutamisest <tt>-x</tt> võtmega.
+
Mõnes kindlas olukorras võib piisata ka [[Üldteavet_arendajatele#eidenv|eidenv]] rakenduse kasutamisest <tt>-x</tt> võtmega.
  
 
Veebirakendustes kasutaja isikuandmeid lugeda ei saa, kuna uus veebilehitseja plugin seda ei võimalda.
 
Veebirakendustes kasutaja isikuandmeid lugeda ei saa, kuna uus veebilehitseja plugin seda ei võimalda.
272. rida: 276. rida:
  
 
Näidet isikuandmete lugemisest on võimalik näha [[Näiterakendused#Avalduste_rakendus|avalduste rakenduses]].
 
Näidet isikuandmete lugemisest on võimalik näha [[Näiterakendused#Avalduste_rakendus|avalduste rakenduses]].
 
== eID abirakendused: eidenv, cdigidoc, digidoc-tool, jdigidoc ==
 
=== eidenv ===
 
Käsurea rakendus <tt>eidenv</tt> kuvab kaardil olevad isikuandmed, asendades endist IDUtil rakendust. Seda levitatakse [http://www.opensc-project.org/opensc OpenSC] tarkvara koosseisus ning on ka ID-kaardi baastarkvara pakis. <tt>eidenv</tt> lähtekood on saadaval aadressil: http://www.opensc-project.org/opensc/browser/OpenSC/src/tools/eidenv.c
 
 
Kasutades <tt>-x</tt> võtit käivitab argumendiks antud programmi keskonnas, kuhu on lisatud <tt>ESTEID_*</tt> muutujad samade andmetega. Näiteks test-ID-kaardil on nendeks:
 
<pre>
 
$ eidenv -x /usr/bin/printenv
 
...
 
ESTEID_SURNAME=MÄNNIK
 
ESTEID_GIVEN_NAMES1=MARI-LIIS
 
ESTEID_GIVEN_NAMES2=
 
ESTEID_SEX=N
 
ESTEID_CITIZENSHIP=EST
 
ESTEID_DATE_OF_BIRTH=01.01.1971
 
ESTEID_PERSONAL_ID=47101010033
 
ESTEID_DOCUMENT_NR=AS0010876
 
ESTEID_EXPIRY_DATE=01.02.2017
 
ESTEID_PLACE_OF_BIRTH=EESTI / EST
 
ESTEID_ISSUING_DATE=01.02.2012
 
ESTEID_PERMIT_TYPE=
 
ESTEID_REMARK1=
 
ESTEID_REMARK2=
 
ESTEID_REMARK3=
 
ESTEID_REMARK4=
 
</pre>
 
Tänu selle on võimalik luua erinevaid isikuandmeid kasutavaid rakendusi ilma, et oleks vaja kaardiga otse suhelda - need kasutavad lihtsalt vastavat keskkonnamuutujat. Sellist rakendust on aga väga lihtne ära petta, kuna väärtuste allikat ei saa kontrollida. Ent mitte-kriitilistes rakendustes ei tohiks see probleemiks olla.
 
 
Et saada rohkem infot rakenduse kohta, tuleb see käivitada <tt>-h</tt> või <tt>--help</tt> võtmega.
 
 
=== cdigidoc, digidoc-tool, jdigidoc ===
 
<tt>cdigidoc</tt>, <tt>digidoc-tool</tt> ning <tt>jdigidoc</tt> (mitte segi ajada jdigidoc-teegiga) on rakendused, mis lubavad teha põhilisi eID toiminguid. Kõik need demonstreerivad omalt poolt kasutatava teegi (vastavalt libdigidoc, libdigidocpp ning jdigidoc) võimalusi ning on heaks näitekoodi allikaks.
 
 
Et saada juhendeid rakenduse kasutamiseks, piisab nende käivitamisest ilma käsureavõtmeteta, mille peale kuvatakse abitekst. <tt>Cdigidoc</tt>'i ning <tt>jdigidoc</tt>'i rakendustest saab rohkem lugeda ka vastava teegi dokumentatsioonist.<ref name="cdigidoc-doc">http://id.ee/public/SK-CDD-PRG-GUIDE.pdf</ref><ref name="jdigidoc-doc">http://id.ee/public/SK-JDD-PRG-GUIDE.pdf</ref>
 
 
== Tehnilised märkused ja tähelepanekud ==
 
=== Rünne täidistusoraaklile ===
 
2012. aastal tõhustati rünnet, mis töötab mitmel laialtlevinud krüptograafiaseadmel, s.h Eesti eID dokumentidel. Selle ründe käigus on võimalik eID dokumendil olevale sertifikaadile krüpteeritud teksti lahti krüpteerida või luua isikutuvastusallkiri (selle ründega seaduslikult siduvat allkirja ei saa võltsida). See tähendab, et rünne toimib ainult esimese, isikutuvastusvõtmepaari vastu. Rünne töötab, kuna Eesti eID dokumendid kasutavad PKCS#1 v1.5 täidist (''padding'').<ref name="padding-oracle-attack">R. Bardou, R. Focardi, Y. Kawamoto, L. Simionato, G. Steel, J. Tsay. ''Efficient Padding Oracle Attacks on Cryptographic Hardware. Cryptology ePrint Archive, Report 2012/417.'' http://eprint.iacr.org/2012/417</ref>
 
 
Rünne toimib ainult siis, kui eksisteerib rünnatavat eID dokumenti kasutav täidistusoraakel (''padding oracle''). Täidistusoraakel on osapool, kes võtab ründaja käest vastu mingi sõnumi, üritab seda endaga seotud eID dokumendiga lahti krüpteerida ning vastab, kas see õnnestus või ei (ning mitte midagi enamat -- oraakel ei tagasta lahti krüpteeritud sõnumit). Oraakliks võib olla näiteks mõni kasutaja arvutis jooksev mitte-pahatahtlik tarkvara (kui tegu oleks kahjurvaraga, siis saaks ID-kaarti palju lihtsamalt rünnata), mõni veebiteenus (kui rünnatakse teenusepakkuja digitemplit) vms.
 
 
Ründaja saab kasutada oraaklilt saadud vastust, et oraakli eID dokumendile suunatud teksti lahti krüpteerida või võltsida isikutuvastusallkirja. Enne 2011. aastat väljaantud ID-kaartidega kulub selleks keskmiselt vastavalt 11,5 tundi ja 49 000 oraaklipäringut (mediaaniga 3,5 tundi ja 14 500 päringut) või 48 tundi ja 203 000 päringut (mediaaniga 30 tundi ja 126 500 päringut). Uuemate kaartidega kulub keskmiselt vastavalt 27 tundi ja 28 300 päringut (mediaaniga 10 tundi ja 10 800 päringut) või 103 tundi ja 109 000 päringut (mediaaniga 65 tundi ja 69 000 päringut).<ref name="padding-oracle-attack" />
 
 
Kirjutamise hetkel ei ole selline rünne aga teostatav, kuna ei leidu sobivaid oraakleid. '''Siinkohal tulebki arendajatel ettevaatlik olla, et nad ei kirjutaks tarkvara, mis täidaks eespool toodud tingimusi''' -- ründe jaoks piisab sellest, et tarkvara vastab, kas lahti krüpteerimine õnnestus või ei.
 
 
Kaks ründe autorit, Yusuke Kawamoto and Joe-Kai Tsay, käisid oma tööd ka Eestis esitlemas ning video sellest on nähtav [http://uttv.ee/naita?id=13146 UTTV-s].
 
 
=== USB õigused ===
 
Linuxi all sõltub pcscd pakk libccid pakist, mis paigaldab ka vajalikud udev reeglid, et pcscd deemon saaks kaardilugejatega suhelda. Kuigi enamasti töötab kõik hästi, võib juhtuda, et deemon siiski ei saa vajalikke õiguseid.
 
 
Lihtsaim lahendus sellest mööda saamiseks on käsitsi vajalike õiguste andmine. Selleks tuleb teada saada, mis siinil kaardilugeja on ning mis on selle seadmenumber.
 
<pre>
 
$ lsusb
 
...
 
Bus 002 Device 003: ID 058f:9520 Alcor Micro Corp. EMV Certified Smart Card Reader
 
</pre>
 
 
Ehk käesoleval juhul on kaardilugeja siinil 2 seade number 3. Seega tuleb teha:
 
<pre>
 
# chown :pcscd /dev/bus/usb/002/003
 
# chmod g+w /dev/bus/usb/002/003
 
</pre>
 
Selle tulemusena peaks <tt>ls -l</tt> kuvama <tt>crw-rw-r-- 1 root pcscd ... 003</tt>.
 
 
See lahendus küll töötab, ent pole väga hea—näiteks seadmenumbri muutudes kaovad õigused ära. udev või mõni analoogne automaatne vahend on parem, ent eelolev lahendus on pakutud juhuks, kui muu on välistatud.
 
 
=== Java ja libpcsclite ===
 
Java üritab kaardilugejatega töötamiseks kasutada /usr/lib/libpcsclite.so, mis Debiani/Ubuntu peal pole selles kohas. Asja töötamiseks tuleb luua sümlink:<ref>http://www.opensc-project.org/opensc/wiki/FrequentlyAskedQuestions#Q:IhaveasmartcardreaderinstalledbutaJavaapplicationdoesnotseeit</ref>
 
<pre>
 
sudo ln -s /lib/libpcsclite.so.1 /usr/lib/libpcsclite.so      # Ubuntu
 
sudo ln -s /usr/lib/libpcsclite.so.1 /usr/lib/libpcsclite.so  # Debian
 
</pre>
 
  
 
== Allikaviited ==
 
== Allikaviited ==
 
<references />
 
<references />

Viimane redaktsioon: 6. juuni 2016, kell 15:45

Uute eID rakenduste loomine

Järgnev osa räägib uute eID rakenduste loomisest. Enne seda tasub kindlasti tutvuda ka üldteabega arendajatele.

Isikutuvastamine

EID kaartidel on sertifikaat digitaalseks isikutuvastuseks. Kui kasutaja suudab tõestada, et tal on ligipääs selle sertifikaadi salajasele võtmele, siis usume, et tegu on sertifikaadi omanikuga.

Isiku tuvastamine toimub vastavalt allolevale (lihtsustatud) protokollile:

  1. Kasutaja esitab süsteemile mingi sertifikaadi ning väidab, et ta on selle omanik.
  2. Süsteem genereerib juhusliku, ühekordse arvu ehk nonsi (nonce), mis antakse kasutajale isikutuvastusvõtmega allkirjastamiseks.
  3. Kasutaja lukustab lahti kaardil oleva isikutuvastuseks mõeldud salajase võtme, kasutades selleks PIN1-koodi.
  4. Kaardile antakse nonss, mille see allkirjastab, ning kaardilt loetakse tulemus, mis edastatakse süsteemile.
  5. Süsteem kontrollib, kas antud allkiri verifitseerub sertifikaadil oleva avaliku võtmega.
  6. Süsteem kontrollib sertifikaadi kehtivust (vt Sertifikaatide kehtivuse kontroll).

Kui kõik õnnestus, siis võib eeldada, et kasutaja on tõesti sertifikaadi omanik -- ja kuna sertifikaadil on isiku nimi ning isikukood, siis on ka teada omaniku identiteet. Kuigi tegelikult võib olla kasutaja lihtsalt keegi, kellel on sertifikaadi omaniku kaart ning teab selle PIN1, ei saa seda enam kuidagi kontrollida.

Isikutuvastamise näitekoodi näeb eraldiseisva rakendusena ning ka avalduste kasutusmalli koosseisus.

Veebis

Veebis toimub isiku tuvastamine SSL/TLS käepigistuse (handshake) käigus, kus kontrollitakse ka kliendi sertifikaati. Protokolli põhjalik kirjeldus on kättesaadav Wikipediast, ent lühidalt kokkuvõetuna tehakse sama, mis eelnevalt kirjeldatud, kuid nonsi asemel antakse allkiri kõigi eelnevate sõnumite räsile. Kuna sõnumid sisaldavad endas juhuarve, siis on ka nende räsi juhuslik.

Siin tuleb arvestada ka sertifikaatide kehtivuse kontrolli SSL/TLS seansis.

Veebis isiku tuvastamist tehakse näitekoodis veebivormil.

SSL/TLS taasläbirääkimise viga

2009. aastal tuvastati SSL/TLS protokollis viga, millega sai ühendustesse ründaja valitud teksti sisestada. [1][2] Selle tulemusena täiendati SSL/TLS spetsifikatsioonis taasläbirääkimist (renegotiation), ent need täiendused ei olnud tagasiühilduvad.[3] Seetõttu pole vanemad SSL/TLS kliendid ja ka veebilehitsejad suutelised taasläbirääkima täiendatud versiooni kasutava serveriga.

Kui algatada SSL/TLS seanss ilma kasutaja sertifikaati küsimata, s.t isikut tuvastamata, siis hiljem on selle tegemiseks vaja läbi viia taasläbirääkimised -- näiteks kui kasutaja külastab veebilehte, kasutades HTTPS-protokolli ning hiljem soovib end ID-kaardiga sisse logida, tuleb teha taasläbirääkimine. Vanemad veebilehitsejad seda aga uue protokolli kohaselt ei oska. Kui siiski on soov sellist olukorda võimaldada, tuleb luua kaks eraldiseisvat ühenduspunkti: esimene, mis teeb "puhast" SSL/TLSi, ja teine, mis küsib kasutaja sertifikaati.

Kui isikut tuvastav server on eraldiseisvas ühenduspunktis, siis sellega seanssi alustades küsitakse kasutajalt kohe isikutuvastuse sertifikaati ning hiljem taasläbirääkimisi pole vaja teha.

Eraldi ühenduspunktid peaksid olema erinevate IP-aadresside peal või vähemalt kasutama erinevat porti. Eraldi virtuaalhostidest ei piisa, kuna enne luuakse SSL/TLS seanss ning alles siis vaadatakse, millist virtuaalhosti kasutada.

Mobiil-ID-ga

Isikutuvastamine Mobiil-ID abil toimub järgmiselt:[4][5][6]

  1. Luuakse tavaline SSL/TLS seanss ilma kliendisertifikaati küsimata.
  2. Kasutaja sisestab oma telefoninumbri ja/või isikukoodi ning viimase välja andnud riigi koodi. Need andmed edastatakse teenusele DigiDocService MobileAuthenticate päringuga.
  3. DigiDocService kontrollib OCSP-protokolli vahendusel, et kasutaja Mobiil-ID isikutuvastuse sertifikaat kehtib.
  4. DigiDocService teeb samaaegselt järgmist:
    • Saadab mobiiloperaatorile isikutuvastuse päringu (mis edastab selle kasutaja telefonile);
    • Tagastab kontrollkoodi ja kasutaja sertifikaadi.
      • NB! Teenus tagastab kõigest tuvastamisel oleva isiku sertifikaadi -- see ei tähenda veel, et kasutaja oleks autenditud!
  5. Rakendus kuvab kasutajale neljakohalise isikutuvastuspäringu kontrollkoodi.
  6. Rakendus hakkab perioodiliselt käima DigiDocService'i käest isikutuvastuse olekut küsimas GetMobileAuthenticateStatus päringuga.
    • Olekupäring on võimalik teha ka sünkroonselt, s.t DigiDocService hoiab ühendust avatuna ning ei tagasta midagi enne, kui mobiiltelefonilt on tulnud vastus.
  7. Kasutaja telefonil kuvatakse teade isikutuvastuspäringu kohta
  8. Kasutaja veendub, et telefonil kuvatav kontrollkood langeb kokku rakenduse poolt kuvatavaga ning sisestab Mobiil-ID PIN1.
  9. Teenuse poolt saadetud väljakutse (challenge) allkirjastatakse SIM-kaardil oleva salajase võtmega ning tulemus saadetakse mobiiloperaatorile, mis edastab selle DigiDocService'ile.
  10. Järgmine kord, kui rakendus tuleb teenuselt päringu olekut küsima, vastab teenus, et kasutaja on autenditud ning tagastab allkirja.

Kasutamise näiteid näeb avalduste kasutusmallis ning SK näiterakenduse leiab siit.

Digitaalne allkirjastamine

Alates 2015. aastast luuakse digitaalseid allkirju BDOC vormingus. Kuni 2014. aasta lõpuni oli kasutusel DDOC formaat . Siit on näha, millised teegid, milliseid formaate toetavad. DigiDocService toetab nii BDOC kui DDOC vormingut.[7]

Allkirjastatud faili loomine

Sõltumata allkirja vormingust on nii teekide kui ka DigiDocService puhul lähenemine sama:

  1. luuakse konteiner,
  2. lisatakse allkirjastatavad failid,
  3. üle andmete genereeritakse räsi,
  4. räsi allkirjastatakse osapoolte salajaste võtmetega,
  5. allkirjastaja sertifikaadile küsitakse kehtivuskinnitus (tühistusnimekirja kontrollimisest on vähe, vt Digiallkirjade andmine ja Sertifikaatide kehtivuse kontroll) ning
  6. allkiri ja kinnitus lisatakse konteinerisse.

Veebirakendustes allkirjastades toimub kõik allkirjastamise-eelne ning -järgne tegevus samamoodi nagu kohaliku allkirjastamise korral, ent räsi allkirjastamine (samm 4) toimub kliendi veebibrauseris. Selle jaoks on loodud JavaScripti teek, mille programmeerimisliides (API) on ühtne ning võimaldab erinevaid allkirjastamispluginaid – sõltumata kasutaja operatsioonisüsteemist ja brauserist – ühte moodi kasutada. Täpsem info siit.

Hiljem allkirja kontrollides tuleb veenduda, et konteineris olevate dokumentide räsid langevad kokku allkirjastatud räsidega ning allkirjad räsidel ja kehtivuskinnitustel on korrektsed (selleks kasutatakse allkirjastaja ning kehtivuskinnituse väljastaja sertifikaatidel olevaid avalikke võtmeid).

Selguse ja turvalisuse tagamiseks peab iga rakendus, kus on digiallkirjastamise funktsioon, vastama kahele nõudele:[8]

  1. Enne allkirjastamist peab kasutaja saama mõistlikul moel andmetega tutvuda.
  2. Pärast allkirjastamist saab kasutaja kontrollida, millele tema allkiri anti, ehk tal on ligipääs DigiDoc-konteinerile koos esialgsete allkirjastatud andmete ja allkirjadega.

Kasutajatoe abi

  • Sagedane on veebilehitsejates allkirjastamise ebaõnnestumine mille peamiseks põhjuseks on veebilehitseja lisamooduli (plugina) keelatud olek. E-teenuste pakkujatel on soovitatav lisada allkirjastamise lisamooduli staatuse kontroll enne kui kasutaja alustab e-vormi täitmist. Näidisena on GitHubi (https://github.com/open-eid/hwcrypto.js/wiki/FAQ) lisatud skript mis teostab kontrolli allkirjastamise plugina kohta.

Juhul kui plugin ei ole aktiivne siis teavitada sellest kasutajat õige sõnumiga. Selliselt on võimalus tõsta teenuse kasutamiskogemust.

Veateate näidis:
Allkirjastamine ebaõnnestus!
Kontrolli kas allkirjastamise plugin on lubatud.
Juhised leiate veebist http://www.id.ee/index.php?id=36636


Dokumentide digitaalset allkirjastamist on demonstreeritud nii eraldiseisva utiliidina kui ka avalduste esitamise kasutusmallis - nii veebis, kasutades DigiDocService-teenust või SWIG mähkurit, kui ka töölauarakenduses.

Allkirja kontrollimist on demonstreeritud eraldiseisvas rakenduses, avalduste rakenduses ja avaldusi töötlevas teenuses.

Mobiil-ID-ga

Mobiil-ID-ga saab allkirjastada dokumente kahte moodi:[4][5][6]

  1. Saadame DigiDocService-teenusele dokumendi, mispeale alustatakse uus seanss, kus luuakse ainult seda dokumenti sisaldav allkirjastatud konteiner, mis tagastatakse päringu esitajale. Selle jaoks tuleb kasutada päringuid MobileCreateSignature ja GetMobileCreateSignatureStatus. See on hea olukorras, kus meil ei ole DigiDocService vaja muuks kui dokumendi allkirjastamiseks.
  2. Allkirjastame olemasolevas seansis loodud konteineri päringutega MobileSign ja GetStatusInfo. Seda lähenemist tasub kasutada siis, kui DigiDocService seanssi kasutatakse ka muude operatsioonide tegemiseks ning konteineri Mobiil-ID-ga allkirjastamine on vaid üks osa sellest.

Üldiselt toimub Mobiil-ID-ga allkirjastamine samamoodi nagu isikutuvastamine, järgmiste erinevustega:

  • Teenusele ei saadeta MobileAuthenticate ja GetMobileAuthenticateStatus, vaid ülaltoodud päringud.
  • Teenusele saadetakse allkirjastatavad dokumendid või nende räsid ning Mobiil-ID allkirja küsitakse hoopis nende räsile, mitte väljakutsele.
  • Allkiri antakse digitaalallkirjastamise salajase võtmega, mitte isikutuvastamise omaga. Sellest tulenevalt kontrollib ning tagastab DigiDocService allkirjastamisertifikaadi ning kasutaja peab sisestama PIN2, mitte PIN1.

Nende toimingute tulemusel moodustab DigidocService-teenus allkirjastatud konteineri, mille rakendus saab alla laadida. Kui alguses saadeti teenusele vaid allkirjastatavate dokumentide räsid, siis lisasammuna peab konteineris asendama räsid dokumentide endiga.

Kasutamise näiteid näeb avalduste kasutusmallis ning SK näiterakenduse leiab siit.

Krüpteerimine

EID kontekstis toimub krüpteerimine vastavalt standardis XML Encryption Syntax and Processing esitatud põhimõtetele, et saata salastatud faile kindlatele adressaatidele. Küll kasutatakse DigiDoc-rakenduste spetsiifilist lähenemist, kus failid lisatakse enne krüpteerimist DIGIDOC-XML konteinerisse, mis võib, kuid ei pea olema allkirjastatud.

Andmed pannakse DDOC-konteinerisse, mis krüpteeritakse sümmeetrilise algoritmiga (128-bitise võtmega AES), andes tulemuseks CDOC-konteineri. Krüpteerimisel kasutatud võti krüpteeritakse saajate isikutuvastus­sertifikaatide avalike võtmetega ning tulemused lisatakse CDOC-konteinerisse. Samuti lisatakse sinna metaandmed krüpteeritud failide kohta, et kasutaja näeks, mis seal sees on. Kuna metaandmeid saavad näha kõik huvilised ilma konteinerit dekrüpteerimata, on soovitatav kasutada ettevaatust ja veenduda, et metaandmetesse ei satuks tundlikku teavet.

Konteineri kättesaamisel kasutab adressaat oma isikutuvastuse sertifikaadi salajast võtit, et saada kätte AES-võti, mille abil saab failid lahti krüpteerida.

Sellist krüpteerimist saab kasutada vaid lühiajaliselt, näiteks andmete transportimiseks. Kuna krüpteeritud andmeid saavad avada ainult saajateks märgitud isikud oma krüpteerimise ajahetkel kehtivate sertifikaatidega, siis ei sobi see lahendus pikaajaliseks arhiveerimiseks -- sertifikaatide aegumisel asendatakse need kasutaja kaardil uutega ning vana salajast võtit pole enam võimalik kasutada.[9] See aga muudab konteineri jäädavalt suletuks. Samuti tuleb meeles pidada, et ID-kaardi jaoks krüpteeritud konteinerit ei saa avada sama isik oma Digi-ID-ga.

Krüpteerimist toetavad teegid libdigidoc (ja seega ka libdigidoccom) ning jdigidoc. DigiDocService-teenust pole võimalik krüpteerimiseks kasutada, aga see poleks ka mõistlik, sest sel juhul tuleks salastatavad andmed enne saata SK-le. Krüpteerimist demonstreeritakse avaldusi töötlevas teenuses ning dekrüpteerimist avalduste rakenduses.

Tähelepanu: luues tarkvara, mis tegeleb andmete lahti krüpteerimisega, tuleb kindlasti silmas pidada rünnet täidistusoraaklile.

Sertifikaatide pärimine LDAP-ist

Selleks et transpordivõtit saaks krüpteerida saaja avalike võtmetega, on vaja viimased kusagilt hankida. Selleks tarbeks on Sertifitseerimiskeskusel LDAP-teenus, mille abil leiab[10]

  • SK sertifitseerijate sertifikaadid ja kehtivad tühistusnimekirjad,
  • kehtivad isikutunnistustele väljastatud sertifikaadid ning
  • kõik väljastatud asutuse sertifikaadid.

Teenus asub aadressil ldap.sk.ee. Suhtlemiseks tuleb kasutada protokolli LDAPv3; juurdepääs teenusele on vaba ja tasuta.[11]

Isikusertifikaadi leidmiseks tuleb päringusse sisestada täpne Common Name (kujul "perenimi,eesnimi,isikukood") või isikukood. Mustri järgi otsimine on keelatud. Näiteks (järgmised päringud ei tagasta midagi, kuna testsertifikaate nendes kataloogiharudes ei hoita—siin võib testimiseks kasutada enda isikukoodi):

# Linux
ldapsearch -x -h ldap.sk.ee -b ou=Authentication,o=ESTEID,c=EE "(cn=MÄNNIK,MARI-LIIS,47101010033)" userCertificate
ldapsearch -x -h ldap.sk.ee -b ou=Authentication,o=ESTEID,c=EE "(serialNumber=47101010033)" userCertificate

# Windows - kui sisestada järgmised päringud Internet Explorer'i aadressiribale, siis
#           käivitatakse Contacts rakendus, mille "IDs" saki alt leiab sertifikaadi(d)
ldap://ldap.sk.ee:389/ou=Authentication,o=ESTEID,c=EE??sub?(cn=MÄNNIK,MARI-LIIS,47101010033)
ldap://ldap.sk.ee:389/ou=Authentication,o=ESTEID,c=EE??sub?(serialNumber=47101010033)

Täpne kataloogistruktuur on nähtav SK repositooriumis.

Päringut esitades tuleb silmas pidada, et ühel isikul võib LDAP-is olla mitu erinevat sertifikaati (nt ID-kaart ja Digi-ID). Samuti tuleb silmas pidada, et LDAP pole turvaline, mistõttu on võimalik ründajal sertifikaat välja vahetada enda omaga ning alati tuleb tagastatud sertifikaat üle kontrollida: kellele see on väljastatud, kelle poolt jne.

Sertifikaatide kehtivuse kontroll

Sertifikaadi kehtivust tuleb eraldi kontrollida ka väljaandja käest; ei piisa vaid sertifikaadil oleva kehtivuse algus- ja lõppkuupäeva kontrollist, kuna sertifikaadi väljaandja võib selle teatud põhjustel varem kehtetuks tunnistada, peatada või peatamist lõpetada.

Märkus: Järgnev jutt kehtib vaid ID-kaardi ning Digi-ID puhul: Mobiil-ID sertifikaati kontrollib DigiDocService ning SSL/TLS seansis isikutuvastamine käib rakenduse tasemel.

Kehtivuse kontrolliks on kaks valikut:

  • Tühistusnimekiri (Certificate Revocation List) ehk CRL, mis on perioodiliselt allalaetav nimekiri kõikidest kehtetuks tunnistatud sertifikaatidest. AS Sertifitseerimiskeskuse tühistusnimekirjade kasutamine on tasuta.
  • Kehtivuskinnitus (Online Certificate Status Protocol) ehk OCSP, mis esitab päringu sertifikaadi kehtivuse kohta OCSP-serverile (edaspidi responder), mis annab vastuse reaalajas. AS Sertifitseerimiskeskuse kehtivuskinnituse teenuse kasutamine on tasuline.[12]

Kuigi tühistusnimekirjade kasutamine on tasuta ning neil on eelis käideldavuse osas (kui CRL-serverid muutuvad kättesaadamatuks, siis on ikkagi teada viimane kord allalaetud seis), ei ole nendes olev info reaalajaline esitus sertifikaatide kehtivusest. Värskeima kehtivusinfo saamiseks tuleb kasutada kehtivuskinnituse teenust, mis aga on tasuline ning responderi mitte-kättesaadavuse korral puudub igasugune info sertifikaatide kohta (ka mitte mõni hetk tagasi kehtinud). Iga veebiteenuse korral on vaja eraldi uurida nõudeid ning otsustada, kumb sobib paremini.

Tähelepanu: Tarkvaraarendajad on mõnikord kasutanud isikutuvastamise juures LDAP-teenust sertifikaatide kehtivuskontrolli vahendina. See on teenuse väärkasutus ja sellisena keelatud, isegi kui see (mõnikord) annab korrektseid tulemusi. LDAP-andmeedastus ei ole turvatud, mistõttu saab vastuseid võltsida või muuta, ning LDAP kataloog võib sisaldada ka kehtetuid sertifikaate.

SSL/TLS seansis

Eraldi teema on SSL/TLS seansi alguses kliendi antud ID-kaardi või Digi-ID sertifikaadi kehtivuse kontrollimine, kuna selle peaks läbi viima veebiserver, mitte -rakendus. Käesolev juhend käsitleb vaid Apache httpd ning Microsoft IIS servereid, kuigi see jutt võib rakenduda ka teistele.

Tühistusnimekirjade kasutamise korral töötab kõik hästi ning veebiserverid on suutelised neid iseseisvalt kasutama. Serveri konfigureerimiseks vaata näiteseadistust.

Kehtivuskinnituse kasutamisel on aga mõned lisatingimused, mida käsitlevad järgmised peatükid.

OCSP rakenduse tasemel

Kuigi nii Apache-l kui ka IIS-il on sisseehitatud vahendid OCSP kehtivuskinnituse küsimiseks, soovivad need, et vastuses oleks kaasas ka OCSP responderi sertifikaat. Viimast on vaja selleks, et saaks kontrollida vastusel olevat allkirja. Sertifikaadi lisamine on aga valikuline ning Sertifitseerimiskeskuse OCSP teenus seda ei tee. Seetõttu ei ole võimalik OCSP kehtivuskinnitust küsida vaikimisi vahenditega. Olemasolevatele seansihaldusvahenditele tuleb lisada tugi OCSP kehtivuskinnituse küsimiseks, et uue seansi alustades saaks veenduda, et kasutaja antud sertifikaat ikkagi kehtib.

Üks võimalus kehtivuse kontrolliks on kasutada DigiDocService meetodit CheckCertificate, mis tagastab parameetriks antud sertifikaadi OCSP staatuse. See on üks lihtsamaid lahendusi, ent nõuab ligipääsu DigiDocService-le (mis on tasuline) ning et veebirakenduses on vahendid SOAP-serveriga suhtlemiseks.

Alati on ka võimalik kasutada alternatiivseid vahendeid, mis suudavad suhelda Sertifitseerimiskeskuse OCSP-teenusega ning ei vaja selleks DigiDocService-i abi; neile tuleb aga responderi sertifikaat vastuse verifitseerimiseks käsitsi ette anda.

NB! Oma rakendustes peab alati OCSP-teenuse vastust verifitseerima, muidu on ründajal lihtne kehtivuskinnitust võltsida! Kui kasutada DigiDocService-teenust, siis see tehakse päringu käigus; alternatiivsete vahendite puhul peab seda suure tõenäosusega käsitsi tegema.

Näitekoodi DigiDocService-ga sertifikaadi kehtivuse kontrolliks leiab veebivormist ja OpenSSL-i kasutavaks alternatiiviks ID.ee näiterakendusest.

Autentimise OCSP

Sertifitseerimiskeskus pakub lisaks "tavalisele" OCSP teenusele ka autentimise OCSP teenust: see on mõeldud kasutamiseks süsteemidesse sisselogimisel. Autentimise OCSP ei kanna kehtivuskinnituse päringuid turvalogisse, mistõttu puudub hilisem tõestus sel hetkel kehtivuse kohta. Samuti on hinnakiri teistsuguse ülesehitusega: tasuma peab erinevate sertifikaatide eest, mille olekut päritakse, mitte päringute hulga eest. Seetõttu on ta sobilik väikese hulga kasutajatega süsteemide jaoks, ent mitte avalike veebiteenuste jaoks.[13]

Autentimise OCSP tagastab oma vastustes ka responderi sertifikaadi, nii et seda saab kasutada Apache ja IIS-i sisseehitatud OCSP-kehtivuskontrolli vahenditega. Seda tasub teha aga vaid tingimusel, kui eelmises lõigus mainitud hinnakirja eripärad on vastuvõetavad, kuna mitme unikaalse kasutaja korral võib teenus osutuda kallimaks tavalisest OCSP-st.

Autentimise OCSP-l puudub ka test-teenus, mistõttu tuleb arendamisel/testimisel saata päringuid live-responderile.

Isikuandmete faili kasutamine

ID-kaardile talletatud isikuandmete faili ei oska ükski DigiDoc teekidest lugeda. Sellepärast on tegu võrdlemisi madala taseme operatsiooniga, mida peab iga arendaja käsitsi tegema. Kuna olulisemad väljad isikuandmete failist (nimi, isikukood ning viimasest tuletatav info) on olemas ka sertifikaadi peal, siis üldjuhul piisab rakenduse jaoks sertifikaadi lugemisest, mida toetavad mitmed DigiDoc teegid.

Märkus: Digi-ID-l on küll isikuandmete fail olemas, et täidetud on vaid dokumendi number; isikukood koosneb tühikutest ning kõikidel teistel väljadel on üks 0-bait.

Kui aga siiski on vajadus isikuandmete faili lugeda, siis selle jaoks on vähe võimalusi. Tuleb kas kaardiga otse suhelda või kasutada mõnda teeki, mis seda minimaalsel määral abstraheerib (näiteks OpenSC). Viimasega on aga see probleem, et sellised teegid on enamasti vaid C jaoks ning nende kasutamine näiteks Javas või .NET-is on keerulisem kui kaardiga otse suhtlemine.

Mõnes kindlas olukorras võib piisata ka eidenv rakenduse kasutamisest -x võtmega.

Veebirakendustes kasutaja isikuandmeid lugeda ei saa, kuna uus veebilehitseja plugin seda ei võimalda.

Kaardiga otse suhtlemine

Eesti eID kiipkaartidega otse suhtlemiseks tuleb kaardile saata vajalikud baidijadad (Application Protocol Data Unit ehk APDU) ning lugeda vastuseid. Sõnumite formaat ning tähendused on paika pandud ISO/IEC 7816-4 standardis, mille viimase versiooni saab osta ISO käest, ent natukene aegunud variant on ka tasuta saadaval. Eesti eID kiipkaartide spetsiifika kohta saab lugeda EstEID-kaardi kasutusjuhendist.

Kuna sõnumite formaat on standardiseeritud, siis ei ole väga tõenäoline, et kirjutatud kood uuemate kaartidega enam ei toimiks. Ainus, mis saab juhtuda, on et uutel kaartidel muutub isikuandmete faili asukoht või et selles olevad andmed erinevad senistest kaartidest. Sellises olukorras tuleb ka OpenSC-d või muid teeke kasutav kood ümber kirjutada ning värskendada faili asukohta ning väljade tähendusi. (Samamoodi vajaks sellises olukorras ümberkirjutamist ka eidenv rakendus, ent selle eest kannaks hoolt selle haldaja.)

Baidijada, mida on isikuandmete faili lugemiseks vaja saata, on järgmised (kasutades T=0 protokolli):[14]

00 A4 00 0C          # Valime juurkataloogi
00 A4 01 0C 02 EE EE # Valime kataloogi EEEE
00 A4 02 04 02 50 44 # Valime faili 5044, mis sisaldab isikuandmeid
00 B2 XX 04          # Loeme isikuandmete failist kirje nr XX (vt tabelit)
                     # Kaart vastab 61 YY, kus YY tähistab, mitu baiti ootavad lugemist
00 C0 00 00 YY       # Loeme kaardilt YY baiti
                     # Kaart vastab ... 90 00, kus ... on soovitud andmed ning 90 00 tähistab OK staatust
Kirje number Sisu Maksimaalne pikkus baitides
1 Perenimi 28
2 Eesnime rida 1 15
3 Eesnime rida 2 15
4 Sugu 1
5 Kodakondsus 3
6 Sünnikuupäev (pp.kk.aaaa) 10
7 Isikukood 11
8 Dokumendi number 9
9 Kehtivuse viimane päev (pp.kk.aaaa) 10
10 Sünnikoht 35
11 Väljaandmise kuupäev (pp.kk.aaaa) 10
12 Elamisloa tüüp 50
13 Märkuste rida 1 50
14 Märkuste rida 2 50
15 Märkuste rida 3 50
16 Märkuste rida 4 50

Kui kasutada kaardiga suhtlemiseks mõnda teeki, siis on võimalik, et viimast sammu ei ole vaja teha. Näiteks kasutades javax.smartcardio klasse saame baidijadale 00 B2 XX 04 vastuseks ResponseAPDU objekti, mille getData() meetod tagastab soovitud andmed ning getSW() tagastab staatuse.[15] Seega pole vaja käsitsi saata sõnumit 00 C0 00 00 YY.

Näidet isikuandmete lugemisest on võimalik näha avalduste rakenduses.

Allikaviited