Szafir SDK i SzafirHost

Zanotuję tutaj kilka spostrzeżeń na temat Szafir SDK abym za parę miesięcy nie musiał odkrywać tego na nowo.

Rozszerzenie przeglądarki

Pobieranie

Dla Chrome jest ono dostępne w webstore. Dla Opery jest ono dostępne w webstore. Dla Firefoxa NIE jest ono dostępne wśród rozszerzeń i instalowane jest ze strony GIIFa.

Linki do pobrania rozszerzenia są zdefiniowane w pliku szafirsdk-module.js dostarczanym przez KIR wraz z biblioteką.

Zadanie rozszerzenia

Rozszerzenie przeglądarki jest konieczne aby używać mechanizmu native messaging (patrz MDN). Ten mechanizm pozwala przegladarce na uruchomienie zewnętrznej aplikacji, z którą rozszerzenie może komunikować się wysyłając tekstowe komendy i odbierając tekstowe odpowiedzi na te komendy, ta komunikacja jest asynchroniczna!!!

Konsola Szafir SDK

Na stronach, które mają znacznik włączający rozszerzenie, w pobliżu paska adresu pojawia się granatowy kwadrat z ikoną „KIR”, po kliknięciu w niego można otworzyć konsolę Szafir SDK.

SzafirHost

Zewnętrzną aplikacją z którą komunikuje się rozszerzenie jest SzafirHost. Linki do pobrania aplikacji SzafirHost są zaszyte w rozszerzeniu. W chwili pisania tego wpisu były to: dla Windows, dla Linux i MacOS. Instalację dla MacOS opisałem w poprzednim wpisie instalacja w systemie Linux jest przeprowadzana analogicznie do instalacji w MacOS.

Zadania aplikacji

Aplikacja składa się z pliku SzafirHost.jar oraz skryptu uruchamiania SzafirHost.sh lub SzafirHost.bat który służy, do uruchomienia SzafirHost.jar z wykorzystaniem maszyny wirtualnej Java (JVM) zainstalowanej na komputerze użytkownika.

Prawdziwa magia aplikacji ukryta jest jednak w instalatorze, który dogrywa pliki manifestu aplikacji natywnej do konfiguracji przegladarki. Aplikacja natywna nazywa się pl.com.kir.szafirhost. Manifestu należy szukać w poniższych lokalizacjach: Chrome, Firefox patrz na NativeMessagingHosts.

Modyfikacja sposobu uruchamiania

Skrypty wykorzystują JVM dostępne na ścieżce uruchamiania. Można wskazać inną maszyną wirtualną Java poprzez poprzez modyfikację zmiennej systemowej PATH lub bezpośrednie wskazanie programu java lub java.exe.

Uruchomienie SzafirHost

  1. Rozszerzenie przeglądarki po wykryciu znacznika w kodzie strony dodaje zmienną globalą pozwalającą JS na stronie komunikować się z rozszerzeniem.

  2. JS wywołuje inicjalizację wywołuje połączenie z natywną aplikacją, na co przeglądarka reaguje uruchomieniem aplikacji wskazanej w pliku manifestu.

    Może się zdarzyć, że proces SzafirHost pracujący w tle zostanie ubity, co skutkuje błędem braku komunikacji z SzafirHost, Wystąpił błąd: Szafir SDK Chrome Host nie został uruchomiony, po wystąpieniu takiego błędu można jedynie zapisać XML z aktualnie edytowanego formularza, zamknąć wszystkie okna przeglądarki i ubić procesy przeglądarki, które pozostały w tle, o ile takie będą, a następnie ponownie uruchomić przeglądarkę (wylogowanie i ponowne zalogowanie użytkownika lub ponowne uruchomienie komputera również zadziała ale jest bardziej inwazyjne)

  3. JS przekazuje do rozszerzenia konfigurację, konfiguracja zawiera

    • URL z katalogiem, w którym na stronie GIIF znajdują się pliki Szafir SDK
    • nazwę manifestu versions.xml z listą plików do pobrania i ich wielkościami.
    • czy debugowanie jest włączone
    • czy używać proxy systemowych
    • adres proxy dla http
    • adres proxy dla https
    • lista nazw/adresów serwerów dla których nie należy używać proxy

    Pozycje zaznaczone italiką można ostrożnie modyfikować na teście, na produkcji. Ustawienia dla testu i dla produkcji są rozdzielne. Mechanizm do modyfikacji konfiguracji SzafirHost i pliku settings.xml jest zaszyty w kodzie JS stron giif.mofnet.gov.pl.

    Według mojego stanu wiedzy na dzieć 2019-11-27, SzafirHost nie jest wstanie przebić się przez proxy wymagające autoryzacji. Kod aplikacji został zabezpieczony przed dekompilacją, co znacznie utrudnia analizę.

  4. SzafirHost pobiera plik versions.xml, następnie pobiera do katalogu tymczasowego pliki tam wymienione.

  5. JS wysyła do SzafirHost plik settings.xml, zawiera on listę certyfikatów urzędów kwalifikowanych, listę certyfikatów wystawców UPO, wskazuje algorytm użyty do wyliczania sumy kontrolnej przy podpisie elektronicznym oraz listę bibliotek PKCS#11.

    Plik settings.xml można ostrożnie modyfikować na teście, na produkcji.

    Należy zwrócić uwagę, że przekazujemy URL do biblioteki a nie położenie pliku. Czyli zamiast: C:\Program Files (x86)\CryptoTech\CryptoCard\CCPkiP11.dll musimy wpisać: file:///C:/Program%20Files%20(x86)/CryptoTech/CryptoCard/CCPkiP11.dll. W elemencie URL można też wpisać samą nazwę biblioteki, w takim wypadku SzafirHost będzie jej szukał w katalogu tymczasowym do którego pobrał elementy Szafir SDK ze strony, a następnie w ścieżce wyszukiwania bibliotek (patrz na zmienną java.library.path w wywołaniu java -XshowSettings:properties -version).

  6. Do tak zainicjalizowanego SzafirHosta, JS wysyła żądanie podpisania danych.

    • SzafirHost iteruje po liście bibliotek PKCS#11, jeśli biblioteki nie ma we wskazanej lokalizacji lub na ścieżce, to w konsoli wyrzuca błąd otwarcia strumienia.
    • Dla każdej znalezionej biblioteki, wywołuje wyszukiwanie kart, jeżeli nie ma czytnika lub karty w czytniku, to w konsoli wyrzuca błąd TOKEN_NOT_FOUND.
    • Dla każdej znalezionej karty wywołuje wyszukiwanie certyfikatów, domyślnie ukrywa certyfikaty przeterminowane, nie pozwala na podpisywanie przeterminowanym certyfikatem.

  7. SzafirHost wyświetla okno podpisu, ze znalezionym certyfikatem (lub bez niego). A po podpisaniu zwraca wynik lub błąd do rozszerzenia (a ono do JS).

