digidoc c-teegi kirjeldus koos kasutusjuhistega · das eesti digitaalallkirja seadus esteid eesti...

91
DigiDoc C-teegi kirjeldus koos kasutusjuhistega Dokumendi versioon: 2.2.5, 27.03.2006

Upload: others

Post on 15-Aug-2020

1 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

DigiDoc C - teegi kirjeldus koos kasutusjuhistega

Doku mendi versioon: 2.2.5, 27.03.2006

Page 2: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Sisukord:

Viited ja lühendid.....................................................................................................9DigiDoc C- teegi kasuta mine...............................................................................10

C - teegi ülevaade ................................................................................................10Sissejuhatus .....................................................................................................10Teegi failid........................................................................................................10Teegi kom ponendid.......................................................................................11Erinevused teegi versioonide 2.2.5 ja 2.1.20 vahel...............................12Erinevused teegi versioonide 2.1.20 ja 2.1.13 vahel.............................12Erinevused teegi versioonide 2.1.13 ja 2.1.0 vahel...............................13Erinevused teegi versioonide 2.1.0 ja 2.0.0 vahel..................................14Erinevused teegi versioonide 2.0.0 ja 1.96 vahel...................................15Erinevused teegi versioonide 1.96 ja 1.93 vahel....................................15Erinevused teegi versioonide 1.93 ja 1.89 vahel....................................15Erinevused teegi versioonide 1.89 ja 1.88 vahel....................................16Erinevused teegi versioonide 1.88 ja 1.80 vahel....................................16Erinevused teegi versioonide 1.80 ja 1.77 vahel....................................17Erinevused teegi versioonide 1.79 ja 1.77 vahel....................................17Erinevused teegi versioonide 1.77 ja 1.76 vahel....................................19Erinevused teegi versioonide 1.76 ja 1.66 vahel....................................19Erinevused teegi versioonide 1.66 ja 1.52 vahel....................................20Erinevused teegi versioonide 1.52 ja 1.41 vahel....................................20Erinevused teegi versioonide 1.52 ja 1.59 vahel....................................21

Juhised enam esinevate p robleemide kiireks lahenda miseks...............22Kuidas luua u usi DigiDoc'e..........................................................................22Kuidas lisada kehtivuskinnitust ?..............................................................25Kuidas otsida ser tifikaate DigiDoc'i funktsioonides ?.........................26Kuidas avada ja lugeda DigiDoc'e..............................................................27Kuidas lisada allkirja DigiDoc'ile...............................................................28

Näiteprogram mid DigiDoc'i C - teegi kasutamiseks..................................30CreateDoc.c......................................................................................................30ListSignatures.c...............................................................................................31

DigiDoc teek.............................................................................................................33Andmestruktuurid.............................................................................................33

SignedDoc.........................................................................................................33DataFile..............................................................................................................33DocInfo..............................................................................................................34SignatureProductionPlace............................................................................34SignerRole.........................................................................................................34SignatureInfo...................................................................................................35NotaryInfo.........................................................................................................35Timesta mp ........................................................................................................36PolicyIdentifier................................................................................................36CertSearch........................................................................................................36CertSearchStore...............................................................................................37ErrorInfo............................................................................................................37CSProvider........................................................................................................37

2

Page 3: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

CertItem............................................................................................................37DEncEncryptionProperty..............................................................................38DEncEncryptionProperties...........................................................................38DEncEncryptedKey.........................................................................................38DEncEncryptedData.......................................................................................38DEncRecvInfo...................................................................................................39DEncRecvInfoList............................................................................................39

Üldised - ja ad ministreerimisfunktsioonid.................................................40getLibName()....................................................................................................40getLibVersion()................................................................................................40getSupportedFormats().................................................................................40getSupportedFormatsAndVersions().........................................................40initDigiDocLib()...............................................................................................40finalizeDigiDocLib().......................................................................................40trim()..................................................................................................................40ascii2utf8()........................................................................................................40u tf82ascii()........................................................................................................41unicode2ascii().................................................................................................41convertStringToTimesta mp().......................................................................41convertTimestam pToString().......................................................................41Timesta mp_new()............................................................................................41Timesta mp_free()............................................................................................42

Üldised krüptograafiafunktsioonid...............................................................42bin2hex()............................................................................................................42calculateFileDigest().......................................................................................42calculateFileSignature().................................................................................42verifyFileSignature().......................................................................................43signData()..........................................................................................................43calculateDigest()..............................................................................................43encode().............................................................................................................43decode().............................................................................................................44

Üldised XMLi genereerivad funktsioonid.....................................................44createTimestam p()..........................................................................................44createXMLSignedInfo()...................................................................................44

Allkirjas ta tud doku mendi halduse funktsioonid......................................44getSimpleFileName()......................................................................................44SignedDoc_new().............................................................................................45SignedDoc_free().............................................................................................45getCountOfDataFiles()...................................................................................45getDataFile().....................................................................................................45getDataFileWithId().........................................................................................45d docGetDataFileCachedData()....................................................................45d docAppendDataFileData()..........................................................................45d docGetLastDataFile()...................................................................................46d docGetDataFileFilename()..........................................................................46DataFile_new().................................................................................................46DataFile_free()..................................................................................................47getCountOfDataFileAttributes()..................................................................47addDataFileAttribute()...................................................................................47getDataFileAttribute()....................................................................................47

3

Page 4: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

calculateDataFileSizeAndDigest()..............................................................47getCountOfSignatures()................................................................................47getSignature()...................................................................................................47getSignatureWithId()......................................................................................48d docGetLastSignature().................................................................................48SignatureInfo_new().......................................................................................48setSignatureProductionPlace()....................................................................48addSignerRole()...............................................................................................48getCountOfSignerRoles()..............................................................................48getSignerRole().................................................................................................49SignatureInfo_delete()...................................................................................49SignatureInfo_free().......................................................................................49addDocInfo()....................................................................................................49DocInfo_free()..................................................................................................49getCountOfDocInfos()...................................................................................49getDocInfo()......................................................................................................50getDocInfoWithId().........................................................................................50d docGetLastDocInfo()....................................................................................50setDocInfoDigest()..........................................................................................50setDocInfoMimeDigest()................................................................................50addAllDocInfos().............................................................................................50calculateSigInfoSignature()..........................................................................50getCountOfNotaryInfos()..............................................................................51getNotaryInfo()................................................................................................51getNotaryWithId()...........................................................................................51getNotaryWithSigId()......................................................................................51d docGetLastNotaryInfo()..............................................................................51NotaryInfo_new()............................................................................................51NotaryInfo_new_file()....................................................................................51NotaryInfo_free().............................................................................................52NotaryInfo_delete().........................................................................................52createXMLSignedProperties().......................................................................52calculateSignedPropertiesDigest()..............................................................52calculateSignedInfoDigest().........................................................................52setSignatureCertFile()....................................................................................53setSignatureCert()...........................................................................................53setSignatureValueFromFile()........................................................................53setSignatureValue()........................................................................................53

Allkirjas ta tud doku mendi kirjutamine........................................................53createSignedDoc()...........................................................................................53

Allkirjas ta tud doku mendi lugemine SAX parseri abil.............................53d docSaxReadSignedDocFromFile().............................................................53d docSaxReadSignedDocFromMemory()....................................................54d docSaxExtractDataFile()..............................................................................54

Allkirjas ta tud doku mendi lugemine XML-Reader API abil....................54d docXRdrReadSignedDocFromFile()..........................................................54d docXRdrReadSignedDocFromMemory().................................................54d docXRdrExtractDataFile()...........................................................................55d docXRdrGetDataFile()..................................................................................55

PKCS11 funktsioonid.........................................................................................55

4

Page 5: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

initPKCS11Library()........................................................................................55closePKCS11Library().....................................................................................55GetSlotIds().......................................................................................................55GetTokenInfo().................................................................................................56getDriverInfo().................................................................................................56GetSlotInfo().....................................................................................................56loadAndTestDriver()......................................................................................56calculateSignatureWithEstID().....................................................................56findUsersCertificate()....................................................................................57

Konfiguratsioonifaili funktsioonid................................................................57initConfigStore()..............................................................................................57cleanupConfigStore().....................................................................................57addConfigItem()..............................................................................................57createOrReplacePrivateConfigItem().........................................................57ConfigItem_lookup()......................................................................................58ConfigItem_lookup_int()...............................................................................58ConfigItem_lookup_bool()............................................................................58ConfigItem_lookup_str()...............................................................................58writePrivateConfigFile().................................................................................58notarizeSignature().........................................................................................58signDocument()...............................................................................................59verifyNotary()...................................................................................................59verifySignatureAndNotary().........................................................................59

Sertifikaatide funktsioonid..............................................................................59getSignCertData()............................................................................................59findCertificate()...............................................................................................59getNotCertData().............................................................................................59getCertIssuerName()......................................................................................60getCertSubjectName()....................................................................................60getCertSerialNumber()...................................................................................60GetCertSerialNumber()..................................................................................60getCertNotBefore()..........................................................................................60getCertNotAfter()............................................................................................60saveCert()..........................................................................................................60decodeCert().....................................................................................................61encodeCert().....................................................................................................61CertSearchStore_new()...................................................................................61CertSearchStore_free()...................................................................................61CertSearch_new()............................................................................................61CertSearch_free().............................................................................................61CertList_free ().................................................................................................61readCertPolicies()............................................................................................61PolicyIdentifiers_free()..................................................................................62isCompanyCPSPolicy()...................................................................................62

Allkirja kontrolli funktsioonid.......................................................................62compareByteArrays().....................................................................................62verifySigDocDigest().......................................................................................62verifySigDocMimeDigest()............................................................................62verifySigDocSigPropDigest()........................................................................63verifySignatureInfo()......................................................................................63

5

Page 6: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

verifySignatureInfoCERT()............................................................................63verifySignatureInfo_ByCertStore()..............................................................64verifySigDoc()...................................................................................................64verifySigDocCERT().........................................................................................64verifySigDoc_ByCertStore ().........................................................................65isCertValid()......................................................................................................65isCertSignedBy()..............................................................................................65isCertSignedByCERT()....................................................................................65verifySigCert()..................................................................................................66verifyNotaryInfo()...........................................................................................66verifyNotaryInfoCERT().................................................................................66verifyNotaryInfo_ByCertStore()...................................................................66verifyNotCert ()................................................................................................66verifyNotaryDigest().......................................................................................66writeOCSPRequest()........................................................................................67getConfirmation()...........................................................................................67calculateNotaryInfoDigest().........................................................................67getSignerCode()...............................................................................................67

Krüpteerimise ja dekrüpteerimise funktsioonid.......................................68dencEncryptedData_new()............................................................................68dencEncryptedData_free()............................................................................68dencEncryptedData_GetId().........................................................................68dencEncryptedData_GetType()....................................................................69dencEncryptedData_GetMimeType().........................................................69dencEncryptedData_GetMimeXmlNs()......................................................69dencEncryptedData_GetEncryptionMethod()..........................................69dencEncryptedData_GetEncryptionPropertiesId().................................69dencEncryptedData_GetEncryptionPropertiesCount().........................69dencEncryptedData_GetEncryptionProperty()........................................69dencEncryptedData_GetLastEncryptionProperty()................................69dencEncryptedData_FindEncryptionPropertyByName().......................69dencEncryptedData_GetEncryptedKeyCount().......................................70dencEncryptedData_GetEncryptedKey()...................................................70dencEncryptedData_FindEncryptedKeyByRecipient()...........................70dencEncryptedData_FindEncryptedKeyByCN().......................................70dencEncryptedData_GetLastEncrypted()..................................................70dencEncryptedData_GetEncryptedData().................................................70dencEncryptedData_GetEncryptedDataStatus().....................................70dencEncryptedData_SetId()..........................................................................70dencEncryptedData_SetType()....................................................................71dencEncryptedData_SetMimeType()..........................................................71dencEncryptedData_SetXmlNs().................................................................71dencEncryptedData_SetEncryptionMethod()...........................................71dencEncryptedData_AppendData()............................................................71dencEncryptedData_SetEncryptionPropertiesId()..................................71dencEncryptedData_DeleteEncryptionProperty()..................................71dencEncryptedData_DeleteEncryptedKey().............................................71dencEncryptionProperty_new()...................................................................72dencEncryptionProperty_free()...................................................................72dencEncryptionProperty_GetId()................................................................72

6

Page 7: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

dencEncryptionProperty_GetTarget()........................................................72dencEncryptionProperty_GetName().........................................................72dencEncryptionProperty_GetContent().....................................................72dencEncryptionProperty_SetId().................................................................72dencEncryptionProperty_SetTarget().........................................................72dencEncryptionProperty_SetName()..........................................................73dencEncryptionProperty_SetContent()......................................................73dencEncryptedKey_new()..............................................................................73dencEncryptedKey_free()..............................................................................73dencEncryptedKey_GetId()...........................................................................73dencEncryptedKey_GetRecipient().............................................................73dencEncryptedKey_GetEncryptionMethod()............................................73dencEncryptedKey_GetKeyName().............................................................74dencEncryptedKey_GetCarriedKeyName()...............................................74dencEncryptedKey_GetCertificate()...........................................................74dencEncryptedKey_SetId()............................................................................74dencEncryptedKey_SetRecipient()..............................................................74dencEncryptedKey_SetEncryptionMethod().............................................74dencEncryptedKey_SetKeyName()..............................................................74dencEncryptedKey_SetCarriedKeyName()................................................74dencEncryptedKey_SetCertificate()............................................................74dencEncryptedData_encryptData()............................................................75dencEncryptedData_decrypt_withKey()....................................................75dencEncryptedData_decryptData()............................................................75dencEncryptedData_decrypt().....................................................................75dencEncryptedData_compressData()........................................................75dencEncryptedData_decom pressData()....................................................75dencRecvInfo_new().......................................................................................76dencRecvInfo_free().......................................................................................76dencRecvInfo_store().....................................................................................76dencRecvInfo_findById()...............................................................................76dencRecvInfo_delete()...................................................................................76dencRecvInfo_findAll()..................................................................................76dencRecvInfoList_add().................................................................................76dencRecvInfoList_free().................................................................................77dencRecvInfoList_delete().............................................................................77dencEncryptFile()............................................................................................77dencGenEncryptedData_toXML()................................................................77dencGenEncryptedData_writeToFile().......................................................77dencSaxReadEncryptedData()......................................................................77dencSaxReadDecryptFile()............................................................................77dencOrigContent_count().............................................................................78dencOrigContent_add().................................................................................78dencOrigContent_findByIndex().................................................................78dencOrigContent_findByIndex().................................................................79dencOrigContent_registerDigiDoc()...........................................................79dencMetaInfo_SetLibVersion().....................................................................79dencMetaInfo_SetFormatVersion().............................................................79dencMetaInfo_GetLibVersion()....................................................................79dencMetaInfo_GetFormatVersion()............................................................79

7

Page 8: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Veatöötlusfunktsioonid....................................................................................80getErrorString()................................................................................................80getErrorClass().................................................................................................80checkDigiDocErrors().....................................................................................81getErrorInfo()...................................................................................................81hasUnreadErrors()...........................................................................................81clearErrors()......................................................................................................81

DigiDoc teegis kasutatavad konstandid ja nende väärtused .................81Allkirjas ta misega seotud konstandid.......................................................81Vorminguga seotud konstandid.................................................................82Veakoodid.........................................................................................................82Kasutusel olevad keeled ..............................................................................87OCSP päringu allkirjasta mise t üübi identifikaatorid...........................87Sertifikaatide o tsingu kohad .......................................................................87Sertifikaatide o tsingu kriteeriumid...........................................................87Toetatud kaar tide nimed..............................................................................88

CDigidoc kasutamine............................................................................................89Digiallkirjastamine.............................................................................................89Krüpteerimine ja dekrüp teerimine................................................................90Käsklused CGI reshiimis...................................................................................90

8

Page 9: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Käesolev doku ment kirjeldab DigiDoci'i C - teeki , mida kasutab saavad kasutada k ik DigiDoc süs teemi rakendused. DigiDoc doku ment onō esitatud XML kujul ning põhineb rahvusvahelistel s tandarditel XML-DSIG ja ETSI TS 101 903. DigiDoc'i teegi COM objektide versioon on doku menteeritud eraldi.

Viited ja lühendid

RFC2560 Myers, M., Ankney, R., Malpani, A., Galperin, S., Adams, C., X.509 Internet Public Key Infrastructure: Online Certificate Status Protocol - OCSP. June 1999.

RFC3275 Eastlake 3rd D., Reagle J., Solo D., (Extensible Markup Language) XML- Signature Syntax and Processing. (XML-DSIG) March 2002.

ETSI TS 101 903 XML Advanced Electronic Signatures (XAdES). February 2002.

XML Schema 2 XML Schema Part 2: Datatypes. W3C Recom mendation 02 May 2001h ttp: / / www.w3.org /TR /xmlschema - 2 /

DAS Eesti Digitaalallkirja Seadus

ESTEID Eesti ID kaar t

CSP (ka MS CSP)Microsoft Crypto Service Provider

PKCS#11 RSA Laboratories Cryptographic Token Interface Standard h t tp: / / www.rsasecurity.com / r salabs /PKCS/index.html

9

Page 10: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

DigiDoc C-teegi kasutamine

C-teegi ülevaade

Sissejuhatus

DigiDoc C- teek sobib kasutamiseks DigiDoc'i vormingut ja ESTEID kasutavates rakendustes. Teegis on funktsioonid DigiDoc for maadis doku mentide loomiseks, kustu ta miseks, haldamiseks ja allkirjas tamiseks. Teegi kasutamise h lbusta miseks on antudō doku mendi l ppu lisatud m ned näited sagedamate probleemideō ō kiireks lahenda miseks. Ta sõltub järgmistes t teekidest:

• OpenSSL – version 0.9.7 või u ue m. Seda saab siit: ftp: / / f t p.openssl.org / snapshot /

• libxml2 – versioon 2.5.1 või uuem. Seda saab siit: ftp: / / f t p.gnome.org / p ub /GNOME/stable / sources /libxml / , h t t p: / /www.xmlsoft.org / ja valmis binary failid siit: h t t p: / /www.zlatkovic.com / p rojects / libxml /index.html

Kui soovite teeki kasutada ka ESTEID kaardiga allkirjastamiseks on tarvilik kaardilugeja koos tarvilike ohjurprogra m midega. Teek toeatab kiipkaardi kasutamist läbi PKCS#11 standardi ( platvormil Win32 ) ja läbi Microsofti CSP.

