(Rozhraní webových služeb a.net assembly) Technická dokumentace Vytvořeno dne: 26.6.2014 Aktualizováno: 24.1.2017 2014-2016 Software602, a.s.
Obsah Popis... 4 Úvod 4 Slovník pojmů... 5 Reference... 6 Technické požadavky... 6 Související požadavky... 7 Autorizace, Evidence a Ověření... 8 Analýza dokumentu... 8 Registrace dokumentu... 8 Aktualizace registrovaného dokumentu... 9 Zjištění stavu dokumentu... 9 Odregistrace dokumentu... 9 Dokumenty k občerstvení... 9 Přímé podepsání dokumentu... 9 Přímé opatření dokumentu časovým razítkem... 9 Konverzní a ostatní služby... 10 Konverze souboru do PDF či PDF/A (Print2PDF)... 10 Konverze souboru z URL adresy... 10 Konverze webové stránky do PDF nebo PDF/A souboru... 10 Konverze PDF do PDF/A... 10 Ověření shody s PDF/A... 10 Získání konverzních profilů... 11 Získání protokolu ověření podpisů v dokumentu... 11 Získání časového razítka... 11 Export textu z PDF s možností technologie OCR... 11 Přečtení obsahu čárových kódů v PDF souboru... 11 Generování čárových kódů do PDF nebo obrázku... 11 Generování platebních příkazů v QR kódu do PDF nebo obrázku... 11 2
Přidání přílohy k PDF souboru... 11 Komprese PDF souboru... 11 Zjištění aktuální verze... 12 Testovací metody služby... 13 Test konverze dokumentu... 13 Test OCR Engine... 13 Test Ověření formátu PDF/A... 13 Test Dostupnosti konverzních profilů... 13 Test funkčnosti služby pro práci s časovými razítky... 13 Test funkčnosti Webové služby... 13 Testování, TRIAL verze... 14 3
Popis Úvod Software602 je čistě serverovým softwarovým řešením pro vytváření a archivaci PDF dokumentů, které odpovídají mezinárodním normám a specifikacím požadavků pro dlouhodobé uchování elektronických originálů dokumentů. Nabízí rozhraní pro manipulaci s elektronickými podpisy nejen PDF dokumentů, ale také Microsoft Office dokumentů, strukturovaných XML dat a obecných CMS dat. Jeho prostřednictvím lze dokumenty elektronicky podepisovat, opatřovat kvalifikovanými časovými razítky a dlouhodobě uchovávat v souladu s normami CAdES, PAdES a XAdES. Toto technické řešení odpovídá svým pojetím a kvalitou požadavku na vytvoření služby vytvářející důvěru dle nařízení Evropského parlamentu a Rady (EU) č. 910/2014 o elektronické identifikaci a službách vytvářejících důvěru pro elektronické transakce na vnitřním trhu. Zejména pak pro službu ověřování platnosti kvalifikovaných elektronických podpisů a službu uchovávání kvalifikovaných elektronických podpisů. Pro svůj provoz potřebuje aktivní uživatelský účet na portálu LongTermDocs.eu, pomocí něhož využívá služby kvalifikovaných časových razítek, ověřovací služby po zjištění platnosti elektronických certifikátů a registrační služby pro metadata jednotlivých dokumentů a souborů určených k archivaci. Služby pro dlouhodobou ověřitelnost LTV a služby kvalifikovaných razítek TSA poskytuje SecuStamp.eu Díky těmto službám a možnostem aplikace Software602 je možné zajistit vznik či konverzi PDF dokumentu v archivním formátu PDF/A a zároveň zajistit jeho adekvátní zabezpečení elektronickým podpisem ve formátu PAdES pro zajištění jeho dlouhodobé ověřitelnosti autenticity a průkaznosti. SDK umožňuje integraci funkcí a operací nad dokumenty pomocí následujících rozhraní: Metody Webových služeb.net knihovny AdES_NET.dll a Software602.Converter.dll.NET knihovny jsou obsaženy po instalaci SDK v adresáři Engine. Rozhraní.NET metod je opatřeno komentáři ve formě.xml dokumentace. Většina metod.net Assembly má stejné rozhraní jako metody webových služeb, které jsou popsány níže. Díky tomu je snadná integrace do jiných informačních systémů, či webových aplikacích. 4
Obrázek 1: Integrace Software602 SDK do aplikací třetích stran Slovník pojmů PAdES elektronicky podepsané PDF dokumenty podle normy ISO-32000-1 nebo standardů rodiny PAdES PAdES Basic, PAdES-BES, PAdES-EPES a PAdES-LTV CMS, PKCS7, CAdES elektronicky podepsaná (interně i externě) obecná data ve formátu CMS/PKCS7/CAdES. Může se například jednat o podepsanou emailovou komunikaci, audio nebo video záznamy apod. Jedním z příkladů interně podepsaných dat podle CAdES jsou také Datové zprávy ISDS. XAdES elektronicky podepsané XML dokumenty podle standardů rodiny XAdES - ETSI TS 101 903 - Electronic Signatures and Infrastructures (ESI); XML Advanced Electronic Signatures (XAdES) PDF souborový formát pro ukládání dokumentů nezávisle na SW ani HW, na kterém byly pořízeny. Řízen normou ISO 32000-1:2008. PDF/A oficiální archivační verze souborového formátu PDF. Jedná se o zúžení definice formátu PDF tak, aby bylo možné soubory uložené v PDF/A otevřít beze ztráty informace i všemi budoucími verzemi softwarových nástrojů. Definována v standardech ISO 19005:1-2008 a ISO 19005-2:2011. Dokument podepsaný PDF dokument nebo jiná podepsaná data ISDOC Information System Document - formát elektronické fakturace v ČR ISDS Informační systém datových schránek OID Object Identifier CRL seznam odvolaných certifikátů vydávaný certifikační autoritou, certifikát se odvolává např. z důvodu ztráty nebo zcizení soukromého klíče 5
Grace perioda čas během kterého je podpis v dokumentu příliš čerstvý na to, aby se dal ověřit vůči CRL seznamu certifikační autority. Zpravidla to bývá 24 hodin. Po této době je již možné platnost elektronického podpisu jednoznačně vyhodnotit. Občerstvení občerstvení dokumentu znamená ověření předcházejících podpisových certifikátů, stažení CRL seznamů a dalších informací nutných pro případně pozdější ověření těchto podpisových certifikátů. Přiložení těchto informací k dokumentu a opatření dalším kvalifikovaným časovým razítkem. Reference ETSI TS 103 171 v2.2.1: "Electronic Signatures and Infrastructures (ESI); XAdES Baseline Profile" ETSI TS 103 173 v2.2.1: "Electronic Signatures and Infrastructures (ESI); CAdES Baseline Profile" ETSI TS 103 172 v2.2.2: "Electronic Signatures and Infrastructures (ESI); PAdES Baseline Profile" ETSI TS 103 174 v2.2.1: "Electronic Signatures and Infrastructures (ESI); ASiC Baseline Profile" ETSI TS 102 778-1: "Electronic Signatures and Infrastructures (ESI); PDF Advanced Electronic Signature Profiles;Part 1: PAdES Overview a framework document for PAdES" ETSI TS 102 778-2: "Electronic Signatures and Infrastructures (ESI); PDF Advanced Electronic Signature Profiles;Part 2: PAdES Basic Profile based on ISO 32000-1" ETSI TS 102 778-3: "Electronic Signatures and Infrastructures (ESI); PDF Advanced Electronic Signature Profiles;Part 3: PAdES Enhanced PAdES-BES and PAdES-EPES Profiles" ETSI TS 102 778-4: "Electronic Signatures and Infrastructures (ESI); PDF Advanced Electronic Signature Profiles;Part 4: PAdES Long Term PAdES LTV Profile" IETF RFC 3852 (2004): "Cryptographic Message Syntax (CMS)" IETF RFC 3161: "Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP)" Technické požadavky 64-bitový operační systém MS Windows Server 2008 R2 SP1 nebo Windows Server 2012 (R2) nebo Windows Server 2016 Dvou nebo vícejádrový procesor Webový Server (IIS) s ASP.NET a.net Framework 3.5 i 4.0 nebo vyšším Vzhledem k zajištění vysoké prostupnosti je vhodné zajistit adekvátní velikost operační paměti a rychlost komunikačních rozhraní. Pro správnou funkčnost SDK je také zapotřebí, aby server (popřípadě firewall, proxy, apod.) nebránil komunikaci s adresami: https://www.secustamp.com a https://wsc.secustamp.com Dále je třeba mít povolené adresy pro kontrolu revokace certifikátu serveru. Aktuálně se jedná o certifikáty vydané od thawte SSL CA - G2: tj.symcd.com:80 t1.symcb.com:80 t2.symcb.com:80 6
Související požadavky Aktivní uživatelský účet na portálu LongTermDocs.eu prostřednictvím kterého uživatel konzumuje konverzní služby a služby pro evidenci a dlouhodobou ověřitelnost dokumentu. Obrázek 2: Přehled operací nad dokumentem v procesu dlouhodobé archivace 7
Autorizace, Evidence a Ověření Sada metod webové služby pro zajištění autorizace, evidence a dlouhodobé ověřitelnosti dokumentu. Zprostředkovává uložení AdES metadat dokumentu na registračním Serveru, díky kterým je možné rychle ověřit, který dokument je třeba k danému datu občerstvit, či v jakém stavu se nachází konkrétní dokument. Analýza dokumentu Ověření stavu dokumentu a jeho formátu (zahrnuje ověření certifikátů elektronických podpisů, značek a časových razítek, jejich kontrolu vůči CRL listu, kontrolu neporušenosti hashe dokumentu). Ověření formátu elektronického podpisu. Pokud je analyzovaný dokument v pořádku, je možné jej přijmout k dlouhodobé archivaci a zajistit tak jeho digitální kontinuitu. Nejprve je třeba ověřit, zda jsou v případě daného dokumentu splněny podmínky pro jeho registraci na Server. K tomu slouží metoda ltvanalyze, jejímž výstupem pro uživatele jsou informace o dokumentu a jeho certifikátech. Z jejího výsledku lze učinit závěr, za jakých okolností lze provést operace pro zajištění dlouhodobé průkaznosti dokumentu. Registrace dokumentu Registrace dokumentu na Server, přidělení unikátního ID a AdES metadat dokumentu. Opatření dokumentu novým archivním časovým razítkem. Struktura podpisu dokumentu po registraci vyhovuje specifikaci PAdES, CAdES nebo XAdES. Do registrace - metoda ltvregister - může vstoupit dokument, který má alespoň jedno časové razítko nebo jeden podpis a časové razítko a zároveň uplynula tzv. grace perioda, kdy je možné ověřit, že certifikát podpisu nebyl revokován a je vydán důvěryhodnou autoritou a výsledek tohoto ověření je v pořádku. Jsou-li podpisy na dokumentu shledány platnými, připojí k nim proces registrace revokační data získaná při předchozí analýze dokumentu dojde k opatření dokumentu časovým razítkem. Následně se provede registrace metadat dokumentu na Server. Při registraci je dokumentu přiděleno unikátní ID a uživatel má možnost zvolit zatřiďovací informace. Z výše uvedeného vyplývá, že při požadavku na registraci dokumentu je nejprve provedena kontrola integrity dokumentu a kontrola podpisů metoda ltvanalyze. Pokud je dokument v pořádku, dojde k výpočtu hashe dokumentu a vyžádání časového razítka k tomuto hash. Zároveň je zaznamenán algoritmus výpočtu hashe. Žádost o časové razítko a odpověď žádosti je v souladu se specifikací RFC 3161. Po obdržení časového razítka je dokument podepsán, opatřen tímto časovým razítkem dle specifikace PAdES ETSI TS 103171 v.2.1.1 http://www.etsi.org/deliver/etsi_ts/103100_103199/103172/02.02.02_60/ts_103172v020202p.pdf CAdES ETSI TS 103173 v.2.2.1 http://www.etsi.org/deliver/etsi_ts/103100_103199/103173/02.02.01_60/ts_103173v020201p.pdf XAdES ETSI TS 103171 v.2.1.1 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf Odpovědí je evidenční číslo registrovaného dokumentu DocId. Software602 vytváří dokument v souladu s LTV požadavky na dlouhodobou ověřitelnost dokumentu. 8
Aktualizace registrovaného dokumentu Aktualizace dříve registrovaného dokumentu před vypršením posledního archivního časového razítka. Opatření dokumentu novým archivním časovým razítkem. Při aktualizaci dokumentu se vždy provede kontrola podpisových certifikátů dokumentu metodou ltvanalyze pro zajištění oprávněnosti další registrace dokumentu. Zjištění stavu dokumentu Funkce ltvgetinfo vrací informace o zadaném ID dokumentu, či skupině dokumentů, které vyhovují zadanému filtru. Struktura odpovědi definuje obsah výstupu z evidenčního Serveru. Dotaz je možné koncipovat na konkrétní ID, nebo jej vztáhnout na konkrétní datum exspirace dokumentu. Odregistrace dokumentu Každý dokument je možné z procesu dlouhodobé archivace vyjmout a odstranit tak informace o archiválii metodou ltvunregister. Dokumenty k občerstvení Slouží pro zjištění, které dokumenty je nutné občerstvit k zadanému datu. Výsledkem metody ltvgetforupdate je seznam ID dokumentů. Výpis je možné omezit jen na určitý počet dokumentů, řazeny jsou chronologicky. Zároveň je možné omezit výběr na vybranou archivační složku definovat zatřiďovací informaci pro filtrování selekce. Přímé podepsání dokumentu V případě potřeby pro podepsání dokumentu elektronickým podpisem bez vazby na archivaci. Je možné podepsat dokument pomocí funkce ltvsign. Cestu k certifikátu ve formátu PFX/PEM a přístupové heslo k němu je možné nastavit v souboru Web.config umístěném v adresáři WebService. Přímé opatření dokumentu časovým razítkem V případě potřeby pro opatření dokumentu elektronickým časovým razítkem bez vazby na archivaci. Je možné opatřit dokument časovým razítkem pomocí funkce ltvtimestamp. 9
Konverzní a ostatní služby Sada funkcí pro zajištění formátu dokumentu do standardního formátu PDF dle ISO 32000-1:2008 a archivního formátu PDF/A dle standardu pro dlouhodobou archivaci ISO 19005-1:2002, ISO 19005-2:2011 a ISO 19005-3:2012. Konverze souboru do PDF či PDF/A Webová služba umožňuje provést na serveru konverzi libovolného dokumentu do formátu PDF, či PDF/A podle definovaných požadavků v konfigurační struktuře požadavku. Je možné nastavit úroveň souladu se specifikací PDF/A, podepsání dokumentu elektronickou značkou, opatření kvalifikovaným časovým razítkem, opatření vodotiskem a další nastavení. Na serveru je nutné mít aplikaci, která umí přečíst formát konvertovaného souboru například pro dokumenty formátu *.docx aplikace Microsoft Word nebo Open Office. Více informací o požadavcích na aplikaci a nastavení pro konverzní služby najdete v dokumentu Příručka Administrátora (kapitola 8). Konverze souboru do PDF či PDF/A (Print2PDF) Webová služba umožňuje provést na serveru konverzi libovolného dokumentu do formátu PDF, či PDF/A podle zvoleného profilu konverze. Je možné nastavit úroveň souladu se specifikací PDF/A, podepsání dokumentu elektronickou značkou, opatření kvalifikovaným časovým razítkem, vodotiskem a další nastavení v rámci každého profilu. Tato metoda je určena hlavně pro zpětnou kompatibilitu s Print2PDF 9. Konverze souboru z URL adresy Jedná se o interní metodu pro komunikaci se spisovou službou. Webová služba umožňuje provést na serveru konverzi libovolného souboru ze zadané URL adresy do formátu PDF, či PDF/A podle definovaných požadavků v konfigurační struktuře požadavku a výsledný soubor nahrát na jiný server. Pro výsledný soubor je možné nastavit úroveň souladu se specifikací PDF/A, podepsání dokumentu elektronickou značkou, opatření kvalifikovaným časovým razítkem, opatření vodotiskem a další nastavení. Konverze webové stránky do PDF nebo PDF/A souboru Webová služba umožňuje konvertovat jakoukoli webovou stránku do PDF souboru. Pro vytvoření archivního PDF/A dokumentu s odkazovanými soubory (pdf, office, apod.) a zdrojovými soubory stránky (SSL certifikát, obrázky, apod.), je možné využít parametrů DownloadReferencedFiles a DoArchive. Konverze PDF do PDF/A Webová služba umožňuje převést PDF dokumentu do odpovídajícího PDF/A formátu. Formát PDF/A je definován v několika úrovních souladu. Tuto úroveň je možné nastavit a pokud PDF dokument neobsahuje neopravitelné chyby a neshody oproti zvolené úrovni souladu, bude převeden do formátu PDF/A. Ověření shody s PDF/A Formát PDF/A je definován v několika úrovních souladu. Tuto úroveň je možné nastavit a vůči ní bude dokument analyzován. 10
Získání konverzních profilů Webová služba umožňuje pracovat s předpřipravenými konverzními profily, které obsahují nastavení pro konverzi. Tyto profily jsou aktuálně dostupné v instalaci, možné ověřit pomocí metody GetProfileList. Získání protokolu ověření podpisů v dokumentu Webová služba umožňuje získat protokol ověření podpisů v dokumentu pomocí volání metody GetSignatureReport. Protokol ověření obsahuje přehled všech podpisů, vystavitelů certifikátů, jejich platnosti, ověřitelnosti a dalších informací ze zdrojového dokumentu. Získání časového razítka Webová služba umožňuje získat časové razítko ze serveru SecuStamp.eu pomocí volání metody GetTimeStamp. Metoda komunikuje se serverem SecuStamp.eu pomocí přihlasovacího jména a hesla nebo certifikátu. Export textu z PDF s možností technologie OCR Webová služba umožňuje exportovat text z libovolného dokumentu ve formátu pdf, umožňuje také scanování textu z obrázků pomocí OCR technologie. Tato metoda umožňuje skenovat více sekcí v jednom dokumentu. Přečtení obsahu čárových kódů v PDF souboru Webová služba umožňuje přečíst obsah čárových kódů typu QR, PDF417, DataMatrix a 1D. Metoda ReadBarcodeToString vrací jenom položku data z čárového kódu, metoda ReadBarcode vrací také jeho polohu a v případě 1D kódu i podtyp a checksum. Generování čárových kódů do PDF nebo obrázku Webová služba umožňuje generování 1D a 2D čárových kódů do obrázků a PDF souborů. Podporovány jsou QR, PDF417, DataMatrix a řada 1D kódů. Jako vstupní parametry jsou typ požadovaného kódu, data, velikost, umístění na stránce a číslo stránky. V případě specifických kódů je možno určit další parametry jako například kódování nebo chybovou korekci. Generování platebních příkazů v QR kódu do PDF nebo obrázku Webová služba umožňuje generování QR čárových kódů obsahujících data pro platební příkaz do obrázků a PDF souborů. Tyto QR kódy splňují standard ČBA pro sdílení údajů v rámci tuzemského platebního styku. Jako vstupní data metody jsou použité údaje o platebním příkazu, ze kterého pak webová služba vygeneruje QR kód a postará se o správné formátování. Přidání přílohy k PDF souboru Webová služba umožňuje přidat ke vstupnímu PDF souboru jakoukoli přílohu. Musí se specifikovat formát přílohy, její jméno a typ. Komprese PDF souboru Metoda pro kompresi PDF souboru. Komprimují se data v rámci PDF dokumentu, tak i vložené obrázky, jejich formát a rozlišení. 11
Zjištění aktuální verze Webová služba umožňuje zjistit verzi aktuálně nainstalovaného Long-Term a ověřit platnost licenčního certifikátu. 12
Testovací metody služby Označeny prefixem test. Slouží pro administrátora při instalaci a ověřování funkčnosti služby. Jejich výhoda spočívá v tom, že nemají žádné vstupní parametry, které by bylo nutné nastavovat a vracejí prostý řetězec. Pokud je služba spuštěna v internetovém prohlížeči na počítači, kde je služba nainstalována zpřístupní se tlačítko Vyvolat. Tím je generována odpovídající metoda testovací služby a zároveň dojde k zobrazení odpovědi. Test konverze dokumentu Testovací metoda, která ověří funkčnost konverzní služby a zároveň informuje o možnostech konverze jednotlivých formátů souborů. Převádí testovací soubory z adresáře TestFiles a vypíše výsledky konverze. Test Licence produktu Ověří správnou licenci instalovaného produktu Test OCR Engine Ověří, zda-li vaše verze obsahuje funkční verzi OCR Engine. Ověření probíhá na souboru Convert_htm.htm v adresáři /TestFiles. Testovací soubor je součástí instalace. Test Ověření formátu PDF/A Ověří správnou funkčnost PDF/A operací Test Dostupnosti konverzních profilů Ověří dostupnost konverzních profilů Test funkčnosti služby pro práci s časovými razítky Ověří správnou funkčnost služby, která zajišťuje komunikaci se serverem pro vydávání časových razítek dle protokolu RFC 3161 Test funkčnosti Webové služby Ověří správnou funkčnost komunikace s webovou službou 13
Testování, TRIAL verze Zde popisované metody webových služeb je možné integrovat do stávajících informačních systémů, či webových aplikací. TRIAL verzi pro přímé ověření implementace včetně kompletní dokumentace je možné získat zde: TRIAL verze produktu 14