Näiterakendused

Allikas: eid.eesti.ee
Redaktsioon seisuga 10. september 2012, kell 08:29 kasutajalt Tiitpikma (arutelu | kaastöö) (Alamleheks)
(erin) ←Vanem redaktsioon | Viimane redaktsiooni (erin) | Uuem redaktsioon→ (erin)
Jump to navigation Jump to search

Näiterakendused

Sõltuvused

Näitekood on loodud platvormil Ubuntu 11.10 ehk Oneiric Ocelot (64-bit), kasutades vaikimisi pakutavate pakkide versioone:

  • libdigidoc 3.5.5782.613-ubuntu-11-04
  • libdigidocpp 3.5.5814.662-ubuntu-11-04
  • gcc 4.6.1
  • Java 1.7.0_147
  • PHP 5.3.6-13ubuntu3.7
  • Apache 2.2.20

Lisaks neile tuleb Java-rakenduste käitamiseks kasutada järgmisi väliseid teeke:

Märkus: Tegu on arendamisel kasutatud versioonidega teekidest. See tähendab, et lähtekood võib kompileeruda ka vanemate teekidega ning samas võivad uuemad teegid seda lihtsustada (nt mugavama API mõttes). Kui mõne rakenduse jaoks on kindlad erinõudeid versiooni või keskkonna osas, siis on need selle juures välja toodud.

Keeled

C++

Kasutab libdigidocpp teeki, mida levitatakse DigiDoc3 kliendi koosseisus - eraldiseisvana seda arendajatele ei pakuta. Kui arendaja aga juhtub olema Linuxi-põhisel operatsioonisüsteemil, siis on võimalik teek alla laadida RIA Fedora, openSUSE või Ubuntu repositooriumitest ilma klientrakenduseta.

Testimisel ilmnes, et kui kasutada libcrypto 0.9.8 (millest libdigidocpp sõltub) asemel mõnda uuemat versiooni, siis tekivad segmentation fault'id: seega, kui süsteemi on paigaldatud uuem, võib olla vaja linkida see versioon käsitsi.

Näiteks:

gcc main.cpp /lib/libcrypto.so.0.9.8 -ldigidocpp

Vaikimisi kasutatakse rakendustes PIN küsimiseks enda loodud lahendust, mis sõltub unistd.h'st (mida Windowsil pole). libdigidocpp teegi SVN hoidlas on EstEIDConsolePinSigner klass, mis töötab ka Windowsi all, ent 02.05.2012 seisuga ei ole RIA Ubuntu repodes olevas teegis. Kui see klass aga on olemas, siis tuleb selle kasutamiseks lisada näiterakendusi kompileerides võti -DHAVE_ESTEID_CONSOLE_PIN_SIGNER.

Java

Kasutab JDigiDoc teeki. Näitekoodis on teeki kasutatud vaid klientrakenduste loomiseks, ent analoogselt on seda võimalik kasutada ka serverrakendustes.

Java konfiguratsioonifail

JDigiDoc-teek kasutab faili Properties konfiguratsiooni haldamiseks. Failist loetavad võtmed on esitatud jdigidoc teegi dokumentatsiooni lisas 1.[1]

Olulised read konfiguratsioonifailis:

  • DIGIDOC_SIGN_PKCS11_DRIVER - kaardi PKCS11 API ohjur,
  • DIGIDOC_LOG4J_CONFIG - logimise konfiguratsiooni fail,
  • SIGN_OCSP_REQUESTS - kas allkirjastada OCSP päringud (seda on vaja näiteks AS Sertifitseerimiskeskuse kehtivuskinnituse teenuse kasutamiseks),
    • DIGIDOC_PKCS12_CONTAINER - allkirjastamiseks kasutatava sertifikaadi asukoht, PKCS12 formaadis,
    • DIGIDOC_PKCS12_PASSWD - parool allkirjastamiseks kasutatava sertifikaadi PKCS12 faili avamiseks,
    • DIGIDOC_OCSP_SIGN_CERT_SERIAL - allkirjastamiseks kasutatava sertifikaadi seerianumber,
  • DIGIDOC_CA_1_CERT#, DIGIDOC_CA_1_OCSP#_CERT, DIGIDOC_CA_1_OCSP#_CA_CERT - sertifikaatide asukohad; kasutada eesliidet jar://, et anda asukoht classpathist.

PHP

