Käsurea näiterakendused

Allikas: eid.eesti.ee

Allkirjastamise, kontrollimise, krüpteerimise käsurea-rakendused

Ülevaade näidetest

Alltoodud näiterakendused realiseerivad eID keerukamaid funktsionaalsusi väikeste, konkreetse eesmärgiga käsurearakendustena, mida saab kasutada allkirjastamist kasutavate erilahenduste loomisel näitekomponentidena. Näidetes kasutatavad keeled on Java ning C++.

Konkreetselt tuuakse näited:

  • autentimisest,
  • allkirjastamisest,
  • allkirja kontrollimisest,
  • dekrüpteerimisest.

Pane tähele, et näited on mõeldud eeskätt teekide kasutamise demonstreerimiseks tarkvara-arenduses, mitte niivõrd praktiliste rakendustena autentimiseks/allkirjastamiseks/jne: erilahenduste koostamisel on üldjuhul mugavam kasutada jgididoc Java teegi osana levitatavat valmis käsurea-rakendust jdigidocutil, mida saab välja kutsuda mistahes programmeerimiskeskkonnast, anda talle vajalikud käsurea-parameetrid (sh näiteks PIN) ja kasutada teda vajaliku funktsionaalsuse jaoks.

Teiseks pane tähele, et autentimise ja allkirjastamise näited on mõttekad ainult kasutaja arvutis realiseeritavate erilahenduste jaoks (kui eID standardtarkvara mingil põhjusel ei sobi). Enamikes eID kasutamise stsenaariumides on kasutaja arvutis aga parem rakendada standardlahendusi, seega on mainitud näited pigem mõttekad teekide kasutamise demonstreerimiseks.

Allkirja kontrollimise rakendus omab aga selgelt mõtet ka serverirakendusena.

Kolmandaks pane tähele, et näidete oluline osa on vajaliku tarkvaralise keskkonna ja konfigureerimise kirjeldus, mis on kriitiline nii teekide kasutamiseks kui mainitud jdigidocutil käsurea-rakenduse kasutamiseks.

Kõik alltoodud koodinäited leiad ka Githubist.

Eeldused: operatsioonisüsteemid ja teegid

Järgnevas toodud Java näited on kasutatavad nii Windowsi operatsioonisüsteemil (katsetatud konkreetselt 64-bitises Windows 7 keskkonnas) kui Ubuntu Linuxi keskkonnas (katsetatud 64-bitisel variandil). Kummalgi juhul on kõigepealt vajalik arvuti seadistamine selliselt, et tal oleks võimalik ID-kaardiga suhelda. Selleks on kõige targem installeerida arvutis standardne DigiDoc kliendirakendus ja katsetada, kas seda õnnestub kasutada.

AS Sertifitseerimiskeskuse teekide üldinfo leht soovitab uute rakenduste koostamisel kasutada jdigidoc Java teeki.

Java teek jdigidoc: seadistused ja kompileerimine

Järgnevad Java koodinäited on katsetatud nii uue 3.8.1.709 kui vanema 3.6.0.157 versiooniga: teegid leiad siit lehelt. Mainitud Java teek ei vaja ei näidete kompileerimiseks ega katsetamiseks mingit täiendavat tarkvara peale kahe täiendava .jar failide komplekti, mida kohe selgitame.

Java versioon peab olema 1.7 või uuem.

PKCS11Wrapper.dll kopeerimine

Lahtipakitud teegi /lib alamkataloogis leiad kataloogid

  • linux32
  • linux64
  • macUniversal
  • win32
  • win64

Neis asuvad vastavale operatsioonisüsteemile sobivad variandid failist PKCS11Wrapper.dll. Võta oma operatsioonisüsteemile/Java versioonile sobiv fail ja kopeeri ta mõnda kataloogi, kust operatsioonisüsteem teda programme kävitades üles leiab. Windowsis võid ta kopeerida näiteks c:\windows\system32 alla või ka lausa C:\Program Files (x86)\Java\jdk1.7.0 alla.

Kehtivuskinnituse (OCSP) seaded

Järgmisena säti lahti pakitud juurkataloogis olevat konfiguratsioonifaili jgididoc.cfg: vaikimisi kaasa tuleva konfiguratsioonifailiga ei saa näiteid ega käsurea utiliiti edukalt käivitada.

Peamine, mis tuleb muuta, on kehtivuskinnituse (OCSP) seaded. Sa pead hankima endale .p12d sufiksiga juurdepääsutõendi lehelt https://www.sk.ee/getaccess/. Salvesta fail samasse lahti pakitud juurkataloogi, kus juba paikneb jgididoc.cfg.

Juurdepääsutõendiga koos saad tema parooli. Kui avad juurdepääsutõendi DigiDoc kliendiprogrammiga, näed lisaks tema seerianumbrit. Seepeale säti vastavaks järgmine blokk jgididoc.cfg failist, st pane SINU_JUURDEPÄÄSUTÕENDI_FAIL asemele reaalne failinimi (.p12d sufiksiga), SINU_PAROOL asemel juurdepääsutõendi parool (mitte ID-kaardi PIN1 või PIN2) ja SINU_SEERIANUMBER asemele juurdepääsutõendi seerianumber (ei ole sama number, mis faili nimi).

