ECR BRÁNA - ROZHRANÍ ECR OBÁLKA 2.0. Verze dokumentu: 1.1 Datum vzniku: Počet stran: 16

Transkript

1 ECR BRÁNA - ROZHRANÍ ECR OBÁLKA 2.0 Zhotovil: Častorál Radek Verze dokumentu: 1.1 Datum vzniku: Počet stran: 16

2 Verze dokumentu Změny 1.0 Úvodní verze určená pro implementátory 1.1 Popis ECR obálky v kapitole 2.3 v sekci Chyba opraven do souladu s XML schématem. V dokumentu nebyl popis chyby zanořen do elementu PopisChyby a nebyly popsány některé volitelné XML uzly. V souladu s tím doplněn text kapitoly

3 1. Úvod ECR brána je systém, který od roku 2002 slouží ke komunikaci celní správy s externími subjekty, převážně s deklaranty. Systém byl průběžně rozšiřován a modernizován, aby pružně reagoval na potřeby celní správy. K jeho zásadní modernizaci došlo v průběhu roku 2008 s cílem použít novou integrační platformu a aplikovat dlouholeté zkušenosti s provozem do samotného jádra ECR brány. Součástí rozšíření byly i dvě podstatné úpravy, které rozšiřují možnosti funkce směrem k deklarantům. Jednou z nich je použití moderních a standardizovaných zabezpečovacích standardů XML signature a XML encryption a druhou úprava ECR obálky tak, aby snáze splňovala různorodé potřeby zastřešovaných celních agend. Těmto dvěma změnám je věnován tento dokument. Současně ale zůstávají v platnosti všechny předchozí dokumenty vztahující se k rozhraní ECR obálky 1.5 a k zabezpečení formou SMIME podepisování a šifrování. K existujícím agendám ECR brána plně podporuje pro zpětnou kompatibilitu rozhraní 1.5, ale u nově vznikajících agend už bude vyžadováno rozhraní 2.0. Stejná pravidla platí pro využívání mechanizmů zabezpečení datových výměn.

4 2. Komunikační zpráva ECR obálka 2.0 ECR obálka je hlavní komunikační zpráva na ECR bráně 2.0 a slouží k zapouzdřování informací o přenášené zprávě, které jsou důležité pro její správné nasměrování na serverovou aplikaci, ověření zabezpečení a pro sledování jejího toku systémem. Veškerá data určená pro průchod ECR bránou musí být do této obálky zapouzdřena. Pro všechny elementy ECR obálky 2.0 je přiřazený jmenný prostor Změny proti verzi 1.5 Hlavní zpráva používaná ECR bránou byla původně navržena pro použití ve dvou vybraných režimech. Obsahuje proto některé režimově specifické údaje a na druhou stranu neumožňuje případné rozšíření o elementy využitelné v agendách nově zaváděných. V rámci změn ECR brány se ukázalo jako maximálně účelné rozvinout definici rozhraní na novou obecnější verzi. Původní ECR brána informovala o chybových stavech pomocí dvou zpráv ChybaVAN a CZ907A. Důvody pro toto dvojí informování se postupně stíraly a v nové verzi je použit již jednotný způsob vracení chyby formou oddílu v ECR obálce. Pro zpětnou kompatibilitu je zajištěno generování původních zpráv. Hlavní změny ECR obálky proti verzi 1.5 jsou následující: - Odstraněny režimově vynucené atributy (např. JmenoSouboru pro ECRFTP) a nahrazeny volnější strukturou atributů zprávy. <Zprava><Atributy><Atribut Nazev="JmenoSouboru" Hodnota="soubor" - Uvolněna sekce Ucastnici tak, aby mohl být počet účastníků větší než doposud podporovaní 3. <Ucastnici><Ucastnik Role="deklarant" Identifikator="05CZ " GuidScenare="" DatumCas="" AplikaceID="dd" AplikaceVerze="1.0 - Umožněno používání XML signature. - Umožněno používání XML encryption. - Lze přidat i atributy, které nejsou v době nynějšího návrhu známy. - Přidána část pro podporu hlášení o chybě. - Původní element <Zprava> rozdělen do dvou <Hlavicka> a <Zprava> podle toho, zda se informace týkají obálky nebo přenášené zprávy Systém kontrol Na příchozí ECR obálku jsou aplikovány kontroly specifické dle komunikační domény. Patří mezi ně zejména: - Kontrola proti XML schématu ECR obálky pro konkrétní doménu. - Logická kontrola vyplňování ECR obálky proti přenášeným datům. - Logická kontrola vyplněných údajů proti registrům komunikačních subjektů. - Rozšifrování a ověření zaručeného elektronického podpisu. Dále popsaný způsob vyplňování je obecně platný, nicméně pro jednotlivé komunikační domény může být zúžen a zpřísněn.

