Erinevus lehekülje "Näiterakendused" redaktsioonide vahel

Allikas: eid.eesti.ee
Jump to navigation Jump to search
 
96. rida: 96. rida:
  
 
.NET näitekoodi on võimalik näha [[#Avalduste_rakendus|avalduse rakenduses]].
 
.NET näitekoodi on võimalik näha [[#Avalduste_rakendus|avalduse rakenduses]].
 
Aastaks 2013 on plaanitud luua ka eraldi .NET teek, mis asendab COM-teegi.<ref>http://id.ee/index.php?id=30290</ref>
 
  
 
== Avalduste esitamise kasutusmall ==
 
== Avalduste esitamise kasutusmall ==

Viimane redaktsioon: 27. august 2015, kell 22:43

Näiterakendused

Sõltuvused

Näitekood on loodud platvormil Ubuntu 12.04 Long-Term Support ehk Precise Pangolin (64-bit), kasutades vaikimisi pakutavate pakkide versioone:

  • libdigidoc 3.6.0.707-ubuntu-12-04
  • libdigidocpp 3.6.0.771-ubuntu-12-04
  • gcc 4.6.3-1ubuntu5
  • OpenJDK 7u7-2.3.2a-0ubuntu0.12.04.1
  • PHP 5.3.10-1ubuntu3.4
  • Apache 2.2.22-1ubuntu1.1

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.

Näiterakendus keeles C++

C++ näidisrakendus kasutab teeki libdigidocpp, mida levitatakse DigiDoc3 kliendi koosseisus -- eraldiseisvana seda arendajatele ei pakuta. Kui arendaja kasutab aga Linuxi-põhist operatsioonisüsteemi, siis on võimalik see teek alla laadida RIA Fedora, openSUSE või Ubuntu repositooriumitest ilma klientrakenduseta.

Tähtis on tähele panna, et libdigidocpp ise toetab ainult BDOC-vormingut. DDOC-vormingus dokumentidega töötamiseks laeb libdigidocpp dünaamiliselt libdigidoc C-teegi ning kasutab seda -- seega peab DDOC jaoks olema paigaldatud ka libdigidoc (vt Teegid).

Lisaks teegile on vaja ka päisefaile: Windowsis paigaldatakse need koos baastarkvaraga, Linux all aga on vaja paigaldada libdigidocpp-dev või libdigidocpp-devel pakk. Kui kasutatakse ka C-teeki, nt krüpteerimiseks, siis on vaja ka selle päised, Windowsi jaoks leiab viimase versiooni id.ee lehelt, Linux jaoks paigaldada libdigidoc-dev või libdigidoc-devel pakk. C-teegi päiseid ei ole vaja libdigidoc ülalmainitud dünaamiliseks laadimiseks.

Vaikimisi kasutatakse näiterakendustes PINi küsimiseks oma 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.

Näiterakendus keeles Java

Java näidisrakendus kasutab JDigiDoc teeki. Näitekoodis on teeki kasutatud vaid klientrakenduste loomiseks, ent samamoodi on seda võimalik kasutada ka serverrakendustes.

Java konfiguratsioonifail

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

Olulised read konfiguratsioonifailis:

  • DIGIDOC_SIGN_PKCS11_DRIVER - kaardi PKCS11 API draiver,
  • DIGIDOC_LOG4J_CONFIG - logimise konfiguratsioonifail,
  • SIGN_OCSP_REQUESTS - kas allkirjastada OCSP-päringud (seda on vaja näiteks SK kehtivuskinnituse teenuse kasutamiseks),
    • DIGIDOC_PKCS12_CONTAINER - allkirjastamiseks kasutatava sertifikaadi asukoht, PKCS12 vormingus,
    • 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.

Näiterakendus keeles 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 määratletud WSDL-is, mille põhjal genereeritakse PHP-klass teenuse kasutamiseks. Kuigi PHP 5 tuleb juba sisseehitatud SOAP kliendi ning WSDL põhjal klassi genereerimise võimalustega[2], kasutab näitekood kaasasolevat PEAR-ist pärit SOAP-moodulit, mille abil töötab kood ka vanemate versioonidega. Kood peaks töötama vähemalt PHP 4.3.4-ga, ent pole välistatud ka töötamine vanematel versioonidel. Kui veebirakenduses kasutatakse PHP 5, siis on soovitatav uute arenduste puhul kasutada sisseehitatud 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 (extension), mille kaasamisel on võimalik kasutada kõiki vahekihi meetodeid.

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

Laiendi kompileerimine

Laadi alla: Vahekihi lähtekood

Tänu loodud vahekihile on näitekoodis olev digidoc'i liides väga lihtne -- see sisaldab ainult direktiivi digidoc.h päiste kaasamiseks. Liidesest saab genereerida mähkuri koodi, andes käsu:

swig -php digidoc.i

Selle tulemusel luuakse kolm uut faili: digidoc_wrap.c, digidoc.php ja php_digidoc.h.

  • Esimene, digidoc_wrap.c sisaldab PHP laienduse kompileerimiseks vajalikku C-keelset 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 vahekihi kood koos genereeritud mähkuri C-koodiga kompileerida üheks jagatud objektiks. Kompileerimisel tuleb ette anda ka PHP interpretaatori päiste asukohad, mida saab teha php-config tööriistaga, ning siis linkida libdigidoc teek. Näiteks GCC-d kasutades näeks kompileerimine välja nii:

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

Laiendi laadimine

digidoc.php kaasamisel üritatakse loodud laiend dünaamiliselt laadida dl käsuga (kui see pole juba laaditud). Kuna dl käsuga on esinenud probleeme[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 tuleb selle konfigureerimiseks muuta faili digidoc.conf. Vaikeväärtused enamasti sobivad, ent seal on üks oluline rida: DIGIDOC_OCSP_URL, mis määrab, kuhu pöördutakse OCSP-päringutega. Testimise jaoks on vaja selle väärtuseks panna http://demo.sk.ee/ocsp.

Tähelepanu! Ära unusta seda tagasi muuta, kui soovid libdigidoc-teegiga esitada päringuid tootekeskkonnas.

Näiterakendus keeles JavaScript - hwcrypto.js

Erinevate operatsioonisüsteemide ja brauserite jaoks on tehtud mitmeid allkirjastamise pluginaid, ent nende API-d erinevad mõnevõrra. Selleks et oleks lihtsam lisada veebirakendustele allkirjastamise tuge, loodi JavaScripti teek, mis pakub ühtset liidest kõigi pluginatega suhtlemiseks.

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 API kirjeldus koos kasutusjuhisega on leitav https://github.com/open-eid/hwcrypto.js/wiki/ModernAPI

Näiterakendus .NET raamistikus

Kuigi .NET lubab teha mitmeid operatsioone kiipkaardiga juba raamistikus olemasolevate vahenditega, puudub sealt DDOC-vormingu tugi. Seetõttu tuleb .NET rakenduse puhul konteineri allkirjastamiseks või kontrollimiseks kasutada COM-teeki või vastav funktsionaalsus ise implementeerida.

.NET näitekoodi on võimalik näha avalduse rakenduses.

Avalduste esitamise kasutusmall

Kasutusmalli osapooled

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

Oletame, et on asutus, kellele saab esitada avaldusi. Selleks on asutusel käima pandud veebiserver veebivormiga. Suhtlus serveriga toimub üle HTTPS-protokolli 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'i abil 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 vastust siis DigiDoc-kliendiga uurida.

Veebivormile on loodud paralleelne rakendus, kus kasutaja peab end tuvastama[4] ning mis koostab allkirjastatud konteineri juba kliendi arvutis[5, 6] ja saadab tervikuna 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'i 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

Veebiserver on kas Apache httpd või Microsoft IIS (mõistagi võib olla kasutuses ka mõni muu veebiservetr, ent need jäävad käsitlusalast väljapoole). Mõlemal juhul on vaja paigaldada PHP tugi ning server konfigureerida kasutama HTTPS-i. Kõik see käib tavaliselt ning puudub eID spetsiifika.

Lisaks on ID-kaardiga sisselogimise jaoks vaja seadistada server küsima vastaval leheküljel kasutajalt tema sertifikaati. Juhised selleks leiab vastavalt 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 juhiste 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.

Nagu eespool märgitud, kasutatakse kliendi sertifikaati SSL/TLS-seansis ainult veebivormi juures, kus on juba DigiDocService'i tugi olemas. Seega saab ka kehtivuskinnitust küsida läbi selle teenuse. Mobiil-ID veebivormis teeb DigiDocService kehtivuse kontrolli juba meie eest ära, nii et seal pole seda eraldi vaja teha.

Veebivorm

Veebivormi järgnevusskeem

Laadi alla: 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 sertifikaatide kehtivuse kontrolli SSL/TLS seansis, 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 allkirjastamissertifikaadi 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õpule (FinalizeSignature), laadib allkirjastatud konteineri alla (GetSignedDoc) ning lõpetab seansi (CloseSession).
  11. Allalaaditud konteineris asendatakse failide räsid nende päris sisuga, mis enne kettale salvestati ning saadetakse avaldusi töötlevale teenusele.
  12. Allalaaditud konteiner ning asutuselt saadud vastus salvestatakse kettale, kust kasutaja saab neid brauseri kaudu omakorda 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.

Laadi alla: 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

Laadi alla: 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 on vastavad meetodid initialize ning new_signature_container).
  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 (meetodid save_signed_document ja free_signature_container. NB! Siinkohal oleks otstarbekas konteiner mälus alles hoida, kuna ta loetakse kohe kettalt tagasi -- seda ei saa aga hetkel 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 (meetod save_encrypted_container. NB! Taas oleks parem konteinerit kettale mitte kirjutada, ent mälus konteineri XML-kujule teisendamine on teegis meie eest peidetud ning ainus võimalus XMLi loomiseks on faili kirjutamine). Konteineri jaoks hõivatud 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).

Siin on oluline meeles pidada, et PHP genereerib DigiDocService-teenusega suhtlemiseks vajaliku klassi vaid ühe korra ning siis salvestab selle kettale. Kui peale seda muuta ülejäänud lähtekoodi, conf.php-d või näiteks paigaldada PHP cURL-moodul, tuleb wsdl.class.php ära kustutada, et see uuesti genereeritaks.

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 digitaaltempli draiverid. Samuti tuleb teha mõned muudatused libdigidoc-teegi seadete failis.

Draiverite paigaldamiseks vaata peatükki krüptopulga kasutamine.

Libdigidoc-teegi seadete faili on vaikimisi asukohas %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 (taas võivad moodulite tegelikud 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

Samuti tuleb ära muuta allkirjastamiseks kasutatava pesa number:

DIGIDOC_SIGNATURE_SLOT=0

Avalduste rakendus

Avalduste rakenduse järgnevusskeem

Laadi alla: Avalduste rakenduse lähtekood (Java, .NET)

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. Rakendus krüpteerib konteineri lahti, kontrollib allkirja ning kuvab konteineri sisu kasutajale.

Rakendus on algselt kirjutatud Javas, kus kasutatakse JDigiDoc teeki, ning seejärel porditud .NET-i, kus kasutatakse COM-teeki. Mõned rakenduse alamosad (allkirjastamine, isikutuvastus, allkirja kontrollimine ja andmete dekrüpteerimine) on ümber kirjutatud ka keeles C++, 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.
    • .NET rakendus kontrollib sertifikaadi kehtivust vaid CRL abil; OCSP toetamiseks tuleb kasutada kolmanda osapoole teeke (nt. Bouncy Castle).
  2. Kasutajalt küsitakse sisendit avaldusele - tegu on lihtsa, üherealise tekstisisestusega. Kuna teegid oskavad kasutada vaid kettale salvestatud faile, siis salvestatakse sisestatud info ajutisse faili.
  3. Ajutiselt salvestatakse kettale kaardilt loetud isikuandmed (teegid isikuandmete faili lugemist ei toeta, mistõttu tehakse seda käsitsi, lähtudes EstEID kaardi kasutusjuhendist -- sellest, kas üldse ja kuidas isikuandmete faili lugeda, loe täpsemalt isikuandmete faili kasutamise alt).
  4. Andmed pannakse DDOC-konteinerisse ning allkirjastatakse -- viimase käigus kontrollitakse ka allkirjastamiseks kasutatava sertifikaadi kehtivust.
  5. Kontrollitakse, kas konteiner verifitseerub ning kirjutatakse see kettale.
  6. Konteiner saadetakse avaldusi töötlevale teenusele ning vastuseks saadakse krüpteeritud konteiner.
    • Kuna COM-teek ei toeta dekrüpteerimist, siis .NET rakenduse puhul palutakse serverilt krüpteerimata vastust. Seetõttu jääb ka järgmine samm vahele.
  7. Konteineris olev transpordivõti krüpteeritakse lahti kasutaja isikutuvastussertifikaadi salajase võtmega ning seda kasutatakse teenuse poolt allkirjastatud vastuse lahtikrüpteerimiseks.
  8. Allkirjastatud vastus salvestatakse kettale ning seejärel kontrollitakse sellel olevat allkirja.
  9. Kasutajale kuvatakse teenuse vastuse sisu.

NB! Java rakendus vajab Java versiooni 1.7 või uuemat.

Vaikimisi töötab avalduste rakendus isikutuvastus vaid 2048-bitiste võtmete kaartidega: kui on soovi kasutada vanemaid kaarte, siis tuleb lähtekoodis räsialgoritm välja vahetada (vt Viga enne 2011. aastat välja antud kaartidega).

Rakenduse kasutamine

Java rakendusega on kaasas Ant ehitusskript, mis kompileerib kõik klassid ning loob neist JAR-faili. Enne kompileerimist tuleb Ant'i skriptis ära muuta kasutatavate teekide asukohad. Pärast seda piisab vaid ant käsu käivitamisest, mis loob client.jar'i. Skript nõuab vähemalt Ant versiooni 1.7.

Java rakendus sõltub järgmistest teekidest (need on kõik JDigiDoc pakiga kaasas, neile tuleb lihtsalt viidata):

  • 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

.NET rakendusega on kaasa Visual Studio 2010 projektifailid, millega saab rakenduse kompileerida. Kui seda veel pole, siis tuleb projekti lisada ka viide COM-teegile. Peale viite lisamist peab References alt avama DIGIDOCLIBCOMLib sätted (Properties) ning Embed Interop Types väärtuseks panema False.

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

java -jar client.jar [-cfg config] [url] # Java
EidClient.exe [url]                      # .NET

Kui teenusega luuakse HTTPS-ühendus (tungivalt soovitatav), siis kontrollitakse, et serveri sertifikaadi väljaandja oleks süsteemile tuttav. Java jaoks tähendab see, et võti oleks keystore'is olemas, ning .NET jaoks, et see on paigaldatud Windowsi sertifikaadihoidlasse.

Kui teenus kasutab enda allkirjastatud (self-signed) sertifikaate (näiteks testimisel), siis on vaja need enne Java 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

Enda allkirjastatud sertifikaadi lisamiseks Windowsi sertifikaadihoidlasse piisab sellele topeltklõpsamisest ning "Paigalda sertifikaat" ("Install certificate") valimisest.

Allkirjastamise rakendus

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

C++

Laadi alla: 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 konteineri nimi; laiendi .bdoc korral luuakse BDOC, vastasel korral DIGIDOC-XML

Java

Laadi alla: 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
  • 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 (need on kõik JDigiDoc pakiga kaasas, neile tuleb lihtsalt viidata):

  • 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 (ehk teisisõnu, 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.

Vaikimisi töötavad rakendused vaid 2048-bitiste võtmete kaartidega: kui on soovi kasutada vanemaid kaarte, siis tuleb räsialgoritm välja vahetada (vt Viga enne 2011. aastat välja antud kaartidega).

C++

Laadi alla: Lähtekood

Kompileerimine:

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

Rakendus käivitatakse ilma argumentideta:

./auth

Java

Laadi alla: 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 classpath'is järgmised teegid (need on kõik JDigiDoc pakiga kaasas, neile tuleb lihtsalt viidata):

  • 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++

Laadi alla: Lähtekood

Vajab Xerces-C++ XML Parser'i arenduspäised. Windows jaoks leiab need teegi kodulehelt, Linux all tuleb paigaldada libxerces-c2-dev või libxerces-c-devel pakk.

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.

DigiDoc rakendustes tõstetakse krüpteeritavad andmed kõigepealt DDOC-konteinerisse ning siis pannakse see CDOC-konteinerisse. Käesolev rakendus võtab dekrüpteerides DDOC-i küll CDOC seest välja, ent jätab andmefailid DDOC sisse: seda sellepärast, et viimane võib olla allkirjastatud ning oleks vaja kontrollida allkirja enne andmete avamist. Samuti võib arendajal olla soov arhiveerida krüpteerimata (kuna eID-dokumendiga krüpteeritud andmed pole selleks sobilikud), ent allkirjastatud DDOC-dokument.

Vaatamata käesoleva rakenduse käitumisele on üldlevinud olukordades allolev DDOC siiski allkirjastamata ning andmeid dekrüpteerides võib selle kohe lahti pakkida. Näidet sellest allkirju kontrollivas rakenduses.

C++

Laadi alla: 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

Lihtne ligipääsukontroll Apache httpd-s

Lühike ja lihtne näide, kuidas Apache httpd veebiserveris lubada ligipääs ainult ID-kaardiga ning kindlatele kasutajatele. Allolevate näidete jaoks peab olema juba seadistatud Apache httpd veebiserver, mis kasutab SSL-i ning nõuab kasutajalt sertifikaati (s.t SSLVerifyClient require).

Kui ligipääs on vaja lubada vaid väikesele ning harva muutuvale hulgale inimestele, siis on kõige lihtsam seda teha SSLRequire direktiiviga:

SSLRequire %{SSL_CLIENT_S_DN_CN} in {"MÄNNIK,MARI-LIIS,47101010033", "PERENIMI,EESNIMI,ISIKUKOOD"}

Kui ligipääs on vaja lubada suurele hulgale inimestele, siis on ligipääsufaile mugavam muuta kui seadistusfaile. Seame üles Basic autentimise ning kasutame FakeBasicAuth'i:

AuthType Basic
AuthName "Ainult ID-kaardiga"
AuthBasicProvider file                  # Siin saab ilmselgelt kasutada ka mõnda teist moodulit
AuthUserFile /kuskil/kaust/httpd.passwd # See fail peab olema turvalises kohas, kus teised seda lugeda ega muuta ei saa
Require valid-user

SSLOptions +FakeBasicAuth

Kui nüüd alustada SSL/TLS seanssi serveriga, siis mod_ssl üritab läbi viia Basic autentimist, kus kasutajanimeks on kliendisertifikaadil olev Distinguished Name ning parooliks "password". Seega on vaja lisada ligipääsufaili vastavad read iga inimese jaoks. Seda saab lihtsalt teha htpasswd utiliidiga:

htpasswd -b /kuskil/kaust/httpd.passwd <DN> password

Sobivas formaadis Distinguished Name saab leida openssl utiliidiga:

openssl x509 -noout -subject -in <sertifikaat>

Testkaardi DN on näiteks /C=EE/O=ESTEID/OU=authentication/CN=M\xC3\x84NNIK,MARI-LIIS,47101010033/SN=M\xC3\x84NNIK/GN=MARI-LIIS/serialNumber=47101010033.

Tähelepanu: FakeBasicAuth tõttu ei saa parooliks "password" asemel midagi muud kasutada. Kuna kellegi nime ning isikukoodi teada saamine pole keeruline, siis on ka autentimisel kasutatava DN-i ja parooli leidmine lihtne. Seetõttu peab serveri kindlasti niimoodi seadistama, et kaitstud kaustale ei oleks võimalik ilma SSL/TLS-ita ligi pääseda. Siis isegi, kui keegi üritab kasutada teise DN-i, asendatakse see tema sertifikaadilt loetuga.

Allikaviited