Problemy z SzafirHost

Po instalacji SzafirHost, rozszerzenie nadal domaga się instalacji SzafirHost

Najprawdopodobniej przeglądarka nie może uruchomić SzafirHost. Należy sprawdzić czy użytkownik może uruchomić skrypt startowy rozszerzenia, po starcie powinna wyświetlić się wersja rozszerzenie, np. 1.0.7 i kilka innych znaków.

Jeśli nie, to należy sprawdzić czy zainstalowano Java i czy użytkownik ma uprawnienia do uruchomienia tego programu.

Zatrzymuje się na pobieraniu versions.xml, „Trwa inicjalizowanie komponentów podpisu elektronicznego”.

Ten błąd widać na konsoli Szafir SDK wyłącznie po włączeniu debugowania.

SzafirHost nie może przebić się przez proxy, jeśli proxy wymaga autoryzacji to problem jest nie do przeskoczenia (trzeba dodać wyjątek na proxy dla żądań GET na adresy poniżej https://www.giif.mofnet.gov.pl/szafir/sdk_builds/build/). Jeśli proxy bez autoryzacji to można zmienić ustawienia.

W dialogu podpisu nie ma certyfikatów.

Kliknąć ‘Wybierz Certyfikaty’,

  • jeżeli nie znajduje karty, to należy:

    • Upewnić się czy karta jest włożona do czytnika.
    • Upewnić się czy czytnik jest dobrze podłączony do komputera (ekipa sprzątająca potrafi wysunać każdy kabel).

    jeżeli to nie pomogło, to można wskazać ręcznie bibliotekę PKCS#11 lub przystąpić do debugowania.

    • Sprawdzić w konsoli Szafir SDK czy biblioteki PKCS#11 zostały znalezione,
      • jeżeli nie zostały znalezione, to można zmodyfikować plik settings.xml aby je odnajdywał.
      • jeżeli zostały odnalezione, to trzeba sprawdzić w jakiej lokalizacji, może zdarzyć się, że 32 bitowe JVM odnalazło 64 bitowe biblioteki, lub 64 bitowe JVM odnalazło 32 bitowe biblioteki. Aby to naprawić należy posprzątać biblioteki, zmodyfikować settings.xml (wskazać bibliotekę w prawidłowej architekturze), lub zmodyfikować skrypt startowy (wskazać JVM w prawidłowej architekturze).

  • jeżeli znajduje kartę (nie wyświetla błędu braku karty), to być może na karcie są wyłącznie przeterminowane certyfikaty, należy wtedy zmienić kartę lub przedłużyć certyfikat. (tik w dialogu pozwala wyłączyć odfiltrowywanie przeterminowanych certyfikatów, po jego zaznaczeniu widać certyfikaty ale nadal nie można ich użyć).