# sign OCSP requests or not. Depends on your responder
SIGN_OCSP_REQUESTS=true
DIGIDOC_PKCS12_CONTAINER=SINU_JUURDEPÄÄSUTÕENDI_FAIL
DIGIDOC_PKCS12_PASSWD=SINU_PAROOL
DIGIDOC_OCSP_SIGN_CERT_SERIAL=SINU_SEERIANUMBER

Järgmised read võivad osutuda samuti oluliseks, eeskätt Linuxi puhul. Windowsis neid üldjuhul muuta vaja ei ole:

DIGIDOC_SIGN_PKCS11_DRIVER - kaardi PKCS11 API draiver
DIGIDOC_LOG4J_CONFIG - logimise konfiguratsioonifail
DIGIDOC_CA_1_CERT, DIGIDOC_CA_1_OCSP, DIGIDOC_CA_1_OCSP - sertifikaatide asukohad; kasutada eesliidet jar:// et anda asukoht classpathist.


Täiendavad jar failid

Järgmisena lae lehelt https://installer.id.ee/media/esteidtestcerts.jar .jar fail testsertifikaatidega ja lisa see .jar fail lib alamkataloogi (alternatiiv on jgididoc.cfg failist eemaldada viited testsertifikaatidele).

Uue teegiversiooni 3.8.1.709 jaoks on vaja täiendavalt laadida java paigalduskataloogi lib/security (näiteks C:\Program Files\Java\jre7\lib\security või C:\Program Files (x86)\Java\jdk1.7.0\jre\lib) pikemaid võtmepikkusi võimaldavad nn policy failid, mille saab aadressilt http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html . Konkreetselt siis lae mainitud lehelt alla .zip fail, paki lahti ja kopeeri sealt leitud .jar faili eelmainitud kataloogi.

Näidete kompileerimine

Kompileerimiseks ei ole vaja mingit täiendavat tarkvara peale standardse JDK. Ka eelmainitud seaded ning täiendavad jar failid ei ole kompileerimiseks olulised.

Võid näiteks kopeerida alltoodud failid JavaSign.java ja JavaAuth.java otse teegi lahtipakitud juurkataloogi, minna ise sinna kataloogi ja öelda Windowsis

 javac -cp ".;jdigidoc-3.8.1-709.jar;lib;lib/*" JavaSign.java

Linuxis tuleb semikoolonid ; ülal asendada kooloniga :

Seepeale peaks samasse kataloogi tekkima fail JavaSign.class

Näidete käivitamine

Kui oled lahtipakitud teegi juurkataloogis ja JavaSign.class on sealsamas, siis käivitamiseks kirjuta analoogiliselt

  java -cp ".;jdigidoc-3.8.1-709.jar;lib;lib/*" JavaSign LICENSE.txt katse.ddoc

mispeale - kui sul ID-kaart on sees ja seadistamisel pole vigu tehtud - küsitakse PIN2-te, küsitakse AS Sertifitseerimiskeskusest kehtivuskinnitust ja luuakse korrektne allkirjastatud ümbrik katse.ddoc, mis sisaldab faili LICENSE.txt

C teek: libdigidocpp

C++ näidisrakendus kasutab teeki libdigidocpp, mida on kõige lihtsam hankida otse DigiDoc3 kliendi koosseisus. Eraldi on ta võimalik hankida:

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.

Universaalne Java käsurea utiliit jdigidocutil

Java teegi jdigidoc koosseisus on väga mugav ja praktiline käsurealt käivitatav utiliit jdigidocutil, mis võimaldab programmiliselt kasutada enamikku ID-kaardi funktsionaalsust, ilma mingi graafilise kasutajaliideseta.

Mistahes eriarenduste loomisel on kõigepealt mõistlik uurida, kas nimetatud utiliit juba ei lahenda teie vajadusi, selle asemel, et hakata kirjutama otse digidoc teeki kasutavat arendust. Käsurea utiliiti on väga lihtne välja kutsuda mistahes programmeerimiskeskkonnast.

Utiliidi käivitamiseks mine teegi lahtipakitud juurkataloogi ja kirjuta

  java -jar jdigidocutil-3.8.1-709.jar -config jdigidoc.cfg -help

mispeale näed erinevaid kasutusviise ja neile vastavaid käsurea-parameetreid.

Faili digiallkirjastamiseks kirjuta samas

  java -jar jdigidocutil-3.8.1-709.jar -config jdigidoc.cfg -ddoc-new -ddoc-add README.txt text/plain -ddoc-sign PAROOL -ddoc-out README.ddoc

kus PAROOL asemel kirjuta PIN2.

Kui seadistused on õigesti tehtud ja ühendus ID-kaardiga õnnestub, saad tulemuseks korrektse allkirjastatud ja kinnitatud digidoc faili README.ddoc

Allkirjastamise rakendus

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


Java

Laadi alla: Lähtekood

Kompileerimine ja käivitamine on eelnevas kirjeldatud.

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

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


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


Java

Laadi alla: Lähtekood

Kompileerimine ja käivitamine on eelnevas kirjeldatud.

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

java JavaAuth [-cfg config]


C++

Laadi alla: Lähtekood

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

Rakendus käivitatakse ilma argumentideta:

./auth


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


Arhivaalse ajatempliga BDOCi valideerimine

Arhivaalse ajatempliga BDOCi on võimalik valideerida libdigidocpp teegis (vt juhis http://open-eid.github.io/libdigidocpp/manual.html peatükk Opening document, validating signatures and extracting data files)

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

Allikaviited