DigiDocService

PHP's allkirjastamiseks ning allkirjade kontrollimiseks on võimalik kasutada DigiDocService-teenust. Et võimaldada teenusega suhtlus üle HTTPS'i on PHP'le vaja paigaldada cURL laiendus.

DigiDocService-teenuse liides on defineeritud WSDL'is, mille põhjal genereeritakse PHP klass teenuse kasutamiseks. Kuigi PHP 5 tuleb juba sisse-ehitatud SOAP kliendi ning WSDL põhjal klassi genereerimise võimalustega[2], kasutab näitekood kaasas olevat PEAR'ist pärit SOAP moodulit, tänu mille töötab kood ka vanemate versioonidega. Kood peaks töötama vähemalt PHP 4.3.4 peal, ent ei ole välistatud, et ka vanematel. Kui veebirakenduses kasutatakse PHP 5, siis on soovitatav uute arenduste puhul kasutada sisse-ehitatud vahendeid.

XML-failide ning DigiDoc konteinerite lugemiseks ja töötlemiseks kasutatakse kärbitud ning veidi muudetud varianti näitekoodist, mis on saadaval aadressil https://www.openxades.org/ddservice/. Kui kärbitud variandist puudub soovitud funktsionaalsus, siis on võimalik, et see on olemas täisversioonis.

SWIG

Kui puudub võimalus või soov kasutada DigiDocService-teenust, siis on alternatiiviks kasutada DigiDoc teeke. PHP jaoks ühtegi kirjutatud ei ole, mistõttu on vaja kasutada mähist (wrapper) mõne olemasoleva ümber.

Lihtsustamaks liidest teegiga ning võimalikult vähendada mähitavat pinda, loodi näitekoodis lihtne vahekiht, mis peidab libdigidoc teegi kasutamise mõne funktsiooni taha. Vahekiht on ülesande-spetsiifiline, mistõttu see ei sobi üldkasutuseks, ent annab aimu, milline see võiks olla. Seejärel loodi SWIG mähis hoopis vahekihi, mitte teegi ümber. Tulemuseks on PHP laiendus, mille kaasamisel on võimalik kõiki vahekihi meetodeid kasutada.

Laiendust kasutatakse serveripoolse vastuse allkirjastamiseks ning krüpteerimiseks. Viimast neist polegi võimalik DigiDocService-teenusega teha, kinnitades teekide kasutamise vajadust.

Laiendi kompileerimine

Vahekihi lähtekood

Tänu loodud vahekihi on näitekoodis olev digidoc.i liides väga lihtne - seal polegi kirjas muud, kui et see kaasaks digidoc.h päised. Liidesest saab genereerida mähkuri koodi käsuga:

swig -php digidoc.i

Selle tulemusena luuakse kolm uut faili: digidoc_wrap.c, digidoc.php ja php_digidoc.h. Esimene, digidoc_wrap.c sisaldab PHP laienduse kompileerimiseks vajalikku C koodi. Teist, digidoc.php'd saab kaasata PHP skriptidesse. See üritab laiendust dünaamiliselt laadida ning paneb mähitud funktsioonid abstraktsesse klassi digidoc. Viimane, php_digidoc.h sisaldab vajalikku päiseinformatsiooni, kui on soov laiend staatiliselt PHP interpretaatorisse linkida. Kui seda soovi pole, siis pole ka seda faili vaja.[3]

Seejärel tuleb lihtsalt vahekihi kood koos genereeritud mähkuri C koodiga üheks jagatud objektiks kokku kompileerida. Selle käigus tuleb ette anda ka PHP interpretaatori päiste asukohad, mida saab teha php-config tööriistaga, ning linkida libdigidoc teek. Näiteks GCC peal näeks kompileerimine välja:

$ gcc `php-config --includes` -fPIC -c digidoc.c digidoc_wrap.c
$ gcc -shared digidoc.o digidoc_wrap.o -ldigidoc -o digidoc.so

TODO Kas ka Windows jaoks on ehitamise näidet vaja? Kui jah, siis mis vahenditega?

Laiendi laadimine

digidoc.php kaasamisel üritatakse loodud laiend dünaamiliselt laadida dl käsuga (kui see pole juba laetud). Kuna dl käsuga on probleeme olnud[4], on parem moodul enne käsitsi laadida. Selle jaoks tuleb lisada php.ini konfiguratsioonifaili rida (või muuta olemasolevat):

