Dokumentacja techniczna

Projekt IForm e-deklaracje Dokumentacja techniczna.1

Projekt IForm e-deklaracje Strona ii SPIS TREŚCI 1 ŚRODOWISKO PROGRAMOWO - SPRZĘTOWE...2 1.1 WYMAGANIA WSTĘPNE...2 1.2 INFRASTRUKTURA PODPISU ELEKTRONICZNEGO...2 1.3 CERTYFIKATY KWALIFIKOWANE...3 2 INSTALACJA OPROGRAMOWANIA...4 2.1 INSTALACJA ZESTAWU KRYPTOGRAFICZNEGO...4 2.2 REJESTRACJA CERTYFIKATU...7 2.3 INSTALACJA PROGRAMU...12 2.4 URUCHOMIENIE PROGRAMU...15 3 OBSŁUGA PROGRAMU...17 3.1 WARUNKI TECHNICZNE...17 3.2 WCZYTYWANIE DOKUMENTU...17 3.3 PODPIS Z UŻYCIEM CERTYFIKATU KWALIFIKOWANEGO...19 3.4 PODPIS Z UŻYCIEM DANYCH AUTORYZUJĄCYCH...24 3.5 PRZESYŁANIE PODPISANEGO DOKUMENTU DO BRAMKI MF...26 3.6 SPRAWDZANIE STATUSU DOKUMENTU...29 3.7 POBRANIE POTWIERDZENIA ODBIORU...30 3.8 ZAKOŃCZENIE PRZETWARZANIA...33 4 OPCJE LINII KOMEND...34 5 KONFIGURACJA...36 6 ROZWIĄZYWANIE PROBLEMÓW...37

Projekt IForm e-deklaracje Strona 1 0 WSTĘP 0.1 PRZEZNACZENIE DOKUMENTU Niniejsza dokumentacja zawiera opis środowiska, sposobu instalacji oraz zasad eksploatacji programu realizowanego w ramach projektu IForm e-deklaracje w oparciu o umowę dnia 31 lipca 2015 roku na zlecenie SigForm.pl z siedzibą w Warszawie przy ul. Gibalskiego 21, 01-190 Warszawa. 0.2 WYKORZYSTANIE DOKUMENTU Dokument przeznaczony jest do wykorzystania przez użytkownika końcowego, odpowiedzialnego za instalację i wstępną konfigurację rozwiązania na komputerze osobistym. 0.3 DOKUMMENTY ZWIĄZANE 1. Specyfikacja funkcjonalna systemu obsługi e-deklaracji z poziomu Microsoft Excel, Borkowski Robert, SignForm.pl, wersja z dnia 2015-07-07, 2. Oferta JRJ Consulting z dnia 2015-07-07 na wykonanie oprogramowania do przesyłania arkuszy Excel do bramki Ministerstwa Finansów, 3. System e-deklaracje, Specyfikacja wejścia-wyjścia, wersja 2.0, Ministerstwo Finansów, Departament Informatyzacji Usług Publicznych, Warszawa 02.01.2015, 4. System e-deklaracje, Specyfikacja wejścia-wyjścia, Środowisko testowe, wersja 2.0, Ministerstwo Finansów, Departament Informatyzacji Usług Publicznych, Warszawa 02.01.2015, 5. Oprogramowanie do podpisu elektronicznego i zarządzania kartami kryptograficznymi dostarczane przez centra certyfikacji, Ministerstwo Finansów, Departament Informatyzacji Usług Publicznych, Warszawa 20.07.2015, 6. Projekt IForm e-deklaracje, Dokumentacja techniczna, Część II. Dokumentacja projektowa.

Projekt IForm e-deklaracje Strona 2 1 ŚRODOWISKO PROGRAMOWO - SPRZĘTOWE Oprogramowanie przeznaczone jest do pracy w środowisku sprzęto-programowym wyposażonym w czytnik kart kryptograficznych oraz oprogramowanie systemowe i narzędziowe zapewniające możliwość skutecznego zarządzania elementami systemu kryptograficznego. 1.1 WYMAGANIA WSTĘPNE Oprogramowanie przeznaczone jest do pracy w środowisku rodziny systemów operacyjnych Microsoft Windows XP, Windows 7, Windows 10, Windows Server 2003 oraz 2008 w wersjach 32 oraz 64 bitowych. Dla poprawnej pracy elementów kryptograficznych wymagana jest instalacja właściwej dla wykorzystywanego systemu operacyjnego - wersji maszyny wirtualnej Java y. Program IForm e-deklaracje wymaga do poprawnej pracy instalacji JRE (Java Runtime Environment) w wersji 1.7 lub 1.8. Uwaga: JRE nie jest dostarczane w ramach pakietu instalacyjnego programu IForm e-deklaracje ze względu na duży rozmiar plików dystrybucyjnych. Właściwą dla zainstalowanego systemu operacyjnego wersję pliku instalacyjnego można pobrać i zainstalować zgodnie z wymaganiami określonymi w serwisie dostawcy platformy http://www.oracle.com/technetwork/java/javase/downloads/ 1.2 INFRASTRUKTURA PODPISU ELEKTRONICZNEGO Według stanu na dzień 30 września 2015 roku świadczenie usług w zakresie wydawania certyfikatów kwalifikowanych wraz z dostawą właściwego dla stosowanego rodzaju kart kryptograficznych (czytnik kart, sterowniki do czytnika, oprogramowanie middleware) działa pięć podmiotów (kwalifikowane podmioty świadczące usługi certyfikacyjne w zakresie podpisu elektronicznego), wpisanych do rejestru Ministerstwa Gospodarki: 1. Krajowa Izba Rozliczeniowa (Szafir) 2. Polska Wytwórnia Papierów Wartościowych (Sigillum) 3. Unizeto Technologies (CERTUM) 4. Enigma S.O.I. (PEM-HEART) 5. EuroCert Dla zapewnienia możliwości pełnego wykorzystania oferowanych na rynku rozwiązań zestawów kryptograficznych architektura programu IForm e-deklaracje w wersji 1.0. wykorzystuje wyłącznie usługi warstwy middleware zgodne ze specyfikacją Microsoft Cryptography API 2.0. Zastosowane rozwiązanie zapewnia niezależność od stosowanego rodzaju kart kryptograficznych, urządzeń oraz mechanizmów

