epuap Usługi sieciowe Profil Zaufany Projekt współfinansowany ze środków Europejskiego Funduszu Rozwoju Regionalnego w ramach Programu Operacyjnego Innowacyjna Gospodarka
1. WSTĘP... 5 1.1. CEL DOKUMENTU... 5 1.2. DOSTĘP DO ŚRODOWISKA TESTOWEGO... 5 1.3. SŁOWNIK I DODATKOWA DOKUMENTACJA... 6 1.4. WYMAGANE CERTYFIKATY... 8 2. OPIS FUNKCJONALNY USŁUGI TPSIGNING... 9 2.1. DOSTARCZANIE INFORMACJI O POSIADANIU PROFILU PZ... 9 2.2. PODPISYWANIE Z UŻYCIEM PZ... 9 2.2.1. Krok pierwszy przekazanie dokumentu... 9 2.2.2. Krok drugi podpisanie przez użytkownika...10 2.2.2.1 Algorytm wizualizacji dokumentu...10 2.2.2.2 Przypadki specjalne...11 2.2.3. Krok trzeci ściągnięcie podpisanego dokumentu...11 2.2.4. Możliwość podpisania certyfikatem kwalifikowanym...12 2.3. WERYFIKACJA PODPISU POTWIERDZONEGO PZ... 12 2.4. STRUKTURA WYNIKU WERYFIKACJI PODPISU... 13 2.5. UPRAWNIENIA... 16 2.6. ADRESY USŁUGI... 17 2.7. DOKUMENT WSDL... 17 3. INTERFEJS PROGRAMISTYCZNY SKŁADANIA PODPISU POTWIERDZONEGO PROFILEM ZAUFANYM (TPSIGNING2)... 18 3.1. USŁUGA SIECIOWA TPSIGNING... 18 3.2. USŁUGA SIECIOWA TPSIGNING2... 18 3.2.1. Uprawnienia do usługi TpSigning2...20 3.2.2. Przykładowa komunikacja (z pominięciem nagłówków WS- Security)...21 3.2.2.1 Metoda przejściowa (ADD-REQ-SIGN-GET)...21 3.2.2.2 Metoda REQ-SIGNC...25 3.2.2.3 Możliwe błędy...26 3.2.3. Adresy usługi...28 2
3.2.4. Dokument WSDL...28 4. INTERFEJS UDOSTĘPNIANIA DANYCH POTWIERDZONYCH PROFILU ZAUFANEGO (USŁUGA TPUSERINFOSERVICE)... 29 4.1. MOTYWACJA... 29 4.2. NOWA USŁUGA SIECIOWA... 29 4.2.1. Przykładowa komunikacja...30 4.2.1.1 Żądanie...30 4.2.1.2 Odpowiedź...30 4.2.1.3 Możliwe błędy...31 4.2.2. Uprawnienia do usługi TpUserInfoService...32 4.2.3. Adresy usługi...32 4.2.4. Dokument WSDL...33 5. ROZSZERZONA USŁUGA WERYFIKACJI PODPISU ELEKTRONICZNEGO 34 5.1. USŁUGA SIGNATUREVERIFICATION... 34 5.1.1. Adresy usługi...34 5.1.2. Dokument WSDL...34 5.1.3. Korzystanie z usługi...35 5.1.3.1 Przykładowa komunikacja...35 6. PODPISYWANIE PACZEK DOKUMENTÓW... 37 6.1. USŁUGA MULTISIGN... 37 6.1.1. Przekazywanie dokumentów do podpisania...37 6.1.2. Podpisywanie dokumentów przez użytkownika na stronach epuap...39 6.1.3. Pobranie podpisanych dokumentów...39 6.1.4. Wspólne parametry wszystkich operacji...40 6.2. PRZYKŁADOWA KOMUNIKACJA... 40 6.3. MOŻLIWE BŁĘDY... 44 6.3.1. Brak nagłówków WS-Security...45 6.3.2. Niepoprawny podpis pod wiadomością...45 6.3.3. Brak uprawnień...46 3
6.3.4. Nieprzekazanie dokumentów do podpisu...46 6.3.5. Brak wymaganych parametrów...47 6.3.6. Ściąganie niepodpisanego dokumentu...47 6.3.7. Nieunikalne identyfikatory dokumentów...48 6.4. UPRAWNIENIA DO USŁUGI MULTISIGN... 49 6.5. ADRESY USŁUGI... 49 6.6. DOKUMENT WSDL... 50 6.7. WERYFIKACJA PODPISÓW... 50 6.8. LIMITY PRZESYŁANYCH DANYCH... 52 7. INNE USŁUGI ZWIĄZANE Z WERYFIKACJĄ PODPISU ELEKTRONICZNEGO... 54 7.1. OASIS DSS WERYFIKACJA PODPISU... 54 4
1. Wstęp 1.1. Cel dokumentu Niniejsza instrukcja ma za zadanie stanowić pomoc dla użytkowników integrujących się z epuap w zakresie interfejsów podsystemu Profil Zaufany. 1.2. Dostęp do środowiska testowego Środowisko testowe epuap jest dostępne pod adresem http://test.epuap.gov.pl/. Instytucja, która planuje przeprowadzenie integracji wysyła zgłoszenie e-mail do MAIC na adres testepuap2@cca.gov.pl z określeniem nazwy Instytucji, danych kontaktowych, opisem systemu oraz planowanym zakresem integracji. W zgłoszeniu należy również podać dane założonego konta na platformie testowej: Nazwa uprawnienia określona w dokumentacji epuap Okres na jaki ma być nadane uprawnienie (maksimum dwa lata, profil zaufany na sześć miesięcy): Nazwa podmiotu: Adres podmiotu: Identyfikator podmiotu (identyfikator powinien zawierać akronim nazwy podmiotu oraz miejscowość siedziby podmiotu): Służbowy adres poczty elektronicznej do korespondencji: Imię, nazwisko i stanowisko administratora podmiotu lub osoby upoważnionej do pełnienia funkcji administratora: Imię, nazwisko i stanowisko osoby uprawnionej do reprezentowania podmiotu: 5
Numer telefonu podmiotu: Uzasadnienie (należy wskazać cel, sposób wykorzystania, zastosowanie) 1.3. Słownik i dodatkowa dokumentacja Pojęcie Opis System epuap Ogół elementów wchodzących w skład platformy epuap. Podsystem epuap Część systemu epuap wyodrębniony w architekturze. Interfejs Definicja zbioru operacji, które mogą być wywoływane przez dwa komunikujące się elementy. Komponent Element składowy systemu (podsystemu) realizujący pewien spójny zakres funkcjonalności. Komunikacja między komponentami odbywa się wyłącznie przy użyciu interfejsów. WebService Jedna z form implementacji interfejsu. Cechą interfejsu jest jego dostępność może być wywołany zdalnie przez system zewnętrzny. 6
Profil Zaufany Aplikacja PZ (Profil Zaufany) Zestaw informacji identyfikujących i opisujących podmiot lub osobę będącą użytkownikiem konta na epuap, który został w wiarygodny sposób potwierdzony przez organ uprawnionego podmiotu publicznego. Aplikacja dostarczająca funkcjonalności obsługi i zarządzania profilami zaufanymi Podpis PZ (podpis profilem zaufanym) HSM Podpis cyfrowy dokonywany przez epuap zawierający informację o podmiocie zaufanym w imieniu, którego dokonano podpisu. Dodatkowe informacje umieszczone są w elemencie claimedrole struktury podpisu. Hardware Security Module sprzętowy moduł kryptograficzny TSA Time Stamping Authority usługi służące do oznaczania czasem SOPEL System Obsługi Podpisu Elektronicznego Konsola DRACO Konsola zarządzania uprawnieniami w epuap dostępna pod adresem https://konsoladraco.epuap.gov.pl/dracoconsole 7
1.4. Wymagane certyfikaty W komunikacji pomiędzy epuap, a systemami zewnętrznymi, stosowany jest standardowy mechanizm WS-Security. Usługi sieciowe epuap wymagają, aby element soap:body przesyłanej wiadomości, stanowiącej wywołania operacji, podpisany był certyfikatem zarejestrowanym w systemie DRACO. W przychodzących wiadomościach weryfikowana jest obecność tokenu zgodnego z http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-tokenprofile-1.0#x509v3 Wiadomości wychodzące z epuap oraz odpowiedzi wywołań operacji web serwisów autoryzowane są w analogiczny sposób poprzez podpisanie elementu soap:body certyfikatem epuap. System zewnętrzny odbierający wiadomości pochodzące z systemu epuap powinien weryfikować podpis epuap na tych wiadomościach. Szczegółowe informacji na temat otrzymania certyfikatu znajdują się na stronie epuap.gov.pl w lokalizacji: Strefa urzędnik > Pomoc > Dla integratorów > Integracja. 8
2. Opis funkcjonalny usługi TPSigning 2.1. Dostarczanie informacji o posiadaniu profilu PZ Interfejs dostarcza informacji o posiadaniu profilu zaufanego i odpowiada rezultatem logicznym (prawda, fałsz) po wywołaniu operacji hastrustedprofileperson dla PZ użytkownika. Operacja jako jedyny argument przyjmuje znacznik sesji epuap (tzw. TGSID). 2.2. Podpisywanie z użyciem PZ Podpisywanie dokumentu XML (na platformie epuap tylko dokumenty XML mogą być podpisywane) profilem zaufanym składa się z punktu widzenia systemu zewnętrznego z trzech kroków. 2.2.1. Krok pierwszy przekazanie dokumentu System zewnętrzny za pośrednictwem usługi WebServices (WS-Security) rejestruje zlecenie podpisu dokumentu. W rezultacie otrzymuje URL, pod który ma przekierować użytkownika. Adres ten jest równocześnie identyfikatorem przekazanego dokumentu, po podpisaniu dokument będzie można go ściągnąć do systemu zewnętrznego przekazując w parametrze odpowiedniej operacji ten właśnie adres. Operacja przekazania dokumentu nosi nazwę adddocumenttosigning. Argumenty operacji: doc - dokument do podpisania, rozmiar wejściowego dokumentu nie może być większy niż 5 MB. W limicie 5 MB musi się zmieścić się podpisany dokument, a więc rekomenduje się przesyłanie dokumentów do 4,5 MB. 9
successurl - URL, na który zostanie przekierowany użytkownik w przypadku udanej próby podpisania dokumentu, nie dłuższy niż 1024 znaki failureurl - URL, na który zostanie przekierowany użytkownik w przypadku nieudanej próby podpisania dokumentu, nie dłuższy niż 1024 znaki additionalinfo - informacje dodatkowe w postaci tekstu prezentowanego na stronie, na której użytkownik podpisuje przekazany dokument (tekst nie powinien zawierać znaczników HTML, wszelkie znaczniki zawarte w parametrze zostaną wyświetlone w postaci tekstu). Maksymalna długość: 1024 znaki 2.2.2. Krok drugi podpisanie przez użytkownika Przeglądarka użytkownik jest przekierowywana przez system zewnętrzny na adres otrzymany w pkt.1. epuap weryfikuje czy użytkownik jest zalogowany na epuap (również przez SSO) i w razie potrzeby automatycznie kieruje go na stronę logowania. Następnie użytkownik podpisuje dokument. Jeśli operacja się powiedzie epuap przekierowuje użytkownika na stronę przekazaną w zleceniu (pkt.1) w parametrze successurl, w przeciwnym wypadku epuap przekierowuje użytkownika na stronę określoną w parametrze failureurl" (w zleceniu pkt.1). 2.2.2.1 Algorytm wizualizacji dokumentu Na stronie podpisywania może być widoczna wizualizacja podpisywanego dokumentu. Wizualizacja jest widoczna wtedy, gdy uda się ustalić adres przekształcenia XSLT, a proces otwarcia przez epuap pliku transformaty i samo przekształcenie odbędą się poprawnie. Jeśli dokument jest dokumentem epuap-owym, tj. ma wyróżnik opublikowany na stronach CRD lub epuap.gov.pl (wzór lokalny FE) wzięta zostanie transformata wskazana w wyróżniku. W przeciwnym razie wzięta zostanie transformata podana w 10
instrukcji przetwarzania xml-stylesheet (musi być to adres bezwzględny i dostępny dla epuap-u). (Za adres wyróżnika przyjmowana jest przestrzeń nazw głównego elementu dokumentu z dodanym na końcu wyroznik.xml. Przykładowo, dla dokumentu pisma ogólnego z przestrzeni nazw http://crd.gov.pl/wzor/2011/06/08/599/ adresem wyróżnika jest http://crd.gov.pl/wzor/2011/06/08/599/wyroznik.xml. W znajdującym się pod tym adresem dokumencie widnieje adres transformaty.) 2.2.2.2 Przypadki specjalne Specjalnym przypadkiem jest podpisywanie dokumentów UPD. Dokumenty te, pochodzące z przestrzeni nazw http://crd.gov.pl/xml/schematy/upo/2008/05/09/ oraz posiadające element pos:upd generowane są przez epuap i posiadają częściowo uzupełnioną strukturę podpisu elektronicznego wskazującą na poświadczany dokument: posiadają element ds:signature pozbawiony elementu ds:signaturevalue. Gdy system epuap napotka taki typ dokumentu podpisanie sprowadzi się do edycji (przede wszystkim uzupełnienia o ds:signaturevalue) istniejącej struktury ds:signature. Jeśli natomiast dokument UPD (np.: generowany przez inny system) nie będzie posiadał struktury podpisu zostanie ona dodana (jednak brak będzie możliwości automatycznej weryfikacji integralności załączanego dokumentu). Słowem zostanie on potraktowany jak zwykły dokument XML. 2.2.3. Krok trzeci ściągnięcie podpisanego dokumentu System zewnętrzny za pośrednictwem usługi WebServices (WS-Security) pobiera podpisany dokument z epuap. Po udanym pobraniu pliku jest on do pewnym zdefiniowanym w systemie czasie usuwany z bazy. W przypadku wystąpienia błędu plik pozostanie w bazie w oczekiwaniu na kolejną próbę pobrania przez pewien ustalony w systemie czas. Argumentem dla operacji pobrania podpisanego pliku jest adres URL uzyskany jako wynik wywołania 11
operacji z kroku pierwszego. Operacja ściągnięcia podpisanego dokument nosi nazwę getsigneddocument. Argumenty operacji: id - klucz identyfikujący podpisany dokument (adres zwrócony operację adddocumenttosigning ) 2.2.4. Możliwość podpisania certyfikatem kwalifikowanym Na stronie pod adresem zwróconym jako wynik wywołania operacji z kroku pierwszego pojawi się strona, na której użytkownik będzie mógł podpisać profilem zaufanym lub certyfikatem. Jeśli system zewnętrzny chce ukryć przed użytkownikiem możliwość podpisania certyfikatem, należy do adresu, na który przekieruje przeglądarkę użytkownika, dodać parametr o nazwie tponly z wartością true. Przykładowo, zwrócony przez WebService adres https://test.epuap.gov.pl/zaufanyprofilweb/externalentryservlet?id=0byl4rr SWNLEYSWu26K80nZmTVUULE należy zamienić przed przekierowaniem na https://test.epuap.gov.pl/zaufanyprofilweb/externalentryservlet?id=0byl4rr SWNLEYSWu26K80nZmTVUULE&tpOnly=true. Adres przekazany do operacji z punktu 3. ( getsigneddocument ) powinien pozostać bez zmian. 2.3. Weryfikacja podpisu potwierdzonego PZ Operacja verifysigneddocument umożliwia przekazanie dokumentu podpisanego przy pomocy PZ lub certyfikatu i weryfikację zawartego w nim podpisu (lub podpisów). Rezultatem weryfikacji jest struktura XML zawierająca wszystkie niezbędne informacje dotyczące podpisu dokumentu. Operacja weryfikacji obsługuje zarówno podpis PZ jak i podpis certyfikatem. Wynik będzie zawierał informacje opisujące oba typy podpisu. Weryfikowany dokument powinien zostać przekazany w postaci zakodowanej algorytmem Base64 (tablica bajtów w przypadku korzystania z klas proxy). Format i znaczenie wynikowej informacji został opisany dalej w tym dokumencie. 12
Argumenty operacji: document - podpisany dokument, rozmiar dokumentu nie może być większy niż 5,5 MB. Dodatkowo, wprowadzono nową usługę weryfikacji podpisu elektronicznego, będącą w stanie weryfikować także podpisy, które odnoszą się do innych dokumentów (ten typ podpisu występuje np.: przy dokumentach UPD oraz wyróżnikach wzorów elektronicznych). Usługa ta została opisana w dalszej części tego dokumentu. 2.4. Struktura wyniku weryfikacji podpisu VerifyResult korzeń dokumentu ValidDocumentSignature element typu boolean, zawierający informację czy dokument jest poprawnie podpisany. Atrybut znaczenie jest opisową zawartością tego pola (Prawidłowy, Nieprawidłowy). SignatureType zawiera typ podpisu (XAdES, PAdES, CAdES) GenerationTime data i godzina wygenerowania tego dokumentu xml StatusInfo dla każdego podpisu w dokumencie tworzona jest oddzielna struktura, której korzeniem jest ten właśnie element, w przypadku braku podpisu w dokumencie również tworzona jest jedna taka struktura. o ValidSignature - element typu boolean, zawierający informację czy podpis jest poprawny. Atrybut znaczenie jest opisową zawartością tego pola (Prawidłowy, Nieprawidłowy). o VerifyStatus element typu int ze statusem weryfikacji podpisu. Atrybut znaczenie jest opisową zawartością tego pola. Obsługiwane wartości wraz z wartością atrybutu znaczenie poniżej. Wartość Znaczenie 0 Zgodny z dokumentem 1 Niezgodny z dokumentem 13
2 Brak załączników 3 Niepoprawna struktura podpisu 5 Brak podpisu o VerifySignerCert - element typu int z informacją o certyfikacie użytym w podpisie. Atrybut znaczenie jest opisową zawartością tego pola. Obsługiwane wartości wraz z wartością atrybutu znaczenie poniżej. Wartość Znaczenie Opis -1 [Brak] brak informacji lub podpisu 0 Ważny certyfikat ważny 1 Nieważny certyfikat nieważny 2 Unieważniony certyfikat podpisujący uniewazniony 3 Nieznany wystawca nie znaleziono certyfikatu wystawcy nie w bazie 4 Brak OCSP lub CRL brak odpowiedzi OCSP lub CRL 5 Błędny ogólny błąd certyfikatu o VerifySignerCertUsage - element typu int z informacją o sposobie użycia certyfikatu wykorzystanego w podpisie. Atrybut znaczenie jest opisową zawartością tego pola, a dodatkowo w przypadku gdy są prawdziwe ustawiane są atrybuty kwalifikowany, logowanie, ocspzaufane", ocspodpowiedz, ocspprzekierowanie", upo", epo", tsa oraz zp. Dopuszczalne pozycje na liście wartości atrybutu znaczenie : Pozycja flagi Znaczenie 1 kwalifikowany 2 niewykorzystany 3 logowanie 4 Zaufana odpowiedź OCSP 5 Generacja odpowiedzi OCSP na podstawie CRL 6 Przekierowanie na OCSP danego CA 7 UPO 14
8 EPO 9 TSA 12 ZP Po przekształceniu wartości elementu VerifySignerCertUsage na reprezentację bitową pierwsze dziewięć bitów (licząc od prawej) oznacza prawdziwość lub nie, w odniesieniu do aktualnie weryfikowanego podpisu, kolejnej pozycji w powyższego zestawienia. Przykładowo mając VerifySignerCertUsage 924 po przekształceniu na reprezentację bitową otrzymujemy 1110011100 co oznacza, że prawdziwe są pozycje: logowanie, Zaufana odpowiedź OCSP, Generacja odpowiedzi OCSP na podstawie CRL, EPO, TSA. Bit na dziesiątej pozycji pełni rolę pomocniczą i oznacza, że przynajmniej jedna pozycja z listy jest prawdziwa. o CommitmentType wartość pola Commitment type z podpisu. o GracePeriod - wartość pola Grace period z podpisu. o ParentSignatureId ID podpisu nadrzędnego (używane przy kontrasygnacie). o SignatureCertIssuer zawiera informację o danych wystawcy certyfikatu, a w atrybutach poszczególne pola z tej informacji. o SignatureCertSerial numer seryjny certyfikatu. o SignatureCertSubject podobnie jak SignatureCertIssuer, ale zawiera informacje o właścicielu certyfikatu. o SignatureId ID podpisu. o SigningTime data i godzina podpisania dokumentu. o UriID wskaźniki do podpisanych elementów. o SignatureTimeStamp informacje o oznaczeniu czasem podpisu, w przypadku braku oznaczenia czasem atrybut znaczenie przyjmuje wartość Brak oznaczenia czasem. TimeStampTime czas oznaczenia podpisu. VerifyStatus - element typu int ze statusem oznaczenia czasem. Atrybut znaczenie jest opisową zawartością tego pola. 15
o ArchiveTimeStamp - informacje o postaci archiwalnej podpisu, w przypadku braku atrybut znaczenie przyjmuje wartość Brak postaci archiwalnej. TimeStampTime czas oznaczenia podpisu. VerifyStatus - element typu int ze statusem oznaczenia czasem. Atrybut znaczenie jest opisową zawartością tego pola. o ZP informacja o podpisie profilem zaufanym. Atrybut "czy_obecny" informuje czy dokument jest podpisany profilem zaufanym. Obsługiwane wartości wraz z wartością atrybutu czy_obecny poniżej Pozycja flagi Znaczenie true informuje, że dokument jest podpisany profilem zaufanym, w tym przypadku element ZP zawiera podpis profilem zaufanym false Informuje, że dokument nie jest podpisany profilem zaufanym 2.5. Uprawnienia Usługi aplikacji Profilu Zaufanego wymagają zarejestrowania systemu zewnętrznego w DRACO. Zarejestrowane systemy mają dostęp do wszystkich usług udostępnianych przez usługę TPSigning. 16
2.6. Adresy usługi Środowisko testowe Usługa TPSigning Adres usługi web service https://test.epuap.gov.pl/zp_signing_external_ws/services/tpsigning Środowisko produkcyjne Usługa TPSigning Adres usługi web service https://ws.epuap.gov.pl/zp_signing_external_ws/services/tpsigning 2.7. Dokument WSDL Dokument WSDL można uzyskać pod powyższymi adresami usług dopisując?wsdl na końcu adresu. 17
3. Interfejs programistyczny składania podpisu potwierdzonego profilem zaufanym (TpSigning2) 3.1. Usługa sieciowa TpSigning Pierwszy sposób integracji systemu zewnętrznego z podsystemem epuap Profil Zaufany polegał na wykonaniu trzech kroków: 1. Przekazaniu do epuap-u dokumentu, który miał być podpisany (operacja adddocumenttosigning z usługi SOAP TPSigning), która zwracała identyfikator dokumentu w postaci adresu URL, pod którym użytkownik może podpisać profilem zaufanym przekazany dokument, 2. Przekierowaniu przeglądarki użytkownika na wskazany adres, 3. Pobraniu podpisanego dokumentu (operacja getsigneddocument usługi SOAP TPSigning) Mankamentem tego rozwiązania jest konieczność czasowego przekierowania użytkownika na epuap celem zalogowania i dokonania podpisu, co bywa dla mniej doświadczonych użytkowników niezrozumiałe i mylące. 3.2. Usługa sieciowa TpSigning2 Usługa sieciowa TPSigning2 umożliwia dokonanie podpisu potwierdzonego profilem zaufanym epuap na stronach systemu zewnętrznego. Podobnie jak w przypadku usługi TPSigning możliwe jest wyłącznie podpisanie dokumentu XML. Warunkiem dokonania tej operacji jest znajomość przez system zewnętrzny znacznika sesji epuap, tzw. TGSID, na podstawie którego można ustalić tożsamość oraz uprawnienia użytkownika w systemie epuap. System 18
zewnętrzny może go uzyskać korzystając z języka SAML 2.0 lub korzystając z natywnych mechanizmów usługi epuap Draco. Oprócz dotychczasowego sposobu integracji (SOAP-przekierowanie-SOAP) dodano dwa nowe. Pierwszy z nich wykorzystuje operacje SOAP adddocumenttosigning oraz getsigneddocument na początku i końcu procesu, zastępuje natomiast przekierowanie wywołaniem dwóch nowych operacji: 1. Operacji requestcode przyjmującej znacznik TGSID i identyfikator podmiotu, w którym zarejestrowany jest system, a zwracającej identyfikator operacji autoryzacyjnej oraz informacje, które system zewnętrzny powinien wyświetlić użytkownikowi, np.: Podaj kod nr 2 z dn. 2011-08-20. Operacja ta powoduje wysłanie wiadomości z kodem jednorazowym do użytkownika. 2. Operacji sign, przyjmującej znacznik TGSID, identyfikator operacji autoryzacyjnej (zwrócony przez requestcode ), kod jednorazowy odczytany przez użytkownika z wiadomości, którą odebrał i wpisany przez niego w stosowne pole w systemie zewnętrznym, identyfikator podpisywanego dokumentu (zwrócony przez operację adddocumenttosigning ) i identyfikator podmiotu, w którym zarejestrowany jest system zewnętrzny. Operacja ta podpisuje dokument i zapisuje go w bazie danych. Opisany powyżej sposób jest sposobem hybrydowym, korzystającym zarówno z operacji usług TPSigning oraz TPSigning2, nie zmienia też zasadniczej zasady pracy z profilem zaufanym: przekazanie dokumentu, podpisanie, ściągnięcie podpisanego dokumentu. Drugi sposób zakłada użycie tylko operacji nowej usługi, mianowicie: 1. Operacji requestcode, dokładnie tak jak zostało to opisane powyżej, 2. Operacji signcontent, która różni się od sign tym, że jednym z argumentów ( content ) jest treść dokumentu do podpisania zamiast identyfikatora uprzednio przekazanego dokumentu ( url ), a podpisany dokument też bezpośrednio zwracany jako odpowiedź na żądanie. 19
Reasumując, możliwe są trzy sposoby integracji: 1. ADD-REDIRECT-GET 2. ADD-REQ-SIGN-GET 3. REQ-SIGNC Gdzie: 1. ADD oznacza operację adddocumenttosigning 2. REDIRECT oznacza przekierowanie przeglądarki użytkownika za adres zwrócony przez ADD 3. GET oznacza operację getsigneddocument 4. REQ oznacza operację requestcode 5. SIGN oznacza operację sign 6. SIGNC oznacza operację signcontent 3.2.1. Uprawnienia do usługi TpSigning2 Aby móc skorzystać z nowej usługi system zewnętrzny musi mieć nadane uprawnienie ZpPodpisywanieZdalne w aplikacji ZP/. Nadawanie tego uprawnienia odbywa się przez nadanie roli ZP-ZpPodpisywanieZdalne podmiotowi, którym zarejestrowany jest system, a następnie oddelegowaniu tego uprawnienia do systemu w ramach podmiotu. W pierwszym sposobie integracji kluczowy, środkowy etap wykonywany jest na stronach epuap, żadne informacje dotyczące tożsamości użytkownika, jego hasło ani kody jednorazowe nie przechodzą przez system zewnętrzny. Dodatkowo, dokument jest wizualizowany przez epuap na podstawie instrukcji przetwarzania zawartej w dokumencie, co zmniejsza prawdopodobieństwo przedstawienia wizualizacji jednego dokumentu, a faktycznie przekazania do podpisu innego. Jest to najbezpieczniejszy sposób integracji (z punktu widzenia użytkowników epuap-u) i jest on dostępny dla każdego zarejestrowanego w Draco systemu zewnętrznego. W dwóch nastepnych sposobach integracji potencjalnych zagrożeń ze strony złośliwego systemu jest więcej, gdyż kod jednorazowy przechodzi przez system zewnętrzny, system zewnętrzny prezentuje wizualizację 20
podpisywanego dokumentu, a kod wpisany przez użytkownika z intencją podpisania jednego dokumentu może być wykorzystany do podpisania innego. Dlatego w/w uprawnienie będzie nadawane tylko zaufanym systemom, których dysponenci oświadczą, że nie będą np.: wykorzystywali kodów wpisanych przez użytkowników do podpisywania innych dokumentów niż te, których podpisania spodziewają się użytkownicy. W przypadku wywołania operacji bez wymaganych uprawnień zwrócony zostanie następujący komunikat: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-fbca5c90-c32e-11e0-8fd8-001a645ae514" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <soapenv:fault> <faultcode>tpsigning2exception</faultcode> <faultstring>pl.gov.epuap.zp.signing2.tpsigning2exception: Brak autoryzacji systemu</faultstring> <detail encodingstyle=""> <p6:tpsigning2exception xmlns:p6="http://signing2.zp.epuap.gov.pl"> <message>brak autoryzacji systemu</message> </p6:tpsigning2exception> </detail> </soapenv:fault> 3.2.2. Przykładowa komunikacja (z pominięciem nagłówków WS-Security) 3.2.2.1 Metoda przejściowa (ADD-REQ-SIGN-GET) Krok 1: żądanie (wysyła dokument XML o treści <test>aaa</test> zakodowany w Base64): <soapenv:envelope xmlns:sig="http://signing.ws.comarch.gov" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-6" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <sig:adddocumenttosigning> <doc>phrlc3q+ywfhpc90zxn0pg==</doc> <successurl>http://success</successurl> <failureurl>http://failure</failureurl> <additionalinfo>opis dokumentu</additionalinfo> 21
</sig:adddocumenttosigning> 22
Krok 1: odpowiedź (zawiera identyfikator podpisywanego dokumentu w postaci adresu URL): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p976:adddocumenttosigningresponse xmlns:p976="http://signing.ws.comarch.gov"> <adddocumenttosigningreturn>https://test.epuap.gov.pl/zaufanyprofilweb/externalentryservlet?id=fn1nkk JHqmhW7LSZdRd2kRGJeoJh8F</addDocumentToSigningReturn> </p976:adddocumenttosigningresponse> Krok 2: żądanie (wysłanie kodu): <soapenv:envelope xmlns:sig="http://signing2.zp.epuap.gov.pl" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <sig:requestcode> <usertgsid>c2b2941ac343d5ed93ff</usertgsid> <systemorganisationid>id_podmiotu</systemorganisationid> </sig:requestcode> Krok 2: odpowiedź (zawiera identyfikator operacji autoryzacyjnej oraz informacje, które należy wyświetlić użytkownikowi): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p6:requestcoderesponse xmlns:p6="http://signing2.zp.epuap.gov.pl"> <requestcodereturn> <feedbackinfo>podaj kod nr 3 z dn. 2011-08-09:</feedbackInfo> <friendlycodeid>3 z dn. 2011-08-09</friendlyCodeId> <sessionid>ip45gtilkimxsrsl3npjndhzklxx0h</sessionid> </requestcodereturn> </p6:requestcoderesponse> 23
Krok 3: żądanie (podpisania dokumentu, zawiera m.in. odebrany przez użytkownika kod): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sig="http://signing2.zp.epuap.gov.pl"> <soapenv:body> <sig:sign> <usertgsid>c2b2941ac343d5ed93ff</usertgsid> <sessionid>ip45gtilkimxsrsl3npjndhzklxx0h</sessionid> <code>kcapdgoy</code> <url>https://test.epuap.gov.pl/zaufanyprofilweb/externalentryservlet?id=fn1nkkjhqmhw7lszdrd2krgjeojh8 F</url> <systemorganisationid>id_podmiotu</systemorganisationid> </sig:sign> Krok 3: odpowiedź (brak błędów oznacza poprawny przebieg operacji): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p6:signresponse xmlns:p6="http://signing2.zp.epuap.gov.pl"/> Krok 4: żądanie (ściągnięcia podpisanego dokumentu): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sig="http://signing.ws.comarch.gov"> <soapenv:body> <sig:getsigneddocument> <id>https://test.epuap.gov.pl/zaufanyprofilweb/externalentryservlet?id=fn1nkkjhqmhw7lszdrd2krgjeojh8f </id> </sig:getsigneddocument> 24
Krok 4: odpowiedź (zawiera wyciętą w przykładzie treść podpisanego dokumentu): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p976:getsigneddocumentresponse xmlns:p976="http://signing.ws.comarch.gov"> <getsigneddocumentreturn>[ ]</getsigneddocumentreturn> </p976:getsigneddocumentresponse> 3.2.2.2 Metoda REQ-SIGNC Krok 1: żądanie (wysłania kodu): <soapenv:envelope xmlns:sig="http://signing2.zp.epuap.gov.pl" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <sig:requestcode> <usertgsid>c2b2941ac343d5ed93ff</usertgsid> <systemorganisationid>id_podmiotu</systemorganisationid> </sig:requestcode> Krok 1: odpowiedź: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p6:requestcoderesponse xmlns:p6="http://signing2.zp.epuap.gov.pl"> <requestcodereturn> <feedbackinfo>podaj kod nr 4 z dn. 2011-08-09:</feedbackInfo> <friendlycodeid>4 z dn. 2011-08-09</friendlyCodeId> <sessionid>kcfgpfraqepnpnn6ldbdhwjqvdmbd1</sessionid> </requestcodereturn> </p6:requestcoderesponse> 25
Krok 2: żądanie podpisania dokumentu (treść przekazana w argumencie): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sig="http://signing2.zp.epuap.gov.pl"> <soapenv:body> <sig:signcontent> <usertgsid>c2b2941ac343d5ed93ff</usertgsid> <sessionid>kcfgpfraqepnpnn6ldbdhwjqvdmbd1</sessionid> <code>umnmusxd</code> <content>phrlc3q+ywfhpc90zxn0pg==</content> <systemorganisationid>id_podmiotu</systemorganisationid> </sig:signcontent> Krok 2: odpowiedź (zawiera pominiętą w przykładzie treść podpisanego dokumentu): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p6:signcontentresponse xmlns:p6="http://signing2.zp.epuap.gov.pl"> <signcontentreturn>[ ]</ signcontentreturn> </p6:signcontentresponse> 3.2.2.3 Możliwe błędy Operacje requestcode, sign i signcontent, zapytanie z niepoprawnym TGSIDem: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p6="http://signing2.zp.epuap.gov.pl">p6:tpsigning2exception</faultcode> <faultstring>pl.gov.epuap.zp.signing2.tpsigning2exception: Niepoprawny TGSID</faultstring> <detail encodingstyle=""> <p6:tpsigning2exception xmlns:p6="http://signing2.zp.epuap.gov.pl"> <message>niepoprawny TGSID</message> </p6:tpsigning2exception> </detail> </soapenv:fault> 26
Operacja requestcode, TGSID użytkownika bez profilu zaufanego: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p6="http://signing2.zp.epuap.gov.pl">p6:tpsigning2exception</faultcode> <faultstring>pl.gov.epuap.zp.signing2.tpsigning2exception: gov.comarch.zp.exceptions.profilenotfoundexception: nie istnieje ważny profil zaufany użytkownika arciuchm</faultstring> <detail encodingstyle=""> <p6:tpsigning2exception xmlns:p6="http://signing2.zp.epuap.gov.pl"> <message>gov.comarch.zp.exceptions.profilenotfoundexception: nie istnieje ważny profil zaufany użytkownika arciuchm</message> </p6:tpsigning2exception> </detail> </soapenv:fault> Operacja sign w przypadku niepoprawnego identyfikatora dokumentu ( url ): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p6="http://signing2.zp.epuap.gov.pl">p6:tpsigning2exception</faultcode> <faultstring>pl.gov.epuap.zp.signing2.tpsigning2exception: Nie znaleziono obiektu w bazie, id=fn1nkkjhqmhw7lszdrd2krgjeojh8f</faultstring> <detail encodingstyle=""> <p6:tpsigning2exception xmlns:p6="http://signing2.zp.epuap.gov.pl"> <message>nie znaleziono obiektu w bazie, id=fn1nkkjhqmhw7lszdrd2krgjeojh8f</message> </p6:tpsigning2exception> </detail> </soapenv:fault> 27
Operacja sign i signcontent, niepoprawny identyfikator operacji autoryzacyjnej ( sessionid ) lub kod jednorazowy ( code ): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p6="http://signing2.zp.epuap.gov.pl">p6:tpsigning2exception</faultcode> <faultstring>pl.gov.epuap.zp.signing2.tpsigning2exception: Brak autoryzacji</faultstring> <detail encodingstyle=""> <p6:tpsigning2exception xmlns:p6="http://signing2.zp.epuap.gov.pl"> <message>brak autoryzacji</message> </p6:tpsigning2exception> </detail> </soapenv:fault> 3.2.3. Adresy usługi Środowisko testowe Usługa TpSigning2 Adres usługi web service https://test.epuap.gov.pl/zp_signing2_external_ws/services/tpsign ing2 Środowisko produkcyjne Usługa TpSigning2 Adres usługi web service https://ws.epuap.gov.pl/zp_signing2_external_ws/services/tpsigni ng2 3.2.4. Dokument WSDL Dokument WSDL można uzyskać pod powyższymi adresami dodając?wsdl na końcu. 28
4. Interfejs udostępniania danych potwierdzonych profilu zaufanego (usługa TpUserInfoService) 4.1. Motywacja W lipcu 2011 Ministerstwo Gospodarki uruchomiło usługę Centralnej Ewidencji i Informacji o Działalności Gospodarczej. Jednym ze sposobów korzystania z CEIDG jest rejestracja oraz logowanie za pomocą profilu zaufanego. Mechanizm polega na przekazaniu do podpisania profilem zaufanych niewielkich dokumentów XML, a następnie pobraniu informacji o użytkowniku z podpisu złożonego pod owymi dokumentami. Sposób ten, zarówno skomplikowany dla użytkownika, powoduje znaczny wzrost obciążenia systemu epuap: podpis wykorzystywany jest nie tylko do podpisania wniosku, ale także do logowania i rejestracji. Dlatego wprowadzono nową usługę sieciową, która dostarcza tych samych danych o użytkowniku co analiza podpisu potwierdzonego profilem zaufanym tego użytkownika. Podobnie jak w przypadku usługi TpSigning2 wystarczy już tylko zalogowanie w epuap. 4.2. Nowa usługa sieciowa Nowa usługa sieciowa, TpUserInfoService, składa się jednej operacji gettpuserinfo. Zwraca ona dokument XML taki jak ten zawarty w sekcji ClaimedRole podpisu potwierdzonego profilem zaufanym (claimedrole) oraz adres e-mail z konta użytkownika (accountemailaddress). 29
4.2.1. Przykładowa komunikacja 4.2.1.1 Żądanie <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:user="http://userinfo.zp.epuap.gov.pl"> <soapenv:body wsu:id="id-19" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <user:gettpuserinfo> <tgsid>c2b2941ac343d5ed93ff</tgsid> <systemorganisationid>id_podmiotu</systemorganisationid> </user:gettpuserinfo> 4.2.1.2 Odpowiedź <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <p590:gettpuserinforesponse xmlns:p590="http://userinfo.zp.epuap.gov.pl"> <gettpuserinforeturn> <accountemailaddress>mkowalski@domena.com</accountemailaddress> <claimedrole><![cdata[<ppzp:podpiszp xmlns:adr="http://crd.gov.pl/xml/schematy/adres/2009/03/06/" xmlns:ins="http://crd.gov.pl/xml/schematy/instytucja/2009/03/06/" xmlns:os="http://crd.gov.pl/xml/schematy/osoba/2009/03/06/" xmlns:ppzp="http://crd.gov.pl/xml/schematy/ppzp/" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance"><ppzp:danezp><ppzp:danezposobyfizycznej><os:nazwisko rodzajczlonu="pierwszy">kos</os:nazwisko><os:imie>peter</os:imie><os:pesel>91111101276</os:pesel><ppz P:IdZaufanegoProfilu>37411</ppZP:IdZaufanegoProfilu><ppZP:IdKontaUzytkownikaEpuap>kowalskim</ppZP:IdK ontauzytkownikaepuap></ppzp:danezposobyfizycznej></ppzp:danezp><ppzp:danepodpisu><ppzp:idkontauzytkow nikaepuap>kowalskim</ppzp:idkontauzytkownikaepuap><ppzp:idpolitykiautoryzacji>1</ppzp:idpolitykiautor yzacji></ppzp:danepodpisu></ppzp:podpiszp>]]></claimedrole> </gettpuserinforeturn> </p590:gettpuserinforesponse> 30
4.2.1.3 Możliwe błędy Odpowiedź (w przypadku zapytania z błędnym lub nieaktualnym TGSID-em): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p411="http://exception.userinfo.zp.epuap.gov.pl">p411:tpuserinfoexception</faultcode> <faultstring>pl.gov.epuap.zp.userinfo.exception.tpuserinfoexception: Brak profilu zaufanego dla podanego TGSID</faultstring> <detail encodingstyle=""> <p411:tpuserinfoexception xmlns:p411="http://exception.userinfo.zp.epuap.gov.pl"> <message>brak profilu zaufanego dla podanego TGSID</message> </p411:tpuserinfoexception> </detail> </soapenv:fault> Odpowiedź (w przypadku, gdy użytkownik, którego dotyczy TGSID nie posiada profilu zaufanego): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <soapenv:body> <soapenv:fault> <faultcode xmlns:p411="http://exception.userinfo.zp.epuap.gov.pl">p411:tpuserinfoexception</faultcode> <faultstring>pl.gov.epuap.zp.userinfo.exception.tpuserinfoexception: nie istnieje ważny profil zaufany użytkownika kowalskim</faultstring> <detail encodingstyle=""> <p411:tpuserinfoexception xmlns:p411="http://exception.userinfo.zp.epuap.gov.pl"> <message>nie istnieje ważny profil zaufany użytkownika kowalskim</message> </p411:tpuserinfoexception> </detail> </soapenv:fault> 31
4.2.2. Uprawnienia do usługi TpUserInfoService Podobnie jak w przypadku usługi TpSigning2 koniecznie jest nadanie uprawnień systemowi zewnętrznemu. Aby system zewnętrzny otrzymał dane z sekcji claimed role ewentualnych podpisów potwierdzonych profilem zaufanym użytkownika epuap konieczne jest nadanie uprawnienia ZpPobieranieDanychZPodpisu w aplikacji ZP/. Analogicznie, nadanie tego uprawnienia odbywa się przez nadanie roli ZP- ZpPobieranieDanychZPodpisu podmiotowi, w którym zarejestrowany jest system i przekazanie tych uprawnień przez administratora podmiotu systemowi. 4.2.3. Adresy usługi Środowisko testowe Usługa TpUserInfo Adres usługi web service https://test.epuap.gov.pl/zp_userinfo_external_ws/services/tpuser InfoService Środowisko produkcyjne Usługa TpUserInfo Adres usługi web service https://ws.epuap.gov.pl/zp_userinfo_external_ws/services/tpuseri nfoservice W przypadku wywołania usługi przez system nieposiadający odpowiednich uprawnień pojawi się następujący błąd: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-25a72640-c331-11e0-93dd-001a645ae514" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <soapenv:fault> <faultcode>tpuserinfoexception</faultcode> <faultstring>pl.gov.epuap.zp.userinfo.exception.tpuserinfoexception: Brak uprawnień</faultstring> <detail encodingstyle=""> <p411:tpuserinfoexception xmlns:p411="http://exception.userinfo.zp.epuap.gov.pl"> 32
<message>brak uprawnień</message> </p411:tpuserinfoexception> </detail> </soapenv:fault> 4.2.4. Dokument WSDL Dokument WSDL można uzyskać pod powyższymi adresami usługi dodając?wsdl na końcu. 33
5. Rozszerzona usługa weryfikacji podpisu elektronicznego Aby systemy zewnętrzne mogły weryfikować poprawność podpisów zawierających odnośniki (np.: podpisy pod UPD i pod wyróżnikami wzorów elektronicznych) konieczne stało się udostępnienie kolejnej operacji, która przyjmowałaby pary nazwa-treść załączników. Operacja ta została udostępniona w nowej oddzielnej usłudze SignatureVerification. 5.1. Usługa SignatureVerification 5.1.1. Adresy usługi Środowisko testowe Usługa SignatureVe rification Adres usługi web service https://test.epuap.gov.pl/zp_verification2_external_ws/services/sig natureverification Środowisko produkcyjne Usługa SignatureVe rification Adres usługi web service https://ws.epuap.gov.pl/zp_verification2_external_ws/services/sig natureverification 5.1.2. Dokument WSDL Dokument WSDL można uzyskać pod powyższymi adresami usługi dodając?wsdl na końcu. 34
5.1.3. Korzystanie z usługi Usługa jest uogólnieniem operacji verifysigneddocument z usługi TPSigning, format zwróconych danych pozostanie identyczny, obowiązują te same ograniczenia dotyczące wielkości weryfikowanego pliku, jedynym dodatkiem jest możliwość przekazania załączników w elementach Attachment opakowanych w element attachments. Elementy te składają się z par nazwa-treść. 5.1.3.1 Przykładowa komunikacja Żądanie weryfikacji podpisu pod UPD (z pominięciem treści plików oraz nagłówków WS-Security): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://verification.zp.epuap.gov.pl"> <soapenv:body wsu:id="id-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <ver:verifysignature> <doc>[tresc dokumentu UPD w base64]</doc> <attachments> <Attachment> <content>[treść dokumentu poświadczanego przez UPD w base64]</content> <name>[nazwa dokumentu poświadczanego przez UPD, np.: wniosek.xml]</name> </Attachment> </attachments> </ver:verifysignature> 35
Żądanie weryfikacji podpisu pod wyróżnikiem: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://verification.zp.epuap.gov.pl"> <soapenv:body wsu:id="id-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <ver:verifysignature> <doc>[treść pliku wyroznik.xml]</doc> <attachments> <Attachment> <content>[treść schematu w base64]</content> <name>schemat.xsd</name> </Attachment> <Attachment> <content>[treść przekształcenia określającego wizualizację, w base64]</content> <name>styl.xsl</name> </Attachment> </attachments> </ver:verifysignature> 36
6. Podpisywanie paczek dokumentów Podsystem Profil Zaufaneg oferuje możliwość podpisania wielu dokumentów jednocześnie, wymagając od użytkownika końcowego wpisania tylko i wyłącznie jednego kodu przesłanego na adres e-mail. Po wpisaniu kodu podpisany z osobna zostanie każdy dokument znajdujący się w paczce. Dodatkowo, każdy dokumentów może mieć do pewnej, określonej w aktualnej konfiguracji systemu, liczby załączników. Na podstawie tych załączników zostaną utworzone dodatkowe odniesienia (referencje) w strukturze podpisu potwierdzonego Profilem Zaufanym. W efekcie przy weryfikacji podpisu pod tak podpisanym dokumentem (dokumentami) należy będzie przekazać treści załączników, a zmiana w treści zarówno dokumentu głównego, jak i jego załączników spowoduje niepoprawność podpisu. 6.1. Usługa Multisign Umożliwienie użytkownikowi podpisania wielu dokumentów XML na raz jest realizowane przez system zewnętrzny za pomocą usługi Multisign. Korzystanie z niej polega na trzech etapach, podobnie jak w przypadku usługi TPSigning: 6.1.1. Przekazywanie dokumentów do podpisania System zewnętrzny powinien wywołać operację initrequest, przekazując jako parametry: successurl - adres powrotu dla sytuacji poprawnego podpisania dokumentów, failureurl - adres powrotu dla sytuacji błędu przy podpisywaniu lub rezygnacji przez użytkownika, requestinfo - informacje o przekazywanych dokumentach (wyświetlane użytkownikowi przez epuap). 37
Operacja ta zwraca identyfikator w postaci adresu URL, którym należy się posługiwać później w komunikacji z usługą. Następnie dla każdego dokumentu, który ma się znaleźć w paczce podpisywanych na raz dokumentów należy wywołać operację adddocumenttorequest przekazując: requesturl - identyfikator paczki (zlecenia podpisania wielu dokumentów), zwrócony przez operację initrequest, documentinfo - informacje o dokumencie (wyświetlane użytkownikowi przez epuap), requestwideid - nadany przez system zewnętrzny unikalny w ramach paczki identyfikator dokumentu (może to być liczba porządkowa lub identyfikator mający wartość w systemie zewnętrznym), unsignedcontent - treść dokumentu (tablica bajtów/base64) XML, niebędącego dokumentem UPD (wynika to z faktu, iż w dokumencie UPD istnieje już częściowo wypełniona struktura podpisu z referencją na dokument, którego UPD dotyczy), attachments - listę załączników (może być pusta). Każdy z załączników powinien być przekazany w postaci: content - treść (tablica bajtów/base64), mimetype - typ MIME (opcjonalny, w przypadku braku system przyjmie application/octet-stream), uri - identyfikator URI (powinien być unikalny w ramach dokumentu) jego wartość zostanie też użyta przy konstruowaniu referencji w podpisie. Po skompletowaniu paczki system zewnętrzny może przystąpić do następnego etapu. 38
6.1.2. Podpisywanie dokumentów przez użytkownika na stronach epuap Podpisywanie dokumentów, podobnie jak w przypadku usługi TPSigning, jest realizowane na stronach epuap. System zewnętrzny powinien przekierować przeglądarkę użytkownika na adres zwrócony przez operację initrequest, a następnie oczekiwać powrotu na zdefiniowane przez siebie strony (oznaczające sukces lub błąd). Na stronach epuap pojawia ekran umożliwiający podpisanie dokumentów Profilem Zaufanym. Dla każdego dokumentu wyświetlona jest krótka sekcja prezentująca dokument (jeśli jest to dokument zgodny ze standardami epuap-u w zakresie wizualizacji dokumentów XML) oraz informacje o nim przekazane przez system zewnętrzny, umożliwiająca jego ściągnięcie oraz ściągnięcie załączników (system nie wizualizuje ich). W przypadku ściągania załączników zostanie użyty typ MIME przekazany przez system zewnętrzny. 6.1.3. Pobranie podpisanych dokumentów Po uzyskaniu informacji o poprawnym podpisaniu paczki (system epuap wyraża ten fakt przekierowując przeglądarkę użytkownika na adres podany w parametrze successurl operacji initrequest) system zewnętrzny powinien ściągnąć z epuap-u po kolei każdy dokument, który znajdował się w paczce. Aby to zrobić należy wywołać operację getsigneddocument, podając: identyfikator paczki, zwrócony przez operację initrequest, identyfikator dokumentu w ramach paczki (nadany przez system zewnętrzny w wywołaniu adddocumenttorequest). System nie udostępnia operacji ściągania załączników, gdyż ich treść nie ulega (w przeciwieństwie do dokumentu/dokumentów głównych) modyfikacji w trakcie podpisu. 39
6.1.4. Wspólne parametry wszystkich operacji Wszystkie operacje składające się na usługę Multisign posiadają dwa parametry: authsubject obowiązkowy parametr określający podmiot, w którym jest zarejestrowany system i w ramach którego powinna odbyć się autoryzacja systemu (o tym dalej), extra opcjonalny parametr, póki co nieużywany. 6.2. Przykładowa komunikacja Podstawowy scenariusz polegający na przekazaniu dwóch dokumentów: jednego z dwoma załącznikami oraz jednego bez żadnych załączników oraz (po podpisaniu przez użytkownika na stronach epuap) ściągnięcie dokumentów. Pominięto elementy związane z WS-Security. Operacja initrequest, żądanie: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.multisign.zp.epuap.gov.pl"> <soapenv:body wsu:id="id-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <ws:initrequest> <successurl>http://ok</successurl> <failureurl>http://blad</failureurl> <requestinfo>paczka dwoch dokumentow</requestinfo> <authsubject>id_podmiotu</authsubject> <extra/> </ws:initrequest> Operacja initrequest, odpowiedź: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-ce534510-830e-11e1-980b-001a645ae514" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <p457:initrequestresponse xmlns:p457="http://ws.multisign.zp.epuap.gov.pl"> 40
<initrequestreturn>https://test.epuap.gov.pl/zaufanyprofilweb/multisignexternalentryservlet?id=22d7dc ce-10b6-46a5-b8ba-17bdf151b696</initrequestreturn> </p457:initrequestresponse> 41
Operacja adddocumenttorequest, żądanie (dokument nr 1): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.multisign.zp.epuap.gov.pl"> <soapenv:body> <ws:adddocumenttorequest> <requesturl>https://test.epuap.gov.pl/zaufanyprofilweb/multisignexternalentryservlet?id=22d7dcce- 10b6-46a5-b8ba-17bdf151b696</requestUrl> <documentinfo>dokument 1</documentInfo> <requestwideid>1</requestwideid> <unsignedcontent>phrlc3q+phrlc3qypnbyenlrbgfkb3dhihryzxnjpc90zxn0mj48l3rlc3q+</unsignedcontent> <attachments> <AttachmentDto> <content>dgvzdg93esbwbglride=</content> <mimetype>text/plain</mimetype> <uri>uri:zalacznika:1</uri> </AttachmentDto> <AttachmentDto> <content>dgvzdg93esbwbglridi=</content> <mimetype>text/plain</mimetype> <uri>uri:zalacznika:2</uri> </AttachmentDto> </attachments> <authsubject>id_podmiotu</authsubject> <extra/> </ws:adddocumenttorequest> Operacja adddocumenttorequest, odpowiedź (dokument nr 1): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body wsu:id="id-114622b0-8310-11e1-980b-001a645ae514" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <p457:adddocumenttorequestresponse xmlns:p457="http://ws.multisign.zp.epuap.gov.pl"/> 42
Operacja adddocumenttorequest, żądanie (dokument nr 2): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.multisign.zp.epuap.gov.pl"> <ws:adddocumenttorequest> <soapenv:body wsu:id="id-4" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <requesturl>https://test.epuap.gov.pl/zaufanyprofilweb/multisignexternalentryservlet?id=22d7dcce- 10b6-46a5-b8ba-17bdf151b696</requestUrl> <documentinfo>dokument 2</documentInfo> <requestwideid>2</requestwideid> <unsignedcontent>phrlc3r4bww+dgvzdhhtbdwvdgvzdhhtbd4=</unsignedcontent> <attachments/> <authsubject>id_podmiotu</authsubject> <extra/> </ws:adddocumenttorequest> Operacja adddocumenttorequest, odpowiedź (dokument nr 2): taka sama jak w przypadku dokumentu nr 1. W tym momencie powinno nastąpić przekierowanie przeglądarki użytkownika na strony epuap, podpisanie dokumentu oraz powrót do systemu zewnętrznego. Następnym krokiem jest dwukrotne wywołanie operacji getsigneddocument: Operacja getsigneddocument, żądanie (dokument nr 1): <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.multisign.zp.epuap.gov.pl"> <ws:getsigneddocument> <soapenv:body wsu:id="id-7" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"> <requesturl>https://test.epuap.gov.pl/zaufanyprofilweb/multisignexternalentryservlet?id=22d7dcce- 10b6-46a5-b8ba-17bdf151b696</requestUrl> <requestwideid>1</requestwideid> <authsubject>id_podmiotu</authsubject> <extra/> </ws:getsigneddocument> 43