extension=digidoc.so  # Linux
extension=digidoc.dll # Windows
libdigidoc konfiguratsioon

Kuna SWIG-mähkur kasutab libdigidoc teeki, siis selle konfigureerimiseks tuleb muuta digidoc.conf faili. Vaikeväärtused enamasti sobivad, ent seal on üks oluline rida: DIGIDOC_OCSP_URL määrab kelle poole pöördutakse OCSP-päringutega. Testimise jaoks on vaja selle väärtuseks seada http://www.openxades.org/cgi-bin/ocsp.cgi.

NB! Ära unusta seda tagasi muuta, kui soovid libdigidoc teegiga esitada mitte-test päringuid.

JavaScript

Erinevate operatsioonisüsteemide ja veebilehtisejate jaoks on tehtud mitmeid allkirjastamise pluginaid, ent nende API erineb mõnevõrra. Et veebirakendustes allkirjastamise toe lisamine lihtsam oleks, loodi JavaScripti teek, mis pakub ühtset liidest kõigi pluginatega suhtlemiseks.[5][6]

Teegi liides võimaldab:

  • laadida operatsioonisüsteemi ja veebilehitseja jaoks parim paigaldatud plugin,
  • lugeda ID-kaardilt kasutaja allkirjastamise sertifikaati ja
  • allkirjastada etteantud räsi kasutaja ID-kaardiga.

Teegi veateated on eesti, inglise, leedu ja vene keeles. Soovitud keele valimiseks tuleb loadSigningPlugin() meetodi väärtuseks anda vastavalt "est", "eng", "lit" või "rus".

Kõike kolme kasutatakse avalduste esitamise veebivormis ning sealt on kättesaadav ka näitekood.

Teek koos juurdekuuluva dokumentatsiooniga on kättesaadav aadressilt: http://id.ee/index.php?id=30369

Lisaks loodi koos teegiga ka uus universaalne plugin, mida levitatakse ID-kaardi baastarkvara kooseseisus ning soovitatakse edaspidi kasutada, kuna vanem Java applet enam uuendusi ei saa.[6]

Avalduste esitamise kasutusmall

Kasutusmalli osapooled

Selleks et demonstreerida mitmesuguseid e-ID võimalusi ning nende omavahelist seostamist, kasutatakse järgmist kasutusmalli:

Oletame, et meil on asutus, kellele saab esitada avaldusi. Selleks on neil püsti veebiserver veebivormiga. Suhtlus serveriga käib üle HTTPS ning nõuab, et kasutaja end tuvastaks[1]. Vormis on nime ning isikukoodi lahtrid eeltäidetud kasutaja sertifikaadilt saadud andmetega. Seejärel kirjutab kasutaja vormi oma avalduse, mille veebiteenus DigiDocService abiga paneb DigiDoc konteinerisse koos nime ja isikukoodiga[2.1]. Viimaks palutakse kasutajal konteiner veebilehitsejas allkirjastada[2.2].

Loodud konteiner edastatakse teisele teenusele, mis kontrollib allkirja[2.3] ning saadab automaatselt vastuse konteineris, mis on asutuse digitaalse templiga allkirjastatud ning kasutaja sertifikaadil oleva avaliku võtmega krüpteeritud[3]. Kasutaja saab esitatud avalduse ning saadud vastuse oma arvutisse salvestada ning siis DigiDoc kliendiga uurida.

Paralleelselt veebivormiga on rakendus, kus kasutaja peab end tuvastama[4] ning mis koostab allkirjastatud konteineri juba kliendi arvutis[5, 6] ja saadab terves tükis samale teenusele mis veebivormgi. Lisaks avaldusele paneb rakendus konteinerisse ka ID-kaardi isikuandmete failis leiduva info[7]. Serveri vastus on sama, ent seekord krüpteeritakse ta ka lahti[8] ning allkirja kontrollitakse rakenduse sees[8], mitte DigiDoc kliendiga.

Seega kasutusmallis demonstreeritakse

  1. veebis isiku tuvastamist,
  2. DigiDocService kasutamist
    1. konteinerite loomiseks,
    2. allkirja andmiseks ja
    3. allkirja kontrollimiseks,
  3. faili krüpteerimist saaja sertifikaadiga,
  4. rakenduses isiku tuvastamist,
  5. rakenduses konteineri koostamist,
  6. rakenduses allkirja andmist,
  7. ID-kaardi isikuandmete faili lugemist,
  8. faili lahti krüpteerimist ning
  9. rakenduses allkirja kontrollimist.