Projekt IForm e-deklaracje Strona 3 zarządzania szeroką gamą kart kryptograficznych. Odpowiedzialność za dostawę właściwych dla stosowanego rozwiązania sterowników oraz elementów oprogramowania dostosowujących oferowany zestaw kryptograficzny do standardu MSC API spoczywa w tym przypadku na dostawcy zestawu do składania podpisu elektronicznego. Podmioty wymienione w pozycjach 1, 2 oraz 4 dostarczają oprogramowanie z modułem CSP (Cryptography Service Provider) w pełni zgodnym z wymaganym standardem. W przypadku poz. 3 na stronach producenta (wg. stanu na dzień 30 września 2015) nie znaleziono deklaracji o gwarancji zgodności dostarczanego rozwiązania ze standardem MSC API. W praktyce oznacza to, że - za ewentualne niewłaściwe zachowania oraz skutki prawne wynikające z wykorzystywania program IForm e-deklaracje wraz z tym zestawem - wyłączną odpowiedzialność bierze na siebie użytkownik programu. Uwaga: Przy opracowywaniu wersji 1.0. programu IForm e-deklaracje nie analizowano zgodności z dostawcą zestawów wg. poz. 5 w związku całkowitym z brakiem informacji dotyczących stosowanej przez firmę polityki (wg wykazu NCERT obowiązująca firmę od dnia 04 kwietnia 2015 roku polityka certyfikacji w wersji 1.2 nie jest publicznie dostępna w serwisie informacyjnym firmy). 1.3 CERTYFIKATY KWALIFIKOWANE Program obsługuje poprawnie zainstalowane w magazynie certyfikatów osobistych systemu Windows certyfikaty kwalifikowane. Zgodnie ze stanem obowiązujących dokumentów określających stosowne polityki bezpieczeństwa podmiotów wymienionych w pkt. 1.2 akceptowane są wyłącznie certyfikaty kwalifikowane X509 spełniające łącznie następujące warunki: 1. OID 2.5.29.19 : Basic Constraints : CA : false 2. OID 2.5.29.15 : Key Usage : Non Repudiation : true 3. OID 2.5.29.32 : Certification Policies : CertificatePolicyId : OID wg poniższej tabeli 1 1.2.616.1.113571.1.1 Krajowa Izba Rozliczeniowa (Szafir) 2 1.2.616.1.113560.10.1.1.0 PWPW (Sigillum) 3 1.2.616.1.113527.2.4.1.1 UNIZETO Technologies (Certum) 4 1.2.616.1.113681.1.1.10.1.1.2 Enigma S.O.I. (PEM-HEART) 5 brak danych - nieobsługiwany EuroCert

Projekt IForm e-deklaracje Strona 4 2 INSTALACJA OPROGRAMOWANIA Pełny proces instalacji oprogramowania od momentu zakupu zestawu kryptograficznego do momentu uruchomienia programu IForm e-deklaracje obejmuje kilka istotnych etapów, z których każdy wykonany winien zostać zgodnie ze stosowną instrukcją. Poniżej omówiono w skrócie każdy z etapów wskazując najistotniejsze jego elementy. 2.1 INSTALACJA ZESTAWU KRYPTOGRAFICZNEGO Instalacja zakupionego czytnika kart oraz dołączonego do niego oprogramowania wykonywana jest zgodnie z dokumentacją techniczną dołączoną przez dostawcę rozwiązania. Typowy proces instalacji wymaga podłączenia czytnika kart do komputera oraz umieszczenia otrzymanej w zestawie płyty instalacyjnej w czytniku (CD/DVD) komputera. Standardowa instalacja sterowników i oprogramowania nadzorowana jest zwykle kreatorem instalacji, a więc w dużej mierze należy krok po kroku wykonać kolejne operacje sugerowane przez narzędzie. Rysunek 2-1. Menadżer kart CryptoCard Suite

Projekt IForm e-deklaracje Strona 5 W zależności od wyboru centrum certyfikacji sterowniki zostaną zainstalowane razem ze stosownym oprogramowaniem albo instalacje sterowników trzeba zainicjować oddzielnie. Pomyślne zakończenie procesu instalacji urządzenia oraz sterowników i oprogramowania do zarządzania kartą umożliwia przejście do etapu aktywowania karty kryptograficznej. Proces aktywacji wymaga umieszczenia otrzymanej karty w czytniku. Do zarządzania kartami kryptograficznymi Polska Wytwórnia Papierów Wartościowych (Sigillum) oraz Krajowa Izba Rozliczeniowa używają aplikacji CryptoCard Suite (rysunek 2-1). W przypadku tych dwóch rozwiązań należy wybrać zakładkę Karty elektroniczne, następnie w górnym oknie wskazać strefę SetEID i wybrać przycisk Aktywuj. Proces aktywacji kończy ustalenie kodu PIN (który w tym rozwiązaniu ma od 4 do 8 znaków) oraz kodu PUK (8 znaków). Rysunek 2-2. Certyfikat kwalifikowany po aktywacji W przypadku wątpliwości lub problemów korzystać należy z dostarczonej wraz z zestawem dokumentacji, oraz w razie potrzeby ze wsparcia dostawcy rozwiązania. Dla potrzeb współpracy z programem IForm e-deklaracje zaleca się dodatkowo przejść do zakładki Konfiguracja i wyłączyć (dolna część dialogu) opcję Oczekuj na włożenie karty elektronicznej do czytnika (rysunek 2-3)

Projekt IForm e-deklaracje Strona 6 Rysunek 2-3. Zalecana konfiguracja zestawu CryptoCard Suite Unizeto Technologies dostarcza dla potrzeb zarządzania kartami aplikację procertum CardManager (rysunek 2-4). W przypadku tego rozwiązania proces aktywowania Rysunek 2-4. Menadżer kart procentrum CardManager karty wymaga naciśnięcia przycisku Czytaj kartę oraz wprowadzenia w kolejnym kroku PIN u (Nowy PIN). Całość potwierdzamy w przypadku tego rozwiązania otrzymanym kodem nadrzędnym (PUK). Dla umożliwienia późniejszej sprawnej rejestracji certyfikatu kwalifikowanego w systemie zdecydowanie zaleca się rezygnację z automatycznej metody instalacji certyfikatu na rzecz bardziej zaawansowanej, lecz niestandardowej, wymagającej samodzielnej instalacji certyfikatu na karcie oraz akceptacji certyfikatu. Po aktywowaniu karty zaleca się

