Specyfikacja interfejsów usług Jednolitego Pliku …

1 I Specyfikacja interfejs w us ug Jednolitego Pliku Kontrolnego Ministerstwo Finans w Departament Informatyzacji 29 lipca 2016 Wersja ii Zmiany Data Wersja Opis Opublikowanie specyfikacji technicznej us ug Jednolitego Pliku Kontrolnego. 1. Zmiana metody dzielenia spakowanego Pliku z metody TAR na binarne dzielenie Pliku SPLIT. 2. Metoda Status: - zmiana zwracanej zawarto ci dla kodu http: 200 i 400 3. Metoda InitUploadSigned w przypadku kodu http: 200 - zmiana typu dla w a ciwo ci TimeoutInSec z Timespan na int 4 Zmiany schematu XSD Pliku metadanych: - dodanie typu dokumentu JPKAH (JPK ad hoc) dla plik w przys anych w ramach kontroli, - poprawienie nazwy (liter wka) EncrypionKey na EncryptionKey, - poprawienie formatu wersji REST API, - poprawienie formatu nazwy Pliku , - dodanie ca kowitej liczby cz ci podzielonego Pliku oraz liczby porz dkowej dla poszczeg lnych cz ci, - usuni cie atrybut w type oraz mode z listy plik w cz stkowych FileSignatureList, - dodanie elementu (Packaging) w li cie plik w cz stkowych FileSignatureList wraz z mo liwo ci wyboru rodzaju podzia u i kompresji Pliku .