5 2.3. ECR obálka 2.0 Základní přehled o možných elementech ECR obálky dává následující tabulka. Hlavicka Název elementu XML typ Datový typ Povinnost vyplňování směrem do ECR brány Povinný Povinnost vyplňování směrem z ECR brány Povinný GuidObalky Atribut UUID Povinný Povinný VerzeObalky Atribut string[10] Povinný Povinný Domena Atribut string[20] Povinný Povinný Zprava Povinný Povinný Typ Atribut string[30] Povinný Povinný HlavniID Atribut string[40] VedlejsiID Atribut string[40] Atributy Atribut [1-n] [1-n] Nazev Atribut string[20] Povinný Povinný Hodnota Atribut string[256] Povinný Povinný Popis s informacemi o obálce. Unikátní identifikátor jednoznačně určující právě jednu instanci ECR obálky. Označení verze ECR obálky. Jméno komunikační domény (agendy), pro kterou je určena datová výměna. s informacemi o přenášené zprávě. Jméno přenášené zprávy, typicky je jím kořenový element obalovaného XML. Hlavní identifikátor přenášené zprávy. Vedlejší identifikátor přenášené zprávy. Seznam doplňkových atributů. Doplňkový atribut. Název doplňkového atributu. Hodnota doplňkového

6 atributu. RozsireneInformace Atribut Ucastnici Ucastnik [1-n] [1-n] Nazev Atribut string[20] Povinný Povinný Hodnota Atribut string[256] Povinný Povinný Povinný Povinný [1-n] Povinný Povinný [1-n] Role Atribut string[20] Povinný Povinný Identifikator Atribut string[40] GuidScenare Atribut UUID DatumCas Atribut datetime AplikaceID Atribut string[50] AplikaceVerze Atribut string[20] Místo, kam lze uložit další dodatečné informace. Doplňkový atribut. Název doplňkového atributu. Hodnota doplňkového atributu. Seznam stran, které se účastní datové výměny (např. deklarant, VAN operátor, GŘC atd.). Komunikační strana. Role komunikační strany (deklarant, VAN, zástupce, PVS, VVAN, GRC) v předem definovaných řetězcích. Jednoznačný identifikátor komunikující strany. Označení scénáře v rámci agendy komunikující strany. Datum a čas průchodu obálky agendou komunikující strany. Označení aplikace, která se o průchod komunikující stranou stará. Označení verze aplikace, která se o průchod komunikující

7 stranou stará. SMIMEZprava string pro umístění přenášené zprávy v SMIME formátu. XMLZprava pro umístění přenášené zprávy v XML formátu. SignatureContext Atribut string[15] Výčtový typ určující rozsah prováděného zaručeného elektronického podpisu. Může nabývat hodnot "envelope" (výchozí hodnota) a "datacontent". Data obsahuje XML data v otevřeném tvaru. EncryptedData obsahuje XML data v šifrovaném tvaru dle doporučení W3C - XML encryption. Signature Umístění informací o elektronickém podpisu dle doporučení W3C - XML signature. BinarníZprava pro umístění přenášené binární zprávy kódované jako base64 SignatureContext Atribut string[15] Výčtový typ určující rozsah prováděného zaručeného elektronického podpisu. Může nabývat hodnot "envelope" (výchozí hodnota) a "datacontent".