Veebiserver

Veebiserveriks on kas Apache httpd või Microsoft IIS (ilmselgelt võib ka mõni muu olla, ent neid ei käsitleta). Mõlemal juhul on vaja paigaldada PHP tugi ning server konfigureerida kasutama HTTPS-i. Kõik see käib tavaliselt ning puudub e-ID spetsiifika.

Lisaks on ID-kaardiga sisselogimise jaoks vaja seadistada server küsima vastaval leheküljel kasutajalt tema sertifikaati—juhendid selleks leiab ID.ee lehelt. Käesolevas kasutusmallis küsitakse ID-kaarti vaid veebivormil, nii et juhend tuleb läbida vaid selle rakenduse jaoks. Kui kõik rakendused jooksevad sama veebiserveri peal, siis tuleb sertifikaadi küsimine seadistada ainult veebivormi jaoks: kindlasti ei tohi sertifikaati küsida avaldusi töötlev teenus, muidu ei saa teised rakendused sellele avaldusi esitada.

Nende juhendite järgi seadistatud serverid kontrollivad kasutajate sertifikaatide kehtivust ainult tühistusnimekirjade (CRL, Certificate Revocation List) abil—tasuks lisada ka kehtivuskinnituse (OCSP, Online Certificate Status Protocol) küsimine. Aga nagu sertifikaatide kehtivuse kontrolli juures mainitud, siis seda veebiserveris niisama lihtsalt teha ei saa.

Kuid nagu juba mainitud, siis kliendi sertifikaati kasutame me SSL/TLS seansis ainult veebivormi juures, kus meil on juba DigiDocService tugi olemas: seega saame ka kehtivuskinnitust läbi selle teenuse küsida. Mobiil-ID veebivormis teeb DigiDocService kehtivuse kontrolli juba meie eest ära, nii et seal pole seda eraldi vaja teha.

Veebivorm

Veebivormi järgnevusskeem

Veebivormi lähtekood

Veebivorm on kirjutatud PHP's ning kasutab konteinerite koostamiseks ja allkirjastamiseks DigiDocService-teenust. Lähemalt PHP kasutamise kohta loe keelte alt.

  1. Veebiserver viib SSL/TLS käepigistuse käigus läbi isikutuvastuse.
  2. Rakendus kasutab DigiDocService-teenust, et kontrollida kliendisertifikaadi kehtivust. Vt veebiserverite peatükki, et lugeda, miks seda tehakse niimoodi.
  3. Kasutajale kuvatakse veebivorm, mis koosneb neljast lahtrist. Kolm neist (eesnimi, perenimi ja isikukood) on eeltäidetud isiku tuvastamisel saadud andmetega.
  4. Vormi esitamisel saadetakse serverile lahtrite sisu ja kasutaja allkirjastamissertifikaat ning selle seerianumber (kuigi seerianumbrit oleks võimalik ka sertifikaadilt lugeda on parem lasta see töö ära teha kliendi poolel).
  5. Vormi sisestatud andmetest luuakse tekstifail, mis salvestatakse serveris ajutisse kausta.
  6. DigiDocService-teenusega alustatakse uus seanss ning luuakse konteiner, kuhu pannakse vastloodud faili räsi (StartSession). Kuigi teenusele on võimalik saata ka algfailid, on privaatsuse ning andmemahu mõttes parem piirduda räside saatmisega.
  7. Valmistutakse ette konteineri allkirjastamiseks: DigiDocService-teenusele saadetakse kasutaja sertifikaat ning allkirja metainfo s.t roll ja asukoht (PrepareSignature). Näitekoodis kasutatakse metainfoks konstante, kuna nende kasutajalt küsimine on triviaalne ning ei vaja eraldi näidet. Teenuselt saadakse vastuseks konteineri räsi, mille klient peab allkirjastama.
  8. Kasutajale kuvatakse järgmine leht, millel on allkirjastamiseks kasutatava sertifikaadi seerianumber ning allkirjastatav räsi.
  9. Kasutaja vajutab nupule "Allkirjasta", mille peale antakse tööjärg üle JavaScript teegile, mis hangib kasutajalt räsile allkirja.
  10. Allkiri saadetakse järgmise päringuga tagasi veebivormile, mis viib allkirjastamise lõpuni (FinalizeSignature), laeb allkirjastatud konteineri alla (GetSignedDoc) ning lõpetab seansi (CloseSession).
  11. Allalaetud konteineris asendatakse failide räsid nende päris sisuga, mis enne kettale salvestati, ja saadetakse avaldusi töötlevale teenusele.
  12. Allalaetud konteiner ning asutuselt saadud vastus salvestatakse kettale, kust kasutaja saab neid alla laadida.