DigiDoc teek ü ritab luua vahendid soovitud for maadis failide lugemisele ja kirjutamisele, sidu mata kasutajat seejuures mingi kindla küptograafiapaketi, faili füüsilise formaadi (XML vs. PKCS#7) või m u u teegi versiooniga. Seepäras t kasutatakse and mete salvestamiseks p rogrameerimiskeele C s t ruct - e, mis ei ole sõltuvad OpenSSL või XML teegi kasutatavatest and mestruktuuridest.

Teegi failid

Teeki on kom pileeritud Fedora Core 1 ja Mandrake 9.2 peal ning WinNT 4.0 ja Win2000 peal. M nede teegi funktsioonide jaoks onō tarvilik kaardilugeja ning ESTEID kiipkaar tDigiDoc C- teegi kooseisus kuuluvad neli algkoodi faili:

1. DigiDocLib.c - pea mine algkoodi fail kuhu on koondatud peaaegu kõik funktsioonid, seal hulgas kõik DigiDoc'i konteineri ja selle elementidega tegelevad funktsioonid, sam uti kontrolli ja kehtivuskinnituse funktsioonid. Mõned eelkõige allkirjas tamisega tegelevad funktsioonid kasutavad ESTEID kaardi võimalusi ning on seega kaardilugeja ohjur p rogram mide kaudu platvormist sõltuvad, realiseeritud on PKCS#11 tüüpi kaardilugeja Windows platvor mil ja MS CSP (samuti Windows platvormil).

10

Page 11: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Platvormist sõltuvad avalikud funktsioonid on:

• GetSignParametersWithEstIdCSP() - kasutatakse mit mesuguste ESTEID para meetrite küsimiseks läbi CSP.

• calculateSignatureWithEstID() - lisab digidoc'ile ESTEID allkirja läbi PKCS#11 tüü pi kaardilugeja.

• calculateSigInfoSignatureWithCSPEstID() - lisab digidoc'ile ESTEID allkirja läbi CSP.

Need funktsioonid sisaldavad kutseid EstIDLib.c's asuvatele platvormist ja ESTEID'st sõltuvatele funktsioonidele, ning m u utuksid m õt tetu teks kui EstIDLib.c's asuvad funktsioonid poleks neile kät te saadavad. Peale nende on ka mõned funktsioonid mida ainult teegi siseselt kasuta takse ja mõnede funktsioonide sees on osa blokke mis mitte windowsi platvormidel kompileerimisest välja jäävad.

Teisetel platvor midel kom pileerides tuleks vältida eelprotsessori konstante WIN32 ja WIN32_CSP mis vastava sõltuvuse koodi sisse kompileerivad.

2. DigiDocLib.h - Selles failis on deklareeritud k ik DigiDoc'i avalikudō funktsioonid ja konstandid

3. DigiDocPKCS11.c - Fail sisaldab funktsioone ESTEID kaardiga vajalike operatsioonide teostamiseks Windows'i ja Linux platvormil läbi PKCS#11 ühilduvate kaardilugejate.

4. DigiDocPKCS11.h - Fail sisaldab DigiDocPKCS11.c's defineeritud funktsioonide deklaratsioone.

5. DigiDocConfig.c - sisaldab configuratsioonifaili lugemiseks vajalikke funktsioone ja lihtsustatud allkirjastamis ning allkirja ja kehtivuskinnituse kontrollfunktsioone.

6. DigiDocConfig.h - sisaldab DigiDocConfig.h - s deklareeritud funktsioone

7. DigiDocError.c – sisaldab veatöötlusfunktsioone ja vigade kirjeldusi.

8. DigiDocError.h – sisaldab veatöötlusfunktsioonide ja veakoodide deklareeratsioone.

9. digidoc.c - käsureautiliit digidoc failidega seotud operatsioonideks ja sa mas ka näiteprogram m.

Teegi komponendid

Teek koosneb kolme liiki kom ponentidest:• Andmestruktuurid - need kasuta tavad C keele s truktuure and mete

paremaks haldamiseks, ena mus neist peegeldab vastavaid DigiDoc'i tag'e aga on ka mõned teegi tööd hõlbustavad st ruktuurid millel p uu dub vaste DigiDoc'is, näiteks ErrorInfo või CertSearch jt.

11

Page 12: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Andmestruktuurid on kirjeldatud samanimelises peatükis allpool ja deklareeritud on nad algfailis DigiDocLib.h.

• Konstandid - Oma töös kasutab teek palju konstante, sealhulgas veakoode. Konstandid on sa m m uti defineeritud failides DigiDocLib.h ja DigiDocError.h , neile on pühendatud oma peatükk käesolevas doku mendis.

• Funktsioonid - need on defineeritud teegi *.c'i failides. Avalikku huvi pakkuvad funktsioonid on ka deklareeritud DigiDocLib.h failis. Need viimased võib jaotada:

• Üldised - ja administreerimisfunktsioonid - siia all kuuluvad funktsioonid teegi enda kohta, sam m uti mõned üldised teisendus funktsioonid.

• Üldised krüptograafiafunktsioonid - siia hulka kuuluvad m õned räsikoodi arvutavad funktsioonid ja üldised allkirjastamise funktsioonid, sam m uti m õned OpenSSL kasutavad teisendus funktsioonid.

• Üldised XMLi genereerivad funktsioonid - siin all on funktsioonid mis sobisid m ääratluse XML'i genereerivad kuid "vähe" DigiDoc'i spetsiifilised funktsioonid.

• Allkirjastatud dokum endi halduse funktsioonid - see on suurim funktsioonide klass kuhu kuuluvad u u te s truktuuride lisamise ja kasuta mise funktsioonid aga ka s truktuuridelt info küsimise ja ESTEID'ga allkirjas tamise funktsioonid.

• Allkirjastatud dokum endi lugemine ja kirjutamine - siin on paar üldist funktsiooni mis tegelevad DigiDoc'i kirjutamise ja lugemisega.

• Sertifikaatide funktsioonid - siia klassi kuuluvad sertifikaatide lugemise, otsimise ja nendelt info küsimise funktsioonid.

• Allkirja kontrolli funktsioonid - selles klassis asub enam us verifiy* funktsioonidest mis tegelevad DigiDoci'i s t ruktuuri erinevate elementide kontrollimisega, samuti mõned üldised kontrolli funktsioonide poolt kasuta tavad funktsioonid.

• Veatöötlusfunktsioonid - selles viimases kuid täh tsas rüh mas on veatöötlusega seotud funktsioonid.

Erinevused teegi versioonide 2.2.5 ja 2.1.20 vahel● Lisati u ued OCSP responderi ser tifikaadid vanade asemel mis

varsti aeguvad.● Parandatu buffer - overflow vigu ja ründe võimalusi digidoc ja

cdoc doku mentide SAX parserites● Lisatud MSSP teenuse kasutamise funktsionaalsus

Erinevused teegi versioonide 2.1.20 ja 2.1.13 vahel● Lisati funktsioonid: d docCertGetSubjectCN() , ddocCertGetIssuerCN(),

12

Page 13: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

d docCertGetIssuerDN(), ddocCertGetSubjectDN(), d docCertGetSubjectFirstName(), ddocCertGetSubjectLastName(), d docCertGetSubjectPerCode()

● Kõik sertifikaatide informatsiooni tagastavad funktsioonid eristati eraldi algkoodifailidesse: DigiDocCert .h /.c

● Eemaldati väli: certNr s truktuurist NotaryInfo kuna sa ma info on väljas szIssuerSerial

● Lisati käsud cdigidoc u tiliidile CGI reshiimis kasuta miseks.

● Lisati võimalus määrata allkirjastamise PIN2 kasutades AUTOSIGN_PIN kirjet konfiguratioonifailis. Seda kasuta takse cdigidoc u tiliidi kasuta misel au tomaatse allkirjastamise reshiimis.

● Asendati funktsioon decodeCertificateData() funktsiooniga d docDecodeX509Data()

● Asendati funktsioon decodeCertificatePEMData() funktsiooniga d docDecodeX509PEMData()

● Lisati funktsioon ddocDecodeOCSPResponseData()

● Asendati funktsioon decodeOCSPResponsePEMData() funktsiooniga d docDecodeOCSPResponsePEMData()

● Lisati parameeter (int nMaxLen) funktsioonidele ReadCertSerialNumber() ja GetCertSerialNumber()

● Mittenõutud konfiguratsioonidfailide lugemisel tagasta takse alati ERR_OK & ERR_CONF_FILE

● Defineeriti g_szPrivateConfigFile - char[_MAX_PATH]

● Muudeti konfigura tsioonifailide asukohta win32 süs teemides

● globaalne konfiguratsioonifail asub: "%systemroot%\digidoc.ini" (tavaliselt "c: \windows \ digidoc.ini")

● kasutaja konfiguratsioonifail asub: "%HOME%\digidoc.ini"

● Parandati viga funktsioonis readCertificatePolicies()

● Rakendati Marc Stern soovitatud and metüü pide konverteerimised vältimaks t ranslaatori hoiatusi.

● Parandati viga funktsioonide verifyNotary() ja ddocConvertFileName() - vähene p uhvri suur us.

Erinevused teegi versioonide 2.1.13 ja 2.1.0 vahel● Parandati m u utuja te initsialiseerimisvead funktsioonides u tf82oem(),

oem2uf8(), getDataFileFileName().

● Lisati abifunktsioon d docConvertFileName() failinime konverteerimiseks vastavalt platfor mile.

● Parandati viga sertifikaadi omaniku nime konverteerimises UTF-8 - sse.

13

Page 14: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

● Lisati voimalus digidoc parserile aktsepteerida ka selliseid digidoc faile milles elemendi < DataFile > atribuut Id väärtus on “null”. Selliseid sai tekitada JdigiDoc teegi vigasel kasutamisel.

● Lisati kirjed vaikimis kasutatavasse konfiguratsioonifaili u u te OCSP reponderi sertifikaatide jaoks.

● Lisati võimalus toetada mitu t OCSP responderi sertifikaati ja valida u ue ja vana ser tifikaadi vahel vastavalt vajadusele (allkirjas tades uus aga kontrollimisel see millega digidoc - i allkiri on kinnitatud)

● Lisati veakood ERR_OCSP_WRONG_SIGNATURE (129) märkimaks olukorda kus OCSP vastuse allkiri on vale.

● Lisati võimalus logida faili. Selleks tuleks konfiguratsioonifaili lisada kirje DEBUG_FILE= <logfile > kus määratakse logifaili täielik nimi.

● Parandati viga räsi arvutamisel reshiimis content - type =HASHCODE mida kasutab digidoc veebiteenus. Viga esines for maadis 1.0 digidoc doku mentide puhul.

● Lisati veakood ERR_NO_OCSP (128) m ärkimaks olukorda kus allkirjal ei ole OCSP kehtivuskinnitus t.

● Parandati välja CPS sisu funktsioonis isCompanyCPSPolicy().

Erinevused teegi versioonide 2.1.0 ja 2.0.0 vahel● Lisati digidoc and mefailide metainfo registreerimiseks funktsioon

dencOrigContent_registerDigiDoc().

● Lisati teegi ja formaadi meta - info lisamiseks ja kasuta miseks funktsioonid dencMetaInfo_SetLibVersion(), dencMetaInfo_SetFormatVersion(), dencMetaInfo_GetLibVersion() ja dencMetaInfo_GetFormatVersion().

● Lisati mitme OCSP responderi sertifikaadi tugi. Konfiguratsioonifailis võis ennem olla iga responderi sr tifikaadi registreerimiseks kirje: DIGIDOC_OCSP_RESPONDER_CERT_x=sertifikaadi - fail - ja -teekond.pem

Nüüd on lubatud veel kirjed s tiilis:

DIGIDOC_OCSP_RESPONDER_CERT_x_y=sertifikaadi - fail - ja -teekond.pem

kus x on antud responderi järjekorra nu mber ja y on ser tifikaadi järjekorra nu mber alus tades 1 - s t. Ühe responderi ser tifikaatide arvu ei ole vaja määrata. Otsing kestab alates 1 - s t niikaua kui järjestikuseid kirjeid leidub. Mõlemaid kirjeid saab läbisegi kasutada ja seejuures ka ühs responderipuhul. Sisuliselt on esimene vorm teise erijuht kus y = 0 ja sellega algab otsing. Selliseid kirjeid kasuta takse ühe responderi jaoks mitme ser tifikaadi registreerimiseks mis on vajalik seetõt tu et responderite ser tifikaadid aeguvad. Seega võib kohalikus arvutis olla korraga mitu respnderi ser tifikaati, millest üks on värske, osad aegunud ja osad mille kehtivus pole veel alanud. Viimaseid on siiski vaja vanade digidoc doku mentide allkirjade kontrollimiseks. Uue kehtivuskinnituse

14

Page 15: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

hankimisel proovitakse saadu d OCSP vastust kontrollida kõigi kohalikus arvutis registreeritud responderi ser tifikaatidega kuni üks neist sobib.

Erinevused teegi versioonide 2.0.0 ja 1.96 vahel● funktsioonile initConfigStore() lisandus parameeter s zConfigFile,

mille abil saab edastada konfiguratsioonifaili nime. Kui kasutada NULL väärtus t siis kasuta takse vaikeväärtus t konfiguratsioonifaili nimena.

● Lisandus PKCS#11 funktsioon findUsersCertificate()● Lisandusid XML-ENC funktsioonid dencOrigContent_count(),

dencOrigContent_add(), dencOrigContent_findByIndex(), dencEncryptedData_findEncryptedKeyByPKCS11() ja dencOrigContent_isDigiDocInside().

● Sertifikaadi infot tagastavada funktsioonid tagastavad nüü d kasutaja nime win32 platfor mil cp1257 (Baltic) ja Linux /UNIX platfor mil UTF-8 kodeeringus.

● cdigidoc u tiliidile lisandus - list käsk ja m u u tus kom mando - decrypt süntaks.

Erinevused teegi versioonide 1.96 ja 1.93 vahel• Lisatud XML-ENC standardi tugi. Toetab failide krüp teerimist ja

dekrüp teerimist.• Eraldi API suur te failide krüpteerimiseks ja dekrüpteerimiseks.• Win32 platfor mil config - API kasutab windowis registryt

Erinevused teegi versioonide 1.93 ja 1.89 vahel• Parandasinfunktsiooni generateDataFileXML() toetamaks sü mbolit '&'

faili nimedes.• Hulk lisanduvaid veasitua tsioonide kontrolle.• Lisatud tugi openssl 0.9.7d jaoks. Kuna openssl funktsioon

OCSP_request_add1_nonce() on m u utunu d nii et puh talt nonce and mete asemel saadetakse ASN.1 s trktuur nimetatud and metega, siis tuli parandada mitmeid funktsioone sellise s t ruktuuri kasuta miseks. Lisaks sellele saadab teek nüü d for maatide 1.2 ja varasemate p uhul teiste funktsioonide abil puh talt 20 baidise nonce (mitte ASN.1 s trktuuri) selleks et vanemad teegi versioonid mis sellise m u ut usega OCSP st ruktuuris ei osanud arvestada saaksid toimida.

• Eemaldasin hulga failinime konverteerimisoperatsione teegist. Nüüd hoiame failinime ainutl UTF-8 kujul ja konverteerime vajalikule kujule näiteks faili avamiseks. Seejuures arvestame win32 keskkonnas systeemi OEM koodilehega. Uued konverteerimisfunktsioonid on algkoodifailides DigiDocConvert.h / .c. Formaatide 1.2 ja vanemate p uhul konverteeritakse failinimi vale algoritmiga win32 platformil käsitledes sisendit ISO- 8859 - 1 koodidena samas kui ta on OEM koodis. See on vajalik selleks et vanem klientprogram m moistaks and meid oieti kuvada.

• Eemaldasin parameetri errbuf funktsioonilt readSignedDoc(), ses t vigade tagastamiseks on eraldi API.

15

Page 16: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Lisasin funktsioonile readSignedDoc() parameetri nMaxDFSize, mis määrab m aksimaalse and mefaili suuruse mille sisu veel m älus hoitakse. Seda kasutatakse hiljem and mete tagastamiseks cachest kui võimalik funktsioonis extractDataFile(). Seetõt tu oli vajalik lisada viimasele funktsioonile ka para meeter “SignedDoc* pSigDoc” et saaks kontrollida cache olemasolu.

• Liigutasin kõik SAX API abil XML parsimise funktsioonid algkoodifailidesse DigDocSAXParser.h / .c

• Nimetasin funktsiooni readSignedDoc() ü mber funktsiooniks d docSaxReadSignedDoc().

• Nimetasin funktsiooni extractDataFile() ü mber funktsiooniks d docSaxExtractDataFile().

• Lõin u ued XML parsimise funktsioonid mis kasutavad libxml2 - e XML-Reader API - t. Need funktsioonid on algkoodifailides: DigDocParser.h / .c

• Lõin u ued mäluhalduse funktsioonid algkoodifailides DigiDocMem.h / .c

• Lõin lihtsa stack s truktuuri toeks funktsioonid algkoodifailides DigiDocStack.h / .c. Neid kasutan XML-Reader API abil digidocdoku mente parsides ja plaanis on seda kasutada ka SAX API p uhul ses t sellise s tacki abil järje hoidmine on kindlam kui ID atribuutide väärtus te abil.

• Loodudon ka funktsioon digidoc doku mendi lugemiseks mälupuvrist faili asemel ja and mefaili sisu tagastamiseks mälupuhvris faili asemel.

• Liasisn funktsiooni d docGetDataFileFilename() mis tagastab korrektse Filename atribuudi väärtuse ja parandab formaatides 1.0, 1.1 ja 1.2 kasuta tud ebakorrektset UTF-8 kodeeringut.

Erinevused teegi versioonide 1.89 ja 1.88 vahel

• Parandasin funktsioone handleStar tDataFile() ja generateDataFileXML() lubamaks sü mboli '&' kasuta miste and mefailide nimedes.

Erinevused teegi versioonide 1.88 ja 1.80 vahel

• Veakoodid ERR_CERT_STORE_READ ja ERR_CERT_READ m u u deti USER kategooria vigadeks, sest kui ser tifikaati ei leia sertstores t voi failist siis on midagi konfiguratsiooniga valesti.

• Parandatud bugid funktsioonis convertStringToTimeT()• Lisatud veakood ERR_OCSP_WRONG_URL kui responderi URL on kyll

sisestatud aga ei osuta OCSP responderile. See on sa muti USER klassi viga.

• Parandatud bugi funktsioonis setSignatureValueFromFile()• Parandatud bugi funktsioonis getSignerCode()• Struktuuride SignatureInfo ja NotaryInfo liige "long nCertSerial"

m u utus "char* szCertSerial" ses t osadel ser tifikaatidel oli nii suur nu mber mis long and metüü pi ära ei mahtunud.

16

Page 17: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Erinevused teegi versioonide 1.80 ja 1.77 vahel

• Dokumendid for maadis DIGIDOC- XML ja versioonis 1.3 peavad nüü d kasuta ma SignedDoc na mespacet. Muudetud funktsioonide generateDataFileXML(), createSignedXMLDoc() ja handleStartDataFile() sisu aga mit te liidest.

• Veaparandused funktsioonides unicode2ascii() ja getSignerLastName().

Erinevused teegi versioonide 1.79 ja 1.77 vahel

• Veatöötlusfunktsioonid ja kons tandid viidud üle failidesse DigiDocError.c ja DigiDocError.h

• Veajadade säilitamine / töötlemine tehtud lõimepõhiseks ja kasuta tavaks erinevates lõimedes samaaegselt.

• Lisatud funktsioon getErrorClass ja veaklassid NO_ERRORS, TECHNICAL, USER ja LIBRARY, veaklassid seostatud veakoodidega.

• Lisatud veakoodid ERR_NULL_PARAM, ERR_BAD_ALLOC, ERR_CONF_FILE, ERR_CONF_LINE.

• Kogu teegi ulatuses rakendatud veasituatsioonide registreerimine.• Objekte tekitavad funktsioonid tagastavad objektiviida asemel

veakoodi.• Muudetud liides: Timestam p *Timestamp_new() - > int

Timesta mp_new()• Muudetud liides: SignedDoc *SignedDoc_new() - > int

SignedDoc_new()• Muudetud liides: DataFile *DataFile_new() - > int DataFile_new()• Muudetud liides: SignatureInfo *SignatureInfo_new() - > int

SignatureInfo_new()• Muudetud liides: NotaryInfo *NotaryInfo_new() - > in t

NotaryInfo_new()• Muudetud liides: NotaryInfo *NotaryInfo_new_file() - > in t

NotaryInfo_new_file() • Muudetud liides: X509* ReadCertificate() - > int ReadCertificate()• Muudetud liides: long GetCertSerialNumber() - > int

GetCertSerialNumber()• Muudetud liides:long ReadCertSerialNumber() - > int

ReadCertSerialNumber()• Muudetud liides:EVP_PKEY* ReadPublicKey() - > int ReadPublicKey()• Muudetud liides: EVP_PKEY* GetPublicKey() - > int GetPublicKey()• Muudetud liides: EVP_PKEY* ReadPrivateKey() - > int

ReadPrivateKey()• Muudetud liides: RSA* ReadRSAPrivateKey() - > int

ReadRSAPrivateKey()• Muudetud liides:void convertStringToTimestamp() - > int

convertStringToTimesta mp()• Muudetud liides: void convertTimestam pToString() - > int

convertTimestam pToString()

17

Page 18: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Muudetud liides:ASN1_GENERALIZEDTIME* s tr2asn1time() - > int s t r2asn1time()

• Muudetud liides: void setString() - > int setString()• Muudetud funktsiooni nimi: int countDataFiles() - > int

getCountOfDataFiles()• Muudetud funktsiooni nimi: int countDataFileAttributes() - > int

getCountOfDataFileAttributes()• Muudetud liides: void addDataFileAttribute() - > int

addDataFileAttribute()• Muudetud liides: void getDataFileAttribute() - > int

getDataFileAttribute()• Muudetud funktsiooni nimi: int countSignatures() - > int

getCountOfSignatures()• Muudetud liides: void setSignatureProductionPlace() - > int

setSignatureProductionPlace()• Muudetud liides: void addSignerRole() - > int addSignerRole()• Muudetud funktsiooni nimi:int countSignerRoles() - > int

getCountOfSignerRoles()• Muudetud liides: DocInfo* addDocInfo() - > int addDocInfo()• Muudetud funktsiooni nimi: int countDocInfos() - > int

getCountOfDocInfos()• Muudetud liides: void addAllDocInfos() - > int addAllDocInfos()• Muudetud liides: X509* decodeCertificateData() - > int

decodeCertificateData()• Muudetud liides: X509* decodeCertificatePEMData() - > int

decodeCertificatePEMData()• Muudetud liides: OCSP_RESPONSE* decodeOcspResponsePEMData()

- > int decodeOcspResponsePEMData()• Muudetud liides: OCSP_RESPONSE* ReadOCSPResponse() - > int

ReadOCSPResponse()• Muudetud liides: void WriteOCSPResponse() - > int

WriteOCSPResponse()• Muudetud liides: OCSP_REQUEST* ReadOCSPRequest() - > int

ReadOCSPRequest()• Muudetud liides: void WriteOCSPRequest() - > int

WriteOCSPRequest()• Muudetud funktsiooni nimi: int countNotaryInfos() - > in t

getCountOfNotaryInfos()• Muudetud liides: void writeCertToXMLFile() - > int

writeCertToXMLFile()• Muudetud liides: void writeOcspToXMLFile() - > int

writeOcspToXMLFile()• Muudetud liides: void extractDataFile() - > int extractDataFile()• Eemaldatud copyDataFile()• Muudetud liides: void* getSignCertData() - > X509* getSignCertData()• Muudetud liides: void* getNotCertData() - > X509* getNotCertData()

18

Page 19: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Muudetud liides: X509_STORE *setup_verifyCERT() - > int setup_verifyCERT()

Erinevused teegi versioonide 1.77 ja 1.76 vahel

• Teek hoiab nüüd kõiki and meid mälus UTF-8 kodeeringus. Faili kirjutades ja sealt lugedes ena m m u u datusi ei teh ta. Kasutaja peab and med edastama ja saadud and meid konverteerima vastavalt vajadusele.

• Eemaldatud parameeter s zCharset funktsioonilt addDataFileAttribute()

• Eemaldatud parameeter s zCharset funktsioonilt setSignatureProductionPlace()

• Lisatud para meeter s zFileNameCharset funktsioonile DataFile_new() ja extractDataFile()

Erinevused teegi versioonide 1.76 ja 1.66 vahel

• Teek toetab nüü d ka for maadi versiooni "1.3" - DIGIDOC - XML 1.3 versioon on loodud eesmärgiga parandada süntaktilisi vigu, et tagada parem ühilduvus XadES spetsifikatsiooniga. Muudetakse järgmisi elemente:• < Q ualifyingProperties > - versioon 1.2 ei oma mingeid atribuute.

Tegelikult peab oma ma atribuute xmlns ="http: / / u ri.etsi.org /01903 /v1.1.1#" ja Target ="# < allkirja -id >"

• <SignedProperties > - versioon 1.2 omab atribuute xmlns ="http: / /www.w3.org /2000 / 09 /x mldsig#" Id ="S0 -SignedProperties" Target ="#S0". Tegelikult on lubatud ainult Id -atribuut.

• <IssuerSerial > - sisaldab versioonis 1.2 allkirjastaja serdi väljaandja poolt omistatud seerianu mbrit. Tegelikult peaks sisaldama alamelemente kujul: <IssuerSerial> <X509IssuerName xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- allkirjastaja sertifikaadi issuer DN --> </X509IssuerName> <X509SerialNumber> <!-- allkirjastaja sertifikaadi seerianumber --> </X509SerialNumber></IssuerSerial>

• dateTime and metüübi viga: kuupäeva osas peab kasuta ma ’.’ asemel ’-’. Ehk siis näiteks: 2003 - 11 - 06T14:23:49Z, mit te 2003.11.06T14:23:49Z. Kehtib elementide <SigningTime > ja <ProducedAt > kohta.

• Elemendis <Cert > pole parameeter „Id“ lubatud• Elemendis <UnsignedProperties > pole para meeter „Target“

lubatud• Elementide <Com pleteCertificateRefs > ja <Cert > vahel peab

täiendavalt olema element <CertRefs >.• Elementide <RevocationValues > ja <EncapsulatedOCSPvalue >

19

Page 20: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

vahel peab täiendavalt olema element < OCSPValues >.•

Erinevused teegi versioonide 1.66 ja 1.52 vahel

• setup_verifyCERT() - votab vastu suvalise pikkusega ser tide array. Ennem tapselt 2 CA- d

• setup_verify() - pole enam vaja, selle asemel setup_verifyCERT()• verifyNotaryInfoCERT() - votab vastu suvalise pikkusega sertide

array • verifyNotaryInfo() - loeb serdid failist ja siis kasutab

verifyNotaryInfoCERT(). Ennem d uplitseeritud kood.• getConfirnation() - votab vastu suvalise pikkusega ser tide array.• isCertValid() - lisandus para meeter "time_t tDate". Timestamp millal

serdi kehtivust kontrollida. Nyyd kasuta takse m u u dest funktsioonidest et kontrollida serdi kehtivust allkirjastamise ajal ja mit te p raegusel hetkel. Parandab aastaarvu kru t timise vea.

• verifySignatureInfo() - kasutab u ut isCertValid() allkirjastamise kuupaevaga

• signOCSPRequestPKCS12() - kontrollib PKCS#12 konteineri serdi aegumist hetkel kui OCSP- d saadetakse

• verifySigDocCERT() - votab vastu suvalise pikkusega sertide array.• verifySignatureInfoCERT() - kasutab uu t isCertValid() allkirjastamise

kuupaevaga• COM jaoks kasutatakse isCertValid() puh ul he tkelist kuupaeva. Siia

pole parameetrit tDate lisatud. COM tegelikult seda ise valjakutsu ma ei pea vaid seda funktsiooni kasutatakse teegi sees t allkirja kontrollimisel.

• decodeHex() - lisandunud• get_authority_key() - lisandunu d• createOCSPCertid() - lisandunud• createOCSPRequest() - Enam ei vaja responderi CA- d et OCSP

requesti teha

Erinevused teegi versioonide 1.52 ja 1.41 vahel

• Lubatud on nüüd ka for maadi versioon "1.2"• Teek hoiab mälus and meid tähestikus "ISO- 8859 - 1". Võimalik on

lisada and medi nii tähestikus "ISO- 8859 - 1" kui ka "UTF-8", kuid lugeda saab neid esialgu vaid tähestikus "ISO- 8859 - 1".

• Versioonis 1.41 parsiti OCSP kehtivuskinnitus lahti ja hoiti mälus vaid sellest loetud vajalikke and meid. Faili kirjuta ti algse OCSP kehtivuskinnituse räsi aga kehtivuskinnitus ise koosta ti u uesti. See rikkus ära räsi väärtuse. Alates versioonist 1.42 hoitakse mälus kogu algset OCSP kehtivuskinnitus t ja salvestatakse m u ut mata kujul ka faili. Räsi vastab faili salvestatud kehtivuskinnitusele.

• Parandatud base64 formadis binary objektide parsimist ja

20

Page 21: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

parandatud osad vead seoses ebastandardse reapikkusega objektide parsimisel.

• Lisatud AID kaar tide toetus PKCS#11 ja CSP draiverite kasuta mise p uhul.

• Elemendil <Reference > mis sisaldab elemendi <SignedProperties > räsi peab olema atribuut: Type ="ht tp: / / u ri.etsi.org /01903 /v1.1.1#SignedProperties".

• Elementidel <SignedInfo > ja <SignedProperties > võib, kuid ei pea olema a trbuuti: xmlns = h ttp: / / www.w3.org /2000 / 09 /x mldsig#.

• Parandatud on xml faili parsimise kiirust. Nüüd loetakse kogu info failist ühe korraga ja ei ole vaja ena m teist korda üksikuid elemente lugeda et nende täpset räsi arvutada. Elementide info koos ta takse nüü d SAX sünd m uste and metest.

Erinevused teegi versioonide 1.52 ja 1.59 vahel

• Integreeriti FreeBSD fix• Lisati veakontroll juurdepääsutõendi kehtivuse lõppemise p uhul.

Sellega seoses tekkis veel üks u us veakood.• Lisati parameeter bUseCA funktsioonidele verifySigDoc(),

verifySignatureInfo(), verifySignatureInfoCERT(), verifySigDocCERT() võimaldamaks jätta kontrollist välja CA serdi abil kontrollimine ja seega kontrollida ka selliseid doku mente, mille CA ser tifikaati kontrollijal ei ole (võõraste CA- de toetus)

• Parandati vana ja u ue teegi yhilduvust. Faili u uesti salvestamisel ei dekodeerita enam DataFile objektide sisu (base64), kna sellega võib kaasneda whitespace kadu ja seega allkirja invalideerumine, vaid kopeeritakse terve DataFile sisu aju tisse faili ja sealt u ude faili.

• Parandati null pikkusega faili allkirjas tamise probleem.• Lühendatid ajutis te failide nimesid. Nüüd koostatakse ajutised failid

m us t ri alusel "ddocXXXXXX", kus viimased kuus kohta määrab süsteem nii et tekiks unikaalne failinimi.

• Ajutised failid salvestatakse süsteemi aju tis te failide kataloogi.• Ajutisi faile luuakse nüü d vaid faili (ümber)salvestamisel kus see

annab olulise võidu väiksema m älu vajadusena. Enam ei kasuta ta ajutisi faile XML kanoniseerimisel kus see erilist võitu ei anna.

• Kontrolliti UTF-8 kujul failinimede kasutamist. Leiti, et sellisel kujul failinimesid ei suu da fopen() kasutada ja m u u d funktsioonid ei ole piisavalt laialt levinud. Otseselt süs teemi tähestikus (ISO- 8859 - 1) failinimedega aga saab nii Windows kui Linux hakkama. Ka sellistega mis sisaldavad täpitäh ti. Linuxi p uhul on vajalik uue m 2.4 kerneliga versioon. Osades vanemates versioonides võib p robleeme tekkida.

• Kontrolliti BIO paketi rakendatavust fopen() asemel ja leiti et pole mõtet kuna BIO ise seda funktsiooni kasutab ja ei ole seega loodetuks por teeruvaks variandiks.

• Lisati s t ruktuur PolicyIdentifier ja funktsioonid readCertPolicies(), PolicyIdentifiers_free() ja isCompanyCPSPolicy() asu tuse sertifikaatide ser tifitseerimispoliitikaga seotud atribuutide lugemiseks.

21

Page 22: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Täiustati DigiDoc por taali u tiliite• Parandati funktsioone verifyNotaryInfo(), verifyNotaryInfoCERT() ja

getConfirmation() täiusta maks kehtivuskinnituse kontrolli tunda mtu CA puhul.

Juhised enam esinevate probleemide kiireks lahendamiseks

Kuidas luua uusi DigiDoc'e

Siin on lihtne ülevaade kuidas saaks luua DigiDoc'e C - teegi funktsioonidega.Kõigepealt tuleb defineerida tarvilikud st ruktuurid:

SignedDoc* pSigDoc;

See st ruktuur kajas tabki DigiDoc'i for maati, k ik teised paiknevad siin sees.ō

DataFile* pDataFile;

Üks selline s truktuur vastab igale DigiDoc'i konteinerile lisatud and mefailile. Ühes DigiDoc'is võib olla mitu and mefaili, kuid ilma and mefailita pole ka DigiDoc'i. Andmefail ise võib olla DigiDoc'i sisse lisatud aga võib jääda ka lisamata.

K igepealt tuleb initsialiseerida teek:ō

initDigiDocLib();

See tagab kõigi kasuta tavate OpenSSL'i väärtus te initsialiseerimise.Seejärel tuleb mälusse luua digidoc'i s t ruktuur:

rc = SignedDoc_new(&pSigDoc, DIGIDOC_XML_1_NAME, DIGIDOC_XML_1_3_VER);

Nende kahe s tring konstanti väärtused on vastavalt "DIGIDOC-XML" ja "1.3" (DigiDocLib.h). Toetatud versioon 1.0, erinevus kahe versiooni vahel on peamiselt and mefaili MIME tüübi erinevas kuvamises, kasutaja jaoks pole selle erinevuse teadmine vajalik, sest teegi funktsioonid teavad ise kuidas an tud versiooni jaoks st ruktuure luua ja salvestada. Vea korral tagastatakse veakood. Versioonid 1.1 ja 1.2 ei erine üks teisest faili formaadi osas. Versioon 1.2 loodi peale oluliste vigade leidmist versiooniga 1.1. kaasas olnud libxml2 teegi vanemas versioonis. Vead esinesid ennekõike halja XML sisesta misel. Kui kasuta te haljast XML-i siis kasutage kindlasti ka versiooni 1.2 juhendamaks kasutajat tõmbama endale uusimat tarkvara millega antud faili korrektselt lugeda saab. Versioonis 1.3 on parandatud olulised erinevused XAdES standardist.

22

Page 23: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Peale DigiDoc’i s t ruktuuri loomist saab sinna lisada and mefaili(d):

rc = DataFile_new(&pDataFile, pSigDoc, NULL, infile, CONTENT_EMBEDDED_BASE64, mime, 0, NULL, 0, NULL, CHARSET_UTF_8, CHARSET_UTF_8);

Siin teiseks para meetriks on pointer DigiDoc’i s t ruktuurile kuhu lisatakse antud and mefail. Kolmandaks parameetriks on and mefaili an tud Digidoc’i piires unikaalne id (const char* ), on soovitatav see para meeter jät ta määramata, siis hoolitseb teek ise selle genereerimise eest. Neljandaks para meetriks on viide faili nimele, viiendaks and mefaili sisaldu misviis, siin on defineeritud järgmised väärtused (DigiDocLib.h):

1) CONTENT_DETATCHED2) CONTENT_EMBEDDED3) CONTENT_EMBEDDED_BASE64

