Näiterakendused keerukam

Allikas: eid.eesti.ee

Keerukam näiterakendus digiallkirjastatud avalduste koostamiseks ja töötlemiseks

Ülevaade

Siin esitatakse näiterakendus ehk kasutusmall avalduste loomiseks, allkirjastamiseks, vastuvõtmiseks ja kontrollimiseks. Näiterakendus koosneb kolmest osast:

  • Avalduste loomise ja digiallkirjastamise veebivorm veebiserveris: realiseeritud PHP-s.
  • Allkirjastatud avaldusi töötlev/kontrolliv/krüpteeriv teenus veebiserveris: realiseeritud PHP-s.
  • Alternatiivne avalduste loomise ja digiallkirjastamise käsurearakendus: realiseeritud Java-s ja .NET-s.
Kasutusmalli osapooled

Detailsemalt:

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.

Näiterakenduse tööpõhimõtted

Veebipõhine avalduste rakendus ID-kaardiga allkirjastamisega

Veebivormi järgnevusskeem

Tegemist on veebikeskkonnas realiseeritud vormi täitmise ja ID-kaardiga allkirjastamise rakendusega.

  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.

Veebipõhine avalduste rakendus mobiil-ID allkirjastamisega

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.

Tegemist on veebikeskkonnas realiseeritud vormi täitmise ja Mobiil-ID abil allkirjastamise rakendusega.

Antud lahendus on muidu samasuguse tööprotsessiga, kui ID-kaardiga allkirjastamise lahendus, kuid omab sellega võrreldes kahte olulist erinevust:

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.

Java ja .Net põhine avalduste rakendus ID-kaardiga allkirjastamisega

Avalduste rakenduse järgnevusskeem

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).

Avaldusi töötlev veebiteenus

Avaldusi töötleva teenuse järgnevusskeem

Kõik eelpool kirjeldatud avalduste klientrakendused pöörduvad avalduse töötlemiseks avaldusi töötleva veebiteenuse poole. See on kirjutatud PHP-s ning kasutab avaldusel oleva allkirja kontrolliks DigiDocService-teenust. Vastuse allkirjastamiseks ja krüpteerimiseks kasutatakse SWIG-mähkurit (vt PHPs DigDoc teegi kasutamine) libdigidoc-teegi ümber.

Teenuse poole pöördutakse URL http://localhost/eid/avaldused/submit.php abil (kui rakendust ei paigaldatud lokaalsesse arvutisse, tuleb localhost asemel kasutada vastava serveri nime). Teenus on käivitatav ka üle HTTPS protokolli (seda tuleb tingimata kasutada päris rakenduste korral).

  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.

Näiterakenduse paigaldamine

Sõltuvused

Veebipõhiste klientrakenduste ning avalduste töötlemise veebiteenuse sõltuvused

Näitekood on loodud platvormil Ubuntu 12.04 Long-Term Support ehk Precise Pangolin (64-bit), millele peab olema paigaldatud järgmised paketid:

  • apache2 2.2.22-1ubuntu1.4
  • php5 5.3.10-1ubuntu3
  • php5-dev 5.3.10-1ubuntu3
  • php5-curl 5.3.10-1ubuntu3
  • swig 2.0.4+really2.0.4-4ubuntu2

Vaikimisi on ubuntu'l komplektis vanad digidoc teegid. Uute kasutamiseks on vaja käivitada käsurealt skript https://installer.id.ee/media/install-scripts/install-esteid-ubuntu.sh.

Java klientrakenduse sõltuvused

Klientrakenduse kompileerimiseks peab olema arvutisse paigaldatud paketid:

  • openjdk-7-jdk
  • ant 1.8.2-4build1

Java klientrakendus nõuab järgmisi väliseid teeke:

Java klientrakenduse paigaldusskriptid ja konfiguratsioon on arvestatud paigaldamiseks samasse arvutisse, kuhu ka avalduste veebirakendus. Kui kasutatakse teist arvutit võib olla sõltuvalt operatsioonisüsteemist vajalik nii paigaldusskriptide muutmine kui ka konfiguratsioonifailide muutmine. Samuti tuleb hoolitseda, et arvutisse oleks paigaldatud digidoc teegid (vt eelmine punkt).

Apache serveri häälestamine

Üldist

Antud näites eeldatakse Apache httpd kasutamist. Serverile 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.

Järgnevates punktides on täpselt sammhaaval lahti kirjeldatud, kuidas näite jaoks vajalikul kujul veebiserver häälestada tuleb.

Sertifikaatide paigaldus

Serveri sertifikaadi loomine

Näidete jaoks piisab, kui serverile on tehtud nn. self-signed sertifikaat. Päris serveri korral tuleb taotleda ametlik SSL serveri sertifikaat. Sertifikaadi saab tekitada järgmiste käskudega:

su -
cd /etc/ssl/private
openssl genrsa -out server.key 1024
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -signkey server.key -out ../certs/server.crt 

SK sertifikaatide laadimine

ID-kaardiga autentimiseks on vaja ära näidata, milliste SK CA sertifikaatide alt välja antud sertifikaatidega on autentimine lubatud. Selleks tuleb vajalikd SK sertifikaadid alla laadida ja liita üheks failiks kokku:

cd /etc/ssl/certs
wget http://sk.ee/upload/files/JUUR-SK.PEM.cer 
wget http://sk.ee/upload/files/EECCRCA.pem.cer 
wget http://sk.ee/upload/files/ESTEID-SK%202007.PEM.cer 
wget http://sk.ee/upload/files/ESTEID-SK%202011.pem.cer 
cat JUUR-SK.PEM.cer EECCRCA.pem.cer ESTEID-SK\ 2007.PEM.cer ESTEID-SK\ 2011.pem.cer > id.crt

Tühistusnimekirjade laadimine

Tühistusnimekirjades on toodud ära sertifikaadid, mis on tühistatud ning millega ei tohi autentimist lubada. Tühistusnimekirjad saab SK veebist, need tuleb Apache jaoks teisendada aga PEM formaati:

mkdir /etc/ssl/crl
cd /etc/ssl/crl
wget http://www.sk.ee/crls/esteid/esteid2007.crl 
wget http://www.sk.ee/crls/juur/crl.crl 
wget http://www.sk.ee/crls/eeccrca/eeccrca.crl 
wget http://www.sk.ee/repository/crls/esteid2011.crl 
openssl crl -in esteid2007.crl -out esteid2007.crl -inform DER 
openssl crl -in crl.crl -out crl.crl -inform DER 
openssl crl -in eeccrca.crl -out eeccrca.crl -inform DER 
openssl crl -in esteid2011.crl -out esteid2011.crl -inform DER 

Tühistusnimekirjade listi tekitamine

Apache otsib tühistusnimekirju kataloogist teatud kujul failinimede järgi. Seetõttu tuleb tekitada vajalikud symbolic lingid järgmisel moel:

ln -s crl.crl `openssl crl -hash -noout -in crl.crl`.r0 
ln -s esteid2007.crl `openssl crl -hash -noout -in esteid2007.crl`.r0 
ln -s eeccrca.crl `openssl crl -hash -noout -in eeccrca.crl`.r0 
ln -s esteid2011.crl `openssl crl -hash -noout -in esteid2011.crl`.r0

Apache serveris mod_ssl sisselüllitamine

Apache serveris on vaikimisi mod_ssl välja lülitatud. Selle saab sisse lülitada järgmiselt:

cp /etc/apache2/sites-available/default-ssl /etc/apache2/sites-enabled/
cd /etc/apache2/mods-enabled
ln -s ../available/ssl.conf
ln -s ../available/ssl.load

Apache serveri konfiguratsiooni täiendamine

ID-kaardi sertifikaatide nõudmise sisselülitamiseks tuleb modifitseerida Apache konfiguratsioonifaili /etc/apache2/sites-enabled/default-ssl, lisades sinna (või muutes olemasolevaid) konfiguratsiooniparameetreid:

SSLCertificateFile    /etc/ssl/certs/server.crt
SSLCertificateKeyFile /etc/ssl/private/server.key
SSLCACertificateFile  /etc/ssl/certs/id.crt
SSLCARevocationPath /etc/ssl/crl/

Apache konfiguratsioonis ID-kaardiga autentimise sisselülitamine

Selleks, et näidata ID-kaardiga autentimise nõutavus vajalikus asukohas, tuleb lisada järgmised read konfiguratsioonifaili /etc/apache2/sites-enabled/default-ssl:

<Location /eid/avaldused/webform>
SSLVerifyClient require 
SSLVerifyDepth  2 
SSLOptions +StdEnvVars +ExportCertData
</Location>

Apache muudatuste jõustamine

Peale Apache konfiguratsioonimuudatuste tegemist tuleb teha restart:

/etc/init.d/apache2 restart

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[1], 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.

Teenuse testversiooni kasutamine

Selleks, et näiterakenduse ID-kaardiga allkirjastamise osa oleks võimalik proovida, on vaja oma ID-kaardi sertifikaat üles laadida test- DigiDoc Portaali https://www.openxades.org/upload_cert.php Selleks, et näiterakenduse Mobiil-ID allkirjastamise osa oleks võimalik proovida, on vaja oma Mobiil-ID sertifikaadid laadida test- DigiDoc Portaali https://www.openxades.org/MIDCertsReg/

Täpsemalt vt. juhendit http://www.id.ee/index.php?id=30303