8 Data string EncryptedData Signature Chyba Nesmí být PopisChyby obsahuje binární data v kódování base64. obsahuje binární data v šifrovaném tvaru dle doporučení W3C - XML encryption. Umístění informací o elektronickém podpisu dle doporučení W3C - XML signature. Pokud při zpracování došlo k chybě, budou zde umístěny příslušné informace. Kod Atribut int Nesmí být Povinný Číselný kód chyby. GuidPuvodniObalky Atribut UUID Nesmí být TypChyby Atribut string[20] Nesmí být Povinný Obsahuje GUID původní obálky, ke které se chyba vztahuje, pokud jí je možné načíst. Označení typu chyby, resp. zdroje chyby. Popis Atribut string[256] Nesmí být Popis chyby. Data string Nesmí být Signature Nesmí být Hlavicka Pokud je to k popisu chyby nutné, jsou zde uvedena data chyby. Umístění informací o elektronickém podpisu dle doporučení W3C - XML signature pro element hlášené chyby Tento element je povinný a obsahuje hlavní informace o agendě a datové výměně. Každá instance ECR obálky musí mít vygenerovaný unikátní GUID (UUID) identifikátor v atributu GuidObalky, uvedenou komunikační doménu v atributu Domena a

9 uvedenou identifikaci verze obálky, což je v současné době konstanta 2.0 v atributu Verze Zprava Tento povinný element zapouzdřuje informace o konkrétní přenášené zprávě nebo datové výměně. Udává se Typ datové výměny, což je u XML komunikací zpravidla jméno kořenového elementu přenášené zprávy. Dále se uvádí volitelně až dva identifikátory z přenášené zprávy, které mohou mít význam pro směrování zprávy. Způsob vyplňování elementů HlavniID a VedlesiID je určen doménou a typem výměny, nicméně ve většině domén se požaduje uvedený alespoň jeden z těchto identifikátorů. V některých případech je nutné uvádět v obálce ještě další atributy a pro ně je určena volitelná struktura Atributy/Atribut RozsireneInformace Tento nepovinný element je v současné době nepoužíván a rezervován pro případná rozšíření ECR obálky v budoucích doménách Ucastnici Povinný element obsahuje informace o všech zúčastněných komunikačních partnerech. Každý zúčastněný komunikační partner musí pro průchodu zprávy jeho systémem přidat jeden podelement Ucastník a uvést svoji roli do atributu Role, svoji identifikaci do atributu Identifikator, datum a čas průchodu zprávy jeho systémem do atributu DatumCas a informace o programovém modulu, který obálku zpracovával, do atributů AplikaceID a AplikaceVerze. Tři nejčastější současné role jsou deklarant (vyplní deklarant, resp. jeho SW), operator (vyplní např. VAN operátor) a grc (vyplní ECR brána). Dále se dle komunikačních mechanizmů mohou vyskytnout i role vvan a pvs. Všechny role kromě grc musí povinně vyplnit všech 5 atributů kromě volitelného GuidScenare, což je GUID, u něhož ECR brána zaručuje, že ho v nezměněné podobě vrátí v odpovědi ve stejné sekci. ECR brána vyplňuje pouze roli a datum a čas a volitelně dle domény identifikaci scénáře. V odpovědi ECR brány se všechny sekce vracejí, neuvádí se však u nich zpravidla již informace o programovém modulu Datový přenášený obsah Příchozí ECR obálka musí obsahovat právě jeden z elementů SmimeZprava, XmlZprava nebo BinarniZprava. V těchto elementech je samotný přenášený datový obsah SmimeZprava Je udržován pro zpětnou kompatibilitu a obsahuje stejný obsah jako v případě starší ECR obálky 1.5. Pro nové domény již není tento způsob komunikace podporován XmlZprava se uvede, mají-li přenášená data formát XML. Ta jsou pak přímo vložena jako podelement elementu Data. Zde je důležité je oddělit jiným jmenným prostorem nebo