Pärast veebivormi paigaldamist tuleb veenduda, et sellel oleks enda kaustas kirjutamisõigus, ning muuta claims.php algust: seal olev require_once käsk peab viitama avaldusi töötlevas teenuses olevale failile DigiDoc.class.php. Kui on soov veebivorm ja avaldusi töötlev teenus eraldi masinatesse paigaldada, siis tuleb ka viidatud fail avaldusi töötleva teenuse lähtekoodist veebivormi ümber kopeerida.

Mobiil-ID

Mobiil-ID veebivormi järgnevusskeem. Sinistes kastides olevaid lõike korratakse, kuni saadakse päringu tulemus. Skeemilt puudub mobiilioperaatori suhtlus kasutajaga, kuna see pole arenduse seisukohalt oluline.

Veebivormi lähtekood

Variant veebivormist, mis kasutab Mobiil-ID-d. Üldjoontes on tegu samasuguse rakendusega nagu veebivorm (vt sealt ka paigaldamisnõudeid), kahe olulise erinevusega.

Esiteks ei küsita SSL/TLS käepigistuse käigus kliendi sertifikaati—sertifikaat on Mobiil-ID SIM-i peal ning kasutaja veebilehitsejal puudub juurdepääs sellele. Selle asemel kasutame DigiDocService meetodit MobileAuthenticate autentimispäringu esitamiseks. Meetodiparameetriteks anname kasutaja telefoninumbri ning keele-eelistuse. Peale seda kutsume iga viie sekundi tagant välja meetodi GetMobileAuthenticateStatus, kuni see tagastab autentimise tulemuse. Meetod tagastab ka kasutaja sertifikaadi, mille kehtivust on juba kontrollitud.

Teiseks, dokumendi allkirjastamiseks ei kasutata veebilehitseja pluginat, vaid Mobiil-ID-d. Selle tulemusena ei kutsu me välja meetodeid PrepareSignature ja FinalizeSignature, vaid MobileSign ning GetStatusInfo: esimene saadab allkirjastamispäringu ning teist kontrollime iga viie sekundi tagant, kuni saame tulemuse. Ülejäänud sammud, mis on vajalikud dokumentide räsimiseks, konteinerite koostamiseks ning metainfo määramiseks, on samad, mis veebivormi korral.

Mõlema olekukontrolli meetodi intervalliks valitud viis sekundit on hea testimise korral, kus testnumbrid vastavad kiirelt. Tootekeskkonnas kulub kasutajatel Mobiil-ID päringule vastamiseks oluliselt kauem, mistõttu võib ka intervalli suurendada (eriti just ooteaega enne esimese päringu tegemist).

Märkus: Avaldusi töötlevalt teenuselt saadud vastus on krüpteeritud ning ainsaks vastuvõtjaks on pandud kasutatud Mobiil-ID isikutuvastussertifikaat—Mobiil-ID aga krüpteerimist ei toeta, mistõttu ei ole ka võimalik seda vastust lugeda. Ent vastuse sisu ei oma mingit tähtsust—see, et vastus üldse tagastati, näitab, et avaldus oli korrektne ning selle saatmine õnnestus.

Avaldusi töötlev teenus

Avaldusi töötleva teenuse järgnevusskeem

Teenuse lähtekood (vajab töötamiseks ka SWIG-mähkurit)