Esimene tähendab, et and mefaili sisu DigiDoc’i sisse ei lisata, ainult viited, soovitatav kui tegu on suurte failidega. Teine tähendab seda and mefaili sisu kopeeritakse otse DigiDoc’i sisse, seda on soovitav kasutada ainult siis kui olete kindel, et and mefaili sees pole eritähendusega sü mboleid, mis võiksid faili lugevatele ja kuvavatele p rogram midele ebameeldivusi põhjustada, alati on kindlam seda v imalust mit te kasutada. Kolmas ning kõige kindlam ja lihtsa m viisō lisab kogu and mefaili, olles selle enne konverteerinud base64 kodeeringusse, üldjuhul on see k ige soovitatuim. Faili nimi tuleks andaō täieliku nimena koos teekonnaga antud alamkataloogini. Salvestamisel teekond faili nimest eemaldatakse kuid digidoc faili koostamisel on see vajalik, ses t te võite lisada faile mit mest eri alamkataloogist. Funktsiooni viies para meeter on and mefaili MIME tüüp näiteks "application - x / ms - word" või "application - x / acrobat - p df" või mis iganes sõltuvalt and mefailist.

Järgmised neli para meetrit peaksid tavajuhul jääma teegi enda arvutada, need on vastavalt:

1) and mefaili suur us baitides2) and mefaili räsi3) and mefaili räsi pikkus4) and mefaili räsi tüüp ( praegu lubatud ainult sha1)

Eelviimaseks parameetriks on sisesta tavate and mete kooditabeli nimi. Teek toetab hetkel kahte tähestikku: ISO- 8859 - 2 ja UTF-8. Mälus hoitaks and meid UTF-8 tähestikus ja faili salvestatakse sam uti UTF-8 -s. Nende kooditabelite jaoks on defineeritud konstandid:• CHARSET_ISO_8859_1• CHARSET_UTF_8Viimaseks para meetriks on faili nime kooditabel. Win32 keskkonnas tuleb üldjuhul edastada faili nimi ISO - 8859 - 1 kodeeringus et teek seda faili avada saaks.Muu kooditabeli nime kasutamisel tekib vigaPeale tagasitulekut sellest funktsioonist on meil an tud DigiDoc’i kopeeritud and mefaili and med ja sõltuvalt välja kutsuja soovist ka fail

23

Page 24: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

ise. Olgu öeldud, et viimase nelja para meetri väär tus t see funktsioon ei arvuta, küll aga leiab unikaalse id kui seda polnud et te an tud. Vea korral tagastatakse NULL.

Järgmisena arvutataksegi välja need suurused mida st ruktuuri loov funktsioon DataFile_new() ei teinud.

rc = calculateDataFileSizeAndDigest(pSigDoc, pDataFile->szId, infile, DIGEST_SHA1);

See funktsioon arvutab ja lisab need neli väär tus t esimeseks para meetriks an tud DigiDoc’I DataFile’I sektsiooni pDataFile->szId, arvutamiseks kasutatakse kolmandas parameetris antud faili nime.

Ainus lubatud räsi tüüp on DIGEST_SHA1. Funktsioon tagastab täisarvu, kui vigu ei olnud, siis on täisarvu väär tuseks ERR_OK (defineeritud DigiDocLib.h ‘s). Vea korral tagastatakse veakood.

Antud veakoodile vastavat veateate saab küsida funktsiooniga,

char * w=getErrorString(rc);

kus rc on veakood; veateated esitatakse inglise keeles.

On võimalik lisada ka suvalist infot an tud andefaili kohta. Selleks kasuta takse funktsiooni addDataFileAttribute(). Näiteks:

addDataFileAttribute(pDataFile, "ISBN", "000012345235623465");addDataFileAttribute(pDataFile, "Owner", "CEO");

Esimeseks para meetriks on viit and mefaili s t ruktuurile, millele järgneb atribuudi nimi ja väär tus. Andmed tuleb edastada UTF-8 kodeeringus.

Digidoc’i faili loomiseks ja salvestamiseks kasuta takse järgmist funktsiooni:

rc = createSignedDoc(pSigDoc, oldfile, outfile);

See funktsioon saab parameetriteks viida salvesta tavale digidoc’i s t ruktuurile ning kaks faili nime, oldfile mis võib ka pu ud uda, ning outpu t ehk väljund faili nimi. Kui old fail on olemas ja teda õnnestub avada, siis kopeeritakse sealt and mefaili sisu.

Peale töö lõppu tuleb vabastada mälu, selleks kasuta takse funktsiooni

SignedDoc_free(pSigDoc);

mis vabastab ka kõigi and mefailide mälu.Viimaseks ülesandeks on teegi sulgemine.finalizeDigiDocLib();

24

Page 25: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Kuidas lisada kehtivuskinnitust ?

Funktsioon getConfirmation() loob Notari ( edaspidi nimetatud OCSP - Online Certificate Status Protocol) päringu antud DigiDoc'i pSigDoc allkirjas t pSigInfo , vastavalt funktsiooni parameetritle allkirjas tab päringu kui see oli n utav ning saadab päringu notaryURL-i pooltō osu tatud aadressile.Saadud vastus lisatakse DigiDoc'i pSigDoc base64 kodeeritult. Funktsiooni eduka täitmise korral tagastatakse ERR_OK vastasel juhul veakood.Selgituseks olgu öeldud, et OCSP päringuga küsitakse, kas mingi sertifikaat on antud hetkel kehtiv.OCSP päringusse pannakse küsitava sertifikaadi ja selle sertifikaadi välja andnud sertifikaadi and med. Päring võib olla allkirjastatud.

int getConfirmation(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, const X509** caCerts, const X509* pNotCert,char* pkcs12FileName, char* pkcs12Password,char* notaryURL, char* proxyHost, char* proxyPort)

Funktsiooni parameetrid:• pSigDoc - u uritava digidoc'i s t ruktuur, see peab juba eelnevat

olema täidetud.• pSigInfo - uuritava ser tifikaadi poolt an tud allkiri, ka see ei tohi

p uu du da•••• pkcs12FileName – OCSP- päringu teostamiseks vajaliku

pääsutõendi asukoht.• pkcs12Password - pääsutõendi kasuta miseks vajalik

paroolifraas.

• notaryURL - URL OCSP teenuse pakkujale. Parameeter ei tohi p uu du da.

• proxyHost - kui notaryURL-i kät te saamiseks on tarvilk kasutada p roksit peab see parameeter olema täidetud, vastasel juhul peab olema NULL.

• proxyPort - kui notaryURL-i kät te saamiseks on tarvilk kasutada p roksit peab see parameeter olema täidetud, vastasel juhul peab olema NULL.

Näide:Küsime kinnitus t digidoci "c: \ \ t t.ddoc" allkirjale "S0"

rc = readSignedDoc(&pSigDoc, "c:\\tt.ddoc", 1, buf);pSigInfo = getSignatureWithId(pSigDoc, "S0");rc = getConfirmation(pSigDoc, pSigInfo,

25

Page 26: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

caCerts, notSigCert, pkcs12FileName, pkcS12Password,"http://ocsp.sk.ee/", "proxy.intern.ee", "8080");

Kuidas otsida sertifikaate DigiDoc'i funktsioonides ?

Funktsioon vajab kolme sertifikaati : allakirjutanud serdi välja andja, OCSP ehk Notari ning OCSP päringu allkirjastaja oma. Kui OCSP päringut ei allkirjastata siis viimast vaja ei ole.

Serdid on saadavad kolmel eri viisil: MS CertStore, PKCS#12 konteiner ja tavaline PEM fail ( edaspidi viidatud kui X509 fail ).Sertide otsimiseks kasutatakse s truktuuri CertSearch_st kus m u utuja searchType määrab ära otsimisviisi.

typedef struct CertSearch_st {int searchType;char* x509FileName;char* keyFileName; char* pkcs12FileName;char * pswd;CertSearchStore* certSearchStore;

} CertSearch;

Muutujal searchType v ib olla kolm väär tus t: ōCERT_SEARCH_BY_STORECERT_SEARCH_BY_X509CERT_SEARCH_BY_PKCS12

Kui valitakse CERT_SEARCH_BY_STORE siis peab olema s truktuuris täidetud ka certSearchStore teised liikmed võivad p uu du da.Kui valitakse CERT_SEARCH_BY_PKCS12 siis peavad s truktuuris olema täidetud ka pkcs12FileName ja pswd teised liikmed võivad pu ud uda.Kui valitakse CERT_SEARCH_BY_X509 s.t sertifikaat on PEM failis siis peab st ruktuuris olema täidetud x509FileName. Kui an tud ser tifikaati kasuta takse ka allkirjastamiseks siis peavad lisaks x509FileName olema täidetud ka keyFileName ja pswd.

Struktuuri CertSearchStore_st kasuta takse ser tide otsimiseks MS CertStore's t.

typedef struct CertSearchStore_st {int searchType;char* storeName; // default is "My"long certSerial;int numberOfSubDNCriterias;char** subDNCriterias;int numberOfIssDNCriterias;char** issDNCriterias;

} CertSearchStore;

26

Page 27: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

MS CertStore's t saab sertifikaate p raegu otsida kolmel eri viisil: seerianu mbri , subjekti ja väljaandja nime järgi, ning neid otsimisviise saab vastavalt soovile omavahel kombineerida. Näiteks saab otsida sertifikaati mis oleks et te an tud seerianu mbri, välja andja nime ja subjekti nimega, või et teantud seeria nu mbri ja väljaandjaga.Otsimisviisi konstandid on:CERT_STORE_SEARCH_BY_SERIALCERT_STORE_SEARCH_BY_SUBJECT_DNCERT_STORE_SEARCH_BY_ISSUER_DNCERT_STORE_SEARCH_BY_KEY_INFOJa neid võib searchType'ks kokku OR'ida.

Kui otsingu tüüp sisaldab otsimist seerianu mbri järgi siis tuleb seerianu mber kirjutada väljale certSerial. Veidi keerulisem on et te anda otsingu parameetreid subjekti ja issueri jaoks.Otsingu parameetriteks on s tringid millest igaüks peab olema nõutud väljal ( vastavalt kas subjekti või issueri väljal ), kokku m oodus tavad need siis kas subDNCriterias v i ō issDNCriterias massiivi, selle suur us ( ehk para meetrite arv ) peab olema kirjas vastavalt numberOfSubDNCriterias v i ō numberOfIssDNCriterias m u ut ujas. Parameeter s t ringid ei ole tõs tu tundlikud ( enne võrdlemist teisendatakse kõik tähed suur teks ) ja tühikute arv ei oma sa muti tähtsust (need eemaldatakse enne võrdlemist ).

Näiteks olgu vaja leida MS CertStorest EST- EID sertifikaat ( kõigi Eesti ID kaar tide ser tide väljaandja ). Tegutsemisskeem on sel juhul põhimõt teliselt järgmine:

CertSearchStore certSearchStore;certSearchStore.searchType=CERT_STORE_SEARCH_BY_SERIAL|CERT_STORE_SEARCH_BY_ISSUER_DN;certSearchStore.certSerial=0x3C445C82;certSearchStore.issDNCriterias[0]=" CN = Juur-SK ";certSearchStore.issDNCriterias[1]=" O = AS Sertifitseerimiskeskus ";certSearchStore.numberOfIssDNCriterias=2;certSearchStore.storeName="CA";

CertSearch certSearch;certSearch.searchType=CERT_SEARCH_BY_STORE;certSearch.certSearchStore=certSearchStore;

Kuidas avada ja lugeda DigiDoc'e

Vaatame näitekoodi, kust parema ülevaate saamiseks on veakontrollid, väheoluliste m u utujate deklara tsioonid jms välja jäetud.

SignedDoc* pSigDoc;DataFile* dataFile;SignatureInfo* pSigInfo;

initDigiDocLib();

27

Page 28: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

rc = readSignedDoc(&pSigDoc, infile, 0, buf);andmefailideArv=getCountOfDataFiles(pSigDoc));allkirjadeArv=getCountOfSignatures(pSigDoc);for(counter=0;;counter++){

//kui sellise järjekorra numbriga andmefaili pole// saama tagasi NULL’idataFile = getDataFile(pSigDoc,counter);if(!dataFile){

break;}// teeme midagi andmefaili struktuuriga

}for(counter=0;counter< allkirjadeArv;counter++){

pSigInfo=getSignature(pSigDoc,counter);// teeme midagi allkirja struktuuriga

}SignedDoc_free(pSigDoc);finalizeDigiDocLib();

Digidoc faili avamiseks ja lugemiseks kasuta takse funktsiooni readSignedDoc(). Selle funktsiooni parameetriteks on digidoc’i viite aadress kuhu kirjutatakse loetud digidoc’i s t ruktuur. Teiseks para meetriks on Digidoc’i faili nimi, kolmas on lipp mis näitab, kas on vaja and mefaili räsi kontrollimine lugemise ajal on nõutud. Kui and mefaili pole lisatud peab see kindlasti olema false. Neljandaks para meetriks on puhver, kuhu XML’i parsiv SAX parser saab kirjutada oma veateateid.

Teised funktsioonid lihtsalt näitavad DigiDoc’i s t ruktuuri sisu.

Kuidas lisada allkirja DigiDoc'ile

Vaatame näitekoodi, kust parema ülevaate saamiseks on veakontrollid, väheoluliste m u utujate deklara tsioonid jms. on välja jäetud.

SignedDoc* pSigDoc;SignatureInfo* pSigInfo;

initDigiDocLib();rc = readSignedDoc(&pSigDoc, infile, 1, buf);

// add new signature with default idrc = SignatureInfo_new(&pSigInfo, pSigDoc, NULL);// automatically calculate doc-info elements for this signatureaddAllDocInfos(pSigDoc, pSigInfo);// add signature production placesetSignatureProductionPlace(pSigInfo, "Tallinn", "Harjumaa", "12345", "Estonia");// add user rolesaddSignerRole(pSigInfo, 0, "VIP", -1, 0);

rc = calculateSigInfoSignatureWithCSPEstID(pSigDoc,pSigInfo);

rc = createSignedDoc(pSigDoc, infile, outfile);

28

Page 29: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

SignedDoc_free(pSigDoc);finalizeDigiDocLib();

Kõigepealt tuleb digidoc’i s t ruktuur luua või lugeda failist. Neid tegevusi kirjeldatakse eraldi doku mentides, siin loetakse digidoc’i s t ruktuur failist funktsiooniga readSignedDoc() .Järgmisena tuleb luua SignatureInfo s truktuur funktsiooniga SignatureInfo_new() esimeseks para meetriks on viit uu t s t ruktuuri hoidvale viidale, teisesks antud digidoc ise, kolmandaks allkirja info unikaalne nimi, on soovitav seda mit te pakkuda, sel juhul arvutab teek selle ise. Funktsioon addAllDocInfos() lisab loodud allkirja info s truktuuri digidoci s t ruktuuri. Funktsioon setSignatureProductionPlace() lisab and med allkirjastamise asukoha kohta. Funktsioon addSignerRole() lisab allkirjastaja rolli allkirja info st ruktuuri pSigInfo, teine parameeter näitab kas roll on kinnitatud või mit te (0 - kinnitamata / 1 - kinnitatud), kolmas para meeter on rolli nimi, neljas rolli nime pikkus –1 tähendab, et teek p roovib selle ise leida. Eelviimane para meeter näitab et, kas rolli nimi tuleb panna base64 kodeeringusse (1) või mit te (0). Viimane parameeter on sisendand mete kooditabel.Allkirjas ta mist läbi MS Crypto Service Provideri teostab funktsioon calculateSigInfoSignatureWithCSPEstID() allkirjastada võib ka PKCS#11 kui teie kaardilugeja seda toetab ja vastav teek on installeeritud, sel juhul kasutatakse funktsiooni calculateSignatureWithEstID() .Need funktsioonid lisavad arvutatud allkirja ka kohe digidoc’i s t ruktuuri.Lõpuks tuleb uuendatud s truktuur salvestada funktsiooniga createSignedDoc().

29

Page 30: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Näiteprogrammid DigiDoc'i C- teegi kasutamiseks

Järgnevad m õningad teegi kasutamist illustreerivad näited, mida saab otse kopeerida.

CreateDoc.c

Seda näiteprogram mi on p roovitud nii LINUXil kui Windows platvor mil. Program m tekitab ja salvestab u ue DigiDoc'e st ruktuuri kasutades et te an tud and mefaili ja MIME tüü pi. Sisend parameetriteks ongi kolm suur ust :• and mefaili nimi• and mefaili MIME tüüp• failinimi kuhu salvestatakse u us DigiDoc

#include "DigiDocLib.h"#include <stdio.h>#include <string.h>//--------------------------------------------------// Use this as a sample how to create a signed doc// and how to read it.//--------------------------------------------------int main(int argc, char** argv){

int rc;SignedDoc* pSigDoc;DataFile* pDataFile;char *file1, *mime1, *outfile;

char buf[100];// print usage...if(argc != 4) {

printf("Usage: CreateDoc <infile> <mime> <outfile> \n");return 1;

}file1 = argv[1];mime1 = argv[2];outfile = argv[3];// init DigiDoc libraryinitDigiDocLib();// create signed docprintf("Creating signed doc\n");rc = SignedDoc_new(&pSigDoc, SK_XML_1_NAME, SK_XML_1_2_VER);// add DataFile1 - embedded PDF file in Base64printf("Embedding (Base64) file: %s - %s\n", file1, mime1);rc=DataFile_new(&pDatafile, pSigDoc, NULL,file1, CONTENT_EMBEDDED_BASE64, mime1, 0, NULL, 0, NULL, charset);// now calculate file length and digestrc = calculateDataFileSizeAndDigest(pSigDoc,

pDataFile->szId, file1, DIGEST_SHA1);// add some arbitrary attributesaddDataFileAttribute(pDataFile, "ISBN", "000012345235623465");addDataFileAttribute(pDataFile, "Owner", "Veiko");// write to fileprintf("Writing to file: %s\n", outfile);rc = createSignedDoc(pSigDoc,NULL, outfile);

30

Page 31: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

// cleanupSignedDoc_free(pSigDoc);

// reading DigiDocrc = readSignedDoc(&pSigDoc, argv[3],0, buf);

// cleanup of DigiDoc libraryfinalizeDigiDocLib();return 0;

}

ListSignatures.c

See näite program m de monst reerib allkirjade lugemist, nende näitamist ja kontrollomist. Program mi käivitamiseks on tarvilikud parameetrid:1. infile = Ühte v i enamat allkirja sisaldav DigiDoc'i fail.ō2. cafile = Allkirja(de) väljaandja sertifikaat.

3. rootca = Juurser tifikaat

4. notcert = Notari (OCSP) sertifikaat.

5. capath = Kataloog täiendavate sertifikaatide lugemiseks, kui rohkem sertifikaate ahelas ei ole võib selle parameetri väär tus olla suvaline.

#include "DigiDocLib.h"#include <stdio.h>#include <string.h>//--------------------------------------------------// Demonstrates how to check all signatures.// Shows only a CVS list of signatures with status.//--------------------------------------------------int main(int argc, char** argv){

int rc, d, i, rc2,rc3;SignedDoc* pSigDoc;ErrorInfo *pInfo;SignatureInfo* pSigInfo;NotaryInfo* pNotInfo;char *infile, *cafile, *rootca, *notcert, *capath, *role, *stime;char buf[300],buf2[300];

// print usage...if(argc != 6) {

printf("Usage: ListSignatures <infile> <CA-cert> <root-cert> <notary-cert> <ca-path>\n");

return 1;}infile = argv[1];cafile = argv[2];rootca = argv[3];notcert = argv[4];capath = argv[5];

// init DigiDoc libraryinitDigiDocLib();

rc = readSignedDoc(&pSigDoc, infile,0, buf);d = getCountOfSignatures(pSigDoc);for(i = 0; i < d; i++) {

pSigInfo = getSignature(pSigDoc, i);rc = verifySignatureInfo(pSigDoc, pSigInfo, cafile, infile,

1);rc2 = -1;pNotInfo = getNotaryWithSigId(pSigDoc, pSigInfo->szId);if(pNotInfo)

31

Page 32: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

rc2 = verifyNotaryInfo(pSigDoc, pNotInfo, rootca, cafile, capath, notcert);

rc3=getSignerCode(pSigInfo, buf2);role = (char*)getSignerRole(pSigInfo, 0,0);

if(!strcmp(charset, CHARSET_UTF_8)) { l = strlen(role);

role = (char*)malloc(l+1); ascii2utf8(getSignerRole(pSigInfo, 0,0), role, &l);}if (!rc3){printf("%s/%s/%s/%s/%s/%s/%s\n", pSigInfo->szId, ((!rc) ? "OK" : getErrorString(rc,1)), buf2, pSigInfo->szTimeStamp, ((rc2 == -1) ? "NONE" : ((!rc2) ? "OK" :

getErrorString(rc2,1))), role, pNotInfo->timeProduced); }

if(!strcmp(charset, CHARSET_UTF_8) && role != getSignerRole(pSigInfo, 0,0))

free(role);}// cleanupSignedDoc_free(pSigDoc);// cleanup of DigiDoc libraryfinalizeDigiDocLib();return 0;

}

32

Page 33: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

DigiDoc teek

Andmestruktuurid

SignedDocDigiDoc doku mendid on kõik väljendatavad s truktuuriga SignedDoc:

typedef struct SignedDoc_st {char* szFormat; // formaadi nimichar* szFormatVer; // formaadi versioonint nDataFiles; // andmefailide arvDataFile** pDataFiles; // andmefailidint nSignatures; // allkirjade arvSignatureInfo** pSignatures; // allkirjadint nNotaries; // kehtivuskinnituste arvNotaryInfo** pNotaries; // kehtivuskinnitused

} SignedDoc;

Üks allkirjastatud fail võib seega sisaldada algand mete faile (või viiteid neile), allkirju ja kehtivuskinnitusi.

DataFile

Algand mete failid on salvestatud järgmise and mes truktuuri abil:

typedef unsigned char byte;

typedef struct DataFile_st {char* szId; // faili unikaalne tunnuschar* szFileName; // andmefaili nimichar* szMimeType; // andmetüüp (mime tüüp)char* szContentType; // DETATCHED, EMBEDDED või

EMBEDDED_BASE64 long nSize; // faili suurus (algkujul)char* szDigestType; // räsi tüüp (sha1)byte* szDigest; // räsi väärtusint nDigestLen; // räsi pikkus (20)int nAttributes; // lisa attribuutide arvchar* szCharset; // datafile initial

codepagechar** pAttNames; // attribuutide nimedchar** pAttValues; // attribuutide väärtused

} DataFile;

Algand mete fail võib olla sises tatud allkirjastatud doku menti algkujul (EMBEDDED), Base64 kodeeritud kujul (EMBEDDED_BASE64) või allkirjas tatud faili sises tatakse ainult viide välisele failile. Kui algand mefail soovitakse sisestada algkujul, siis tingituna hetkelisest XML-l põhinevast faili formaadis t peab tegu olema XML kujul and metega, mis ei tohi sisaldada siin kasuta tud XML tag - e (vaata doku menti "DigiDoc for maadi kirjeldus") ega XML faili algusrida (<?xml

33

Page 34: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

... ?>). Algkujul XML and mete allkirja kontroll on na tuke aeglasem, sest tingituna SAX parserist ei saa neid and meid terviklikul kujul vaid ainult SAX sünd m ustena ja seetõt tu tuleb räsi arvutamiseks antud faili teistkordselt lugeda. Kui algand mefaili kohta sisestatakse vaid viide, siis peab allkirja kontrollimise ja faili sisselugemise hetkel vastav väline fail olema allkirjasta tud doku mendiga samas kataloogis.

Iga algand mefaili kohta kaitstakse allkirjastatud räsi abil vaid faili sisu (algkujul) ja and metüüp (szMimeType). Muud faili a t t ribuudid on infor matiivse sisuga. Faili nimi sisestatakse alati ilma teekonnata. Failile võib lisada suvalise arvu m uid atribuute (meta - info jaoks), mis esitatakse nimi /väär tus paaridena. DigiDoc teek haldab nende salvestamist ja lugemist kui ei süüvi sisusse. Nimetatud atribuutide nimed ja väärtused ei tohi sisaldada reavahetusi ja spetsiaalseid XML poolt reserveeritud sü mboleid.

Iga allkiri peab kinnitama kõik allkirjastatud doku mendis sisalduvad algand mefailid. Peale esimese allkirja lisamist ei tohi enam algand mefaile lisada ega m u uta. Allkirjad on kirjeldatud järgmiste and mes truktuuridega:

DocInfo

Ühe konkreetse algandmefaili allkirjastatud attribuudid

typedef struct DocInfo_st {char* szDocId; // dokumendi unikaalne tunnuschar* szDigestType; // räsi tüüp (sha1)byte* szDigest; // algandmete räsi väärtusint nDigestLen; // algandmete räsi pikkus (20)byte* szMimeDigest; // andmetüübi räsi väärtusint nMimeDigestLen; // andmetüübi räsi pikkus (20)

} DocInfo;

SignatureProductionPlace

Allkirjastamise koht

typedef struct SignatureProductionPlace_st {char* szCity; // linna nimichar* szStateOrProvince; // maakonna nimichar* szPostalCode; // postiindekschar* szCountryName; // riigi nimi

} SignatureProductionPlace;

SignerRole

Allkirjastaja rollid

typedef struct SignerRole_st {

34

Page 35: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

int nClaimedRoles; // kinnitamata rollide hulkchar** pClaimedRoles; // kinnitamata rollidint nCertifiedRoles; // kinnitatud rollide hulkchar** pCertifiedRoles; // kinnitatud rollid

} SignerRole;

SignatureInfo

Peamine struktuur mis hoiab kliendi allkirja infot

typedef struct SignatureInfo_st {char* szId; //allkirja unikaalne tunnusint nDocs; //allkirjastatud algandmefailide hulkDocInfo** pDocs; // allkirjastatud algandmefailid infochar* szTimeStamp; // allkirjastamise aeg formaadis

// "YYYY-MM-DDTHH:MM:SSZ"byte* szSigPropDigest;// allkirjastatud allkirja omaduste

// räsi väärtusint nSigPropDigestLen;// allkirjastatud allkirja

// omaduste räsi pikkus (20)byte* szSigPropRealDigest; // allkirjastatud allkirja

omaduste räsi väärtus failist loetud kujulint nSigPropRealDigestLen; // räsi pikkus (20)byte* szSigInfoRealDigest; // elemendi <SignedInfo>

räsi väärtus failist loetud kujulint nSigInfoRealDigestLen; // räsi pikkus (20)char* szSigType; // allkirja tüüp

// (sha1WithRSAEncryption)byte* szSigValue; // allkirja väärtusshort nSigLen; // allkirja väärtuse pikkus (128)void* pX509Cert; // allkirjastaja sertifikaatlong nIssuerSerial; // sertifikaadi numberbyte* szCertDigest; // sertifikaadi räsi väärtusint nCertDigestLen;// sertifikaadi räsi pikkusSignatureProductionPlace sigProdPlace;SignerRole signerRole;

} SignatureInfo;

NotaryInfo

NotaryInfo ehk allkirjastaja sertifikaadi kehtivuskinnitus. Igal allkirjal võib olla null või enam kehtivuskinnitust. Kehtivuskinnitused on salvestatud järgmise andmestruktuuri abil:

typedef struct NotaryInfo_sk {char* szId; //kehtivuskinnituse unikaalne tunnuschar* szSigId; //kinnitatud allkirja unikaalne tunnuschar* szNotType; // kehtivuskinnituse tüüp (OCSP-1.0)char* timeProduced;// kehtivuskinnituse tekitamise aegchar* szRespIdType;//kehtivuskinnituse andja tunnuse tüüp

// ("NAME" või "KEY HASH")char* szRespId; // kehtivuskinnituse andja tunnusint nRespIdLen; //kehtivuskinnituse andja tunnuse pikkuschar* thisUpdate; // sertifikaadi kinnituse aegchar* nextUpdate; // sertifikaadi järgmise kinnituse aeg

35

Page 36: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

// (esialgu alati NULL)unsigned long certNr; // sertifikaadi numberchar* szDigestType; // räsi tüüp (sha1)byte* szIssuerNameHash;//sertifikaadi väljaandja nime räsiint nIssuerNameHashLen;// sertifikaadi väljaandja nime

// räsi pikkusbyte* szIssuerKeyHash;//sertifikaadi väljaandja võtme räsiint nIssuerKeyHashLen;//sertifikaadi väljaandja võtme

//räsi pikkusbyte* szUserSign; // kinnitatud allkirja väärtuse räsi

// (OCSP Nonce)int nUserSignLen; // kinnitatud allkirja allkirja

// väärtuse räsi pikkus// notaries personal signaturechar* szSigType; // kehtivuskinnituse allkirja tüüp

// (sha1WithRSAEncryption)byte* szSigValue; // kehtivuskinnituse allkirja väärtusshort nSigLen;//kehtivuskinnituse allkirja väärtuse pikkusvoid* pX509Cert;// kehtivuskinnituse andja sertifikaatlong nIssuerSerial;//kehtivuskinnituse andja sertifikaadi

//numberbyte* szCertDigest; // kehtivuskinnituse andja

//sertifikaadi räsiint nCertDigestLen; // kehtivuskinnituse andja

//sertifikaadi räsi pikkus} NotaryInfo;

Timestamp

Seda struktuuri kasutatakse erinevate aegade arvutamisel DigiDoc'is.

typedef struct Timestamp_st { int year; //aasta int mon; //kuu int day; //päev int hour; //tunnid int min; //minutid int sec; //sekundid int tz; //ajavööde GMT'st.} Timestamp;

PolicyIdentifier

Seda st ruktuuri kasuta takse ser tifikaadi kasuta mise ja allkirjas tamise reeglite lugemiseks allkirjastaja ser tifikaadist.

typedef struct PolicyIdentifier_st { char* szOID; // stringikujuline reegli OID char* szCPS; // sertfikaadi reegli URL char* szUserNotice; // märkus / kommentaar} PolicyIdentifier;

CertSearchSeda struktuuri kastutatakse sertifikaatide otsimiseks ja lugemiseks.

36

Page 37: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

typedef struct CertSearch_st {int searchType;//otsingu tüüp v.t "Kasutusel olevad

konstantid"char* x509FileName; //Kui PEM fail siis selle nimichar* keyFileName; // Privaatv tme faili nimiōchar* pkcs12FileName; //PKCS #12 konteineri nimichar * pswd; // privaatv tme/ PKCS #12 paroolōCertSearchStore* certSearchStore; //MS sertifikaatde

hoidla otsing} CertSearch;

CertSearchStoreMS sertifikaatide hoidla otsingu kriteeriumite struktuur.

typedef struct CertSearchStore_st {int searchType; // mille järgi saab otsidachar* storeName; // default is "My"long certSerial; // serdi seerinumberint numberOfSubDNCriterias; //subjekti nime komponentide

arvchar** subDNCriterias; // subjekti nime komponendidint numberOfIssDNCriterias; // väljaandja nime

komponentide arvchar** issDNCriterias; // väljaandja nime komponendidvoid* publicKeyInfo; // avaliku võtme info}

CertSearchStore;

ErrorInfoVeainfot esitatakse mälus ErrorInfo struktuurina:

typedef struct ErrorInfo_st {int code; //veakoodchar *fileName; //lähtekoodi fail, kus viga avastatiint line; //lähtekoodi rea number, kus viga avastatichar *assertion;//vääraks osutunud kontrollavaldis

} ErrorInfo;

CSProviderHoiab teegi jaoks vajalikke CSP parameetreid. typedef struct CSProvider_st {

char* CSPName;int rsa_full; // kui FALSE, siis kasutatakse RSA_SIG int at_sig; // kui FALSE, siis kasutatakse AT_KEYEXCHANGE

} CSProvider;

CertItemÜldine struktuur X509 viitade nimistu hoidmiseks:typedef struct CertItem_st {

X509* pCert;struct CertItem_st* nextItem;

} CertItem;

37

Page 38: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

DEncEncryptionProperty

Seda st ruktuuri kasuta takse krüp teeritud doku mendi mingite algsete omadus te salvestamiseks mis krüp teeritud kujul ei salvestata. Näiteks faili algne nimi, suurus ja mime tüü p.

typedef struct DEncEncryptionProperty_st { char* szId; // Id atribuudi väärtus (optional) char* szTarget; // Target atribuudi väärtus (optional) char* szName; // "name" atribuudi väärtus (vajalik) char* szContent; // elemendi sisu} DencEncryptionProperty;

DEncEncryptionProperties

Seda st ruktuuri kasuta takse krüp teeritud doku mendi omadus te loeteluna.

typedef struct DEncEncryptionProperties_st { char* szId; // ID atribuudi väärtus (optional) DEncEncryptionProperty** arrEncryptionProperties; // loetelu int nEncryptionProperties; // elemendtide arv} DEncEncryptionProperties;

DEncEncryptedKey

Seda st ruktuuri kasuta takse krüp teeritud doku mendi vastuvõtja and mete salvestamiseks

typedef struct DEncEncrytedKey_st { char* szId; // Id atribuudi väärtus (optional) char* szRecipient; // Recipient atribuudi väärtus (optional) char* szEncryptionMethod; // EncryptionMethod elemendi väärtus (vajalik) char* szKeyName; // KeyName elemendi väärtus (optional) char* szCarriedKeyName; // CarriedKeyName elemendi väärtus (optional) X509* pCert; // vastuvõtja sertifikaat (vajalik) DigiDocMemBuf mbufTransportKey; // krüpteeritud AES transpordivõti} DEncEncryptedKey;

DEncEncryptedData

Seda st ruktuuri kasuta takse krüp teeritud doku mendi and mete hoidmiseks.

typedef struct DEncEncrytedData_st { char* szId; // Id atribuudi väärtus (optional) char* szType; // Type atribuudi väärtus (optional) char* szMimeType; // MimeType atribuudi väärtus (optional) char* szEncryptionMethod; // EncryptionMethod elemendi väärtus

38

Page 39: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

(nõutud) char* szXmlNs; // xmlns atribuudi väärtus (optional) DEncEncryptedKey ** arrEncryptedKeys; // <EncryptedKey> loetelu int nEncryptedKeys; // loetelu pikkus DigiDocMemBuf mbufEncryptedData; // krüpteeritud andmed DEncEncryptionProperties encProperties; // algfaili omadused // private transient fields DigiDocMemBuf mbufTransportKey; // krüpteerimata transpordivõti // flags int nDataStatus; int nKeyStatus;} DEncEncryptedData;

DEncRecvInfo

Seda st ruktuuri kasuta takse krüp teeritud doku mendi vastuvõtja and mete haldamiseks ja salvestamiseks konfiguratsioonifailides.

typedef struct DEncRecvInfo_st { char* szId; // ID atribuudi väärtus (vajalik) char* szRecipient; // Recipient atribuudi väärtus (optional) char* szKeyName; // KeyName elemendi väärtus (optional) char* szCarriedKeyName; // CarriedKeyName elemendi väärtus (optional) X509* pCert; // vastuvõtja sertifikaat (vajalik)} DEncRecvInfo;

DEncRecvInfoList

Seda st ruktuuri kasuta takse RecvInfo s truktuuride loeteluna.

typedef struct DEncRecvInfoList_st { int nItems; // objektide hulk DEncRecvInfo** pItems; // loetelu} DEncRecvInfoList;

39

Page 40: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Üldised- ja administreerimisfunktsioonidSellesse kategooriasse kuuluvad DigiDoc teegi initsialiseerimis - , sulgemis - ja versiooniinfo funktsioonid.

getLibName()Tagastab teegi nimeconst char* getLibName();

getLibVersion()Tagastab teegi versiooniconst char* getLibVersion();

getSupportedFormats()Tagastab NULL-ga lõpetatud massiivi toetatud formaatidestconst char** getSupportedFormats();

getSupportedFormatsAndVersions()Tagastab NULL-ga lõppeva jada toetatud formaadi ja versiooni kombinatsioonidest.FormatAndVer* getSupportedFormatsAndVersions();

initDigiDocLib()Initsialiseerib DigiDoc teegi ja selle poolt kasutatavad teegid (OpenSSL), tuleb alati programmi algul välja kutsudavoid initDigiDocLib();

finalizeDigiDocLib()Suleb (cleanup) DigiDoc teegi ja kasutusel olnud teegid (OpenSSL), tuleb alati programmi lõpus välja kutsudavoid finalizeDigiDocLib();

trim()Eemaldab algusest ja lõpust tühikud, ning reavahetused - ' ','\n','\r'char* trim(char* src);

ascii2utf8()Funktsioon, mis konverteerib esimese parameetris antud ASCII (ISO Latin1) stringi teises parameetris allokeeritud mällu UTF8 vormingusse.• ascii - sisend andmed ISO Latin1 vormingus• utf8out - output puhver UTF8 teksti jaoks• outlen - output puhvri pikkuschar* ascii2utf8(const char* ascii, char* utf8out, int* outlen);

40

Page 41: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

utf82ascii()Eelmise pöördfunktsioon, konverteerib esimeses parameetris antud UTF8 stringi teises parameetris allokeeritud mällu ASCII (ISO Latin1) vormingusse. • utf8in - sisend andmed UTF8 vormingus• asciiout - väljund puhver ISO Latin1 vormingus stringi jaoks• outlen - väljund puhveri pikkuschar* utf82ascii(const char* utf8in, char* asciiout, int* outlen);

unicode2ascii()Konverteerib st ringi unicode'ist asciisse• uni - sisend s tring unicode'is• dest - ascii vormingus väljundile allokeeritud p uhvervoid unicode2ascii(const char* uni, char* dest);

convertStringToTimestamp()Teisendab stringi kujul antud Timestamp'i vastavaks struktuuriks.• pSigDoc - viide kasutusel olevale DigiDoc'ile• szTimestamp - Timestamp stringi kujul• pTimestamp - Timestamp struktuur kuhu fuktsioon kirjutab oma

väljundivoid convertStringToTimestamp(const SignedDoc* pSigDoc,const char* szTimestamp, Timestamp* pTimestamp);

convertTimestampToString()Teisendab antud Timestamp struktuuri stringiks• pSigDoc - viide kasutusel olevale DigiDoc'ile• pTimestamp - Timestamp struktuur milest luuakse string• szTimestamp - allokeeritud puhver Timestamp stringi kirjutamiseksvoid convertTimestampToString(const SignedDoc* pSigDoc, const Timestamp* pTimestamp, char* szTimestamp);

Timestamp_new()Konstrueerib antud parameetritest uue Timestamp struktuuri.

• ppTimestamp – viit viidale, mis saab viitama loodud struktuurile.• year - aasta• month - kuu• day - kuupäev• hour - tunnid• minute - minutud• second - sekundid

• timezone – ajavööndFunktsioon tagastab ERR_OK või veakoodi.

int Timestamp_new(Timestamp **ppTimestamp, int year,int month,int day,int hour,int minute,int second,int timezone)

41

Page 42: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Timestamp_free()Kustutab antud Timestamp struktuuri ja vabastab mälu.void Timestamp_free(Timestamp* pTimestamp);

convertStringToTimeT ()Konverteerib ajatempli stringi time_t väärtuseks.time_t convertStringToTimeT(const SignedDoc* pSigDoc, const char* szTimestamp);

Üldised krüptograafiafunktsioonidSelle kategooria funktsioone kasutatakse enamasti teegi siseselt, kuid võivad ka m ujal kasulikuks osutuda.

bin2hex()Konverteerib binaarsed andmed vastavaks hex-stringiks• pData – algandmed• nDataLen - algandmete pikkus• pBuf - buffer hex-stringi jaoks. Vaja on algandmetest 2 korda

pikemat puhvrit • nBufLen - puffri suuruse aadress. Tuleb enne funktsiooni

kasutamist initsialiseerida puffri pikkusega. Funktsioon salvestab siia kasutatud pikkuse.

Funktsiooni tulemuseks on veakood või 0 (ERR_OK)int bin2hex(const byte* pData, int nDataLen,

char* pBuf, int* nBufLen);

calculateFileDigest()Arvutab faili SHA1 räsikoodi• szFileName – faili nimi• nDigestType – räsi tüüp. Peab olema – DIGEST_SHA1• pDigestBuf – puffer räsi väärtuse jaoks• nDigestLen - puffri suuruse aadress. Tuleb enne funktsiooni

asutamist initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

• lFileLen – siia salvestatkse loetud faili pikkus baitides

int calculateFileDigest(const char* szFileName, int nDigestType,byte* pDigestBuf, int* nDigestLen, long* lFileLen);

calculateFileSignature()Arvutab faili RSA+SHA1 allkirja • szFileName – faili nimi• nDigestType – räsi tüüp. Peab olema – DIGEST_SHA1• pSigBuf – puffer allkirja väärtuse jaoks• nSigLen - puffri suuruse aadress. Tuleb enne funktsiooni

kasutamist initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

• keyfile – allkirjastaja salajase võtme faili nimi (PEM formaadis)• passwd - allkirjastaja salajase võtme salakood (ei toimi hetkel!)

42

Page 43: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

int calculateFileSignature(const char* szFileName, int nDigestType,byte* pSigBuf, int* nSigLen, const char *keyfile, const char* passwd);

verifyFileSignature()Kontrollib faili RSA+SHA1 allkirja • szFileName – faili nimi• nDigestType – räsi tüüp. Peab olema – DIGEST_SHA1• pSigBuf – allkirja väärtuse• nSigLen - allkirja väärtuse pikkus• certfile – allkirjastaja sertifikaadi faili nimi (PEM formaadis)int verifyFileSignature(const char* szFileName, int nDigestType,

byte* pSigBuf, int nSigLen, const char *certfile);

signData()• Arvutab mingite andmete RSA+SHA1 allkirja • data – allkirjastatavad andmed• dlen - allkirjastatavate andmete pikkus• nDigestType – räsi tüüp. Peab olema – DIGEST_SHA1• pSigBuf – puffer allkirja väärtuse jaoks• nSigLen - puffri suuruse aadress. Tuleb enne funktsiooni

kasutamist initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

• keyfile – allkirjastaja salajase võtme faili nimi (PEM formaadis)• passwd - allkirjastaja salajase võtme salakood (ei toimi hetkel!)int signData(const byte* data, int dlen, byte* pSigBuf, int* nSigLen,

int nDigestType, const char *keyfile, const char* passwd);

calculateDigest()Arvutab mingite andmete SHA1 räsikoodi• data – allkirjastatavad andmed• dlen - allkirjastatavate andmete pikkus• nDigestType – räsi tüüp. Peab olema – DIGEST_SHA1• pDigestBuf – puffer räsi väärtuse jaoks• nDigestLen - puffri suuruse aadress. Tuleb enne funktsiooni

asutamist initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

int calculateDigest(const byte* data, int nDataLen, int nDigestType,byte* pDigestBuf, int* nDigestLen);

encode()Kodeerib sisendandmed Base64 kujul• raw – algandmed• rawlen – algandmete pikkus• buf – puffer Base64 andmete jaoks• buflen - puffri suuruse aadress. Tuleb enne funktsiooni kasutamist

initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

void encode(const byte* raw, int rawlen, byte* buf, int* buflen);

43

Page 44: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

decode()Dekodeerib Base64 kujul sisendandmed• raw – Base64 kujul algandmed• rawlen – Base64 kujul alganmete pikkus• buf – puffer dekodeeritud andmete jaoks• buflen - puffri suuruse aadress. Tuleb enne funktsiooni kasutamist

initsialiseerida puffri pikkusega. Funktsioon salvestab siia asutatud pikkuse.

void decode(const byte* raw, int rawlen, byte* buf, int* buflen);

Üldised XMLi genereerivad funktsioonidNeed funktsiooni tekitavad XML-i vorme mida teegi allkirjastamise ja räsifunktsiooni funktsioonid kasutavad sisendandmeteks.

createTimestamp()Konverteerib arvuti jooksva ajahetke kujul DD.MM.YYYY HH:MM:SS+HH:MM p uhvrisse buf, mis peab olema eelnevalt allokeeritud. Tagastab kirjutatud ajatem pli pikkuse.• buf - p uhhver ajatempli salvesta miseks.int createTimestamp(char* buf);

createXMLSignedInfo()Loob <SignedInfo> XML bloki an tud sisendis t ja tagastab selle s tringina.• pSigInfo - SignedDoc objekt• pSigInfo - allkirja info objektchar* createXMLSignedInfo(const SignedDoc* pSigDoc, const SignatureInfo* pSigInfo);

createMimeType ()Loob MimeType="" atribuudi allkirja arvutamiseks. Kasutatid vanemas 1.0 versioonis.int createMimeType(char* buf, const char* mime, const char* sigId, const char* docId);

Allkirjastatud dokumendi halduse funktsioonidSelle kategooria funktsioonid haldavad ülalkirjeldatud and mestruktuuride elemente, allokeerivad mälu u ute jaoks jne.

getSimpleFileName()Hangib faili nime (ilma teekonnata), ehk teisiti öeldes eraldab failinime teekonnast. Tagastab pointeri mis viitab sellele aadressile parameetriks antud stringi sees kust hakkab failinime osa.• szFileName – faili nimi koos teekonnagaconst char* getSimpleFileName(const char* szFileName);

44

Page 45: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

SignedDoc_new()Allokeerib uue allkirjastatud dokumendi struktuuri

• pSignedDoc – uus loodav struktuur.• format – allkirjastatud dokumendi formaat. Peab olema –

SK_XML_1_NAME• version – formaadi versioon. Peab olema - SK_XML_1_2_VER

int SignedDoc_new(SignedDoc **pSignedDoc, const char* format, const char* version)

SignedDoc_free()Vabastab antud allkirjastatud dokumendi ja kõigi tema osade jaoks allokeeritud mälu.• pSigDoc - allkirjastatud dokumendi struktuuri aadressvoid SignedDoc_free(SignedDoc* pSigDoc);

getCountOfDataFiles()Tagastab allkirjastatud dokumendis registreeritud algandmefailide arvu.• pSigDoc - allkirjastatud dokumendi struktuuri aadressint countDataFiles(const SignedDoc* pSigDoc);

getDataFile()Tagastab soovitud algandmefaili info• pSigDoc - allkirjastatud dokumendi struktuuri aadress• nIdx – algandmefaili indeks (algab 0-st)DataFile* getDataFile(const SignedDoc* pSigDoc, int nIdx);

getDataFileWithId()Tagastab soovitud tunnusega algandmefaili info• pSigDoc - allkirjastatud dokumendi struktuuri aadress• id – algandmefaili unikaalne tunnusDataFile* getDataFileWithId(const SignedDoc* pSigDoc, const char* id);

ddocGetDataFileCachedData()Tagastab soovitud algandmefaili sisu mälupuhvrist kui võimalik, s.o. Kui antud algandmefaili andmeid hoitakse mälus.• pSigDoc - allkirjastatud dokumendi struktuuri aadress• szDocId – algandmefaili unikaalne tunnus• ppBuf – aadress allokeeritava mälu aadressi jaoks. Kasutaja peab

mälu vabastama.• pLen – allokeeritud puhvri pikkuse aadress.int ddocGetDataFileCachedData(SignedDoc* pSigDoc, const char* szDocId, void** ppBuf, int* pLen);

ddocAppendDataFileData()Seda funktsiooni kasuta takse sisemiselt algand mete lugemisel ja lisamisel mälupuhvrisse.

45

Page 46: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pDf – algand mefaili objekt• maxLen – suurim algand mefaili suur us mille p uhul and meid veel

hoitakse mälus.• data – lisatavad and med• len – lisatavata and mete pikkus baitides.void ddocAppendDataFileData(DataFile* pDf, int maxLen, void* data, int len);

ddocGetLastDataFile()Tagastab viimase angandmefaili info.• pSigDoc - signed doc pointerDataFile* ddocGetLastDataFile(const SignedDoc* pSigDoc);

ddocGetDataFileFilename()Tagastab soovitud angandmefaili Filename atribuudi väärtuse. Parandab formaatides 1.0, 1.1 ja 1.2 kasutatud vale UTF-8 kodeeringu.• pSigDoc - signed doc objekt• szDocId – andmefaili tunnus• ppBuf – aadress allokeeritud mälu pointeri jaoks.• pLen – aadress puhvri pikkuse salvestamiseks.int ddocGetDataFileFilename(SignedDoc* pSigDoc, const char* szDocId, void** ppBuf, int* pLen);

DataFile_new()Allokeerib mälu uue algandmefaili info jaoks. Iga parameetri jaoks, mille väärtust hetkel ei tea tuleb kasutada NULL-i ja vastava parameetri pikkus, kui see on n utud, peab siis olema 0.ō

• newDataFile – loodav struktuur.• pSigDoc - allkirjastatud dokumendi struktuuri aadress• id – algandmefaili unikaalne tunnus. Kasuta NULL-i vaikimis

omistatud tunnuse kasutamiseks (soovitatud variant)• filename – algandmefaili nimi• contentType – faili tüüp (mime tüüp)• size – faili suurus baitides• digest – faili räsikood • digLen - faili räsikoodi pikkus• digType - faili räsikoodi tüüp. Kasuta - DIGEST_SHA1_NAME• szCharset - sisendandmete kooditabel. Kasuta CHARSET_ISO_8859_1

või CHARSET_UTF_8• szFileNameCharset - faili nime kooditabel. Kasuta

CHARSET_ISO_8859_1 või CHARSET_UTF_8

Funktisoon tagastab ERR_OK või veakoodi.

int DataFile_new(DataFile **newDataFile, SignedDoc* pSigDoc, const char* id, const char* filename, const char* contentType,

const char* mime, long size, const byte* digest, int digLen, const char* digType, const char* szCharset, const char* szFileNameCharset)

46

Page 47: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

DataFile_free()Vabastab antud algandmefaili info jaoks allokeeritud mälu• pDataFile - algandmefaili info aadressvoid DataFile_free(DataFile* pDataFile);

getCountOfDataFileAttributes()Tagastab algandmefaili lisa-atribuutide arvu• pDataFile - algandmefaili info aadressint countDataFileAttributes(const DataFile* pDataFile);

addDataFileAttribute()Lisab algandmefailile mingi uue attribuudi• pDataFile - algandmefaili info aadress• name – attribuudi nimi• value – attribuudi väärtus

void addDataFileAttribute(DataFile* pDataFile, const char* name, const char* value);

getDataFileAttribute()Tagastab algandmefailile soovitud attribuudi• pDataFile - algandmefaili info aadress• idx – attribuudi indeks• name – puffer attribuudi nime aadressi jaoks• value – puffer attribuudi väärtuse aadressi jaoksvoid getDataFileAttribute(DataFile* pDataFile, int idx,

char** name, char** value);

calculateDataFileSizeAndDigest()Arvutab soovitud algandmefaili suuruse ja räsikoodi ning salvestab need andmed allkirjastatud dokumendi struktuuri.• pSigDoc – allkirjastatud dokumendi info• id – algandmefaili tunnus• filename – algandmefaili nimi• digType – räsikoodi tüüp. Peab olema - DIGEST_SHA1int calculateDataFileSizeAndDigest(SignedDoc* pSigDoc,

const char* id, const char* filename, int digType);

getCountOfSignatures()Tagastab allkirjade arvu• pSigDoc – allkirjastatud dokumendi infoint countSignatures(const SignedDoc* pSigDoc);

getSignature()Tagastab soovitud allkirja info• pSigDoc – allkirjastatud dokumendi info• nIdx – allkirja indeksSignatureInfo* getSignature(const SignedDoc* pSigDoc, int nIdx);

47

Page 48: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

getSignatureWithId()Tagastab soovitud tunnusega allkirja info• pSigDoc – allkirjastatud dokumendi info• id – allkirja tunnusSignatureInfo* getSignatureWithId(const SignedDoc* pSigDoc, const char* id);

ddocGetLastSignature()Tagastab viimase allkirja info• pSigDoc – allkirjastatud dokumendi infoSignatureInfo* ddocGetLastSignature(const SignedDoc* pSigDoc);

SignatureInfo_new()Allokeerib mälu uue allkirja struktuuri jaoks• newSignatureInfo – viit loodava struktuuri viidale.• pSigDoc – allkirjastatud dokumendi info• id – allkirja tunnus

int SignatureInfo_new(SignatureInfo **newSignatureInfo, SignedDoc* pSigDoc, const char* id)

setSignatureProductionPlace()Lisab/muudab allkirjastamise koha info. Kasutage NULL-i tundmatute väärtuste jaoks.• pSigInfo – allkirja info aadress• city – linna nimi• state – maakonna nimi• zip – postiindeks• country – riigi nimivoid setSignatureProductionPlace(SignatureInfo* pSigInfo,

const char* city, const char* state,const char* zip, const char*);

addSignerRole()Lisab uue allkirjastaja rolli• pSigInfo – allkirja info aadress• nCertified – flag: 0=kinnitamata roll, 1=kinnitatud roll (rolli

sert)• role – kinnitamata rolli nimi või kinnitatud rolli serdi aadress• rLen – stringi puhul -1, serdi puhul serdi andmete pikkus• encode – flag: 0=salvesta algkujul (string), 1=kodeeri base64

formaadisvoid addSignerRole(SignatureInfo* pSigInfo, int nCertified,

const char* role, int rLen, int encode);

getCountOfSignerRoles()Tagastab allkirjastaja rollide hulga• pSigInfo – allkirja info aadress• nCertified – flag: 0=kinnitamata roll, 1=kinnitatud roll (rolli

sert)

48

Page 49: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

int countSignerRoles(SignatureInfo* pSigInfo, int nCertified);

getSignerRole()Tagastab soovitud allkirjastaja rolli info• pSigInfo – allkirja info aadress• nCertified – flag: 0=kinnitamata roll, 1=kinnitatud roll (rolli

sert)• nIdx – allkirjastaja rolli indeks (kinnitatud ja kinnitamata

rollidel on erladi loendurid)const char* getSignerRole(SignatureInfo* pSigInfo, int nCertified, int nIdx);

SignatureInfo_delete()Kustutab id'ga viidatud SignatureInfo stuktuuri pSigDoc struktuurist ja vabastab tema mälu.• pSigDoc - signed doc objekt• id - eemaldatava allkirja idint SignatureInfo_delete(SignedDoc* pSigDoc, const char* id);

SignatureInfo_free()Vabastab allkirja ja tema alamelementide jaoks allokeeritud mälu• pSigInfo – allkirja info aadressvoid SignatureInfo_free(SignatureInfo* pSigInfo);

addDocInfo()Lisab allkirja infole uue algandmefaili allkirjastatud atribuutide info.• pSigInfo – allkirja info aadress• docId – algandmefaili info tunnus• digType – räsi tüübi nimi. Peab olema – DIGEST_SHA1_NAME• digest – faili räsikood• digLen - faili räsikoodi pikkus• mimeDig – faili andmetüübi räsikood• mimeDigLen - faili andmetüübi räsikoodi pikkusDocInfo* addDocInfo(SignatureInfo* pSigInfo, const char* docId,

const char* digType, const byte* digest,int digLen, const byte* mimeDig, int mimeDigLen);

DocInfo_free()Vabastab algandmefaili allkirjastatud atribuutide info jaoks allokeeritud mälu• pDocInfo - algandmefaili allkirjastatud atribuutide info aadressvoid DocInfo_free(DocInfo* pDocInfo);

getCountOfDocInfos()Tagastab algandmefaili allkirjastatud atribuutide info struktuuride hulga• pSigInfo – allkirja info aadressint countDocInfos(const SignatureInfo* pSigInfo);

49

Page 50: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

getDocInfo()Tagastab algandmefaili allkirjastatud atribuutide info• pSigInfo – allkirja info aadress• idx – algandmefaili allkirjastatud atribuutide info indeksDocInfo* getDocInfo(const SignatureInfo* pSigInfo, int idx);

getDocInfoWithId()Tagastab soovitud algandmefaili allkirjastatud atribuutide info• pSigInfo – allkirja info aadress• id – algandmefaili tunnusDocInfo* getDocInfoWithId(const SignatureInfo* pSigInfo, const char* id);

ddocGetLastDocInfo()Tagastab viimase algandmefaili allkirjastatud atribuutide info• pSigInfo – allkirja info aadressDocInfo* ddocGetLastDocInfo(const SignatureInfo* pSigInfo);

setDocInfoDigest()Seab algandmefaili infos faili räsikoodi väärtuse ja tüübi• pDocInfo – algandmefaili allkirjastatud info aadress• digest - algandmefaili räsi väärtus• digLen - algandmefaili räsi väärtuse pikkus• digType - algandmefaili räsi tüüp. Kasuta - DIGEST_SHA1_NAMEvoid setDocInfoDigest(DocInfo* pDocInfo, const byte* digest,

int digLen, const char* digType);

setDocInfoMimeDigest()Seab algandmefaili infos andmetüübi räsikoodi väärtuse• pDocInfo – algandmefaili allkirjastatud info aadress• mimeDig - algandmefaili andmetüübi räsi väärtus• mimeDigLen - algandmefaili andmetüübi räsi väärtuse pikkusvoid setDocInfoMimeDigest(DocInfo* pDocInfo,

const byte* mimeDig, int mimeDigLen);

addAllDocInfos()Arvutab kõigi registreeritud algandmefailide allkirjastatavate atribuutide räsid ja lisab need antud allkirjale• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja infovoid addAllDocInfos(SignedDoc* pSigDoc, SignatureInfo* pSigInfo);

calculateSigInfoSignature()Arvutab SHA1+RSA allkirja väärtuse ja salvestab ta antud allkirja infos. See ei ole EstID-ga ühilduv allkiri!!!• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• nSigType – allkirja tüüp. Peab olema – SIGNATURE_RSA• keyfile – allkirjastaja salajase võtme faili nimi (PEM)• passwd - allkirjastaja salajase võtme salasõna

50

Page 51: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• certfile – allkirjastaja sertifikaadi faili nimi (PEM)int calculateSigInfoSignature(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, int nSigType, const char* keyfile, const char* passwd, const char* certfile);

getCountOfNotaryInfos()Tagastab allkirjastatud dokumendi kehtivuskinnituste arvu.• pSigDoc – allkirjastatud dokumendi infint countNotaryInfos(const SignedDoc* pSigDoc);

getNotaryInfo()Tagastab soovitud kehtivuskinnituse info• pSigDoc – allkirjastatud dokumendi info• nIdx – kehtivuskinnituse indeksNotaryInfo* getNotaryInfo(const SignedDoc* pSigDoc, int nIdx);

getNotaryWithId()Tagastab soovitud tunnusega kehtivuskinnituse info• pSigDoc – allkirjastatud dokumendi info• id – kehtivuskinnituse tunnusNotaryInfo* getNotaryWithId(const SignedDoc* pSigDoc, const char* id);

getNotaryWithSigId()Tagastab soovitud allkirja kehtivuskinnituse info• pSigDoc – allkirjastatud dokumendi info• sigId – allkirja tunnusNotaryInfo* getNotaryWithSigId(const SignedDoc* pSigDoc, const char* sigId);

ddocGetLastNotaryInfo()Tagastab viimase allkirja kehtivuskinnituse info• pSigDoc – allkirjastatud dokumendi infoNotaryInfo* ddocGetLastNotaryInfo(const SignedDoc* pSigDoc);

NotaryInfo_new()Allokeerib mälu uue kehtivuskinnituse jaoks• newNotaryInfo – viit loodava struktuuri viidale• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info

int NotaryInfo_new(NotaryInfo **newNotaryInfo, SignedDoc* pSigDoc, const SignatureInfo* pSigInfo)

NotaryInfo_new_file()Allokeerib mälu uue kehtivuskinnituse jaoks ja initsialiseerib ta andmetega OCSP vastuse failist• newNotaryInfo – viit loodava struktuuri viidale• pSigDoc – allkirjastatud dokumendi info

51

Page 52: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pSigInfo – allkirja info• ocspRespFile – OCSP vastuse faili nimi• notaryCertFile – OCSP responderi sertifikaadi faili nimi (PEM)•

Funktsioon tagastab ERR_OK või veakoodi.

int NotaryInfo_new_file(NotaryInfo **newNotaryInfo, SignedDoc *pSigDoc,

const SignatureInfo *pSigInfo, const char *ocspRespFile, const char *notaryCertFile)

NotaryInfo_free()Vabastab antud kehtivuskinnituse jaoks allokeeritud mälu• pNotary – kehtivuskinnituse infovoid NotaryInfo_free(NotaryInfo* pNotary);

NotaryInfo_delete()Eemaldab antud id'ga viidatud NotaryInfo antud SignedDoc struktuurist ning vabastab tema mälu.• pSigDoc - SignedDoc struktuur• id - eemaldatava notari ifno id int NotaryInfo_delete(SignedDoc* pSigDoc, const char* id);

createXMLSignedProperties()Koostab XML-i <SignedInfo> bloki. Vajalik juhul kui soovite ise allkirja koostada. Siis oleksid need siin andmed, mida allkirjastada• pSigInfo – allkirja infochar* createXMLSignedProperties(const SignatureInfo* pSigInfo);

calculateSignedPropertiesDigest()Arvutab SHA1 räsi XML-i <SignedProperties> blokist. Tagastab veakoodi või 0 (ERR_OK).• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja infoint calculateSignedPropertiesDigest(SignedDoc* pSigDoc, SignatureInfo* pSigInfo);

calculateSignedInfoDigest()Arvutab SHA1 räsi XML'i <SignedInfo> blokist. Tagastab veakoodi või 0 (ERR_OK).• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• digBuf - puhver räsi kirjutamiseks• digLen - algselt puhvri digBuf pikkus, funktsioon uuendab selle

räsi tegelikuks pikkuseksint calculateSignedInfoDigest(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, byte* digBuf, int* digLen)

52

Page 53: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

setSignatureCertFile()Loeb failist sertifikaadi arvutab selle räsi ning lisab, sertifikaadi, tema seerianumbri ja räsi antud allkirja info struktuuri.• pSigInfo - Allkirja info objekt• certFile - sertifikaadi fail PEM vormingusint setSignatureCertFile(SignatureInfo* pSigInfo, const char* certFile);

setSignatureCert()Arvutab sertifikaadi räsi ning lisab sertifikaadi, tema seerianumbri ja räsi antud allkirja info struktuuri.• pSigInfo - Allkirja info objekt• cert - sertifikaatint setSignatureCert(SignatureInfo* pSigInfo, X509* cert);

setSignatureValueFromFile()Loeb antud failist allkirja base64 kujul ja lisab selle antud allkirja info struktuuri.• pSigInfo - allkirja info struktuur• szSigFile - faili nimiint setSignatureValueFromFile(SignatureInfo* pSigInfo, char* szSigFile);

setSignatureValue()Määrab allkirja väärtuse.• pSigInfo - allkirja info struktuur• szSignature - allkirja väärtus• sigLen - allkirja pikkusint setSignatureValue(SignatureInfo* pSigInfo, byte* szSignature, int sigLen);

Allkirjastatud dokumendi kirjutamineSelle kategooria funktsioonide abil saab allkirjasta tud doku mente digidoc failidesse kirjutada.

createSignedDoc()Salvestab allkirjastatud dokumendi soovitud faili• pSigDoc – allkirjastatud dokumendi info• szOutputFile – faili nimi kuhu salvestadaint createSignedDoc(SignedDoc* pSigDoc, const char* szOutputFile);

Allkirjastatud dokumendi lugemine SAX parseri abil.Selle kategooria funktsioonide abil saab allkirjastatud dokumente failist lugeda ja eraldi faili salvestada. Antud moodul kasutab libxml2 teegi SAX parseri osa. SAX parser on kiirem ja effektiivsem, sest ta ei loe kogu dokumenti mällu vaid genereerib sündmuse iga osa andmete kohta mis sisse loetakse.

ddocSaxReadSignedDocFromFile()Loeb allkirjastatud dokumendi antud failist

53

Page 54: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• ppSigDoc – puffer allokeeritud dokumendi info jaoks• szFileName – sisendfaili nimi• checkFileDigest – (0/1) kas kontrollida viidatavate andmefailide

räsikoode.• lMaxDfLen – suurim algandmefaili suurus mille puhul tema andmedi

veel hoitakse mälus.int readSignedDoc(SignedDoc** ppSigDoc, const char* szFileName, int checkFileDigest, int lMaxDfLen);

ddocSaxReadSignedDocFromMemory()Loeb allkirjastatud dokumendi mälupuhvrist• ppSigDoc – puffer allokeeritud dokumendi info jaoks• pData – sisendandmed• len – sisendandmete pikkus baitides.• lMaxDfLen – suurim algandmefaili suurus mille puhul tema andmedi

veel hoitakse mälus.int ddocSaxReadSignedDocFromMemory(SignedDoc** ppSigDoc,

const void* pData, int len, long lMaxDFLen);

ddocSaxExtractDataFile()Loeb allkirjastatud dokumendi antud failist ja salvestab soovitud algandmefaili antud uude faili• pSigDoc – Allkirjastatud digidoc dokumendi objekt• szFileName – sisendfaili nimi• szDataFileName – väljundfaili nimi• szDocId – soovitud algandmefaili tunnus• szCharset - soovitav väljundi kooditabelFunktsioon tagastab ERR_OK või veakoodi.

int ddocSaxExtractDataFile(SignedDoc* pSigDoc, const char* szFileName, const char* szDataFileName, const char* szDocId, const char* szCharset);

Allkirjastatud dokumendi lugemine XML-Reader API abil.Selle kategooria funktsioonide abil saab allkirjastatud dokumente failist lugeda ja eraldi faili salvestada. Antud moodul kasutab libxml2 teegi XML-Reader parseri osa. XML-Reader parser võimaldab kasutada ka X-Path -i mida oleks vaja osade XAdES implementatsioonide loodud failide lugemiseks.

ddocXRdrReadSignedDocFromFile()Loeb allkirjastatud dokumendi antud failist• ppSigDoc – puffer allokeeritud dokumendi info jaoks• szFileName – sisendfaili nimi• lMaxDfLen – suurim algandmefaili suurus mille puhul tema andmedi

veel hoitakse mälus.int ddocXRdrReadSignedDocFromFile(const char* szFileName,

SignedDoc** ppSigDoc, long lMaxDFLen);

ddocXRdrReadSignedDocFromMemory()Loeb allkirjastatud dokumendi antud failist• ppSigDoc – puhver allokeeritud dokumendi info jaoks• szXml – sisendandmed

54

Page 55: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• xmlLen – sisendandmete pikkus baitides.• lMaxDfLen – suurim algandmefaili suurus mille puhul tema andmedi

veel hoitakse mälus.int ddocXRdrReadSignedDocFromMemory(const char* szXml,

int xmlLen, SignedDoc** pSigDoc, long lMaxDFLen);

ddocXRdrExtractDataFile()Loeb allkirjastatud dokumendi antud failist ja salvestab soovitud algandmefaili antud uude faili• pSigDoc – Allkirjastatud digidoc dokumendi objekt• szFileName – sisendfaili nimi• szDataFileName – väljundfaili nimi• szDocId – soovitud algandmefaili tunnus• szCharset - soovitav väljundi kooditabelFunktsioon tagastab ERR_OK või veakoodi.int ddocXRdrExtractDataFile(SignedDoc* pSigDoc,

const char* szFileName, const char* szDataFileName, const char* szDocId, const char* szCharset);

ddocXRdrGetDataFile()Loeb allkirjastatud dokumendi antud failist ja tagastab selle andmed uues mälupuhvris. Kasutaja peab selle mälu vabastama.• pSigDoc – Allkirjastatud digidoc dokumendi objekt• szFileName – sisendfaili nimi• szDataFileName – väljundfaili nimi• szDocId – soovitud algandmefaili tunnus• pBuf – mälupuhvriobjekt (andmed ja pikkus)Funktsioon tagastab ERR_OK või veakoodi.int ddocXRdrGetDataFile(SignedDoc* pSigDoc, const char* szFileName,

const char* szDocId, DigiDocMemBuf* pBuf);

PKCS11 funktsioonidSelle kategooria funktsioonide abil saab lugeda kasutada kiipkaar ti nii Windows kui Linux /UNIX keskkonnas. Võimalik on kasutada kas Eesti Ühispanga loodud voi Marie Fischer ja Martin Paljaku täiendus tega OpenSC PKCS#11 ohjurprogram mi.

initPKCS11Library()Laeb mällu ja initsialiseerib PKCS#11 ohjurprogrammi.• libName – PKCS#11 ohjurprogrammi nimi (s.o. .dll või .so nimi)Funktsioon tagastab PKCS#11 teegi handle mida on vaja edasises töös.LIBHANDLE initPKCS11Library(const char* libName);

closePKCS11Library()Suleb teegi- ja/või kaardisessiooni.• pLibrary – PKCS#11 teegi handle• hSession – kaardisessiooni handleFunktsioon tagastab PKCS#11 teegi handle mida on vaja edasises töös.void closePKCS11Library(LIBHANDLE pLibrary, CK_SESSION_HANDLE hSession);

GetSlotIds()Tagastab PKCS#11 „slottide“ tunnuste loetelu.

55

Page 56: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pSlotids – PKCS#11 „slottide“ tunnuste jada aadress.• pLen – jada algne pikkus / mahutavus. Siin tagastatakse ka leitud

tunnuste arv.Funktsioon tagastab PKCS#11 taseme veakoodi või CKR_OK.CK_RV GetSlotIds(CK_SLOT_ID_PTR pSlotids, CK_ULONG_PTR pLen);

GetTokenInfo()Tagastab soovitud PKCS#11 „tokeni“ andmed. Üks token vastab ühele võtmepaarile.• pTokInfo – PKCS#11 „tokeni“ detailandmete puhvri aadress.• id – valitud sloti tunnus.Funktsioon tagastab PKCS#11 taseme veakoodi või CKR_OK.CK_RV GetTokenInfo(CK_TOKEN_INFO_PTR pTokInfo, CK_SLOT_ID id);

getDriverInfo()Tagastab PKCS#11 ohjurprogrammi andmed.• pInfo – PKCS#11 ohjurprogrammi detailandmete puhvri aadress.Funktsioon tagastab PKCS#11 taseme veakoodi või CKR_OK.CK_RV getDriverInfo(CK_INFO_PTR pInfo);

GetSlotInfo()Tagastab soovitud PKCS#11 „sloti“ andmed. Üks slot vastab ühele kaardilugejale. OpenSC jagab kaartidel leitud võtmepaarid (tokenid) sedasi virtuaalsetesse slottidesse et igas slotis on täpselt üks token.• pSlotInfo – PKCS#11 „sloti“ detailandmete puhvri aadress.• id – valitud sloti tunnus.Funktsioon tagastab PKCS#11 taseme veakoodi või CKR_OK.CK_RV GetSlotInfo(CK_SLOT_INFO_PTR pSlotInfo, CK_SLOT_ID id);

loadAndTestDriver()Laeb PKCS#11 ohjurprogrammi, loeb slottide ja tokenite andmed ja kontrollib vajaliku sloti olemasolu.• driver – PKCS#11 ohjruprogrammi faili nimi.• pLibrary – puhver teegi handle salvestamiseks.• slotids – slottide jada aadress• slots – slottide jada mahutavus• slot – soovitud sloti järjekorranumbr. Funktsioon tagastab veakoodi või ERR_OK.int loadAndTestDriver(const char* driver, LIBHANDLE* pLibrary, CK_SLOT_ID* slotids, int slots, CK_ULONG slot);

calculateSignatureWithEstID()Arvutab ID kaardiga RSA+SHA allkirja väärtuse ja salvestab antud allkirja objektis.• pSigDoc – digidoc dokumendi objekt.• pSigInfo – uue allkirja objekt. Siia salvestatakse ka arvutatud

allkirja väärtus.• slot – allkirjastamiseks kasutatava sloti järjekorranumber.• passwd – allkirjastamiseks vajalik PIN kood.Funktsioon tagastab veakoodi või ERR_OK.int calculateSignatureWithEstID(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, int slot, const char* passwd);

56

Page 57: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

findUsersCertificate()Loeb kasutada sertifikaadi kaardilt.• slot – PKCS#11 sloti number (näiteks 0)• ppCert – uue sertifikaadi osuti puhvri aadress. Kasutaja peab

vabastama teegi poolt allokeeritud sertifikaadi obejekti.Funktsioon tagastab veakoodi või ERR_OK.int findUsersCertificate(int slot, X509** ppCert);

Konfiguratsioonifaili funktsioonidSelle kategooria funktsioonide abil saab lugeda ja kirju tada konfiguratsioonifaile, ning kasutada lihtsustatud allkirjas tamisfunktsioone, mille puhul osa sageli korduvatest väär tus test loetakse konfiguratsioonifailist. DigiDoc teek kasutab Linux /UNIX keskkonnas kahte eri konfiguratsioonifaili:

• globaalne - / e tc / digidoc.conf

• kasutaja oma / p rivaatne - ~ / . digidoc.conf

Windows keskkonnas kasutatakse vaid ühte konfiguratsioonifaili – c: \ programs \ digidoclib \ digidoc.ini, mis tulevikus tõenäoliselt asendatakse registry kasutamisega. Globaalse ja p rivaatse konfiguratsioonifaili kasutamisel mõjub globaalne fail kõigile an tud arvuti kasutajatele aga privaatne ainult an tud kasutajale. Mõlemas failis võib kasutada sam u kirjeid aga p rivaatses failis salvestatud valikud võetakse kasutusele alati kui nad on olemas ja globaalse faili kirjeid arvestatakse ainult siis kui privaatses failis sellist kirjet ei olnud.

initConfigStore()Initsialiseerib API ja loeb konfiguratsioonifailidest andmed.● szConfigFile – võimaldab edastada konfiguratsioonifaili täielikku

nime ja teeonda. Kui edastada NULL siis kasutatakse vaikeväärtust.Funktsioon tagastab veakoodi või ERR_OK.int initConfigStore();

cleanupConfigStore()Eemaldab mälust konfiguratsioonifailidest loetud andmed.Funktsioon tagastab veakoodi või ERR_OK.int cleanupConfigStore();

addConfigItem()Lisab uue konfiguratsiooni kirje. Seejuures faili otseselt ei salvestata, selleks on oma funktsioon.• Key – kirje tunnus • value – kirje väärtus• type – kirje tüüp: ITEM_TYPE_GLOBAL või ITEM_TYPE_PRIVATE• status – kirje staatus: ITEM_STATUS_OK või ITEM_STATUS_MODIFIED.

Enne salvestamist peaks olema ITEM_STATUS_MODIFIED.Funktsioon tagastab veakoodi või ERR_OK.int addConfigItem(const char* key, const char* value, int type, int status);

createOrReplacePrivateConfigItem()Lisab uue konfiguratsiooni kirje kasutaja privaatsesse faili. Asendab olemasoleva kirje väärtuse kui selline juba eksisteerib.

57

Page 58: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Key – kirje tunnus • value – kirje väärtusFunktsioon tagastab veakoodi või ERR_OK.int createOrReplacePrivateConfigItem(const char* key, const char* value);

ConfigItem_lookup()Otsib mingi tunnusega kirje väärtuse alguses privaatsest ja siis globaalsest failist.• Key – kirje tunnusFunktsioon tagastab vastava tunnusega kirje väärtuse või NULL kui sellist ei leidunud.const char* ConfigItem_lookup(const char* key);

ConfigItem_lookup_int()Otsib mingi tunnusega numbrilise kirje väärtuse alguses privaatsest ja siis globaalsest failist.• Key – kirje tunnus• defValue - vaikeväärtusFunktsioon tagastab vastava tunnusega kirje väärtuse või vaikeväärtuse kui sellist ei leidunud.int ConfigItem_lookup_int(const char* key, int defValue);

ConfigItem_lookup_bool()Otsib mingi tunnusega loogilise kirje väärtuse alguses privaatsest ja siis globaalsest failist.• Key – kirje tunnus• defValue - vaikeväärtusFunktsioon tagastab vastava tunnusega kirje väärtuse või vaikeväärtuse kui sellist ei leidunud.int ConfigItem_lookup_bool(const char* key, int defValue);

ConfigItem_lookup_str()Otsib mingi tunnusega kirje väärtuse alguses privaatsest ja siis globaalsest failist.• Key – kirje tunnus• defValue - vaikeväärtusFunktsioon tagastab vastava tunnusega kirje väärtuse või vaikeväärtuse kui sellist ei leidunud.const char* ConfigItem_lookup_bool(const char* key, const char* defValue);

writePrivateConfigFile()Kirjutab kirjetele tehtud muudatused privaatsesse konfiguratsioonifaili.Funktsioon tagastab veakoodi või ERR_OK.int writePrivateConfigFile();

notarizeSignature()Hangib allkirjale kehtivuskinnituse kasutades konfiguratsioonifailides toodud sertifikaate ja valides OCSP responderi sertifikaadi vastavalt responderilt saadud vastusele.• pSigDoc – digidoc objekt• pSigInfo – allkiri, millele lisada kehtivuskinnitus.Funktsioon tagastab veakoodi või ERR_OK.int notarizeSignature(SignedDoc* pSigDoc, SignatureInfo* pSigInfo);

58

Page 59: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

signDocument()Lisab dokumendile allkirja ja hangib ka kehtivuskinnituse.• pSigDoc – digidoc objekt• ppSigInfo – aadress uue allkirja osuti jaoks.• pin – allkirjastamiseks vajalik PIN kood• manifest – allkirjastaja manifest / roll• city – allkirjastaja aadress: Linn• state – allkirjastaja aadress: maakond• zip – allkirjastaja aadress: postiindeks• country – allkirjastaja aadress: MaaFunktsioon tagastab veakoodi või ERR_OK.int signDocument(SignedDoc* pSigDoc, SignatureInfo** ppSigInfo,

const char* pin, const char* manifest, const char* city, const char* state, const char* zip, const char* country);

verifyNotary()Kontrollib kehtivuskinnituse allkirja.• pSigDoc – digidoc objekt• pNotInfo – kehtivuskinnitus.Funktsioon tagastab veakoodi või ERR_OK.int verifyNotary(SignedDoc* pSigDoc, NotaryInfo* pNotInfo);

verifySignatureAndNotary()Kontrollib allkirja ja kehtivuskinnituse andmeid.• pSigDoc – digidoc objekt• pSigInfo – allkirja objekt.• szFileName – sisendandmete fail / digidoc dokument.Funktsioon tagastab veakoodi või ERR_OK.int verifySignatureAndNotary(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, const char* szFileName);

Sertifikaatide funktsioonidSelle kategooria funktsioonide abil saab lugeda mitmesuguseid allkirjas taja ja kehtivuskinnituse sertifikaadi and meid.

getSignCertData()Tagastab allkirjastaja sertifikaadi andmed (X509*)• pSigInfo – allkirja infovoid* getSignCertData(const SignatureInfo* pSignInfo);

findCertificate()Tagastab sertifikaadi vastavalt otsingu kriteeriumitele• certSearch - sertifikaadi otsingu kriteeriumite struktuurX509* findCertificate(const CertSearch * certSearch);

getNotCertData()Tagastab kehtivuskinnituse sertifikaadi andmed (X509*)• pNotInfo – kehtivuskinnituse infovoid* getNotCertData(const NotaryInfo* pNotInfo);

59

Page 60: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

getCertIssuerName()Tagastab sertifikaadi väljastaja nime (DN)• cert – sertifikaadi info (X509*)• buf – puffer väljastaja nime jaoks• buflen – puffri pikkuse aadress.int getCertIssuerName(void* cert, char* buf, int* buflen);

getCertSubjectName()Tagastab sertifikaadi omaniku nime (DN)• cert – sertifikaadi info (X509*)• buf – puffer omaniku nime jaoks• buflen – puffri pikkuse aadress.int getCertSubjectName(void* cert, char* buf, int* buflen);

getCertSerialNumber()Tagastab sertifikaadi numbri• cert – sertifikaadi info (X509*)• nr – puffer sertifikaadi numbri jaoksint getCertSerialNumber(void* cert, int* nr);

GetCertSerialNumber()Tagastab sertifikaadi numbri• certfile – sertifikaadi faili nimi (PEM formaadis)long GetCertSerialNumber(const char *certfile);

getCertNotBefore()Tagastab sertifikaadi kehtivuse alguskuupäeva• pSigDoc - viide kasutatavale DigiDoc'ile• cert – sertifikaadi info (X509*)• timestamp - sertifikaadi kehtivuse alguskuupäevint getCertNotBefore(const SignedDoc* pSigDoc, void* cert, char* timestamp);

getCertNotAfter()Tagastab sertifikaadi kehtivuse lõppkuupäeva• pSigDoc - viide kasutatavale DigiDoc'ile• cert – sertifikaadi info (X509*)• timestamp - sertifikaadi kehtivuse lõppkuupäevint getCertNotAfter(const SignedDoc* pSigDoc, void* cert, char* timestamp);

saveCert()Salvestab sertifikaadi faili.• cert – sertifikaadi info (X509*)• szFileName – väljudnfaili nimi• nFormat - väljudnfaili format (FILE_FORMAT_PEM või

60

Page 61: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

FILE_FORMAT_ASN1)int saveCert(void* cert, const char* szFileName, int nFormat);

decodeCert()Dekodeerib andtud PEM formaadis baitid X509 sertifikaadi struktuuriks;• pemData - PEM vormigus sertifikaatvoid* decodeCert(const char* pemData);

encodeCert()Kodeerib X509 sertifikaadi struktuuri binaarkujule;• x509 - X509-vormigus sertifikaat• encodedCert - viit, kuhu kirjutatakse tulemus• encodedCertLen - viit, kuhu kirjutatakse tulemuse pikkusvoid encodeCert(const X509* x509, char * encodedCert, int* encodedCertLen);

CertSearchStore_new()Loob uue CertSearchStore struktuuri, kasutamist saab vaadata näitest "Kuidas otsida sertifikaate DigiDoc'i funktsioonides".CertSearchStore* CertSearchStore_new();

CertSearchStore_free()Kustutab CertSearchStore objekti ja vabastab mälu void CertSearchStore_free(CertSearchStore* certSearchStore);

CertSearch_new()Loob uue CertSearch struktuuri, kasutamist saab vaadata näitest "Kuidas otsida sertifikaate DigiDoc'i funktsioonides".CertSearch* CertSearch_new();

CertSearch_free()Kustutab CertSearch struktuuri ja alamstruktuurid ning vabastab mälu. void CertSearch_free(CertSearch* certSearch);

CertList_free ()Vabastab sertifikaatide nimistu elemendid ning nende sisu. • pListStart - CertItem viit, mis osutab sertfikaatide nimistule.

void CertList_free(CertItem* pListStart);

readCertPolicies()Loeb ser tifikaadi ja allkirjastamise reeglid an tud sertifikaadist.

61

Page 62: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pX509 - sertifikaadi viit.• pPolicies - reeglite massiivi osuti aadress. Teek allokeerib malu

selle massivi jaoks ja salvestab etteantud aadressil allokeeritud malu aadressi. Kasutaja peab selle massiivi hiljem ise vabastama.

• nPols - allokeeritud reeglite arvu osuti.

PolicyIdentifiers_free()Vabastab allokeeritud reeglite m assiivi kasutatud mälu.• pPolicies - reeglite massiivi osuti. • nPols - allokeeritud reeglite arv.

isCompanyCPSPolicy()Kontrollib, kas an tud ser tifikaadi kasuta mise reegel on tüübist "asutuse sertifikaadi kasutamise poliitika" ehk siis kas see ser tifikaat on asutuse sertifikaat.• pPolicy - ser tifikaadi kasuta mise reegli osuti.

Allkirja kontrolli funktsioonidSelle kategooria funktsioonide abil saab kontrollida allkirja.

compareByteArrays()Võrdleb kahte baidijada. Kasutatakse räside kontrollimisel.• dig1 – esimese räsi väärtus• len1 - esimese räsi pikkus• dig2 – teise räsi väärtus• len2 - teise räsi pikkus• Tagastab 0 kui räsid on võrdsedint compareByteArrays(const byte* dig1,int len1,const byte* dig2, int len2);

verifySigDocDigest()Kontrollib soovitud algandmefaili räsikoodi antud allkirjas ja tagastab ERR_OK kui räsi on õige• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• pDocInfo - algandmefaili allkirjastatud attribuutide info• szFileName – algandmefaili nimi DETACHED tüübi jaoks.• szDataFile – algne allkirjastatud dokumendi fail puhta XML algkuju

lugemiseks 1.0 versioonis failides, kus XML-i ei kanoniseeritud.int verifySigDocDigest(const SignedDoc* pSigDoc,const SignatureInfo* pSigInfo,const DocInfo* pDocInfo,const char* szFileName, const char* szDataFile);

verifySigDocMimeDigest()Kontrollib soovitud algandmefaili andmetüübi räsikoodi antud

62

Page 63: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

allkirjas ja tagastab 0 kui räsi on õige• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• pDocInfo - algandmefaili allkirjastatud attribuutide infoint verifySigDocMimeDigest(const SignedDoc* pSigDoc,const SignatureInfo* pSigInfo, const DocInfo* pDocInfo);

verifySigDocSigPropDigest()Kontrollib allkirja allkirjastatud omaduste räsikoodi ja tagastab 0 kui räsi on õige• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• szDataFile – algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.) Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

int verifySigDocSigPropDigest(const SignedDoc* pSigDoc,const SignatureInfo* pSigInfo,const char* szDataFile);

verifySignatureInfo()Kontrollib seda allkirja ülalkirjaldatud funktsioonide abil• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• signerCA – allkirjastaja CA sertifikaadi faili nimi (PEM)• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.)Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

• bUseCA - 1=kontrolli ka antud CA sertifikaadi abil allkirjastaja sertifikaadi kuuluvust tuntud CA-le, 0=ära kontrolli CA abil.

int verifySignatureInfo(const SignedDoc* pSigDoc,const SignatureInfo* pSigInfo,const char* signerCA, const char* szDataFile);

verifySignatureInfoCERT()Kontrollib seda allkirja ülalkirjaldatud funktsioonide abil, eelmisega v rreldes on erinevuseks see, et sertifikaati faili asemelō on parameetriks sertifikaadi struktuuri.• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• signerCA – allkirjastaja CA sertifikaat• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.)Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui

63

Page 64: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

• bUseCA - 1=kontrolli ka antud CA sertifikaadi abil allkirjastaja sertifikaadi kuuluvust tuntud CA-le, 0=ära kontrolli CA abil.

int verifySignatureInfoCERT(const SignedDoc* pSigDoc, const SignatureInfo* pSigInfo, const void* signerCACert, const char* szDataFile);

verifySignatureInfo_ByCertStore()Kontrollib seda allkirja ülalkirjaldatud funktsioonide abil, eelmistega v rreldes on erinevuseks see, et allkirjastaja sertifikaatō loetakse dokumendist ning ahel leitakse MS sertifikaadihoidlast.• pSigDoc – allkirjastatud dokumendi info• pSigInfo – allkirja info• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.) Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

int verifySignatureInfo_ByCertStore(const SignedDoc* pSigDoc, const SignatureInfo* pSigInfo, const char* szDataFile);

verifySigDoc()Kontrollib kogu allkirjastatud dokumenti• pSigDoc – allkirjastatud dokumendi info• signerCA – allkirjastaja CA sertifikaadi faili nimi (PEM)• notaryCA – kehtivuskinnituse andja CA sertifikaadi faili nimi• rootCA – juur CA sertifikaadi faili nimi• caPath – sertifikaatide kataloogi nimi• notCert – kehtivuskinnituse andja sertifikaadi faili nimi• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.) Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

• bUseCA - 1=kontrolli ka antud CA sertifikaadi abil allkirjastaja sertifikaadi kuuluvust tuntud CA-le, 0=ära kontrolli CA abil.

int verifySigDoc(const SignedDoc* pSigDoc, const char* signerCA,const char* notaryCA, const char* rootCA,const char* caPath, const char* notCert,const char* szDataFile);

verifySigDocCERT()Teeb sama mis eelmine funktsioon verifySigDoc() ehk kontrollib kogu allkirjastatud dokumenti, ainsaks erinevuseks on see, et sertifikaadi failinimede asemel on parameetriteks sertifikaatide struktuurid ise.• pSigDoc – allkirjastatud dokumendi info• signerCA – allkirjastaja CA sertifikaat• notaryCA – kehtivuskinnituse andja CA sertifikaat

64

Page 65: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• rootCA – juur CA sertifikaat• caPath – sertifikaatide kataloogi nimi v ib olla nullō• notCert – kehtivuskinnituse andja sertifikaat• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.) Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

• bUseCA - 1=kontrolli ka antud CA sertifikaadi abil allkirjastaja sertifikaadi kuuluvust tuntud CA-le, 0=ära kontrolli CA abil.

int verifySigDocCERT(const SignedDoc* pSigDoc, const void* signerCA, const void* notaryCA, const void* rootCA, const char* caPath, const void* notCert, const char* szDataFile);

verifySigDoc_ByCertStore ()Teeb sama mis teised verifySigDocXxx() funktsioonid, aga loeb sertifikaadid dokumendi seest ning leiab ahela MS sertifikaadihoidla abil.• pSigDoc – allkirjastatud dokumendi info• szDataFile - algne allkirjastatud dokumendi fail allkirjastatud

omaduste lugemiseks nende esialgses formaadis. Kasulik siis kui fail on koostatud teise teegi poolt, mis formateerib XML-i natuke erinevalt (reavahetused vms.) Kui selle parameetri väärtuseks panna NULL, siis koostab ise allkirjastatud omaduste XML kuju mälus olevate andmete pealt. See on kiirem kuid toimib vaid siis kui algne fail on tehtud just selle teegiga (või täpselt sama formaati kasutavaga)

int verifySigDoc_ByCertStore(const SignedDoc* pSigDoc, const char* szDataFile)

isCertValid()kontrollib kas antud sertifikaat on kehtiv. Seda oma algus- ja lõppkuupäeva alusel!!!• cert – sertifikaadi andmed (X509*)int isCertValid(void* cert);

isCertSignedBy()kontrollib kas antud sertifikaat on allkirjastatud antud CA sertifikaadi poolt• cert – sertifikaadi andmed (X509*)• cafile – CA sertifikaadi faili nimiint isCertSignedBy(void* cert, const char* cafile);

isCertSignedByCERT()kontrollib kas antud sertifikaat on allkirjastatud antud CA sertifikaadi poolt,ainsaks erinevuseks on see, et sertifikaatide failinimede asemel on parameetriteks sertifikaatide struktuurid ise.• cert – uuritav sertifikaat• cafile – CA sertifikaat

int isCertSignedByCERT(const void* cert, const void* caCert);

65

Page 66: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

verifySigCert()Kontrollib, kas allkirjastaja sertifikaadi andmed (number ja räsi) vastavad allkirjastatud omadustes toodud andmetele• pSigInfo – allkirja infoint verifySigCert(const SignatureInfo* pSigInfo);

verifyNotaryInfo()Kontrollib kehtivuskinnituse allkirja • pSigDoc – allkirjastatud dokumendi info• pNotInfo - kehtivuskinnituse info• fileEstEidSK – allkirjastaja ja kehtivuskinnituse CA sertifikaadi

faili nimi (PEM)• fileJuurSK – juur CA sertifikaadi faili nimi• CApath – sertifikaatide kataloogi nimi• notCertFile – kehtivuskinnituse andja sertifikaadi faili nimiint verifyNotaryInfo(const SignedDoc* pSigDoc, const NotaryInfo* pNotInfo,const char *fileJuurSK, const char *fileEstEidSK,const char *CApath, const char* notCertFile);

verifyNotaryInfoCERT()Kontrollib kehtivuskinnituse allkirja,ainsaks erinevuseks on see, et sertifikaatide failinimede asemel on parameetriteks sertifikaatide struktuurid ise. • pSigDoc – allkirjastatud dokumendi info• pNotInfo - kehtivuskinnituse info• certEstEidSK – allkirjastaja ja kehtivuskinnituse CA sertifikaat• certJuurSK – juur CA sertifikaat• CApath – sertifikaatide kataloogi nimi• notCertFile – kehtivuskinnituse andja sertifikaatint verifyNotaryInfoCERT(const SignedDoc* pSigDoc, const NotaryInfo* pNotInfo, const void *certJuurSK, const void *certEstEidSK,const char *CApath, const void* notCert);

verifyNotaryInfo_ByCertStore()Kontrollib kehtivuskinnituse allkirja, ainsaks erinevuseks eelmisest on see, et funktsioon loeb sertifikaadid dokumendi seest ning leiab ahela MS sertifikaadihoidla abil.• pSigDoc – allkirjastatud dokumendi info• pNotInfo - kehtivuskinnituse infoint verifyNotaryInfo_ByCertStore(const SignedDoc* pSigDoc, const NotaryInfo* pNotInfo);

verifyNotCert ()Kontrollib, kas kehtivuskinnituse sertifikaadi andmed (number ja räsi) vastavad allkirjastatud omadustes toodud andmetele• pSigInfo – allkirja infoint verifyNotCert(const NotaryInfo* pNotInfo);

verifyNotaryDigest()Kontrollib antud notari info räsikoodi.

66

Page 67: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pSigDoc - viide kasutatavale DigiDoc'ile• pNotInfo - notari info struktuurint verifyNotaryDigest(const SignedDoc* pSigDoc, const NotaryInfo* pNotInfo);

writeOCSPRequest()Koostab OCSP formaadis kehtivuskinnituse taotluse ja salvestab at etteantud faili• signerCertFile – allkirjastaja sertifikaadi faili nimi• issuertCertFile - allkirjastaja CA sertifikaadi faili nimi• nonce - allkirja räsi• nlen - allkirja räsi pikkus• szOutputFile – väljundfaili nimiint writeOCSPRequest(const char* signerCertFile, const char* issuertCertFile,byte* nonce, int nlen, const char* szOutputFile);

getConfirmation()Loob (ja allkirjastab) notari (OCSP) päringu, saadab selle OCSP responderile, parsib vastuse ning lisab vastuse antud SignedDoc struktuuri.Selle funktsiooni kasutamist saab vaadata näitest "Kuidas lisada kehtivuskinnitust ?"• pSigDoc - SignedDoc struktuur• pSigInfo - SignatureInfo struktuur, mille allkirjasta koha

küsitakse kehtivus kinnitust.• notaryCert - notari sertifikaat• pkcs12FileName – pääsutõendi failinimi• pkcs12Password – pääsutõendi paroolifraas• signCert - notari päringu allkirjasta sertifikaat• notaryURL - notaryi (OCSP responderi) URL •• proxyHost - kui notari URL'I kätte saamiseks on vajalik proksi

siis selle nimi• proxyPort - proksi pordi number

•int getConfirmation(SignedDoc* pSigDoc, SignatureInfo* pSigInfo, const X509** caCerts, const X509* pNotCert, char* pkcs12FileName, char* pkcs12Password, char* notaryURL, char* proxyHost, char* proxyPort)

calculateNotaryInfoDigest()Arvutab räsikoodi üle notari info struktuuri, tagastab ERR_OK v iō veakoodi.• pNotInfo - notari info struktuur • digBuf - väljund puhver räsikoodile• digLen - väljund puhveri pikkus (siia kirjutatakse räsi pikkus)int calculateNotaryInfoDigest(const NotaryInfo* pNotInfo, byte* digBuf, int* digLen);

getSignerCode()Loeb antud allkirja andnud isiku ID koodi

67

Page 68: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pSigInfo - uuritava allkirja info struktuur• buf - eelnevalt allokeeritud väljund puhver ID koodileint getSignerCode(const SignatureInfo* pSigInfo, char* buf);

getSignerFirstName()Loeb antud allkirja andnud isku eesnime• pSigInfo - uuritava allkirja info struktuur• buf - eelnevalt allokeeritud väljund puhver eesnime jaoksint getSignerFirstName(const SignatureInfo* pSigInfo, char* buf);

getSignerLastName()Loeb antud allkirja andnud isku perekonnanime• pSigInfo - uuritava allkirja info struktuur• buf - eelnevalt allokeeritud väljund puhver perekonnanime jaoksint getSignerLastName(const SignatureInfo* pSigInfo, char* buf);

Krüpteerimise ja dekrüpteerimise funktsioonidSelle kategooria funktsioonide abil saab luua krüpteeritud faile, mis vastavad XML-ENC standardile, neid lugeda ja derüp teerida. API salvestab sisseloetud krüp teeritud faili and med C s trktuurides ja pakub ka funktsioone iga sellise st ruktuurielemendi lugemiseks ja m u ut miseks. Soovitav oleks kasutada neid funktsioone st ruktuuri otsese m u ut mise asemel, ses t funktsioonid teevad ka näiteks veakontrolli. Igas krüpteeritud failis on vaid üks <EncryptedData > element mis sisaldab ühe ainsa krüpteeritud and meelemendi. Sellel elemendil on aga üks või mitu <EncryptedKey > alamelementi, üks iga doku mendi vastuvõtja jaoks. Vastuvõtja on isik, kelle avaliku võtmega on krüpteeritud üks koopia antud doku mendi t ranspordivõtmest ja kes seega on suu teline seda doku menti oma ID kaardiga dekrüp teerima.

dencEncryptedData_new()Loob uue <EncryptedData> objekti mälus.• ppEncData – aadress kuhu salvestada loodava objekti pointer• szXmlNs – XML namespace väärtus• szEncMethod – <EncryptionMethod> alamelemendi väärtus• szId – antud elemendi ID atribuudi väärtus• szType – antud elemendi Type atribuudi väärtus• szMimeType – antud elemendi MimeType atribuudi väärtus• Tagastab veakoodi või ERR_OK (0)

dencEncryptedData_free()Kustutab <EncryptedData> objekti ja kõik tema alamobjektid mälust.• pEncData – kustutatava objekti aadress• Tagastab veakoodi või ERR_OK (0)

dencEncryptedData_GetId()Tagastab <EncryptedData> objekti ID atribuudi väärtuse.• pEncData – objekti aadress• Tagastab ID atribuudi väärtuse või NULL

68

Page 69: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

dencEncryptedData_GetType()Tagastab <EncryptedData> objekti Type atribuudi väärtuse.• pEncData – objekti aadress• Tagastab Type atribuudi väärtuse või NULL

dencEncryptedData_GetMimeType()Tagastab <EncryptedData> objekti MimeType atribuudi väärtuse.• pEncData – objekti aadress• Tagastab MimeType atribuudi väärtuse või NULL

dencEncryptedData_GetMimeXmlNs()Tagastab <EncryptedData> objekti xmlns atribuudi väärtuse.• pEncData – objekti aadress• Tagastab xmlns atribuudi väärtuse või NULL

dencEncryptedData_GetEncryptionMethod()Tagastab <EncryptedData> objekti EncryptionMethod alamelemendi väärtuse.• pEncData – objekti aadress• Tagastab EncryptionMethod alamelemendi väärtuse või NULL

dencEncryptedData_GetEncryptionPropertiesId()Tagastab <EncryptedData> objekti <EncryptionProperties> alamelemendi ID atribuudi väärtuse.• pEncData – objekti aadress• Tagastab <EncryptionProperties> alamelemendi ID atribuudi väärtuse

või NULL

dencEncryptedData_GetEncryptionPropertiesCount()Tagastab <EncryptedData> objekti <EncryptionProperties> / <EncryptionProperty> alamelementide arvu.• pEncData – objekti aadress• Tagastab <EncryptionProperty> alamelementide arvu või -1 vea

puhul.

dencEncryptedData_GetEncryptionProperty()Tagastab <EncryptedData> objekti <EncryptionProperty> alamelemendi.• pEncData – objekti aadress• nIdx – alamelemendi index (alates 0 -st)• Tagastab <EncryptionProperty> alamelemendi aadressi või NULL

dencEncryptedData_GetLastEncryptionProperty()Tagastab <EncryptedData> objekti viimase <EncryptionProperty> alamelemendi.• pEncData – objekti aadress• Tagastab viimase <EncryptionProperty> alamelemendi aadressi või

NULL

dencEncryptedData_FindEncryptionPropertyByName()Tagastab <EncryptedData> objekti sellise <EncryptionProperty> alamelemendi, mille Name atribuudil on soovitud väärtus.• pEncData – objekti aadress• name – soovitud alamelemendi Name atribuudi väärtus

69

Page 70: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Tagastab <EncryptionProperty> alamelemendi aadressi või NULL

dencEncryptedData_GetEncryptedKeyCount()Tagastab <EncryptedData> objekti <EncryptedKey> alamelementide arvu.• pEncData – objekti aadress• Tagastab <EncryptedKey> alamelementide arvu või -1 vea puhul.

dencEncryptedData_GetEncryptedKey()Tagastab <EncryptedData> objekti <EncryptedKey> alamelemendi.• pEncData – objekti aadress• nIdx – alamelemendi index (alates 0 -st)• Tagastab <EncryptedKey> alamelemendi aadressi või NULL

dencEncryptedData_FindEncryptedKeyByRecipient()Tagastab <EncryptedData> objekti sellise <EncryptedKey> alamelemendi mille Recipient atribuudil on toodud väärtus• pEncData – objekti aadress• recipient – soovitud alamelemendi Recipient atribuudi väärtus.• Tagastab <EncryptedKey> alamelemendi aadressi või NULL

dencEncryptedData_FindEncryptedKeyByCN()Tagastab <EncryptedData> objekti sellise <EncryptedKey> alamelemendi mille sertifikaadi omaniku DN välja CN alamväljas on toodud väärtus• pEncData – objekti aadress• cn – soovitud alamelemendi sertifikaadi omaniku DN välja CN

alamvälja väärtus.• Tagastab <EncryptedKey> alamelemendi aadressi või NULL

dencEncryptedData_GetLastEncrypted()Tagastab <EncryptedData> objekti viimase <EncryptedKey> alamelemendi.• pEncData – objekti aadress• Tagastab <EncryptedKey> alamelemendi aadressi või NULL

dencEncryptedData_GetEncryptedData()Tagastab <EncryptedData> objektis olevate krüpteeritud andmete mälupuhvri.• pEncData – objekti aadress• ppBuf – aadress kuhu salvestada krüpteeritud andmete mälupuhvri

pointer.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_GetEncryptedDataStatus()Tagastab <EncryptedData> objektis olevate krüpteeritud andmete staatuse.• pEncData – objekti aadress• ppBuf – aadress kuhu salvestada krüpteeritud andmete mälupuhvri

pointer.• Tagastab krüpteeritud andmete staatuse

dencEncryptedData_SetId()Omistab <EncryptedData> objekti ID atribuudile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus

70

Page 71: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_SetType()Omistab <EncryptedData> objekti Type atribuudile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_SetMimeType()Omistab <EncryptedData> objekti MimeType atribuudile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_SetXmlNs()Omistab <EncryptedData> objekti xmlns atribuudile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_SetEncryptionMethod()Omistab <EncryptedData> objekti <EncryptionMethod> alamelemendile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_AppendData()Omistab või lisab <EncryptedData> objektis hoitud, hetkel veel krüpteerimata, andmetele uue andmebloki. Selle funktsioon abil lisatakse <EncryptedData> objektile andmed, mida siis järgmistes sammudes krüpteerima hakatakse.• pEncData – objekti aadress• data – uus andmeblokk• len – andmete pikkus baitides. Kasuta -1 kui lisad 0 -ga lõpetatud

stringi.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_SetEncryptionPropertiesId()Omistab <EncryptedData> objekti <EncryptionProperties> alamelemendi ID atribuudile uue väärtuse.• pEncData – objekti aadress• value – omistatav väärtus• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_DeleteEncryptionProperty()Kustutab <EncryptedData> objekti <EncryptionProperty> alamelemendi.• pEncData – objekti aadress• nIdx – kustutatava alamelemendi index (alates 0 -st)• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_DeleteEncryptedKey()Kustutab <EncryptedData> objekti <EncryptedKey> alamelemendi.

71

Page 72: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pEncData – objekti aadress• nIdx – kustutatava alamelemendi index (alates 0 -st)• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_new()Loob uue <EncryptionProperty> objekti ja lisab ta <EncryptedData> objekti vastavasse loetelusse. Üldiselt kasutame neid alamobjekte mingi doumendi omaduse nagu näiteks faili nimi, originaalsuuruse või mime tüübi salvestamiseks. Sel juhul omistame atribuudile Name salvestata omaduse tunnuse, näiteks „Filename“, ja elemendi sisus salvestame antud väärtuse. On loodud ka funktsioonid Name atribuudi väärtuse järgi sellise objekti otsimiseks.• pEncData – EncryptedData objekti aadress loodava alamobjekti jaoks• pEncProperty – aadress kuhu salvestada loodava alamobjekti pointer• szId – objekti ID atribuudi väärtus (optional)• szTarget – objekti Target atribuudi väärtus (optional)• szName – objekti Name atribuudi väärtus (optional)• szContent – objekti sisu (optional)• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_free()Kustutab <EncryptionProperty> objekti.• pEncProperty – kustutatava objekti aadress• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_GetId()Tagastab <EncryptionProperty> objekti ID atribuudi väärtuse.• pEncProp – objekti aadress• Tagastab ID atribuudi väärtuse või NULL

dencEncryptionProperty_GetTarget()Tagastab <EncryptionProperty> objekti Target atribuudi väärtuse.• pEncProp – objekti aadress• Tagastab Target atribuudi väärtuse või NULL

dencEncryptionProperty_GetName()Tagastab <EncryptionProperty> objekti Name atribuudi väärtuse.• pEncProp – objekti aadress• Tagastab Name atribuudi väärtuse või NULL

dencEncryptionProperty_GetContent()Tagastab <EncryptionProperty> objekti sisu.• pEncProp – objekti aadress• Tagastab elemendi sisu või NULL

dencEncryptionProperty_SetId()Omistab <EncryptionProperty> objekti ID atribuudile uue väärtuse.• pEncProp – objekti aadress• value – atribuudi uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_SetTarget()Omistab <EncryptionProperty> objekti Target atribuudile uue väärtuse.

72

Page 73: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• pEncProp – objekti aadress• value – atribuudi uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_SetName()Omistab <EncryptionProperty> objekti Name atribuudile uue väärtuse.• pEncProp – objekti aadress• value – atribuudi uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptionProperty_SetContent()Omistab <EncryptionProperty> objektile uue sisu.• pEncProp – objekti aadress• value – objekti uus sisu• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_new()Loob uue <EncryptedKey> objekti ja lisab ta <EncryptedData> objekti vastavasse loetelusse. Neid objekte kasutame krüpteeritud dokumendi vastuvõtjate andmete salvestamiseks. Iga vastuvõtja kohta üks selline objekt. Vajalik on vähemalt vastuvõtja sertifikaat, sest sellega krüpteerime tegelike dokumendi andmete krüpteerimiseks kasutatud AES transpordivõtme.• pEncData – EncryptedData objekti aadress loodava alamobjekti jaoks• pEncKey – aadress kuhu salvestada loodava alamobjekti pointer• szEncMethod - <EncryptionMethod> alamobjekti väärtus (vajalik)• szId – objekti ID atribuudi väärtus (optional)• szRecipient – objekti Recipient atribuudi väärtus (optional)• szKeyName – <KeyName> alamobjekti väärtus (optional)• szCarriedKeyName – <CarriedKeyName> alamobjekti väärtus (optional)• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_free()Kustutab <EncryptedKey> objekti.• pEncKey – kustutatava objekti aadress.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_GetId()Tagastab <EncryptedKey> objekti ID atribuudi väärtuse.• pEncKey – objekti aadress• Tagastab ID atribuudi väärtuse või NULL

dencEncryptedKey_GetRecipient()Tagastab <EncryptedKey> objekti Recipient atribuudi väärtuse.• pEncKey – objekti aadress• Tagastab Recipient atribuudi väärtuse või NULL

dencEncryptedKey_GetEncryptionMethod()Tagastab <EncryptedKey> objekti <EncryptionMethod> alamobjekti väärtuse.• pEncKey – objekti aadress• Tagastab <EncryptionMethod> alamobjekti väärtuse või NULL

73

Page 74: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

dencEncryptedKey_GetKeyName()Tagastab <EncryptedKey> objekti <KeyName> alamobjekti väärtuse.• pEncKey – objekti aadress• Tagastab <KeyName> alamobjekti väärtuse või NULL

dencEncryptedKey_GetCarriedKeyName()Tagastab <EncryptedKey> objekti <CarriedKeyName> alamobjekti väärtuse.• pEncKey – objekti aadress• Tagastab <CarriedKeyName> alamobjekti väärtuse või NULL

dencEncryptedKey_GetCertificate()Tagastab <EncryptedKey> objektis salvestatud vastuvõtja sertifikaadi.• pEncKey – objekti aadress• Tagastab vastuvõtja sertifikaadi või NULL

dencEncryptedKey_SetId()Omistab <EncryptedKey> objekti ID atribuudile uue väärtuse.• pEncKey – objekti aadress• value – atribuudi uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_SetRecipient()Omistab <EncryptedKey> objekti Recipient atribuudile uue väärtuse.• pEncKey – objekti aadress• value – atribuudi uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_SetEncryptionMethod()Omistab <EncryptedKey> objekti <EncryptionMethod> alamobjektile uue väärtuse.• pEncKey – objekti aadress• value – alamobjekti uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_SetKeyName()Omistab <EncryptedKey> objekti <KeyName> alamobjektile uue väärtuse.• pEncKey – objekti aadress• value – alamobjekti uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_SetCarriedKeyName()Omistab <EncryptedKey> objekti <CarriedKeyName> alamobjektile uue väärtuse.• pEncKey – objekti aadress• value – alamobjekti uus väärtus.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedKey_SetCertificate()Omistab <EncryptedKey> objektile vastuvõtja sertifikaadi.• pEncKey – objekti aadress• value – vastuvõtja sertifikaadi aadress.

74

Page 75: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_encryptData()Krüpteerib dokumendi andmed.• pEncData – objekti aadress• nCompressOption – komprimeerimise valik. Võimaliku väärtused on:

DENC_COMPRESS_ALLWAYS (komprimeeri), DENC_COMPRESS_NEVER (mitte komprimeerida) või DENC_COMPRESS_BEST_EFFORT (komprimeeri aga kasuta komprimeeritud andmeid vaid siis kui nende maht komprimeerimisel vähenes, vastasel juhul kasuta originaalandmeid)

• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_decrypt_withKey()Dekrüpteerib dokumendi andmed selleks edastatud, juba dekrüpteeritud, AES transpordivõtme abil. Seda funktsiooni kasutatakse siis kui ei soovita kasutada PKCS#11 ohjruprogrammi ja/või ID kaarti AES transpordivõtme dekrüpteerimiseks.• pEncData – objekti aadress• tKey – dekrüpteeritud AES transpordivõti.• KeyLen – transpordivõtme pikkus baitides.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_decryptData()Dekrüpteerib dokumendi andmed objektis salvestatud, juba dekrüpteeritud, AES transpordivõtme abil. Seda funktsiooni kasutatakse siis kui üks objektis hoitud <EncryptedKey> alamobjektidest on juba dekrüpteeritud vastuvõtja poolt ja seega transpordivõti dekrüpteeritud kujul olemas.• pEncData – objekti aadress• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_decrypt()Dekrüpteerib dokumendi andmed objektis salvestatud <EncryptedKey> abil. Vastav ID kaart peab olema sisestatud kaardilugejasse ja PKCS#11 ohjruprogramm installeeritud. • pEncData – objekti aadress• pEncKey – valitud vastuvõtja / <EncryptedKey> objekt• pin – antud vastuvõtja PIN1 kood.• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_compressData()Komprimeerib dokumendis hoitud andmed. Andmed ei tohi veel olla krüpteeritud. • pEncData – objekti aadress• nCompressOption – komprimeerimise valik. Võimaliku väärtused on:

DENC_COMPRESS_ALLWAYS (komprimeeri), DENC_COMPRESS_NEVER (mitte komprimeerida) või DENC_COMPRESS_BEST_EFFORT (komprimeeri aga kasuta komprimeeritud andmeid vaid siis kui nende maht komprimeerimisel vähenes, vastasel juhul kasuta originaalandmeid)

• Tagastab veakoodi või ERR_OK (0).

dencEncryptedData_decompressData()Dekomprimeerib dokumendis hoitud andmed. • pEncData – objekti aadress• Tagastab veakoodi või ERR_OK (0).

75

Page 76: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

dencRecvInfo_new()Loob uue RecvInfo objekti. Neid objekte kasutame krüpteeritud dokumendi vastuvõtjate andmete haldamiseks konfiguratsioonifailis. Iga vastuvõtja kohta üks selline objekt. Vajalik on vähemalt vastuvõtja sertifikaat, sest sellega krüpteerime tegelike dokumendi andmete krüpteerimiseks kasutatud AES transpordivõtme.• ppRecvInfo – aadress kuhu salvestada loodava alamobjekti pointer• szId – objekti ID atribuudi väärtus. See atribuut on vajalik

vastvõtjate andmete haldamiseks konfiguratsioonifailis ja nende andmete hilisemaks otsinguks.

• szRecipient – objekti Recipient atribuudi väärtus (optional)• szKeyName – <KeyName> alamobjekti väärtus (optional)• szCarriedKeyName – <CarriedKeyName> alamobjekti väärtus (optional)• pCert – vastuvõtja sertifikaat. (nõutud)• Tagastab veakoodi või ERR_OK (0).

dencRecvInfo_free()Kustutab RecvInfo objekti.• pRecvInfo – kustutatava objekti aadress.• Tagastab veakoodi või ERR_OK (0).

dencRecvInfo_store()Kirjutab RecvInfo objekti (muudetud?) andmed konfiguratsioonifaili.• pRecvInfo – kustutatava objekti aadress.• Tagastab veakoodi või ERR_OK (0).

dencRecvInfo_findById()Otsi RecvInfo objekti konfiguratsioonifailist tema ID atribuudi väärtuse järgi.• pConfStore – konfiguratsioonifaili / loetelu objekti aadress.

Kasuta NULL väärtust vaikimisi failist lugemiseks. Seda objekti saab kasutada selleks, et näiteks mingite kriteeriumide alusel otsitud ja sellisesse loetelisse salvestatud andmete hulgast nüüd ühe vastuvõtja andmed välja lugeda.

• ppRecvInfo – aadress kuhu salvestada loodud/otsitud objekti osuti.• szId – ID atribuudi väärtus mille alusel vastuvõtja andmed valida• Tagastab veakoodi või ERR_OK (0).

dencRecvInfo_delete()Kustutab RecvInfo objekti konfiguratsioonifailist.• pRecvInfo – kustutatava objekti osuti.• Tagastab veakoodi või ERR_OK (0).

dencRecvInfo_findAll()Loeb kõik RecvInfo objektid konfiguratsioonifailist.• pRecvInfoList – loetelu RecvInfo objektide hoidmiseks.• Tagastab veakoodi või ERR_OK (0).

dencRecvInfoList_add()Lisab ühe RecvInfo objekti loetelusse.• pRecvInfoList – loetelu RecvInfo objektide hoidmiseks.• pRecvInfo – lisatava objekti osuti.• Tagastab veakoodi või ERR_OK (0).

76

Page 77: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

dencRecvInfoList_free()Vabastab loetelu poolt kasutatud mälu.• pRecvInfoList – loetelu RecvInfo objektide hoidmiseks.• Tagastab veakoodi või ERR_OK (0).

dencRecvInfoList_delete()Kustutab soovitud RecvInfo objekti loetelust.• pRecvInfoList – loetelu RecvInfo objektide hoidmiseks.• szId – kustutatava RecvInfo objekti ID atribuut• Tagastab veakoodi või ERR_OK (0).

dencEncryptFile()Krüpteerib soovitud sisendfaili ja salvestab väljundfaili. Kasuta seda funktsiooni eriti suurte failide krüpteerimiseks. Antud versioonis ei rakenda see funktsioon veel komprimeerimist.• pEncData – EncryptedData objekt initsialiseeritud AES

transpordivõtme ja vastuvõtjate andmetega.• szInputFileName – sisendfaili nimi• szOutputFileName – väljundfaili nimi• szMimeType – sisendfaili mime tüüp (optional)• Tagastab veakoodi või ERR_OK (0).

dencGenEncryptedData_toXML()Genereerib EncryptedData XML vormingu ja tagastab selle DigiDocMemBuf struktuuris. Viimane sisaldab osutit andmetele (pMem) ja andmete mahtu baitides (nLen). Kasutaja peab allokeeritud mälu vabastama DigiDocMemBuf_free() funktsiooniga.• pEncData – EncryptedData objekt.• pBuf – mälupuhvri objekt XML tagastamiseks.• Tagastab veakoodi või ERR_OK (0).

dencGenEncryptedData_writeToFile()Genereerib EncryptedData XML vormingu ja kirjutab selle soovitud faili. • pEncData – EncryptedData objekt.• szFileName – väljundfaili nimi.• Tagastab veakoodi või ERR_OK (0).

dencSaxReadEncryptedData()Loeb krüpteeritud faili mällu. Kasuta seda väiksemate ja keskmiste failide jaoks. • ppEncData – aadress kuhu salvestada loodud EncryptedData objekti

osuti.• szFileName – sisendfaili nimi.• Tagastab veakoodi või ERR_OK (0).

dencSaxReadDecryptFile()Loeb krüpteeritud faili osade kaupa sisse, dekrüpteerib ja kirjutab dekrüpteeritud andmed väljundfaili. Seda funktsiooni saab kasutada eriti suurte failide dekrüpteerimiseks. Kasutab PKCS#11 ohjurprogrami dekrüpteerimisel.• szFileName – sisendfaili nimi.• szOutputFileName – väljundfaili nimi• szCertCN – vastuvõtja sertifikaadi omaniku DN välja CN alamväli.

77

Page 78: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Selle alusel valitakse EncryptedKey element mille abil transpordivõtit dekrüpteerda.

• szPin – vastuvõtja ID kaardi PIN1• Tagastab veakoodi või ERR_OK (0).

dencOrigContent_count()Loendab EncryptionProperty objektide hulga mis sisaldavad and meid pakitud ja krüpteeritud digidoc documendi kohta.

• pEncData – EncruptedData objekt [nõutud].

• objektide hulga või - 1

EXP_OPTION int dencOrigContent_count(DEncEncryptedData* pEncData);

dencOrigContent_add()Lisab uue EncryptionProperty objekti krüpteeritud digidoc doku mendi and mete salvestamiseks. Seda funktsiooni tuleks kasutada üks kord iga krüpteeritud doku mendi and mefaili kohta. Faili suuruse saab küll edastada st ringi kujul kui siia tuleks salvestada otsene baitide arv (ainult nu mbriline).

● pEncData – EncruptedData objekt [nõutud].

● s zOrigContentId – mingi väärtus loodava EncryptionProperty obejkti Id atribuudi jaoks [mitte nõu tud]

● s zName – and mefaili nimi

● s zSize – and mefaili suurus (täpne baitide arv)

● s zMime – and mefaili maimi tüüp

● s zDfId – and mefaili Id a tribuudi väärtus

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencOrigContent_add(DEncEncryptedData* pEncData, const char* szOrigContentId, const char* szName, const char* szSize, const char* szMime, const char* szDfId);

dencOrigContent_findByIndex()Loeb soovitud krüpteeritud digidoc documendi andmeid sisaldava EncryptionProperty andmed. Siin kasutatud järjekorranumber ei ole mitte üldine EncryptionProperty objektide järjekorranumber vaid hlmab vaid selliseid objekte mis sisaldavad krüpteeritud digidoc documendi andmeid. Seega algab 0 - st ja lõpeb dencOrigContent_count() tagastatud väärtusega.

● pEncData – EncruptedData objekt [nõutud].

● szOrigContentId – mingi väärtus loodava EncryptionProperty obejkti Id atribuudi jaoks [mitte nõutud]

● szName – puhver andmefaili nime jaoks

● szSize – puhver andmefaili suuruse jaoks

● szMime – puhver andmefaili maimi tüübi jaoks.

● szDfId – puhver andmefaili Id atribuudi väärtuse jaoks.

● Funktsioon tagastab veakoodi või ERR_OK.

78

Page 79: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

EXP_OPTION int dencOrigContent_findByIndex(DEncEncryptedData* pEncData, int origContIdx, char* szName, char* szSize, char* szMime, char* szDfId);

dencOrigContent_findByIndex()Kontrollib kas krüpteeritud fail on digidoc dokument.

● pEncData – EncruptedData objekt [nõutud].

● Funktsioon tagastab 1 kui krüpteeritud fail on digidoc dokument.

EXP_OPTION int dencOrigContent_isDigiDocInside(DEncEncryptedData* pEncData);

dencOrigContent_registerDigiDoc()Lisab krüpteeritud dokumendile sobiva maimi tüübi mis viitab sellele et sisuks on krüpteeritud digidoc dokument. Koostab iga digidoc objekti andmefaili (DataFile) objekti kohta EncryptionProperty objekti kuhu salvestatakse puhastekstina andmefaili nimi, suurus ja maimi tüüp.

● pEncData – EncryptedData objekt [nõutud].

● pSigDoc – SignedDoc objekt [nõutud].

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencOrigContent_registerDigiDoc(DEncEncryptedData* pEncData, SignedDoc* pSigDoc);

dencMetaInfo_SetLibVersion()Lisab krüpteeritud dokumendile EncryptionProperty objekti kuhu salvestatakse dokumendi koostanud teegi nimi ja versioon.

● pEncData – EncryptedData objekt [nõutud].

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencMetaInfo_SetLibVersion(DEncEncryptedData* pEncData);

dencMetaInfo_SetFormatVersion()Lisab krüpteeritud dokumendile EncryptionProperty objekti kuhu salvestatakse dokumendi formaadi nimi ja versioon.

● pEncData – EncryptedData objekt [nõutud].

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencMetaInfo_SetFormatVersion(DEncEncryptedData* pEncData);

dencMetaInfo_GetLibVersion()Loeb krüpteeritud dokumendi EncryptionProperty objektist dokumendi koostanud teegi nime ja versiooni.

● pEncData – EncryptedData objekt [nõutud].

● szLibrary – puhver teegi nime jaoks [nõutud].

● szVersion – puhver teegi versiooni jaoks [nõutud].

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencMetaInfo_GetLibVersion(DEncEncryptedData* pEncData, char* szLibrary, char* szVersion);

dencMetaInfo_GetFormatVersion()Loeb krüpteeritud dokumendi EncryptionProperty objektist dokumendi formaadi nime ja versiooni.

● pEncData – EncryptedData objekt [nõutud].

79

Page 80: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

● szFormat – puhver formaadi nime jaoks [nõutud].

● szVersion – puhver formaadi versiooni jaoks [nõutud].

● Funktsioon tagastab veakoodi või ERR_OK.

EXP_OPTION int dencMetaInfo_GetFormatVersion(DEncEncryptedData* pEncData, char* szFormat, char* szVersion);

VeatöötlusfunktsioonidVeatöötlusfunktsioonid võimaldavad hankida infot DigiDoc teegi funktsioonide töös tekkinud veasituatsioonide kohta. Veasituatsioone võidakse DigiDoci poolt registreerida kahel viisil:

• funktsiooni tagastusväärtusena. Sel juhul on võimalik DigiDocist küsida veakoodi tähendus t tekstikujul.

• mälus hoitava veainfona. Veainfot saab kät te funktsiooni getErrorInfo abil. Mällu registreeritakse veainfo enamsti siis, kui funktsiooni tagastusväärtus ei kuju ta endast veakoodi, vaid midagi m u u d, näiteks viita and mestruktuurile.

Mällu registreeritud vigade olemasolu saab kindlaks teha funktsiooni hasUnreadErrors abil või viimati väljakutsu tud funktsiooni anomaalse tulemuse: nulline viit või veakood tagastusväär tusena.

Tagastusväär tusena antud veakoodi variandi p uhul on võimalik, et registreeriti ka viimast veakoodi põhjustanud varemtoimunud vigu mällu. Seetõt tu on mõis tlik alati peale veakoodi avastamist ka mällu registreeritud vigu kontrollida.

getErrorString()Tagastab vea tekstilise kirjelduse vastavalt veakoodile ja keelele.

• code – veakood (funktsiooni poolt tagastatud või ErrorInfo sruktuurist)

char* getErrorString(int code);

getErrorClass()Tagastab vea klassifikatsiooni.

Hetkel on registreeritud kolm vigade klassi:

NO_ERRORS – viga ei esinenud, puudub reageerimise vajadus.

TECHNICAL – mingi tehniline probleem.

USER - kasutaja poolt likvideertav probleem.

LIBRARY - teegisisene viga

• code – veakood (funktsiooni poolt tagastatud või ErrorInfo sruktuurist)

ErrorClass getErrorClass(int code);

80

Page 81: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

checkDigiDocErrors()// kontrollib vigu ja trükib nad// standardväljundisse. Tagastab viimase vea

int checkDigiDocErrors();

getErrorInfo()Tagastab hiliseima, kuid veel lugemata vea ErrorInfo struktuuri.Kui vigu ei ole registreeritud, siis tagastatakse 0.ErrorInfo* getErrorInfo();

hasUnreadErrors()Tagastab 1 kui eksisteerib veel lugemata vigu, 0 kui lugemata vigu pole.int hasUnreadErrors();

clearErrors()Kustutab kõigi mälus olevate (nii loetud kui lugemata) vigade info.v

DigiDoc teegis kasutatavad konstandid ja nende väärtused

Allkirjastamisega seotud konstandid

SIGNATURE_LEN 128/ / kasutatud allkirja pikkus

DIGEST_LEN 20/ / räsi pikkus

DIGEST_SHA1 0/ / kasutusel olev räsi

CERT_DATA_LEN 2048/ / ser tifikaadi and mete suurim pikkus

X509_NAME_LEN 256/ / ser tifikaadi nimevälja (subject ja issuer) pikkus

SIGNATURE_RSA 0/ / kasutusel olev allkiri

CONTENT_DETATCHED "DETATCHED"CONTENT_EMBEDDED "EMBEDDED"CONTENT_EMBEDDED_BASE64 "EMBEDDED_BASE64

/ / need konstandid näitavad kuidas and mefail on seotud / / d igidoci konteineriga

81

Page 82: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Vorminguga seotud konstandid

SK_PKCS7_1 "SK-PKCS#7 - 1.0"SK_XML_1_NAME "SK-XML"SK_XML_1_VER "1.0"DIGIDOC_XML_1_1_VER "1.1"DIGIDOC_XML_1_2_VER "1.2"SK_NOT_VERSION "OCSP-1.0"

CHARSET_ISO_8859_1 "ISO- 8859 - 1"CHARSET_UTF_8 "UTF-8"

DIGEST_SHA1_NAME "sha1"SIGN_RSA_NAME "RSA"OCSP_NONCE_NAME "OCSP Nonce"RESPID_NAME_VALUE "NAME"RESPID_KEY_VALUE "KEY HASH"OCSP_SIG_TYPE "sha1WithRSAEncryption"

FILE_FORMAT_ASN1 0FILE_FORMAT_PEM 1

Veakoodid

ERROR_BUF_LENGTH 20/ / Vigade p uhvri suur us

ERR_OK 0/ / See kood näitab , et vigu polnud

ERR_UNSUPPORTED_DIGEST 1/ / Prooviti kasutada räsikoodi mida teek ei toeta,

hetkel/ / lubab teekkasutada ainult SHA1.

ERR_FILE_READ 2/ / Ei saanud faili lugemiseks avada

ERR_FILE_WRITE 3/ / Ei saanud faili kirjutamiseks avada

ERR_DIGEST_LEN 4/ / Vale räsikoodi pikkus

ERR_BUF_LEN 5/ / Liiga väike mälupuhvri pikkus

ERR_SIGNATURE_LEN 6/ / Vale allkirja pikkus

ERR_PRIVKEY_READ 7/ / Privaatvõtme lugemine ebaõnnestus

82

Page 83: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

ERR_PUBKEY_READ 8/ / Avaliku võtme lugemine ebaõnnestus

ERR_CERT_READ 9/ / Sertifikaadi lugemine ebaõnnestus

ERR_SIGNEDINFO_CREATE 10/ / Ei suutnud tekitada allkirja objekti

ERR_SIGNEDINFO_DATA 11/ / Ei suutnud tekitada allkirja objekti

ERR_SIGNEDINFO_FINAL 12/ / Ei suutnud tekitada allkirja objekti

ERR_UNSUPPORTED_FORMAT 13/ / Vale allkirjastatud doku mendi for maat

ERR_BAD_INDEX 14/ / Vale indeks

ERR_TIMESTAMP_DECODE 15/ / Ajatempli dekodeerimine ebaõnnestus

ERR_DIGIDOC_PARSE 16/ / Viga doku mendi süntaksianalüüsil

ERR_UNSUPPORTED_SIGNATURE 17/ / Vale allkirja tüüp

ERR_CERT_STORE_READ 18/ / Ei suutnud lugeda ser tifikaati sertifikaatide / / hoidlast

ERR_SIGPROP_DIGEST 19/ / Vale allkirja omadus te räsikood

ERR_COMPARE 20/ / Vale allkiri

ERR_DOC_DIGEST 21/ / Vale doku mendi räsikood

ERR_MIME_DIGEST 22/ / Vale doku mendi tüübi räsikood

ERR_SIGNATURE 23/ / Vale allkiri

ERR_CERT_INVALID 24/ / Sobimatu ser tifikaat

ERR_OCSP_UNSUCCESSFUL 25/ / OCSP päring ebaõnnestus

ERR_OCSP_UNKNOWN_TYPE 26/ / Tund matu OCSP tüü p

ERR_OCSP_NO_BASIC_RESP 27/ / OCSP_BASIC_RESP pu ud ub

ERR_OCSP_WRONG_VERSION 28/ / Vale OCSP versioon

ERR_OCSP_WRONG_RESPID 29/ / OCSP vastuse ID on vale

ERR_OCSP_ONE_RESPONSE 30/ / OCSP vastuste arv ei klapi

ERR_OCSP_RESP_STATUS 31/ / Vale OCSP vastuse s taatus

ERR_OCSP_NO_SINGLE_EXT 32

83

Page 84: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

/ / Ebakorrektne OCSP laiendusERR_OCSP_NO_NONCE 33

/ / OCSP vastuses pu ud ub NONCEERR_NOTARY_NO_SIGNATURE 34

/ / Puudub allkiri mille kohta OCSP päringut / / teostada

ERR_NOTARY_SIG_MATCH 35/ / Notari allkiri vigane

ERR_WRONG_CERT 37/ / Sobimatu ser tifikaat

ERR_NULL_POINTER 38/ / Nulline viit

ERR_NULL_CERT_POINTER 39/ / Nulline sertifikaadi viit

ERR_NULL_SER_NUM_POINTER 40/ / Nulline sertifikaadi nu mbri viit

ERR_NULL_KEY_POINTER 41/ / Nulline võtmeviit

ERR_EMPTY_STRING 42/ / Tühi s tring

ERR_BAD_DATAFILE_INDEX 43/ / Andmefaili indeks on piirides t väljas

ERR_BAD_DATAFILE_COUNT 44/ / Andmefailide loendur on vale

ERR_BAD_ATTR_COUNT 45/ / Atribuu tide loendur on vale

ERR_BAD_ATTR_INDEX 46/ / Atribuudi indeks on piiridest väljas

ERR_BAD_SIG_INDEX 47/ / Allkirja indeks on piiridest väljas

ERR_BAD_SIG_COUNT 48/ / Allkirjade loendur on vale

ERR_BAD_ROLE_INDEX 49/ / Rolli indeks on piiridest väljas

ERR_BAD_DOCINFO_COUNT 50/ / Dok. info loendur on vale

ERR_BAD_DOCINFO_INDEX 51/ / Dok. info indeks on piirides t väljas

ERR_BAD_NOTARY_INDEX 52/ / Notari indeks on piirides t väljas

ERR_BAD_NOTARY_ID 53/ / Vale notari ID

ERR_BAD_NOTARY_COUNT 54/ / Notarite loendur on vale

ERR_X509_DIGEST 55/ / X509 räsikoodi arvutus ebaõnnestus

ERR_CERT_LENGTH 56/ / Sertifikaadi pikkus on vale

ERR_PKCS_LIB_LOAD 57/ / PKCS #11 DLL-i laadimine ebaõnnestus

84

Page 85: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

ERR_PKCS_SLOT_LIST 58/ / Ebaõnnestus PKCS #11 slot tide küsimine

ERR_PKCS_WRONG_SLOT 59/ / Sellist PKCS #11 slot ti ei ole olemas

ERR_PKCS_LOGIN 60/ / Kaart ei ole sisestatud, PIN on vale või / / blokeeritud

ERR_PKCS_PK 61/ / Ei suuda leida EstID salajase võtme asukohta

ERR_PKCS_CERT_LOC 62/ / Ei suuda lugeda EstID allkirjastamise

sertifikaatiERR_PKCS_CERT_DECODE 63

/ / Sertifikaadi dekoreerimine ebaõnnestusERR_PKCS_SIGN_DATA 64

/ / Allkirjastamine EstID kaardiga ebaõnnestusERR_PKCS_CARD_READ 65

/ / EstID kaardi lugemine ebaõnnestusERR_CSP_NO_CARD_DATA 66

/ / EstID kaar t ei ole kät tesaadavERR_CSP_OPEN_STORE 67

/ / Ei õnnestu avada süsteemi ser tifikaatide hoidlatERR_CSP_CERT_FOUND 68

/ / Ei leitud sertifikaati, kontrollige kas ser tifikaat / / on registreeritud

ERR_CSP_SIGN 69/ / Allkirjastamine CSP-ga ebaõnnestus

ERR_CSP_NO_HASH_START 70/ / Ei suuda alustada CSP räsi arvutamist

ERR_CSP_NO_HASH 71/ / CSP räsi arvutamine ebaõnnestus

ERR_CSP_NO_HASH_RESULT 72/ / Ei suuda lugeda CSP räsi tulemust

ERR_CSP_OPEN_KEY 73/ / CSP ei suuda avada kaardi võtit

ERR_CSP_READ_KEY 74/ / CSP ei suuda lugeda kaardi võtit

ERR_OCSP_SIGN_NOT_SUPPORTED 75/ / Valitud OCSP allkirjasta mise viis ei toeta ta

ERR_OCSP_SIGN_CSP_NAME 76/ / Ei suuda lisada allakirjutaja nime OCSP

päringuleERR_CSP_CERT_DECODE 77

/ / Sertifikaadi dekoreerimine ebaõnnestusERR_OCSP_SIGN_PKCS_NAME 78

/ / Ei suuda lisada allkirjutaja nime OCSP päringuleERR_OCSP_SIGN_OSLL_CERT 79

/ / Ei suuda lisada sertifikaati OCSP päringusse

85

Page 86: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

ERR_OCSP_SIGN 80/ / Ei suuda allkirjas tada OCSP päringut

ERR_CERT_ISSUER 81/ / Tund matu autoriteedi poolt välja an tud / / ser tifikaat, või vale allkiri sertifikaadil

ERR_OCSP_PKCS12_CONTAINER 82/ / Ei suuda avada PKCS#12 konteinerit

ERR_MODIFY_SIGNED_DOC 83/ / Ei saa m u u ta allkirjastatud faili. Eemaldage / / enne allkirjad!

ERR_NOTARY_EXISTS 84/ / Ei saa kustu tada allkirja kui kehtivuskinnitus / / o n olemas. Eemaldage esmalt vastav / / kehtivuskinnitus!

ERR_UNSUPPORTED_CERT_SEARCH 85/ / Tund matu otsigu meetod

ERR_INCORRECT_CERT_SEARCH 86/ / Vigane otsingu m uster

ERR_BAD_OCSP_RESPONSE_DIGEST 87/ / Kehtivuskinnituse kontrollkood on vale

ERR_LAST_ESTID_CACHED 88/ / Vale ser tifikaat p uhvris, proovige u uesti.

ERR_BAD_DATAFILE_XML 89/ / Andmed ei tohi sisaldada XML faili esimest rida

ERR_UNSUPPORTED_VERSION 90/ / Doku ment on loodud uue ma tarkvara / / versiooniga. Palun uuendage tarkvara!

ERR_UNSUPPORTED_CHARSET 91/ / mit te toetatud kooditabel

ERR_PKCS12_EXPIRED 92/ / Juurdepääsutõendi kehtivusaeg on lõppenud!

ERR_CSP_USER_CANCEL 93/ / Kasuja loobus ser tifikaadi valikust

ERR_CSP_NODEFKEY_CONTAINER 94/ / Ei leitud vaikevõtme konteinerit

ERR_CONNECTION_FAILURE 95 / / Ühendus ebaõnnestus

ERR_WRONG_URL_OR_PROXY 96/ /Vale URL või proksi

ERR_NULL_PARAM 97/ / Kohustuslik parameeter oli NULL

ERR_BAD_ALLOC 98/ / Viga mäluhõlvamisel

ERR_CONF_FILE 99/ / Viga konfiguratsioonifaili avamisel

ERR_CONF_LINE

/ / Viga konfiguratsioonifailisERR_MAX

102

86

Page 87: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

/ / viimane kood omab ainult teegi sisest tähendus t

Kasutusel olevad keeled

DDOC_LANG_ENGLISH 0DDOC_LANG_ESTONIAN 1DDOC_NUM_LANGUAGES 2

OCSP päringu allkirjastamise tüübi identifikaatorid

OCSP_REQUEST_SIGN_PKCS12 5/ / OCSP päring allkirjas ta takse eeldusel, et

p rivaatne v ti ō/ / ja sertifikaat on PKCS #12 tüüpi konteineris.

Sertifikaatide otsingu kohad

Nende konsta tn tide kasutamise kohta saab infot näitest "Kuidas otsida sertifikaate"CERT_SEARCH_BY_STORE 1

/ / ser tifikaat loetakse MS Certificate Storest ehk Windowsi

/ / ser tifikaatide hoidlastCERT_SEARCH_BY_X509 2

/ / ser tifikaat loetakse PEM failistCERT_SEARCH_BY_PKCS12 3

/ / ser tifikaat loetakse PKCS#12 tüüpi konteinerist.

Sertifikaatide otsingu kriteeriumid

Nende konstantide abil saab juhtida ser tifikaatide otsimist Windowsi sertifikaatide hoidlast.CERT_STORE_SEARCH_BY_SERIAL 0x01CERT_STORE_SEARCH_BY_SUBJECT_DN 0x02

87

Page 88: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

CERT_STORE_SEARCH_BY_ISSUER_DN 0x04 CERT_STORE_SEARCH_BY_KEY_INFO 0x08

Toetatud kaartide nimed

Kasuta takse hetkel vaid teegi siseselt.EST_EID_CSP "EstEID Card CSP"EST_AEID_CSP "Gemplus GemSAFE Card CSP"EST_AEID_CSP_WIN "Gemplus GemSAFE Card CSP v1.0"

88

Page 89: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

CDigidoc kasutamine

Libdigidoc teegiga kaasneb väike käsureaprogram m – cdigidoc – mille abil saab kasutada ena must teegi funktsioonidest. Selle abil saate lugeda faile OpenXAdES for maadis, neid allkirjastada ja allkirju kontrollida.

Digiallkirjastamine1. Abiinfo ku vamine – “cdigidoc - help” või “cdigidoc - ?”

2. Uue dokum endi loomine – “cdigidoc - new [format] [version]”. Vaikeväärtused võetakse konfiguratsioonifailist. See käsk ei ole nõu tud. Kui kasutate näiteks - add käsku and mekogumi lisamiseks ja cdigidoc doku menti sessioonis ei ole siis luuakse see automaatselt.

3. Andmefaili lisamine – “cdigidoc - add < faili nimi > < m aimi - tüüp > [<sisu - tüüp >] [<tähestik >]”. Vaikeväärtused võetakse konfigura tsioonifailist.

4. Allkirjade kontrollimine – “cdigidoc - verify”

5. DigiDoc sisu ku vamine - “cdigidoc - in < d ocu ment > - list”

6. digidoc doku m endi luge mine – “cdigidoc - in < f aili nimi >”

7. digidoc doku m endi kirjutamine - “cdigidoc - out < faili nimi >”

8. Allkirjastamine – “cdigidoc - sign < pin > [<manifest >] [<linn > < m aakond > < p os tiindeks > < riik >]”. Vaikeväärtused võetakse konfigura tsioonifailist.

9. Andmefaili eraldi faili salvestamine – “cdigidoc - extract < d oc - id > < faili nimi > [<tähestik >] [<faili - nime - tähestik >]”.

Kirjeldatud käsklusi saab keeruka mateks käskudeks kombineerida. Näiteks:

• Loeme digidoc doku mendi failist ja kontrollime allkirju:

# cdigidoc -in <filename> -verify

• Loome uue digidoc doku mendi 1.1 formaadis, lisame PDF faili, allkirjastame, kontrollime tulemust ja salvestame u ude faili.

# cdigidoc -new DIGIDOC-XML 1.1 -add mydoc.pdf application/pdf -sign <pin> “Olen nõus” -out mydoc.ddoc -verify

• Loeme olemasoleva digidoc doku mendi failist, lisame oma allkirja, kontrollime tulemust ja salvestame uu de faili.

# cdigidoc -in mydoc.ddoc -sign <pin> “I reject this proposal!” -out mydoc2.ddoc -verify

• Loeme olemasoleva digidoc doku mendi failist ja salvesta me ühe and mefaili eraldi faili.

# cdigidoc -in mydoc.ddoc -extract D0 mydoc2.pdf

89

Page 90: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

Krüpteerimine ja dekrüpteerimine1. Krüpteerimine mälus – “cdigidoc - encrypt < sisendfail > - out

<väljundfail > - encrecv < f aili - vastuvõtjate - and med >”. See käsk teostab krüpteerimise m älus ja on effektiivne väiksemate failide p uhul. Teda ei saa kasutada ilma - encrecv käsuta, ses t m uidu tekiks fail mida keegi enam dekrüp teerida ei suuda. CDigiDoc kasutab ZLIB algoritmi and mete pakkimiseks enne krüpteerimist alati kui võimalik ja and mete m aht seetõt tu vähenes.

2. Vastu võtjate määramine – “cdigidoc - encrypt ... - encrecv < cer t -file > [<recipient >] [<keyname >] [<carried - key - na me >]”. Selle käsuga lisatakse ühe võimaliku väljudnfaili vastuvõtja / dekrüpteerija and med. Enamate vastuvõtjate p uhul tuleb kasutada seda käsku üks kord iga vastuvõtja jaoks. Vajalik on vaid vastuvõtja aut ten timis ser tifikaadi edastamine (parameeter < cer t - file >, PEM for maadis) ja cdgidoc jaoks ka < recipient > parameeter. Hetkel nimelt vajab cdigidoc seda para meetrid - decrypt käsus t ranspordivõtme identifitseerimiseks. GDigiDoc seda ei vaja. Viimased 3 parameetrdi on üldjuhul lihtsalt mingid nimetused mis omistatakse ühele vastuvõtjale / t ranspordivõtmele ja võimaldavad seda hiljem mitmete hulgast identifitseerida. Mitte ükski ei ole formaadiga nõutud. Vajalik on vaid vastuvõtja sertifikaat, kus on sam uti omaniku tunnus DN ja /või CN at ribuu tide näol. GDigiDoc kasutab viimast.

3. Dekrüpteerimine – “cdigidoc - decrypt < sisendfail > < pin1 > - out <väljundfail >”. Dekrüpteerib krüpteeritud faili ja kirjutab tulemuse väljundfaili. See käsk teostab dekrüp teerimise mälus ja on effektiivne väiksemate failide puhul. Kui and med olid enne krüp teerimist pakitud siis pakitakse nad automaatselt lahti.

4. Kuvamine - “cdigidoc - denc - list < k r ü p teeritud - sisendfail >”. Loeb sisse krüpteeritud faili (.cdoc) ja kuvab sisu (andmed, vastuvõtjad jms.) aga ei ürita faili dekrüpteerida. Teine võimalus on kasutada - list käsku, näiteks “cdigidoc - in < k r üp teeritud - sisendfail > - list”.

5. Suure faili krüpteerimine - “cdigidoc - encrypt - file < in - file - name > < o u t - file - na me > [<in - file - mime - type >] - encrecv ...”. Krüpteerib sisendfaili ühe või ena ma vastuvõtja jaoks ja kirju tab väljudnfaili. See käsk krüp teerib faili blokkide kaupa ja on effektiivne eriti suur te failide puhul aga ta ei paki and meid.

6. Suure faili dekrüpteerimine - “cdigidoc - decrypt - file < in - file -name > < o u t - file - name > < recipient - cert - cn > < pin1 >”. Dekrüp teerib sisendfaili ja kirjutab väljudnfaili. See käsk dekrüp teerib faili blokkide kaupa ja on effektiivne eriti suurte failide p uhul aga ta eeldab et and med ei ole ei pakitud.

Käsklused CGI reshiimisKäsureautiliiti cdigidoc on võimalik kasutada CGI p rogram mina digiallkirjasta mise lisamiseks veebisaitidele. Selleks saab kasutada järgmisi käsklusi:

90

Page 91: DigiDoc C-teegi kirjeldus koos kasutusjuhistega · DAS Eesti Digitaalallkirja Seadus ESTEID Eesti ID kaart CSP (ka MS CSP)Microsoft Crypto Service Provider ... DigiDocLib.c - peamine

1. Digiallkirja räsi arvutamine: “cdigidoc - calc - sign < cer t - file > [< manifes t >] [<city > < s ta te > < zip > < coun try >]". Allkirjastaja ser tifikaat peab olema PEM for maadis eraldi failis. Väljastab konsoolile allkirjastatava räsi base64 kujul, mida saaks järgnevalt allkirjastada näiteks Java appleti või ActiveX komponendiga.

2. RSA - SHA1 allkirja väärtuse lisamine: "cdigidoc - add - sign - value < sign - value - file > < sign - id > \ n". Allkirja väär tus peab olema base64 kujul eraldi failis.

3. Digiallkirja eemaldamine: "cdigidoc - del - sign < sign - id >"

4. Kehtivuskinnituse lisamine alkirjale: "cdigidoc - get - confirmation < sign - id >”

Käsureautiliidile cdigidoc lisati ka valik: - cgimode [<oupu t - separator] CGI reshiimis tulemuste väljastamiseks. Antud juhul väljastab cdigidoc tulemused CGI reshiimi jaoks sobivas formateeringus, kus iga info alamhulk on eraldatud teistes spetasiaalse eraldaja sü mboliga, mida ülalnimetatud valikuga m u uta saab. Vaikimisi kasuta takse eraldajat “ |”. Vaikimisi eraldaja sü mbolit saab määrata konfiguratsioonifailis kirjega:

DIGIDOC_CGI_SEPARATOR= < s ü mbol >.

Muud CGI reshiimiga seotud konfiguratsioonifaili kirjed on:

DIGIDOC_CGI_MODE=true / false – lülitab CGI väljastuse sisse / välja

DIGIDOC_CGI_PRINT_HEADER=true / false – lülitab päiseinfo kuvamise sisse /välja.

DIGIDOC_CGI_PRINT_TRAILER=true / false – lülitab jaluseinfo kuvamise sisse /välja.

91