10 uvedením prázdného, aby nebyla interpretována v kontextu jmenného prostoru ECR obálky. Mají-li být data šifrována, umístí se do struktury XML encryption do elementu EncryptedData. Do elementu Signature je možné uvést zaručený elektronický podpis. Obsah elementů EncryptedData a Signature je určen doporučeními W3C a popsán v kapitole BinarniZprava se uvede, mají-li přenášená data binární nebo jinou než XML povahu. Ta jsou pak přímo zakódovaná v base64 jako textová hodnota elementu Data. Mají-li být data šifrována, umístí se do struktury XML encryption do elementu EncryptedData. Do elementu Signature je možné uvést zaručený elektronický podpis. Obsah elementů EncryptedData a Signature je určen doporučeními W3C a popsán v kapitole Chyba Tento element nesmí být uveden v příchozí zprávě. Je vždy generován ECR bránou a informuje o některém z problémů, ke kterým může při příjmu, ověřování a kontrole zprávy dojít. Odpovídá-li ECR brána zprávou ECR obálka 2.0 s uvedeným elementem Chyba, není uveden žádný z datových elementů z kapitoly má vždy na svém podelementu PopisChyby uveden číselný Kod chyby a její zdroj TypChyby. Volitelně může být přítomen atribut GuidPuvodniObalky, jenž odkazuje na identifikaci ECR obálky, k níž je chyba hlášena. Rovněž volitelně je obsažen Popis chyby a u některých chyb i další doprovodná informace v podobě chybných dat v textovém elementu Data. U agend, které vyžadují opatření chybových zpráv zaručenou elektronickou značkou (chyba je právně závaznou zprávou), je tato značka přítomna v elementu Signature a strukturou odpovídá kapitole Seznam chyb, které může ECR brána aktuálně vracet, je uveden v kapitole 4.

11 3. Formáty zabezpečení dat ECR obálky 3.1. Šifrování Šifrování v ECR obálce se plně řídí doporučením W3C XML Encryption ( Je-li datový obsah šifrován, použije se jako vstup pro XML encryption element Data. Ten je následně nahrazen elementem EncryptedData už ve jmenném prostoru příslušného W3C doporučení. Příklad použitého šifrování je na následujícím zkráceném XML fragmentu: <XmlZprava> <EncryptedData Type=" xmlns=" <EncryptionMethod Algorithm=" cbc" <KeyInfo xmlns=" <EncryptedKey xmlns=" <EncryptionMethod Algorithm=" <KeyInfo xmlns=" <X509Data> <X509IssuerSerial> <X509IssuerName>CN=VM-BTS CA, OU=Technologie, O=Aquasoft s.r.o., L=Prague, S=Czech Republic, C=CZ</X509IssuerName> <X509SerialNumber> </X509SerialNumber> </X509IssuerSerial> </X509Data> </KeyInfo> <CipherData> <CipherValue>RkSilm7TlI2Nzc+Y+OVm+2KT0WoQtB7wky+aAtfowWxecq+9jV /huxtq80ddmht9oovueh1uja1oa1norrzsta==</ciphervalue> </CipherData> </EncryptedKey> </KeyInfo> <CipherData> <CipherValue>Yg82r6P+QvWTYhujTR0NWm4AoRvbXEi6Oc6pTw+4zFM3c0MeA hz+. AD7GHNDIgMPVS6fqfwkUifoEgJgmJFrVEcc27I3fQvYj7p5Z99iOV7GaYVVJes +GrO/UbaIQ==</CipherValue> </CipherData> </EncryptedData> </XmlZprava>

12 3.2. Zaručený elektronický podpis Zaručený elektronický podpis se v ECR obálce plně řídí doporučením W3C XML Signature ( Použití zaručeného elektronického podpisu nad otevřeným XML přináší jako výhodu fakt, že - pokud nejsou šifrována jsou data čitelná. To usnadňuje případné dohledávání problémů. Při používání XML signature je nutné mít na paměti zejména následující fakta: 1) Je vždy nutné provést kánonizaci XML a uvést ji ve struktuře podpisu. 2) Předmětem podpisu je vždy element SignatureInfo, který obsahuje miniaturu (SHA5 hash) podepisovaného dokumentu. 3) Znaky typu mezera, tabulátor a formátování konce řádku jsou pro XML signature významnými znaky, kanonizace je neodstraňuje a jejich změna vede na porušení podpisu. Mezi procesem podepsání zprávy a ověření podpisu tedy nesmí dojít například k přeformátování XML. 4) Pojmenování jmenných prostorů a jejich hodnoty jsou pro XML signature významnými znaky, kánonizace s nimi nijak nepracuje a nesmí být měněny. Je také nutné vést v patrnosti, že přidání pojmenovaného jmenného prostoru se promítne v DOM reprezentaci do všech podřízených, které tento jmenný prostor zdědí, a to může narušit podpis, přestože nadřazený element nebyl předmětem podpisu. V ECR bráně je vždy předlohou pro výpočet miniatury samotná přenášená zpráva uvnitř elementu Data, nikoliv element Data samotný. Součástí zaručeného elektronického podpisu musí být i veřejná část certifikátu použitelná pro ověření. Z pohledu doporučení W3C podporuje ECR brána následující typy XML signature: Typ Enveloping Tento typ znamená, že přenášená zpráva není umístěna jako potomek elementu Data (ten zůstává prázdný), ale je obsažena přímo jako definovaný objekt uvnitř struktury Signature, která je potomkem elementu XmlZprava nebo BinarniZprava. Při tomto použití nemusí být předepsána žádná transformace, ale výsledek nelze šifrovat, protože došlo v přemístění dat. Příklad uvádí následující fragment: <XmlZprava> <Data <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" <SignatureMethod Algorithm=" <Reference URI="#dataID"> <DigestMethod Algorithm=" <DigestValue>59vhtCKrP1oxMOgWl+YOMexcOwQ=</DigestValue> </Reference> </SignedInfo>