Avaldusi töötlev teenus on kirjutatud PHP-s ning kasutab avaldusel oleva allkirja kontrolliks DigiDocService-teenust. Vastuse allkirjastamiseks ja krüpteerimiseks kasutatakse SWIG-mähkurit libdigidoc-teegi ümber.

  1. Teenusele esitatakse POST-päring, millel on kaks kohustuslikku välja: claim ja cert.
    • cert peab sisaldama vastuse saaja isikutuvastamise sertifikaati base64 kodeeritud DER-kujul (tegu pole PEM'iga, kuna puuduvad BEGIN ja END read),
    • claim peab sisaldama allkirjastatud avaldust. Faili MIME-tüüp peab olema kas application/x-ddoc või application/vnd.bdoc-*.
  2. Teenus kontrollib, kas üleslaadimine õnnestus ning kas avaldusel olev allkiri kehtib. Kehtivuse kontrolliks saadetakse avaldus DigiDocService-teenusele, kasutades päringut StartSession, kus lipp bHoldSession on pandud eitavaks, et ühendus kohe suletaks. Vastuseks saadab DigiDocService allkirja staatuse.
    • Taaskord, DigiDocService-teenusele ei saadeta terve avaldus, vaid andmefailid asendatakse nende räsidega.
  3. Avalduse seest loetakse selles sisalduvad andmefailid ning need kirjutatakse kettale.
  4. Kui allkiri on kehtiv, siis luuakse vastus. Selle sisu pole meie jaoks oluline, nii et tegu on konstantse sõnega.
  5. Lähtestatakse libdigidoc teek ning luuakse allkirjastamise konteiner (SWIG-mähkuris initialize ning new_signature_container meetodid).
  6. Konteinerisse lisatakse loodud vastus (add_data_file) ning see allkirjastatakse (sign_container). Allkirjastamiseks kasutatav PIN võib olla nii allkirjastamise funktsiooni argumendiks kui ka libdigidoc teegi konfiguratsioonifailis võtme AUTOSIGN_PIN väärtus (sel juhul jäetakse funktsiooni väljakutsel parameetri pin väärtuseks NULL).
  7. Allkirjastatud vastus kirjutatakse kettale ning vabastatakse mälust (save_signed_document ja free_signature_container - NB! Siinkohal oleks otstarbekam konteiner mälus alles hoida, kuna ta loetakse kohe kettalt tagasi - seda aga hetkel ei saa teha, kuna teegifunktsioon createSignedDocInMemory toodab vigast XML-i, nii et me peame kasutama kettale kirjutavat versiooni).
  8. Teenus loob uue krüpteerimise konteineri (new_encryption_container) ning krüpteerib vastloodud vastuse (encrypt_ddoc).
  9. Kasutatud transpordivõti krüpteeritakse cert väljal oleva sertifikaadi avaliku võtmega ning see lisatakse konteinerisse (add_recipient).
  10. Krüpteeritud konteiner salvestatakse kettale (save_encrypted_container - NB! Taaskord oleks parem konteinerit kettale mitte kirjutada, ent mälus konteineri XML kujule teisendamine on teegis meie eest peidetud ning ainus võimalus XML saamiseks on faili kirjutamine), selle mälu vabastatakse (free_encryption_container) ning vastus saadetakse esialgse päringu tegijale.

Teenust paigaldades tuleb veenduda, et sellel oleks enda kaustas kirjutamisõigus, ning kohendada conf.php faili, kus minimaalselt tuleb ära muuta DD_RESPONSE_SERVER aadress (seda kasutab veebivorm ning selle väärtuseks peab olema avaldusi töötleva teenuse aadress).

Digitaalse templi seadistamine

Selleks, et teenus kasutaks vastuse allkirjastamiseks digitaalset templit ning mitte ID-kaarti, on vaja libdigidoc versiooni 3.7 või uuemat ning tuleb paigaldada digitaalse templi ohjurid. Samuti tuleb teha mõned muudatused libdigidoc-teegi seadete failis.

Ohjurite paigaldamiseks vaata peatükki krüptopulga kasutamine.

libdigidoc-teegi seadete faili leiab vaikimisi %PROGRAMFILES%\Estonian ID card\digidoc.ini (Windows) või /etc/digidoc.conf (Linux).

Seadete failis peaksid leiduma järgmised read (mooduli asukoht võib erineda):

DIGIDOC_DEFAULT_DRIVER=1
DIGIDOC_DRIVERS=1
DIGIDOC_DRIVER_1_NAME=OpenSC
DIGIDOC_DRIVER_1_DESC=OpenSC projects PKCS#11 driver
DIGIDOC_DRIVER_1_FILE=/usr/lib/opensc-pkcs11.so

Siinkohal on vaja kasutada OpenSC mooduli asemel vastpaigaldatud SafeNet eToken oma. Selleks saab lihtsalt asendada olemasolev mooduli või lisada uue. Viimane variant näeks välja järgmine (taaskord võivad moodulite asukohad erineda):

DIGIDOC_DEFAULT_DRIVER=2
DIGIDOC_DRIVERS=2
DIGIDOC_DRIVER_1_NAME=OpenSC
DIGIDOC_DRIVER_1_DESC=OpenSC projects PKCS#11 driver
DIGIDOC_DRIVER_1_FILE=/usr/lib/opensc-pkcs11.so
DIGIDOC_DRIVER_2_NAME=eToken
DIGIDOC_DRIVER_2_DESC=SafeNet eToken PKCS#11 driver
DIGIDOC_DRIVER_2_FILE=/lib/libeToken.so.8

Avalduste rakendus

Avalduste rakenduse järgnevusskeem

Avalduste rakenduse lähtekood

TODO Kui wiki seda lubama hakkab, siis laadida üles kompileeritud .jar

Tegu on käsurearakendusega, mis kasutajalt ja isikutunnistuselt saadud info põhjal loob avalduse, paneb selle konteinerisse ja allkirjastab ning saadab avaldusi töötlevale teenusele. Vastuseks tuleb uus konteiner, mille see krüpteerib lahti, kontrollib allkirja ning siis kuvab sisu kasutajale. Rakendus on algselt kirjutatud Javas ning seejärel porditud .NET'i. Mõned alamosad on ümber kirjutatud ka C++'i, kuid kuna selle kasutamine on piisavalt sarnane Javale, siis polnud vajadust tervet rakendust ümber portida.

  1. Rakendus viib läbi isikutuvastuse nii nagu kirjeldatud isikutuvastuse juures ning realiseeritud eraldiseisvas isikutuvastuse rakenduses.
  2. Kasutajalt küsitakse sisendit avaldusele - tegu on lihtsa, üherealise tekstisisestusega. Kuna JDigiDoc teek oskab kasutada vaid kettale salvestatud faile, siis salvestame sisestatud info ajutisse faili.
  3. Salvestame ajutiselt kettale kaardilt loetud isikuandmed (JDigiDoc teek isikuandmete faili lugemist ei toeta, mistõttu tehakse seda käsitsi lähtudes EstEID kaardi kasutusjuhendist - täpsem seletus isikuandmete faili kasutamise all).
  4. Andmed pannakse DDOC-konteinerisse ning allkirjastatakse - viimase käigus kontrollitakse ka allkirjastamiseks kasutatava sertifikaadi kehtivust.
  5. Kontrollitakse üle, kas konteiner verifitseerub ning see kirjutatakse kettale.
  6. Konteiner saadetakse avaldusi töötlevale teenusele ning vastuseks saadakse krüpteeritud konteiner.
  7. Konteineris olev transpordivõti krüpteeritakse lahti kasutaja isikutuvastussertifikaadi salajase võtmega ning seda kasutatakse teenuse poolt allkirjastatud vastuse lahti krüpteerimiseks.
  8. Allkirjastatud vastus salvestatakse kettale ning seejärel kontrollitakse sellel olevat allkirja.
  9. Kasutajale kuvatakse teenuse vastuse sisu.

Vajab Java versiooni 1.7 või uuemat.

Rakenduse kasutamine

Rakendusega on kaasas Ant ehitusskript, mis kompileerib kõik klassid ning loob neist JAR-faili. Skript nõuab vähemalt Ant versiooni 1.7.

Enne kompileerimist tuleb Ant skripti sees ära muuta kasutatavate teekide asukohad. Peale seda piisab vaid ant käsu käivitamisest, mis loob client.jar'i.

Seejärel saab rakendust käivitada käsuga:

java -jar client.jar [-cfg config] [url]
  • config - kasutatav konfiguratsioonifail, vaikimisi otsitakse praegusest kasutast jdigidoc.cfg
  • url - avaldusi töötleva teenuse aadress, vaikimisi https://localhost/eid/submit.php

Rakendus sõltub järgmistest teekidest:

  • bcprov-jdk15on-147.jar
  • commons-codec-1.6.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

Kui teenusega luuakse HTTPS-ühendus (tungivalt soovitatav), siis kontrollitakse, et serveri sertifikaadi väljaandja oleks Java keystore's olemas. Kui teenus kasutab enda allkirjastatud sertifikaate (näiteks testimisel), siis on vaja need enne keystore'i lisada:

keytool -import -alias <sertifikaadi alias> -file <sertifikaadi asukoht> -keystore <keystore asukoht>

Näiteks Ubuntu all:

# keytool -import -alias snakeoil -file /etc/ssl/certs/ssl-cert-snakeoil.pem -keystore /usr/lib/jvm/default-java/jre/lib/security/cacerts

Allkirjastamise rakendus

Rakendus on käsureautiliit, millele antakse sisendandmetena ette nimekiri failidest ning mis väljastab konteineri allkirjastatud failidega ja OCSP kehtivuskinnitusega.

C++

Lähtekood

Kompileerimine:

gcc sign.cpp common/EstEIDConsolePinSigner.cpp -ldigidocpp -o sign

Kasutus:

./sign infile:mimetype... outfile
  • infile - failid, mida allkirjastada
  • mimetype - allkirjastatava faili MIME tüüp, nt text/plain
  • outfile - loodava BDOC konteineri nimi, soovitatav laiendus .bdoc

Java

Lähtekood

Kompileerimine (kus $JAVA_LIB on vajalike Java teekide asukoht):

javac -cp $JAVA_LIB/jdigidoc.jar JavaSign.java

Kasutus:

java JavaSign [-cfg config] infile1 ... infileN outfile[.bdoc]
  • config - kasutatav konfiguratsioonifail, vaikimisi otsitakse praegusest kaustast jdigidoc.cfg
  • infile - failid, mida allkirjastada
  • outfile - loodava konteineri nimi; kui faili nimi lõppeb laiendiga .bdoc, siis luuakse BDOC formaadis allkiri, muidu DIGIDOC-XML

Käivitamisel peavad olema Java classpathil järgmised teegid:

  • bcprov-jdk15on-147.jar
  • commons-codec-1.6.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

Vajab Java versiooni 1.7 või uuemat, kuna allkirjastatava faili MIME-tüübi tuvastamiseks kasutatakse klassi Files.

Isikutuvastuse rakendus

Rakendus on käsureautiliit, mis teeb kindlaks, kas kasutajal on juurdepääs sertifikaadile vastavatele privaatvõtmele, s.t kas ta teab ID-kaardi PIN1-koodi. Kasutaja sisestab lugejas oleva kaardi PIN1-koodi, mille peale kuvatakse teade, kas isiku tuvastamine õnnestus või mitte. Kui peaks tekkima mingeid muid tõrkeid (nt on ID-kaardil olev sertifikaat kehtetu), siis kuvatakse vastav veateade.

C++

Lähtekood

Kompileerimine:

gcc auth.cpp common/EstEIDConsolePinSigner.cpp -ldigidocpp -ldigidoc -o auth

Rakendus käivitatakse ilma argumentideta:

./auth

Java

Lähtekood

Kompileerimine (kus $JAVA_LIB on vajalike Java teekide asukoht):

javac -cp $JAVA_LIB/jdigidoc.jar:$JAVA_LIB/bcprov-jdk15on-147.jar JavaAuth.java

Rakenduse käivitamisel on võimalik anda valikuline argument -cfg config, mis töötab nii nagu allkirjastamise rakenduse puhul:

java JavaAuth [-cfg config]

Käivitamisel peavad olema Java classpathil järgmised teegid:

  • bcprov-jdk15on-147.jar
  • commons-compress-1.3.jar
  • esteidtestcerts.jar
  • iaikPkcs11Wrapper.jar
  • jakarta-log4j-1.2.6.jar
  • jdigidoc-3.6.0.157.jar

Allkirja kontrollimise rakendus

Käsureautiliit, mis kontrollib etteantud konteineril olevat allkirja.

C++

Lähtekood

Kompileerimine:

gcc verify.cpp -ldigidocpp -o verify

Kasutus:

./verify infile
  • infile - fail, mille allkirju kontrollida

Andmete dekrüpteerimise rakendus

Käsureautiliit, mis dekrüpteerib etteantud konteineri.

C++

Lähtekood

Kompileerimine:

g++ decrypt.cpp -ldigidoc -o decrypt

Kasutus:

./decrypt infile pin outfile
  • infile - fail, mida dekrüpteerida
  • pin - dekrüpteerimisel kasutatava kaardi PIN 1
  • outfile - fail, kuhu dekrüpteeritud tulemus salvestada

Allikaviited