Näiterakenduse tarkvara paigaldamine

Kõik rakendusjuhendi näiterakendused asuvad github keskkonnas: https://github.com/tammet/eid

Näiterakenduse paigaldamiseks tuleb see alla laadida, käivitada koosteskript ning paigaldusskript:

cd /var/www
git clone https://github.com/tammet/eid
cd eid/avaldused
sh ./build.sh
su -c ./inst-root.sh

NB! Installskript muudab /etc/digidoc.conf faili sisu test- DigiDoc Service jaoks sobivaks. Toodangulahenduse kasutamiseks see enam ei sobi. Vana fail säilitatakse nimega /etc/digidoc.conf.orig.

Näiterakenduse avalduste töötlemise komponendis on vaikimisi vastuse allkirjastamine välja lülitatud. Kui see soovitakse sisse lülitada, tuleb hoolitseda, et serveriga oleks ühendatud ID-kaardi lugeja, see häälestatud töövalmis antud juhendis kirjeldatud moel ning lugejas on eID kaart. Allkirjastamise sisselülitamiseks tuleb failis eid/avaldused/conf.php muuta definitsiooni DD_SIGN_RESPONSE väärtuseks 1:

define('DD_SIGN_RESPONSE', 1);

Näiterakenduse veebivormide paigaldamine

Näiterakenduse veebipõhiste kliendivormide kävitiamiseks mingeid täiendavaid tegevusi teha pole vaja. Veebivormide kasutamiseks tuleb liikuda veebilehitsejaga URLile https://localhost/eid/avaldused/ ning valida sealt soovitud veebivormi link. ID-kaardiga allkirjastatava veebivormi korral nõutakse seejärel koheselt ID-kaardiga sisselogimist.

Kui näiterakendus ei asu veebilehitsejaga samas masinas, siis tuleb URLis asendada localhost õige arvuti nimega.

Näiterakenduse Java kliendi paigaldamine

Kui on soov testida näiterakenduse Java klienti, siis tuleb see täiendavalt eraldi kompileerida. Selleks tuleb minna kataloogi eid/avaldused/client-java ja seal anda käsk:

sh ./build.sh

Kliendi saab mugavalt käivitada käsuga:

sh ./client.sh

Klient on häälestatud töötama avaldusi töötleva veebiteenusega üle HTTP protokolli. Kui on soov testida üle HTTPS protokolli toimimist (vajalik tingimata pärisrealisatsioonides), tuleb vastavalt modifitseerida client.sh skriptis leiduvat URLi. Lisaks tuleb hoolitseda, et serveri sertifikaadi väljaandja oleks süsteemile tuttav. Selleks peab vastav sertifikaat olema keystore'is olemas. 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


Näiterakenduse .Net kliendi paigaldamine

.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.

Klient on häälestatud töötama avaldusi töötleva veebiteenusega üle HTTP protokolli. Kui on soov testida üle HTTPS protokolli toimimist (vajalik tingimata pärisrealisatsioonides), tuleb anda kliendile parameetriks vastavURL. Lisaks tuleb hoolitseda, et serveri sertifikaadi väljaandja oleks süsteemile tuttav. Selleks peab vastav sertifikaat olema paigaldatud Windowsi sertifikaadihoidlasse. Enda allkirjastatud sertifikaadi lisamiseks Windowsi sertifikaadihoidlasse piisab sellele topeltklõpsamisest ning "Paigalda sertifikaat" ("Install certificate") valimisest.

Rakendus on käivitatav käsuga:

EidClient.exe [url]

Märkused näiterakenduse kohta

Näiterakenduse JavaScript komponendid

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.[2][3]

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 meetodi loadSigningPlugin() 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.[3]

Näiterakenduse .NET komponent

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.

Tulevikus on plaanitud luua ka eraldi .NET teek, mis asendab COM-teegi.[4]

PHPs DigDoc teegi kasutamine

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

Laiend asub allalaetud tarkvaras kataloogis eid/avaldused/swig. Näiterakenduse paigaldusskript teostab kõik vajalikud tööd selle paigaldamiseks. Allpool on toodud juhendid juhuks, kui on soov seda käsitsi paigaldada.

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.[5]

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[6], 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://www.openxades.org/cgi-bin/ocsp.cgi.

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

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

Allikaviited

  1. http://php.net/manual/en/class.soapclient.php
  2. JavaScripti klienditeek (idCard.js) veebis allkirjastamise lihtsustamiseks. http://id.ee/index.php?id=30369
  3. 3,0 3,1 Veebilehel allkirjastamine ID-kaardi ja digi-ID'ga. http://id.ee/index.php?id=30279
  4. http://id.ee/index.php?id=30290
  5. http://www.swig.org/Doc1.3/Php.html
  6. http://php.net/manual/en/function.dl.php