13 <SignatureValue>cw55CRsMlzP+h/ihf4g9CQHq+vR8KMq+WefYV0XDVhgS9uOgq lsavthzlrjuz25ufpbjy9slvkqtrbkktauyga==</signaturevalue> <KeyInfo> <X509Data> <X509Certificate>MIIE+../ISwJKV7</X509Certificate> </X509Data> </KeyInfo> <Object Id="dataID"> <CZ384A xmlns=""> <AOSD> <AOSD01>08CZ JZUV4J2D17</AOSD01> </AOSD> </CZ384A> </Object> </Signature> </XmlZprava> Typ Enveloped, mimo zprávu, SignatureContext = envelope Tento typ znamená, že je podpis vytvořen v kontextu celé ECR obálky (v době podpisu již byla sestavena) a element Signature je umístěn jako potomek elementu XmlZprava nebo BinarniZprava. Vždy musí být uvedena transformace enveloped-signature a xpath, která určuje cestu k podepisovaným datům. <XmlZprava> <Data> <CZ384A xmlns=""> <AOSD> <AOSD01>08CZ JZUV4J2D17</AOSD01> </AOSD> </CZ384A> </Data> <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" <SignatureMethod Algorithm=" <Reference URI=""> <Transforms> <Transform Algorithm=" <Transform Algorithm=" <XPath xmlns:parns="