Projekt IForm e-deklaracje Strona 7 dodatkowo przejść do ustawienia opcji programu (przycisk Opcje) oraz wyłączyć opcję Pamiętaj kod PIN dla aplikacji korzystających z CSP dla obu widocznych profili: zwykłego i bezpiecznego (rysunek 2-5). Rysunek 2-5. Zalecana konfiguracja procentrum CardManager W przypadku jakichkolwiek wątpliwości lub problemów występujących na tym etapie instalacji korzystać należy z dostarczonej wraz z zestawem dokumentacji, oraz w razie potrzeby ze wsparcia dostawcy rozwiązania. 2.2 REJESTRACJA CERTYFIKATU Proces rejestracji certyfikatu kwalifikowanego w magazynie certyfikatów osobistych systemu Windows (Windows-My) jest etapem niezbędnym, warunkującym poprawną pracę z wykorzystaniem programu IForm e-deklaracje. W przypadku stosowania oprogramowania CryptoCard Suite wybieramy kolejno zakładkę Narzędzia, a dalej Dodatkowe narzędzia i przycisk Uruchom. W kolejnym kroku (rysunek 2-6) wskazujemy niezbędny kreator (w tym przypadku Rejestracja certyfikatu w systemie). W przypadku kart elektronicznych w standardzie multisign certyfikat kwalifikowany pamiętany jest w strefie QESv2, a więc należy zaznaczyć tę strefę przed wykonaniem kolejnego kroku (rysunek 2-7). Dalsze kroki wykonać należy bazując na podpowiedziach kreatora, zwracając szczególną uwagę na to, by wskazać w kolejnych krokach właściwy magazyn certyfikatów: Osobisty. W przypadku stosowania rozwiązania Unizeto (Certum) szczegółowy opis pobrania certyfikatu kwalifikowanego zawarty jest w dostępnej na stronach instrukcji http://www.certum.pl/.../krok_3_pobranie_certyfikatu_kwalifikowanego.pdf

Projekt IForm e-deklaracje Strona 8 Rysunek 2-6. Rejestracja certyfikatu w systemie Aby możliwa była rejestracja certyfikatu w systemie niezbędne jest zastosowanie omówionej szczegółowo w powołanej wyżej instrukcji zaawansowanej (nieautomatycznej) procedury pobrania i instalacji certyfikatu. Zastosowanie tej procedury umożliwia pobranie certyfikatu kwalifikowanego ze stron Certum w postaci pliku *.cer na dowolną lokalizację dyskową w swojej stacji roboczej.