2 Obecnie mo liwe jest u ycie kompresji zip (deflate) z podzia em binarnym - element SplitZip z atrybutami type (split) oraz mode (zip), - dodanie elementu Encryption w li cie plik w cz stkowych FileSignatureList wraz z mo liwo ci wyboru algorytmu szyfrowania. Obecnie wykorzystanie algorytmu AES256 - element AES z atrybutami size (256), block (16), mode (CBC), padding (PKCS#7) oraz elementem IV (Initialization Vector) z atrybutami bytes (16) i encoding (Base64). Zmiany schematu XSD Pliku metadanych: - ustalenie obs ugiwanej wersji REST API - , - zmiana wyra enia regularnego elementu FileName. - uzupe nienie zbioru kod w odpowiedzi dla metody Status 1. Dodanie opisu specyfikacji szyfrowania klucza szyfruj cego. 2. Zmiana w opisie interfejs w - przet umaczenie komunikat w na j zyk polski. 3. Dodanie identyfikatora dania (RequestId) w strukturze odpowiedzi dla kodu http: 400 i 500 4. Rozszerzenie zbioru kod w odpowiedzi b d w (400 Bad Request) metody InitUploadSigned.

3 5. Dodanie informacji o dopuszczalnych transformacjach dla podpisu metadanych. 6. Ograniczenie d ugo ci warto ci funkcji skr t w w schemacie XSD Pliku metadanych. iii Data Wersja Opis 1. Rozszerzenie zbioru kod w odpowiedzi b d w (400 Bad Request) metody InitUploadSigned. 2. Dodanie przyk ad w prawid owych odpowiedzi inicjowania sesji metod InitUploadSigned. 3. Zamieszczenie przyk ad w wykorzystania narz dzi programistycznych SDK metody Put Blob. 4. Dodanie informacji o parametrze umo liwiaj cym w czenie weryfikacji podpisu z certyfikatem kwalifikowanym przy inicjowaniu sesji metod InitUploadSigned na rodowisku testowym. 1. Doprecyzowanie mechanizmu kompresji ZIP. iv Spis tre ci 1 Przygotowanie danych JPK .. 5 Przygotowanie dokument w JPK .. 5 Kompresja danych JPK .. 7 Szyfrowanie danych JPK .. 7 Przygotowanie metadanych uwierzytelniaj cych .. 8 2 Specyfikacja interfejsu przyjmuj cego dokumenty JPK dla klient w .. 9 Wst p.

4 9 Opis interfejsu .. 9 InitUploadSigned .. 109 Put Blob .. 2221 FinishUpload .. 2522 Status .. 2724 5 1 Przygotowanie danych JPK Przygotowanie dokument w JPK Dane JPK przygotowywane b d po stronie klienta (np. systemu ERP) w formie plik w XML zgodnych ze schematem XSD opublikowanym przez Ministerstwo Finans w na stronie w sekcji "Struktury JPK" w bloku "Pliki do pobrania". Ka dy z dokument w opisanych w a ciwym schematem ma stanowi osobny plik XML. Wygenerowany plik XML powinien by zakodowany w UTF-8. Przygotowanie dokument w JPK do wys ania odbywa si zgodnie ze schematem zamieszczonym poni ej: 6 Klient generuje jednorazowy klucz szyfruj cy 256-bitowy We kolejny wygenerownay dokument JPKS kompresuj plik metod ZIPP odziel utworzone archiwum na cz ci o rozmiarze max 60 MB zgodnie z narz dziem SPLIT (prosty podzia binarny)Zaszyfruj ka d z utworzonych cz sci archiwum algorytmem AES 256 przy u yciu klucza wygenerowanego w kroku to ostatni dokument JPK?

5 NieKoniecTakPolicz warto funkcji skr tu SHA256 (do wykorzystania w daniu uwierzytelniaj cym)Policz warto funkcji skr tu MD5 I zakoduj j w Base64 7 Rysunek 1 Schemat blokowy krok w przygotowywania do wysy ki danych JPK Kompresja danych JPK Wygenerowany dokument JPK zostanie skompresowany do Pliku w formacie ZIP oraz podzielony binarnie na cz ci o wielko ci nie przekraczaj cej 60 MB. Nale y spodziewa si wysokiego stopnia kompresji co spowoduje, e scenariusz w kt rym b dziemy mieli wi cej ni jedn cz , b dzie stosunkowo rzadki. Wymagana metoda kompresji to format Pliku ZIP z u yciem algorytmu DEFLATE, bez stosowania opcji dzielenia (split/multipart). W wyniku kompresji powinien powsta jeden plik ZIP zawieraj cy pojedynczy dokument JPK. Je eli rozmiar otrzymanego Pliku ZIP przekracza 60MB, nale y go podzieli binarnie na odpowiedni liczb cz ci o wielko ci 60MB ka da oraz ostatni cz o rozmiarze nie wi kszym ni 60MB.

6 Takie podej cie z jednej strony zapewnia wykorzystanie znanych i powszechnie stosowanych narz dzi oraz atwo implementacji dla r nych platform, z drugiej efektywno , w szczeg lno ci operacji kompresji i prostot API dla tych operacji. Szyfrowanie danych JPK Skompresowane pliki b d szyfrowane. Do szyfrowania plik w wykorzystany b dzie algorytm AES256, z kluczem szyfruj cym wygenerowanym po stronie klienta. W implementacji mechanizmu szyfrowania nale y u y nast puj cej specyfikacji algorytmu AES: D ugo klucza Key Size 256 bits / 32 bytes Tryb szyfru Cipher Mode CBC (Chain Block Chaining) Dope nienie Padding PKCS#7 Rozmiar bloku Block Size 16 bytes Wektor inicjuj cy Initialization Vector 16 bytes Algorytm procesu szyfrowania b dzie wygl da nast puj co: klient generuje losowy, 256 bitowy klucz, wygenerowanym kluczem szyfrowane s wszystkie cz ci skompresowanego archiwum (zgodnie z pkt. ) - algorytmem szyfruj cym jest AES256.

7 Klucz szyfruj cy jest szyfrowany z wykorzystaniem algorytmu asymetrycznego RSA, z wykorzystaniem certyfikatu klucza publicznego udost pnionego przez Ministerstwo Finans w, 8 zaszyfrowany klucz jest do czany do Pliku metadanych, zgodnie z przedstawionym poni ej opisem tego Pliku . Szyfrowanie klucza szyfruj cego Szyfrowanie klucza szyfruj cego nale y wykona algorytmem asymetrycznym RSA z wykorzystaniem certyfikatu klucza publicznego udost pnionego przez Ministerstwo Finans w. W implementacji mechanizmu szyfrowania nale y u y nast puj cej specyfikacji algorytmu RSA: D ugo klucza Key Size 256 bits / 32 bytes Tryb szyfru Cipher Mode ECB (Electronic Codebook) Dope nienie Padding PKCS#1 Rozmiar bloku Block Size 256 bytes Przygotowanie metadanych uwierzytelniaj cych Po przygotowaniu zasadniczych dokument w zgodnych ze schematem Jednolitego Pliku Kontrolnego (JPK), klient, w celu wys ania danych, musi przygotowa dane uwierzytelniaj ce, maj ce posta odpowiedniego XML, przes ane w metodzie InitUploadSigned (opisanej w nast pnym rozdziale).

8 Plik metadanych musi by podpisany cyfrowo podpisem kwalifikowanym zgodnie z algorytmem XAdES Basic Electronic Signature w postaci Pliku XML zgodnego ze schematem , w skr cie XAdES-BES w wersji Enveloped (podpis jako dodatkowy element ds:Signature w oryginalnym XML) lub Enveloping (oryginalny dokument zawarty jako element w podpisanej strukturze). Przy podpisywaniu mo na dokona transformacji obiektu podpisywanego zgodnie z kodowaniem #base64. Funkcj skr tu wykorzystywan w podpisie powinna by RSA-SHA256 lub RSA-SHA1. Przyk ad metadanych uwierzytelniaj cych mo na znale w p. , gdzie om wiona jest metoda InitUploadSigned, przyjmuj ca metadane uwierzytelniaj ce. 9 2 Specyfikacja interfejsu przyjmuj cego dokumenty JPK dla klient w Wst p Mechanizm przyjmowania dokument w oparty jest o us ugi REST, dzia aj ce w oparciu o protok HTTPS. Takie podej cie zapewnia zar wno efektywno i sprawno interfejsu (cho by w por wnaniu np.)

9 Do interfejs w typu SOAP), jak i atwo integracji z rozwi zaniami ERP i innymi, napisanymi w r nych technologiach. Opis interfejsu Zasadnicza cz interfejsu dla klient w ERP sk ada si z nast puj cych metod: InitUploadSigned Put Blob FinishUpload Status Implementacja rodowiska testowego dost pna jest pod adresem: Natomiast adresy poszczeg lnych metod przedstawiaj si nast puj co: {referenceNumber} Implementacja rodowiska produkcyjnego dost pna jest pod adresem: Natomiast adresy poszczeg lnych metod przedstawiaj si nast puj co: {referenceNumber} Poni ej znajduje si szczeg owy opis dzia ania metod. 10 InitUploadSigned Metoda inicjuj ca sesj klienta. Jej wywo anie jest warunkiem koniecznym do przes ania danych metod Put Blob us ugi Azure. Nazwa InitUploadSigned Typ metody POST Typ przesy anej zawarto ci application/xml Typ zwracanej zawarto ci application/json Maksymalny rozmiar dania 100KB Opis parametr w przekazywanych w adresie metody: Nazwa Opis Typ Walidacja enableValidateQualifiedSignature W przypadku przekazania warto ci true (na rodowisku testowym), system zweryfikuje czy przesy any plik zosta podpisany poprawnym podpisem kwalifikowanym.

10 Bool Opcjonalny dopuszczalne warto ci: true, false Adres metody z w czon weryfikacj podpisu kwalifikowanego: Opis struktury XML stanowi cego zawarto dania (message body): Nazwa Opis Typ Walidacja InitUpload Metadane dla metody InitUpload Obiekt Wymagany DocumentType Nazwa typu przesy anego String Wymagany - dopuszczalne 11 dokumentu. warto ci: JPK - dokumenty przesy ane cyklicznie JPKAH - dokumenty przesy ane dora nie w ramach kontroli Version Wersja REST API do kt rej adresowane jest zapytanie String Wymagany, EncryptionKey Klucz symetryczny zaszyfrowany algorytmem asymetrycznym (RSA) String Wymagany Algorytm, kt rym zaszyfrowany jest klucz symetryczny String dopuszczalne warto ci: RSA Wymagany Tryb szyfrowania String dopuszczalne warto ci: ECB Wymagany Format dope nienia klucza szyfruj cego String dopuszczalne warto ci: PKCS#1 Wymagany Algorytm kodowania warto ci klucza String dopuszczalne warto ci: Base64 Wymagany 12 DocumentList Lista przes anych dokument w Lista obiekt w typu Document Wymagany.