14 r-or-self::cz384a[/parns:ecrobalka/parns:xmlzprava/parns:data/cz384a =.]</XPath> </Transform> </Transforms> <DigestMethod Algorithm=" <DigestValue>QKp4Lv7MzQ69wEVxcgA/EPXd18o=</DigestValue> </Reference> </SignedInfo> <SignatureValue>coZcE+3q/xzoiQz3AKIuoGtWQC4zkW8MEd3Ppui5QgMKlFy EjMG8uW+4rebs2Z9/UDtE04fOW12T4Oxh7PN4mw==</SignatureValue> <KeyInfo> <X509Data> <X509Certificate>MIIE+jCCBGO./ISwJKV7</X509Certificate> </X509Data> </KeyInfo> </Signature> </XmlZprava> Typ Enveloped, mimo zprávu, SignatureContext = datacontent Princip tohoto podpisu je stejný jako v případě s tím rozdílem, že při podpis vznikl nad přenášenou zprávou, která nebyla ještě vložena do ECR obálky. Stejný postup se pak musí aplikovat při ověřování podpisu. Protože toto není výchozí nastavení atributu SignatureContent, musí být na elementu XmlZpráva uveden. <XmlZprava SignatureContext="datacontent"> </XmlZprava> Typ Enveloped, uvnitř zprávy, SignatureContext = envelope Tento typ znamená, že je podpis vytvořen v kontextu celé ECR obálky (v době podpisu již byla sestavena) a element Signature je umístěn jako potomek kořenového elementu podepisované zprávy. Vždy musí být uvedena transformace enveloped-signature. <XmlZprava> <Data> <CZ384A xmlns=""> <AOSD> <AOSD01>08CZ JZUV4J2D17</AOSD01> </AOSD> <Signature xmlns=" <SignedInfo> <CanonicalizationMethod Algorithm=" <SignatureMethod Algorithm=" <Reference URI=""> <Transforms>

15 <Transform Algorithm=" </Transforms> <DigestMethod Algorithm=" <DigestValue>FXHzwKRRyvE1IV5BrWqNXxZy/MA=</DigestValue> </Reference> </SignedInfo> <SignatureValue>DeECqDL1FfRAnSR6EMyrwF3b8EpiFDGvBW+6DwK0S2PCz gjahoqdjeg76hpqtzvatskgqreorrzn2g1lyjygjg==</signaturevalue> <KeyInfo> <X509Data> <X509Certificate>MIIE+jCCBGOgAwIBA../ISwJKV7</X509Certificate> </X509Data> </KeyInfo> </Signature> </CZ384A> </Data> </XmlZprava> Typ Enveloped, uvnitř zprávy, SignatureContext = datacontent Princip tohoto podpisu je stejný jako v případě s tím rozdílem, že při podpis vznikl nad přenášenou zprávou, která nebyla ještě vložena do ECR obálky. Stejný postup se pak musí aplikovat při ověřování podpisu. Protože toto není výchozí nastavení atributu SignatureContent, musí být na elementu XmlZpráva uveden. <XmlZprava SignatureContext="datacontent"> </XmlZprava> 3.3. Kombinace zaručeného elektronického podpisu a šifrování Při kombinaci obou zabezpečení se nejprve provede vytvoření zaručeného elektronického podpisu a následně se provede šifrování elementu Data. V tomto případě nelze použít typ XML Signature popsaný v kapitole 3.2.1, protože by data uvnitř elementu Signature ve výsledku nebyla zašifrována. Při zpracování příchozí zprávy se postupuje obráceně, nejprve se dešifruje a u výsledku ověří podpis.

16 4. Příloha A číselník chyb odesílaných ECR bránou Kód Text chyby 0 Invalid incomming XML 1 Internal server error 2 Invalid incomming XML message type 3 Message domain is not valid 4 ID for declarant is unknown 5 VAN operator $ is not allowed for domain $ 6 At least primary or secondary identifier have to be filled in 7 Message $ is not allowed to pass through in the domain $ 11 Load from MIME failed in the $ phase. 12 Decrypt SMIME/XML failed with: $ 13 Verify sign SMIME/XML failed due to an incorrect sign format with: $ 14 Verify sign SMIME/XML failed due to message changes Verify sign SMIME/XML failed due to the incorrect certificate chain or certificate revocation. Certificate number: $ Verify sign SMIME/XML failed due to the unauthorized certificate. Certificate number: $ 17 Decoding base64 in MIME failed in the $ phase. 18 Incorrect data security found: $ 53 XML schema general validation error 54 Invalid child element 55 Incomplete content 56 Value too short 57 Value too long 58 Invalid datatype 59 Pattern constraint failed 60 Attribute missing 70 Primary identifier is not equal to inner message 71 Secondary identifier is not equal to inner message 72 Message type is not equal to inner message 73 Unable to perform inner XML controls in order to incomplete inner message