Projekt IForm e-deklaracje Strona 9 Rysunek 2-7. Wybór certyfikatu kwalifikowanego - strefa QESv2 Po zainstalowaniu i aktywowaniu certyfikatu można w kolejnym kroku przejść do rejestracji pobranego ze stron Unizeto (Certum) certyfikatu kwalifikowanego. Niezbędnym elementem procesu rejestracji będzie pobrany wcześniej i zapisany na dysku stacji roboczej plik *.cer (zawierający certyfikat w formacie PKCS#12). Proces rejestracji certyfikatu jest w tym rozwiązaniu inicjowany z poziomu systemu operacyjnego (oprogramowanie procertum nie posiada odpowiednich mechanizmów). Uruchamiamy korzystając z przycisku Start / Uruchom - przystawkę o nazwie certmgr.msc (rysunek 2-8). Rysunek 2-8. Uruchomienia menadżera certyfikatów w systemie Windows 7 W otwartym panelu menadżera certyfikatów rozwijamy w lewym oknie zakładkę Osobisty / Certyfikaty. W prawym oknie ukaże się lista certyfikatów aktualnie zarejestrowanych w wybranym magazynie (rysunek 2-9).

Projekt IForm e-deklaracje Strona 10 Rysunek 2-9. Magazyn certyfikatów w systemie Windows 7 Rysunek 2-10. Kreator importu plików systemu Windows 7

Projekt IForm e-deklaracje Strona 11 Pozycjonując kursor w prawym oknie klikamy prawym przyciskiem myszki, wybierając kolejno Wszystkie zadania / Importuj Po uruchomieniu kreatora importu w kolejnych krokach pojawi się okno przedstawione na rysunku 2-10. Wskazujemy na plik *.cer z certyfikatem kwalifikowanym pobranym uprzednio ze strony Unizeto (Certum), kontynuując proces rejestracji zgodnie z podpowiedziami kreatora. Poprawnie zainstalowany certyfikat powinien pojawić się na kolejnej pozycji w prawym panelu menadżera certyfikatów. Uwaga: nie należy w żadnym przypadku podejmować prób związanych z instalacją certyfikatu w innym z magazynów systemu. W procesie rejestracji certyfikatu w magazynie certyfikatów program prosi zwykle o podanie przyjaznej nazwy (alias), pod którą certyfikat widoczny będzie w magazynie, i co nie mniej ważne : na której bazował będzie w przyszłości proces wyszukiwania wskazanego certyfikatu w magazynie. Oznacza to, iż nazwy certyfikatów w magazynie winny być zawsze unikalne. Na rysunku 2-11 zilustrowano omawianą sytuację : w magazynie umieszczone są trzy certyfikaty z identycznym aliasem Certyfikat CCZO. W efekcie próba wyszukania certyfikatu przez nazwę zawsze prowadzić musi do zwrócenia w wyniku jednego z nich, a dwa pozostałe nigdy nie będą dostępne. Rysunek 2-11. Nieunikalne aliasy w magazynie certyfikatów W podobnym przypadku najprostszym i najszybszym wyeliminowanie problemu jest edycja Przyjaznej nazwy (aliasu). W prawym oknie wybieramy kolejno każda z trzech lini, naciskająć prawy przycisk myszy wybieramy Właściwości i drogą edycji edycji omawianego pola eliminujemy duplikowane nazwy (np. metodą ich zaindeksowania, jak zilustrowano na rysunku 2-12).

Projekt IForm e-deklaracje Strona 12 Rysunek 2-12. Eliminacja zduplikowanych aliasów metodą numerowania 2.3 INSTALACJA PROGRAMU Przed przystąpieniem do instalacji programu IForm e-deklaracje należy upewnić się, czy: 1. spełnione są wszystkie warunki wstępne, określone w pkt. 1.1 niniejszej dokumentacji, 2. w oparciu o dokumentację zakupionego zestawu kryptograficznego wykonano instalację czytnika kart, stosownego oprogramowania do zarządzania kartą oraz dokonano aktywacji karty kryptograficznej (patrz pkt 2.1), 3. poprawnie zainstalowano aktualny certyfikat kwalifikowany we właściwym magazynie certyfikatów, wg zasad określonych w pkt. 2.2 niniejsze dokumentacji. W przypadku, gdy wymienione wyżej warunki są spełnione, można przystąpić do instalacji programu IForm e-deklaracje. Proces instalacji realizowany jest z minimalnym udziałem użytkownika, poprzez uruchomienie programu instalacyjnego dystrybuowanego pod nazwą IFSetup.exe. Dystrybucja programu instalacyjnego odbywać się może zarówno w formie dostawy nośnika zawierającego utrwaloną kopię, lub poprzez ściągnięcie wersji instalacyjnej udostępnianej w serwisie internetowym.

Projekt IForm e-deklaracje Strona 13 Uruchomienie programu instalacyjnego powoduje pojawienie się na ekranie dialogu początkowego rozpoczynającego proces instalacji. Istotnym elementem jest wersja programu prezentowana na ekranie. Użytkownik używając przycisku Dalej inicjuje kolejne kroki kreatora, podczas których koniecznym staje się potwierdzenie faktu zapoznania się z warunkami licencji oraz podjęcie ostatecznej decyzji (wyrażenie zgody) na rozpoczęcie etapu fizycznej instalacji plików. Program instalacyjny weryfikuje zgodność platformy systemu operacyjnego z wymaganiami określonymi w pkt. 1.1 niniejszej dokumentacji oraz sprawdza, czy użytkownik inicjujący proces instalacji posiada uprawnienia administracyjne. Aktualna wersja programu instalacyjnego nie daje możliwości zmiany katalogu docelowego, co oznacza, że instalowany komponent zawsze umieszczany jest w katalogu C:\Program Files\JRJ Consulting\IForm e-deklaracje\ Rysunek 2-13. Ekran początkowy programu instalacyjnego

Projekt IForm e-deklaracje Strona 14 Rysunek 2-14. Akceptacja zasad licencjonowania Program instalacyjny dokonuje w każdym przypadku zastąpienia istniejących plików przez elementy aktualnie instalowane, nie wymagając przy tym potwierdzenia ze strony użytkownika. Jedynym plikiem, którego nie nadpisuje się bez zgody użytkownika jest z oczywistych względów plik konfiguracyjny iformapp.xml. Każdorazowo zatem w trakcie instalacji pojawia się pytanie jak na rysunku 2-15. Rysunek 2-15. Instalacja pliku iformapp.xml Przyjęte rozwiązanie z jednej strony umożliwia proste i szybkie przywrócenia oryginalnych ustawień programu IForm e-deklaracje, z drugiej zaś daje możliwość zachowania zestawu parametrów w przypadkach, gdy zostały one świadomie zmienione.

Projekt IForm e-deklaracje Strona 15 Plik konfiguracyjny iformapp.xml jako jedyny umieszczany jest w katalogu danych użytkownika %LOCALAPPDATA%\IForm e-deklaracje a w przypadku, gdy symbol %LOCALAPPDATA% nie został zdefiniowany (co ma miejsce np. w przypadku instalacji w systemie Windows XP) w katalogu %APPDATA%\IForm e-deklaracje W trakcie instalacji w katalogu docelowym umieszczany jest również program umożliwiający w razie potrzeby wykonanie standardową metodą deinstalacji zainstalowanych uprzednio składników. Zawartość katalogu instalacyjnego bezpośrednio po zakończeniu procesu instalacji pokazano na rysunku 2-16. Rysunek 2-16. Zawartość katalogu instalacyjnego 2.4 URUCHOMIENIE PROGRAMU Pierwszego uruchomienia zainstalowanego programu dokonujemy poprzez zaznaczenie pliku iformapp.exe oraz podwójne kliknięcie. Potwierdzeniem prawidłowej instalacji programu jest pojawienie się na ekranie okna aplikacji pokazanego na rysunku 2-17.

Projekt IForm e-deklaracje Strona 16 Należy sprawdzić, czy wersja programu widoczna na pasku tytułowym głównego oka aplikacji jest zgodna z numerem wersji prezentowanym uprzednio na ekranie powitalnym programu instalacyjnego. Ewentualna rozbieżność wskazywać może wyłącznie na problem natury techniczno organizacyjnej (np. brak możliwości nadpisania określonych plików w czasie poprzedniej lub bieżącej procedury instalacyjnej, co w większości przypadków jest skutkiem ręcznych zmian i ingerencji w systemie plików). Uwaga: jedyną znaną przyczyną kłopotów natury technicznej objawiających się niemożliwością uruchomienia programu (brak pojawiania się okna głównego aplikacji na ekranie) jest brak poprawnie zainstalowanej wersji Java y. Wszystkie wspierane (patrz pkt. 1.1) wersje systemu Windows dostarczane są dystrybucyjnie wraz z profesjonalnie zainstalowaną maszyną wirtualną Java y. W przypadku poprawnie tworzonych środowisk produkcyjnych prawdopodobieństwo wystąpienia omawianych trudności jest zatem niewielkie, a dotyczyć może głównie stacji roboczych niezbyt właściwie utrzymywanych (administrowanych) w cyklu życia oprogramowania. Jedynym rozwiązaniem jest w omawianym przypadku dokonanie ponownej poprawnie instalacji Java y (pkt. 1.1), być może po wcześniejszej pełnej deinstalacji - zainstalowanych a niefunkcjonujących poprawnie - składników tej platformy. Rysunek 2-17. Okno główne aplikacji IForm e-deklaracje

Projekt IForm e-deklaracje Strona 17 3 OBSŁUGA PROGRAMU 3.1 WARUNKI TECHNICZNE W czasie pracy programu wymagany jest praktycznie w każdej fazie przetwarzania stały i stabilny dostęp do internetu. 3.2 WCZYTYWANIE DOKUMENTU Program przetwarza z założenia wyłącznie dwa typy dokumentów: 1. dokumenty w formacie XML, zgodne z wymaganiami dotyczącymi deklaracji podatkowych (obowiązujące schematy XSD publikowane są w serwisie informacyjnym Ministerstwa Finansów) wg wykazu na stronie http://www.mf.gov.pl/web/wp/systemy-informatyczne/e-deklaracje/ struktury-dokumentow-xml Rysunek 3-1. Stan okna w trakcie wykonywania ładowania i analizy dokumentu

Projekt IForm e-deklaracje Strona 18 2. pliki programów MS Excel 2003/2007/2010 (pliki z rozszerzeniami *.xls, *.xlsx oraz *.xslm), których zawartość (struktura wewnętrzna) zgodna jest ze specyfikacją zawartą w Dokumentacji technicznej, Część II. Dokumentacja projektowa opracowanej w ramach projektu IForm e-deklaracje. Po wybraniu żądanego pliku, którego struktura zgodna jest z wymaganiami określonymi wyżej (nazwa wskazanego pliku widoczna jest w polu Dokument) oraz naciśnięciu przycisku Dalej rozpoczyna się faza przetwarzania związaną z wczytaniem i analizą zgodności wczytanego dokumentu z wymaganiami rozwiązania. Ten stan programu sygnalizowany jest na bieżąco właściwym komunikatem w polu Status programu. Wyświetlane w tym polu komunikaty prezentowane są z użyciem trzech kolorów: 1. szary oznacza informację o aktualnie realizowanej operacji, należy zwrócić uwagę, iż w tym stanie niedostępne są przyciski funkcyjne (rysunek 3-1), 2. zielony oznacza informację informująca o zakończeniu z sukcesem wykonywanej operacji, co w zalezności od fazy przetwarzania skutkuje udostępnieniem właściwych dla stanu programu przycisków (rysunek 3-2), 3. czerwony wskazujący na przerwanie bieżącej operacji z błędem (rysunek 3-3). Rysunek 3-2. Stan okna po poprawnym zakończeniu operacji wczytywania i weryfikacji dokumentu Rysunek 3-3. Stan okna po spowodowanym błędem przerwaniu operacji wczytywania lub sprawdzania Faza wczytywania analizy dokumentu zakończyć się może błędem wykonania. Znaczenie poszczególnych komunikatów w tej fazie omówiono niżej. 1. Nieudana próba pobrania aktualnego wykazu schematów XSD

Projekt IForm e-deklaracje Strona 19 - oznacza, że próba pobrania przez program wykazu obowiązujących schematów XSD z serwisu MF (którego adres URL wskazano wyżej zakończyła się niepowodzeniem (brak dostępu programu do Internetu, strona lub serwis MF nie odpowiada w oczekiwanym czasie), 2. Wersja użytego schematu XSD niezgodna z aktualnie obowiązującą - oznacza, że przetwarzany dokument odwołuje się w swej treści do nieaktualnej wersji schematu XSD (serwis MF, którego adres URL wskazano wyżej dla danego typu deklaracji zawiera odwołanie do zaktualizowanego nowszego schematu XSD dokumentu (należy zmodyfikować przetwarzany dokument źródłowy wprowadzając odwołanie do aktualnej wersji schematu) 3. Nieudana próba pobrania żądanego schematu XSD - oznacza, że próba pobrania z internetu pliku zawierającego aktualny schemat XSD zakończyła się niepowodzeniem (brak dostępu do internetu, strona lub serwis epuap nie odpowiada) 4. Struktura dokumentu XML nie jest zgodna ze schematem XSD - oznacza, iż struktura przetwarzanego dokumentu nie jest zgodna z pobranym aktualnym schematem XSD, może to być skutkiem wprowadzenia modyfikacji obowiązującego schematu XSD, co z kolei wymusza konieczność dostosowania struktury dokumentu do nowych wymagań MF 5. Nie odnaleziono wskazanego pliku lub odmowa dostępu - oznacza brak możliwości otwarcia lub odczytania określonego pliku, co może być skutkiem konfliktu w dostępie (plik aktualnie otwarty przez inny program w trybie wyłączności) 6. Operacja wczytania dokumentu zakończona błędem - oznacza inny, niesklasyfikowany wyżej, bliżej nieokreślony błąd w działaniu systemu. 3.3 PODPIS Z UŻYCIEM CERTYFIKATU KWALIFIKOWANEGO Po poprawnym wczytaniu dokumentu oraz zakończonej pozytywnie weryfikacji zgodności składni dokumentu z obowiązującym dokumentem XSD program umożliwia przejście do fazy wyboru właściwej metody podpisu (podpis z użyciem certyfikatu kwalifikowanego lub o ile to jest możliwe z użyciem danych autoryzacyjnych).

Projekt IForm e-deklaracje Strona 20 Operację podpisu inicjujemy z użyciem przycisku Podpisz. Stan okna głównego programu po zapoczątkowaniu operacji podpisu przedstawiono na rysunku 3-4. W chwilę po zainicjowaniu operacji na ekranie pojawi się dialog wyboru rodzaju składanego podpisu (rysunek 3-5). W niniejszym punkcie omówiono wyłącznie technikę składania podpisu z użyciem poprawnie zainstalowanego w magazynie certyfikatów certyfikatu kwalifikowanego. Rysunek 3-4. Stan okna po zainicjowaniu operacji składania podpisu Rysunek 3-5. Dialog wyboru certyfikatu (wszystkie kwalifikowane, karta w czytniku)

Projekt IForm e-deklaracje Strona 21 Technika składania podpisu z użyciem danych autoryzujących omówiona została w punkcie 3.4 niniejszej dokumentacji. Na powyższym rysunku 3-5 prezentowana jest lista zarejestrowanych w magazynie certyfikatów kwalifikowanych, zarówno ważnych, jak i tych, które ważność utraciły (zaznaczona opcja Pokaż wszystkie). Na rysunku widoczne są dwa certyfikaty nieaktywne i jeden aktywny. Stan aktywny oznacza, iż dla wybranego (selekcja) certyfikatu kwalifikowanego umieszczona została prawidłowo zainicjowana karta kryptograficzna, oraz na karcie odnaleziono właściwy dla wybranego certyfikatu kwalifikowane klucz prywatny. Rysunek 3-6. Dialog wyboru certyfikatu (wszystkie kwalifikowane, brak karty w czytniku) Rysunek 3-6 przedstawia stan dialogu po wyjęciu karty z czytnika. Certyfikat o numerze seryjnym 16894579 staje się nieaktywny, gdyż klucz prywatny niezbędny do złożenia podpisu przestał być dostępny. Rysunek 3-7. Dialog wyboru certyfikatu (wyłącznie ważne kwalifikowane, brak karty) Wyłączenie opcji Pokaż wszystkie umożliwia usunięcie (odfiltrowanie) z prezentowanej listy certyfikatów kwalifikowanych, które utraciły ważność.

Projekt IForm e-deklaracje Strona 22 Rysunek 3-8. Dialog wyboru certyfikatu (wyłącznie ważne kwalifikowane, karta w czytniku) Ponowne umieszczenie właściwej karty w czytniku powoduje po chwili odświeżenie okna, umożliwiając skuteczny wybór certyfikatu kwalifikowanego. Po zaakceptowaniu wyboru właściwego certyfikatu kwalifikowanego z użyciem przycisku Wybierz spowoduje zamknięcie okna dialogu wyboru certyfikatu. W chwilę później winno na akranie pojawić się okienko dialogowe z żądaniem podania kodu PIN właściwego dla użytek karty kryptograficznej (kodu PIN nadanego przy aktywacji karty). Rysunek 3-9. Składania podpisu kwalifikowanego (zapytanie o pin) Uwaga: Wyświetlenie okna z żądaniem podania kodu PIN leży w zakresie odpowiedzialności komponentów technicznych dostarczanych wraz z zestawem kryptograficzny, nigdy zaś po stronie programu IForm e-deklaracje. Program nie żąda (bo nie ma takiej możliwości) PIN u w żadnym przypadku. Program zwraca się

Projekt IForm e-deklaracje Strona 23 do komponentu technicznego (CSP) z żądaniem udostępnienia klucza prywatnego i to komponent techniczny przed udostępnieniem klucz winien zweryfikować PIN, którym klucz zabezpieczono. W niektórych rozwiązaniach fakt, czy pytanie o PIN się pojawi, czy też nie, zależy od opcji konfiguracyjnych ustawianych z użyciem dostarczanego wraz z zestawem kryptograficznym programu zarządzającego kartami (patrz pkt. 2.1). Po skutecznym złożeniu z użyciem certyfikatu kwalifikowanego podpisu w formacie XAdES-BES treść podpisanego dokumentu prezentowana jest w głównym oknie programu. Faza składania podpisu elektronicznego zakończyć się może komunikatem 1. Operacja złożenia podpisu w standardzie XAdES-BES zakończona błędem oznacza, że w trakcie wykonywania algorytmu składania podpisu lub w fazie weryfikacji poprawności złożonego podpisu wystąpiły nieoczekiwane problemy natury technicznej (np. program utracił komunikacje z karta kryptograficzną). Rysunek 3-10. Okno główne programu (podpisany dokument w formacie XAdES)

Projekt IForm e-deklaracje Strona 24 Po zakończonej sukcesem fazie składania podpisu elektronicznego pojawia się możliwość (aktywny przycisk Zapisz) utrwalenia podpisanej elektronicznie wersji dokumentu na dysku stacji roboczej. Podpisany dokument w formacie XML zapisywany jest w sygnowanym datą i czasem sporządzenia podpisu pliku z rozszerzeniem *.sig. Rysunek 3-11. Utrwalenie na dysku podpisanego elektronicznie dokumentu 3.4 PODPIS Z UŻYCIEM DANYCH AUTORYZUJĄCYCH Dla niektórych typów dokumentów (deklaracji) możliwe jest skuteczne podpisanie z użyciem tzw. danych autoryzujących, a więc bez wykorzystania karty kryptograficznej. Szczegółowe informacje, który rodzaj dokumentu (deklaracji) może być w ten sposób podpisany (dotyczy to wyłącznie osób fizycznych) znaleźć można na stronach serwisu MF. Tam też poszukiwać należy informacji związanych z Rysunek 3-12. Okno pomocy

Projekt IForm e-deklaracje Strona 25 określeniem, jaką wartość (zależne od roku i typu deklaracji) podać należy w jedynym podlegającym aktualizacji polu Kwota przychodu (rysunek 3-13). Podpowiedź uzyskać można z po naciśnięciu przycisku (przycisku pomocy, rysunek 3-12) Rysunek 3-13. Podpis z użyciem danych autoryzujących Skuteczne złożenie podpisu z użyciem danych autoryzujących możliwe jest wyłącznie w sytuacji braku jakiejkolwiek karty kryptograficznej w czytniku (brak aktywnego certyfikatu na liście powyżej). Tylko bowiem w takim przydatku do edycji udostępniona zostaje dola część okna. Przed złożeniem podpisu z użyciem danych autoryzujących program prosi o potwierdzenie zgody na wykonanie takiej operacji (rysunek 3-14).

Projekt IForm e-deklaracje Strona 26 Rysunek 3-14. Potwierdzenie zgody na użycie danych autoryzujących Rysunek 3-15. Potwierdzenie złożenia podpisu z użyciem danych autoryzujących Po zakończonym sukcesem złożeniu podpisu niekwalifikowanego z użyciem danych autoryzujących możliwe jest zapisanie dokumentu XML w pliku dyskowym stacji roboczej (przycisk Zapisz). 3.5 PRZESYŁANIE PODPISANEGO DOKUMENTU DO BRAMKI MF Po poprawnym złożeniu podpisu z użyciem certyfikatu kwalifikowanego lub danych autoryzujących możliwe staje się przesłanie podpisanego dokumentu do bramki MF. Uwaga: Standardowo dokumenty wysyłane są do tzw. bramki testowej MF. Zmiana trybu pracy programu polegająca na przekierowaniu strumienia wysyłanych dokumentów do systemu produkcyjnego wymaga świadomego użycia opcji programu (patrz pkt. 4 niniejszej dokumentacji). Proces komunikacji z bramką inicjujemy z wykorzystaniem przycisku Wyślij.

Projekt IForm e-deklaracje Strona 27 Rysunek 3-16. Komunikacja z bramką Ministerstwa Finansów Rysunek 3-17. Odpowiedź serwera bramki po pomyślnym zarejestrowaniu dokumentu Wykaz możliwych statusów dokumentu zawarty jest w odpowiednich dokumentach MF (specyfikacja wejścia wyjścia bramek, patrz pkt. 0.3). Można przyjąć, że 200 oznacza przyjęcie i zakończenie przetwarzania, status z grupy 3xx oznacza, że dokument został doręczony, lecz nadal znajduje się w fazie przetwarzania oraz status z grupy 4xx sygnalizuje błąd w strukturze dokumentu lub inny problem, uniemożliwiający akceptację dokumentu przez MF. Status z grupy 1xx nie powinien w praktyce wystąpić. Z reguły sygnalizuje błąd strumienia danych dostarczanych do bramki MF (przyczyna leżeć może po stronie programu lub błędów transmisji w trakcie przesyłania).

Projekt IForm e-deklaracje Strona 28 Faza wysyłania dokumentu do bramki MF zakończyć się może błędem wykonania sygnalizowanym przez program. Znaczenie poszczególnych komunikatów w tej fazie omówiono niżej. 1. Walidacja certyfikatu serwera bramki e-deklaracje zakończona błędem - oznacza, że wystąpiły problemy natury technicznej z certyfikatem SSL bramki, ze stron MF należy pobrać certyfikat SSL bramki (lub bramki testowej) i zainstalować z godnie z zawartą na stronach instrukcją. 2. Przesyłanie dokumentu do bramki e-deklaracje zakończone błędem - oznacza, że w trakcie przesyłania dokumentu lub pobierania odpowiedzi zwrotnej serwera MF wystąpiły problemy z łącznością (błąd transmisji danych lub brak odpowiedzi serwera w oczekiwanym czasie) Rysunek 3-18. Utrwalenie na dysku numeru referencyjnego dokumentu Po zakończonej sukcesem fazie przesłania dokumentu do bramki MF pojawia się możliwość (aktywny przycisk Zapisz) utrwalenia odpowiedzi serwera (numeru referencyjnego zarejestrowanego przez bramkę dokumentu w postaci 32 cyfrowej liczby heksadecymalnej) na dysku stacji roboczej. Dane zapisywane są w pliku tekstowym z rozszerzeniem *.txt o nazwie sygnowanej datą i czasem sporządzenia podpisu. Należy zwrócić uwagę, iż w przypadku przesyłania dokumentu do bramki testowej proces przetworzenia dokumentu trwa zwykle kilkanaście do kilkudziesięciu sekund, a więc UPO (Urzędowe Poświadczenie Odbioru) pobrać można zwykle w ciągu tej samej sesji pracy programu, kilkukrotnie sprawdzając stan przetworzenia (patrz pkt. 3.6). W przypadku przesyłania dokumentu do bramki w trybie produkcyjnym, UPO gotowe jest do odbioru w czasie ok. dwóch godzin po dostarczeniu dokumentu. Zapisanie numeru referencyjnego do pliku umożliwia w dowolnym czasie do wznowienia pracy programu i pobrania UPO korzystając z zawartej w pliku *.txt informacji o numerze referencyjnym dostarczonego do bramki dokumentu.

Projekt IForm e-deklaracje Strona 29 3.6 SPRAWDZANIE STATUSU DOKUMENTU Sprawdzenie statusu przetworzenia dokumentu w trakcie tej samej sesji programu (sesji w ramach której nastąpiło wysłanie dokumentu) możliwe jest wielokrotnie poprzez naciśnięcia przycisku Sprawdź. Zachowanie się programu oraz sposób reakcji na ewentualne sytuacje nieprawidłowe jest analogiczny z omówionym w pkt. 3.5. Jeżeli opuścimy program, i po pewnym czasie powrócimy do sprawdzania stanu dokumentu, program wymagał będzie dostarczenia dodatkowej informacji o numerze referencyjnym badanego dokumentu. W takim przypadku wymagane jest uruchomienie programu z linii komend w sposób zilustrowany na rysunkach 3-19 (3-20 odpowiednio dla bramki produkcyjnej). Rysunek 3-19. Sprawdzenie statusu (bramka testowa) - odczyt nr. referencyjnego z pliku Rysunek 3-20. Sprawdzenie statusu (bramka produkcyjna) - nr. referencyjny z pliku

Projekt IForm e-deklaracje Strona 30 Rysunek 3-21. Żądanie wskazania pliku zawierającego poprawny numer referencyjny Faza sprawdzania statusu dokumentu zakończyć się może błędem wykonania sygnalizowanym przez program. 1. Nie odnaleziono wskazanego pliku lub odmowa dostępu - oznacza, że wystąpiły problemy z odnalezieniem pliku, pliku nie udało się otworzyć (np. otwarty w innym programie) lub nie odczytano z pliku prawidłowego numeru referencyjnego (wewnętrzny format pliku nie jest zgodny z oczekiwanym np. wskutek ręcznej ingerencji/edycji zawartości pliku). 3.7 POBRANIE POTWIERDZENIA ODBIORU W normalnym trybie pracy (wysyłanie do bramki produkcyjnej) po ok. dwóch godzinach od momentu wysłania dokumentu na serwerach MF zostaje przygotowane do obioru o ile przetwarzanie zakończyło się sukcesem, czyli status dokumentu równy 200) tzw. UPO (Urzędowe Potwierdzenie Odbioru). W sytuacji, gdy wykonanie operacji sprawdzenia dokumentu stwierdza, że status przetworzenia zwracany przez bramkę jest równy 200, udostępniony zostaje (rysunek 3-20) przycisk Drukuj, umożliwiający pobranie UPO w formacie *.pdf. Pobrany plik można zarówno wydrukować, jak również zapisać na dysku roboczym komputera do późniejszego przeglądania (wydruku).

Projekt IForm e-deklaracje Strona 31 Rysunek 3-22. Przetwarzanie dokumentu zakończone sukcesem

Projekt IForm e-deklaracje Strona 32 Rysunek 3-203. UPO - przykład wydruku

Projekt IForm e-deklaracje Strona 33 3.8 ZAKOŃCZENIE PRZETWARZANIA Rysunek 3-2421. Okno główne programu po zakończeniu cyklu wysyłki dokumentu Po pobraniu UPO wszystkie przyciski funkcyjne, z wyjątkiem umożliwiającego zakończenie pracy (Zakończ) oraz przejście do ewentualnego przetwarzania kolejnego dokumentu (Dalej) stają się nieaktywne.

Projekt IForm e-deklaracje Strona 34 4 OPCJE LINII KOMEND Program IForm e-deklaracje sterowany może być z linii komend z użyciem opcji. Poniżej zawarto pełne zestawienie opcji dostępnych do wykorzystania przez użytkownika. -e Opcja zmienia tryb pracy programu z testowego na produkcyjny. Brak opcji e oznacza zawsze komunikacje z bramką testową MF. Użycie opcji e umożliwia przesłanie dokumentu do bramki produkcyjnej MF. -r Opcja umożliwia uruchomienie programu w celu pobrania UPO dla wcześniej przesłanego do bramki dokumentu (numer referencyjny pobierany z pliku) -rid <numer referencyjny> Opcja umożliwia uruchomienie programu w celu pobrania UPO dla wcześniej przesłanego do bramki dokumentu, numer referencyjny wskazany bezpośrednio poprzez wartość parametru (32 cyfry heksadecymalne) -f <nazwa pliku> Opcja umożliwia uruchomienie programu w celu przetworzenia dokumentu zapisanego w pliku o wskazanej nazwie <nazwa pliku> -s Opcja umożliwia pominięcie pytania o wskazanie certyfikatu kwalifikowanego w przypadku, gdy program odnajdzie dokładnie jeden ważny certyfikat kwalifikowany, i będzie on aktywny (karta kryptograficzna w czytniku, klucz prywatny dostępny) -d Opcja zmienia zakres informacji wyprowadzanych do pliku logowania na bardziej szczegółowy. Plik logowania o nazwie iformapp.log zapisywany jest w katalogu %LOCALAPPDATA% (lub %APPDATA% jeżeli symbol %LOCALAPPDATA% nie został zdefiniowany) -a Opcja blokuje możliwość przeprowadzenia operacji złożenia podpisu z użyciem danych autoryzujących A więc przykładowo polecenie linii komend iformapp.exe f VAT-7(15).xlsm e -d

Projekt IForm e-deklaracje Strona 35 oznacza żądanie wczytania, podpisania i wysłania do bramki produkcyjnej MF dokumentu zapisanego w pliku o nazwie VAT-7(15).xlsm, przy czym szczegółowe informacje dokumentujące proces przetwarzania zapisane mają zostać do pliku logowania.

Projekt IForm e-deklaracje Strona 36 5 KONFIGURACJA Podstawowe parametry konfiguracyjne programu zapisane są w pliku iformapp.xml, który zlokalizowany jest w katalogu %LOCALAPPDATA% (lub %APPDATA% jeżeli symbol %LOCALAPPDATA% nie został zdefiniowany). Struktura pliku, oraz wartości odpowiednich parametrów ustalane przez program instalacyjny są następujące: <?xml version="1.0" encoding="utf-8" standalone="no"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <comment/> <entry key="userpath"> \ </entry> <entry key="serveruri"> https://bramka.e-deklaracje.mf.gov.pl/xsd </entry> <entry key="testserverurl"> https://test-bramka.edeklaracje.gov.pl/uslugi/dokumenty/ </entry> <entry key="prodserverurl"> https://bramka.e-deklaracje.mf.gov.pl/uslugi/dokumenty/ </entry> <entry key="helpserverurl"> http://www.iform.pl/txtfile/readme.txt </entry> <entry key="docschemaurl"> http://www.mf.gov.pl/web/wp/systemy-informatyczne/edeklaracje/struktury-dokumentow-xml </entry> <entry key="defschemaurl"> http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2011/06/21/ed/definicj etypy/ </entry> </properties> W warunkach normalnej eksploatacji systemu modyfikacja tego pliku nie jest zalecana, i zwykle zbędna. Jeżeli jednak pojawi się konieczność edycji w.w. pliku, zawsze można przywrócić jego wartość pierwotną poprzez całkowite usunięcie pliku (skasowania). Podczas kolejnego uruchomienia program o ile nie znajdzie pliku konfiguracyjnego utworzy nową jego wersje nadając parametrom wartości domyślne (jak na załączonym wykazie).

Projekt IForm e-deklaracje Strona 37 6 ROZWIĄZYWANIE PROBLEMÓW W przypadku, gdy podczas eksploatacji programu wystąpią problemy natury technicznej lub programowej, których nie udaje się zdiagnozować lub rozwiązać z użyciem niniejszej dokumentacji, należy: 1. O ile to możliwe, sprawdzić, czy problem jest powtarzalny, tzn, czy kolejne uruchomienia programu z tym samym dokumentem oraz w tym samym otoczeniu programowym przebiegają w analogiczny sposób. 2. Jeżeli problem jest powtarzalny, uruchomić program w trybie logowania (ustawiając dodatkowy parametr linii komend d). 3. Opisać niewłaściwe zdaniem użytkownika zachowanie (działanie), dokumentując w miarę możliwości zrzutem ekranu, a następnie przesłać drogą elektroniczną na adres iform-support@jrj.pl a. zwarty opis problemu, b. stosowne zrzuty z ekranu, c. dokument źródłowy, którego przetwarzanie stwarza problem, d. plik logowania iformapp.log otrzymany w kroku 2.

Projekt IForm e-deklaracje Strona 38 KONTROLA ZMIAN Tytuł: Wydanie:.1 Dokumentacja techniczna. Data: 25 października 2015 Autor: Dystrybucja: Referencje: Nazwa pliku: Zakres nadzoru: Jerzy R. Jaworowski Zespół projektowy IForm e-deklaracje IForm e-deklaracje I - 1.doc Reedycja wyłącznie w postaci kompletnego dokumentu ZATWIERDZENIE DOKUMENTU Podpis Data Funkcja Opracował Zespół projektowy 02-10-2015 Konsultant Weryfikował dr inż. Jerzy R. Jaworowski 03-10-2015 Kierownik projektu DZIENNIK ZMIAN DOKUMENTU Date Wersja Autor Szczegóły zmiany 03-10-2015 Pierwsze kompletne wydanie 25-10-2015.1 Jerzy R. Jaworowski 1.3, 2.2, 2.3, 2.4, 3,4, 3.5, 4

Projekt IForm e-deklaracje Jerzy Roman Jaworowski Strona 39 Elektronicznie podpisany przez Jerzy Roman Jaworowski DN: c=pl, o=jrj Consulting Jerzy Jaworowski, serialnumber=pesel: 51102803811, cn=jerzy Roman Jaworowski, postaladdress=olimpijska 19a, 30-065 Kraków, Polska, małopolskie, givenname=jerzy Roman, sn=jaworowski Data: 2015.10.29 23:13:16 +01'00'