https://pydyniak.pl RSS feed

Tworzenie klastra w Liferayu - przewodnik

Wed, 26 May 2021 00:00:00 GMT

Uwaga Poniższy artykuł jest tłumaczeniem oryginału z angielskiej wersji strony. Jeżeli interesują Cię tego typu tematy to polecam czytać wersje angielską z uwagi na to, że artykuły zawsze w pierwszej kolejności tworzone są tam, a strona polska czasami nawet bardzo długo jest "do tyłu".

Witaj! W tym artykule chciałbym zaprezentować możliwości stworzenia klastra w CMSie Liferay. W moim przykładowym środowisku użyję Dockera, aczkolwiek kroki będą analogiczne jeżeli po prostu instalujesz w sposób "tradycyjny" dwie instancje (lub więcej) na jednym serwerze lub kilku.

Postaram się pokazać cały proces tworzenia środowiska krok po prostu, tak abyś mógł jak najlepiej zrozumieć "jak to działa". Niemniej jednak gdybyś chciał od razu zobaczyć stworzone środowisko - jest ono dostępne na moim githubie.

Ważna sprawa - skupię się na konfiguracji Liferaya i prostocie całego środowiska. W związku z tym nie będę tworzył klastra bazy danych/Elasticsearcha/Load Balancera. Jeżeli byś tego potrzebował to rozszerzenie mojej konfiguracji powinno być dość proste, a w Internecie można znaleźć mnóstwo materiałów na te tematy. W moim przykładowym środowisku będzie jedynie podstawowa konfiguracja tych trzech, a klaster powstanie tylko dla Liferaya.

Wymagania wstępne

Aby rozpocząć będziesz potrzebował Dockera na swojej maszynie. Nie będę omawiał podstaw Dockera/konteneryzacji/Docker Compose więc dobrze by było abyś miał chociaż podstawowe pojęcie na ich temat, aczkolwiek nie jest to konieczne aby jako tako prześledzić artykuł.

Jeżeli planujesz "na bieżąco" tworzyć środowisko podczas czytania to możesz rozpocząć od stworzenia nowego katalogu z plikami/katalogami jak na screenie poniżej. Pliki oczywiście na tym etapie mogą być puste.

Początkowa struktura plików

W tym samym katalogu stwórz dwa foldery "portal-node-1" i "portal-node-2":

Początkowa struktura katalogów "deploy"

Docker storage - mountowanie, wolumeny (volumes)

Uwaga Po opublikowaniu wstępnej wersji tego postu pomyślałem o jednej dodatkowej kwestii - w poniższych instrukcjach użyłem "Docker volumes" do przetrzymywania niektórych danych (Elasticsearch/dokumenty Liferaya), a inne "zamountowałem" (katalogi deploy: portal-node-1/portal-node-2). Dodatkowo niektóre pliki (konfiguracyjne, jary, portal-ext.properties) kopiuję używając "Dockerfile", a niektórych danych (MySQL) nie zapisuję nigdzie.

To podejście oczywiście pokazuje różne możliwości, ale z drugiej strony powinienem wspomnieć o tym, że jest to podejście "pokazowe". Jeżeli planujesz stworzyć środowisko, które będzie realnie wykorzystywane to powinieneś najpierw zapoznać się ze wszystkimi możliwościami przechowywania plików. Prawdopodobnie najlepiej zacząć od dokumentacji Dockera. Jest to istotne gdyż każda metoda przechowywania danych ma swoje plusy i minusy.

Proces tworzenia środowiska

Kontenery Liferaya

Chcemy stworzyć klaster, a więc potrzebujemy dwóch lub więcej instancji Liferaya. W przypadku tego tutorialu użyję dwóch, ale użycie większej liczby jest analogiczne.

Tak więc od początku - jak w ogóle zacząć? Skoro chcemy użyć Docker Compose potrzebujemy stworzyć plik docker-compose.yml. Plik ten służy do definicji tego jakie kontenery chcemy mieć stworzone oraz opisuje to jak mają one zostać stworzone (np. gdzie chcemy przechować dane kontenera). Aby jednak rozpocząć pracę nad docker-compose.yml potrzebujemy obrazów dla naszych kontenerów. W większości użyjemy gotowych, już zbudowanych obrazów, ale w przypadku Liferaya stworzymy własny obraz, który rozszerzy oficjalny.

Aby tego dokonać tworzymy plik "Dockerfile-liferay" z następującą treścią:

FROM liferay/portal:7.0.6-ga7
MAINTAINER Rafal Pydyniak <rafal@pydyniak.pl>

COPY ./configs/portal-ext.properties $LIFERAY_HOME/
COPY ./configs/\*.config $LIFERAY_HOME/osgi/configs/
COPY ./configs/\*.jar $LIFERAY_HOME/osgi/portal/

Tak więc tworzymy nasz własny obraz na bazie oficjalnego w wersji 7.0.6 GA7. Użyłem takiej wersji, ale wszystkie 7+ będą działały podobnie. W naszej wersji obrazu dodajemy kopiowanie portal-ext.properties do katalogu LIFERAY_HOME a także kopiujemy niezbędne konfiguracje/JARy o czym będzie później. Moglibyśmy oczywiście zamiast tego zmapować nasz dysk na dysk kontenera, ale dla przykładu użyjemy tej metody szczególnie, że pliki konfiguracyjne/JARy nie będą się zmieniały w czasie. Prawdopodobnie co do portal-ext.properties lepiej byłoby go zmapować, ale póki co zostawmy to w ten sposób.

Jeżeli chciałbyś przetestować obraz możesz to zrobić budując go, uruchamiając a następnie łącząc się do kontenera. Następnie możesz zweryfikować czy pliki rzeczywiście zostały skopiowane. Poniższe komendy pomogą Ci w tym zadaniu:

docker build -t my-liferay-7-tutorial -f Dockerfile-liferay . # budujemy "Dockerfile-liferay". Stworzony obraz będzie się nazywał "my-liferay-7-tutorial". Kropka na końcu służy do wskazania tak zwanego "context directory" czyli katalogu, który ma być "wyjściowym" między innymi przy kopiowaniu w komendach COPY.
docker run -d my-liferay-7-tutorial # Uruchamiamy stworzony obraz
docker exec -it CONTAINER_NAME /bin/bash # Podłączamy się do kontenera, tak aby przetestować czy wszystko działa poprawnie. Odpowiednią nazwę kontenera (do podstawienia pod CONTAINER_NAME) możesz sprawdzić używajć komendy docker container ls.

Komentarze do komend opisują działanie.

Stwórzmy docker-compose.yml i wykorzystajmy nasz obraz

Kolejnym krokiem będzie stworzenie kontenerów Liferaya czyli naszych instancji. Wykorzystamy do tego wspomniany wcześniej docker-compose.yml. Pierwsza wersja tego pliku poniżej:

version: '3.3'
services:
  liferay-portal-node-1:
    build:
      context: .
      dockerfile: Dockerfile-liferay
    ports:
      - '6080:8080'
      - '21311:11311'
    hostname: liferay-portal-node-1.local
    volumes:
      - lfr-dl-volume:/opt/liferay/data/document_library
      - ./deploy/portal-node-1:/opt/liferay/deploy
    depends_on:
      - mysql
      - es-node-1
  liferay-portal-node-2:
    build:
      context: .
      dockerfile: Dockerfile-liferay
    ports:
      - '7080:8080'
      - '31311:11311'
    hostname: liferay-portal-node-2.local
    volumes:
      - lfr-dl-volume:/opt/liferay/data/document_library
      - ./deploy/portal-node-2:/opt/liferay/deploy
    depends_on:
      - mysql
      - liferay-portal-node-1
      - es-node-1
volumes:
  lfr-dl-volume:

Zdefiniowaliśmy więc dwie instancje Liferaya:

liferay-portal-node-1
liferay-portal-node-2

wykorzystując stworzony wcześniej obraz oraz ustawiając aktualny katalog jako "context" (wykorzystywany do wskazania skąd obraz ma brać pliki). Dodatkowo definiujemy porty, które mają być dostępne poza kontenerem. W ramach przypomnienia: zapis "6080:8080" oznacza, że port 8080 wewnątrz kontenera będzie dostępny na porcie 6080 "na zewnątrz". Tak więc wszystkie dostępne porty to:

6080 - instancja nr 1 (node1)
7080 - instancja nr 2 (node2)
21311 - gogo shell (do obsługi OSGI) instancji nr 1
31311 - gogo shell (do obsługi OSGI) instancji nr 2

Ustawiamy również hostname dla naszych instancji, tak aby móc je rozróżnić oraz używamy volumes do dwóch rzeczy:

Przechowywania danych documents & media jako wolumen dockerowy. Używamy tego samego wolumenu dla obu instancji dzięki czemu pliki są współdzielone między instancjami. Jest to krok wymagany przy klastrowaniu w Liferayu
Mapujemy nasze lokalne deploy/portal-node-X na katalog deploy w kontenerze. W ten sposób możemy łatwo deployować nasze moduły bezpośrednio do kontenerów

Na końcu definiujemy także wszystkie nasze wolumeny - póki co jedynie "lfr-dl-volume"

Możesz także zwrócić uwagę na fragment "depends_on". Jest to po prostu deklaracja tego, który kontener "zależy" od którego. W ten sposób możemy zdefiniować, że chociażby nasze instancje Liferaya nie powinny startować przed bazą danych czy Elasticsearchem co powodowałoby błędy. Na ten moment oczywiście nie mamy w ogóle zdefiniowanej bazy/Elasticsearcha, ale niedługo do tego przejdziemy.

Documents & media

Warto zwrócić uwagę, że produkcyjnie prawdopodobnie powinieneś użyć "Advanced File System Store" jako repozytorium danych zamiast domyślnego "simple". W tym wypadku użyłem opcji domyślnej. Zmiana na "Advanced..." jest zalecana, aczkolwiek nie wymagana do klastrowania. Jeżeli chciałbyś dowiedzieć się więcej o repozytoriach danych w Liferayu możesz sprawdzić ten artykuł.

Konfiguracja bazy danych

Do uruchomienia Liferaya niezbędna jest baza danych (nie chcemy używać "domyślnej" i "wbudowanej" H2). W docker-compose dodajemy poniższy blok:

mysql:
    image: mysql:5.6
    environment:
      MYSQL_ROOT_PASSWORD: my-secret-pw
      MYSQL_DATABASE: lportal
    ports:
      - "33066:3306"

Jest on raczej dość jasny. Używamy oficjalnego obrazu, udostępniamy porty oraz ustawiamy hasło dla roota i tworzymy bazę danych przez zmienne środowiskowe. W tym wypadku używam MySQL, ale równie dobrze możesz użyć dowolnej innej - w większości wypadków z łatwością znajdziesz odpowiedni obraz na DockerHub

Musimy oczywiście również zdefiniować połączenie do naszej bazy danych w samym Liferayu. Aby tego dokonać używamy pliku konfiguracyjnego portal-ext.properties. Plik ten kopiowany jest do kontenera podczas tworzenia naszego obrazu co zdefiniowaliśmy wcześniej. Konfiguracja bazy będzie następująca:

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://mysql:3306/lportal
jdbc.default.username=root
jdbc.default.password=my-secret-pw

Możesz oczywiście dodać tutaj dowolne inne wpisy konfiguracyjne tak jak byś to zrobił w kazdym innym przypadku. Wrócimy jeszcze do tego pliku później, podczas konfiguracji klastra.

Uwaga: Jak wspominałem wcześniej - w powyższej konfiguracji nigdzie nie przechowujemy danych bazy danych. Usunięcie kontenera spowoduje utrate danych. Aby tego uniknąć możesz stworzyć volume (zobacz konfiguracje Elasticsearch dla przykładu) lub stworzyć dodatkowy katalog i zmapować go:

volumes:  
- ./data/mysql:/var/lib/mysql

Konfiguracja Elasticsearch

Jednym z kroków tworzenia klastra, opisanym w dokmentacji, jest instalacja osobnej instancji Elasticsearch (ES). W związku z faktem, że tworzymy klaster nie możemy użyć "wbudowanego", gdyż wszystkie nasze instancje muszą komunikować się z tym samym serwerem ES (lub serwerami w klastrze ES). W naszym wypadku potrzebujemy wersji 2.4.6, ale jeżeli używasz innej wersji Liferaya możesz potrzebować innej. Sprawdź artykuł opisujący instalacje instancji ES gdzie opisany jest proces sprawdzania wersji.

Gdy już znajdziesz odpowiednią wersje musisz dodać tworzenie serwera ES do pliku docker-compose.yml. W moim przypadku w wersji 2.4.6 wygląda to jak poniżej:

es-node-1:
    image: elasticsearch:2.4.6-alpine
    environment:
      - cluster.name=elasticsearch
      - bootstrap.memory_lock=true
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - esdata1:/usr/share/elasticsearch/data
    ports:
      - 9200:9200

Czyli po raz kolejny. Na początku definiujemy obraz, którego chcemy użyć. Następnie mamy dodatkowe opcje konfiguracyjne, które są raczej dość jasne np. ustawienia pamięci oraz kilka ustawień, które mogą być mniej jasne, ale łatwo odnaleźć ich znaczenie w google (szczególnie ulimits). Istotna część to "cluster.name" - musi być ona unikalna dla twojego środowiska, ale jednocześnie może to być dowolny String. W naszym wypadku oczywiście dowolna nazwa będzie unikalna, ale jeżeli przykładowo na jednym serwere masz dwa środowiska (np. DEV i TEST) to musisz zwrócić uwagę, aby instancje ES miały inne cluster.name, tak aby można było je rozróżnić.

Możesz też zauważyć, że używamy wolumenu dockerowego o nazwie esdata1. Pamiętajmy, że musimy dodać jego definicje również na końcu naszego docker-compose. Nasza definicja wolumenów będzie teraz wyglądała następująco:

volumes:
  lfr-dl-volume:
  esdata1:

Użycie zewnętrznego Elasticsearcha w Liferayu

Skonfigurowaliśmy naszą instancje ES, a teraz musimy jej jeszcze użyć w Liferayu. Aby tego dokonać użyjemy pliku konfiguracyjnego OSGI. Stwórzmy plik o nazwie "com.liferay.portal.search.elasticsearch.configuration.ElasticsearchConfiguration.config" w katalogu "configs" o następującej zawartości:

operationMode="REMOTE"
transportAddresses="es-node-1:9300"
clusterName="elasticsearch"

Kod ten sprawia, że Liferay będzie używał zewnętrznej instancji ES zamiast wbudowanej. Ustawiamy również wcześniej zdefiniowany clusterName oraz adress naszej instancji ES. Jeżeli zastanawiasz się dlaczego używamy es-node-1:9300 a nie jakiegoś adresu IP typu 127.0.0.1 czy localhost to jest tak dlatego, że wszystkie serwisy zdefiniowane w docker-compose są w tej samej sieci dockerowej, a co za tym idzie są przez siebie osiągalne przez ich nazwę kontenera. Bindowanie adresów jest obsługiwane przez samego Dockera - generalnie dodawane są odpowiednie wpisy w pliku /etc/hosts.

Nic więcej nie musimy robić, gdyż już wcześniej zdefiniowaliśmy, że wszystkie pliki konfiguracyjne mają być kopiowane do LIFERAY_HOME/osgi/configs - zrobiliśmy to w naszym obrazie Liferaya.

Używamy wersji "multiple" niektórych modułów

W Liferayu 7.0 CE, którego używamy na potrzeby tego artykułu musimy dokonać dodatkowego kroku opisanego tutaj. Generalnie domyślnie ta wersja Liferaya nie wspiera uruchamiania w trybie klastra. Aby dodać tą funkcje musimy "podmienić" trzy moduły:

com.liferay.portal.cache.single
com.liferay.portal.cluster.single
com.liferay.portal.scheduler.single

Na odpowiednie wersje z końcówką "multiple". Te domyślne jednocześnie musimy zdezaktowywać. W artykule wspomnianym wyżej opisane są kroki kompilacji tych modułów więc nie będę wchodził w szczególy. Opiszę jedynie co gdy już je zdobędziemy.

Uwaga: Jeżeli również używasz wersji 7.0.6 to możesz te moduły po prostu pobraż z przykładowego repozytorium GITa, które podawałem wcześniej

Uwaga 2: Możliwe, że w ogóle nie potrzebujesz wykonywać tych kroków jeżeli Twoja wersja już wspiera moduły w wersji "multiple". Jeżeli używasz Liferaya w wersji DXP to z pewnością tak jest. Jeżeli wersji CE to możesz to sprawdzić w gogo shellu - po prostu uruchom komendę "lb portal.scheduler" i sprawdź czy jest uruchomiony moduł "Liferay Portal Scheduler Multiple". Jeżeli tak to pomiń ten krok.

Gdy już masz wersje "multiple" modułów musisz:

zdeployować je do katalogu "configs" w kontenerze - stworzony przez nasz obraz Liferaya to zrobi. Wystarczy, że wrzucisz moduły do katalogu "configs"
włączyć ignorowanie wersji "single" - aby tego dokonać stwórz nowy plik "com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config" w katalogu "configs" z następującą treścią blacklistBundleSymbolicNames="com.liferay.portal.cache.single,com.liferay.portal.cluster.single,com.liferay.portal.scheduler.single"

Obraz Dockerfile-Liferay zrobi resztę czyli skopiuje pliki do odpowiednich katalogów.

Włączenie klastra

Ok, przygotowaliśmy już dość dużo, ale nadal nie dodaliśmy żadnych ustawień odnośnie klastrowania do samego Liferaya. Na szczęście ten krok będzie bardzo prosty - jedyne co musimy zrobić to dodać poniższą linijkę do pliku portal-ext.properties:

cluster.link.enabled=true

Czy to wystarczy? Okazuję się, że tak - przynajmniej w niektórych przypadkach. Generalnie ustawienie te sprawia, że instancje Liferaya zaczynają używać kanału JGroups do komunikacji między sobą na domyślnych IP i portach. Komunikacja odbywa się za pomocą połączenia UDP multicast co jest bardzo istotne gdyż zadziała to tylko jeżeli instancje są w stanie komunikować się za pomocą multicasta. Niestety nie zawsze tak jest. Nawet jeżeli Twoje serwery są w tej samej podsieci to i tak komunikacja przez multicasta może nie działać. Przykładowo Azure nie wspiera multicasta w swoich wirtualnych sieciach i nie ma planów na dodanie tego, przynajmniej gdy to sprawdzałem jakiś czas temu. W takim wypadku najlepiej sprawdzić dokumentacje Liferaya gdzie opisane są inne metody - sam korzystałem z opcji unicasta przez TCP i nie jest to specjalnie trudne - dochodzi jedynie drobna konfiguracja.

W naszym wypadku jednak takie rozwiązanie jest jak najbardziej wystarczające, gdyż serwisy w ramach jednego docker-compose.yml mogą komunikować się przy użyciu multicasta.

Ostatnia rzecz, którą możemy dodać do pliku portal-ext.properties to:

web.server.display.node=true

Konfiguracja ta sprawi, że każda instancja w klastrze będzie wyświetlać informacje o tym jaki to serwer. Jest to przydatne, gdyż normalnie wchodząc na wspólny adres nie wiemy z którym serwerem się łączymy. Informacja taka przydaję się do testów tego czy klaster rzeczywiście działa.

Jeżeli chcesz poczytać więcej o tym jak działa komunikacja to najlepiej sprawdzić oficjalną dokumentacje. Jest to dość proste i kilka minut powinno wystarczyć, żeby zrozumieć idee.

Load balancing

Wstęp

Od razu zaznaczę - krok ten jest w pełni opcjonalny. Nasza konfiguracja da nam dwie instancje na dwóch różnych portach. Jeżeli robisz to np. na serwerze to możesz już mieć jakiegoś load balancera czy serwer HTTP (np. Apache/Nginx) i wtedy konfiguracje powinieneś najlepiej przeprowadzić tam a nie dodawać kolejną warstwę w Docker Compose. Jeżeli jednak nie masz niczego co mogłoby posłużyć za reverse proxy i load balancera to pokaże jak dodać load balancing przy użyciu HAProxy, który zdefiniujemy jako kolejny serwis w Docker Compose.

Uwaga jeżeli pomijasz ten krok i chcesz dokonać konfiguracji sam to należy zwrócić uwagę, że do działania niezbędne jest ustawienie tak zwanego "sticky session". Odpowiednie instrukcje na pewno znajdziesz w dokumentacji danego narzędzia.

Konfiguracja Dockerowa

Jeżeli jednak wybierasz load balancing po stronie Docker Compose to poniżej przedstawiam niezbędne kroki. Load balancing jest potrzebny bo oczywiście nie chcemy, aby user sam musiał wybierać odpowiedni serwer, a zamiast tego powinien móc wejść na jeden wspólny adres np. app.pydyniak.com (nic tam nie ma, nie musisz sprawdzać ;)). Rozdzielanie ruchu powinno nastomiast działać "w tle". Poniższy diagram pokazuje mniej więcej idee rozwiązania:

Diagram architektury

Tak jak wspominałem ja użyję HAProxy, ale możesz użyć dowolnego innego narzędzia. Krok ten jest zupełnie niezależny od Liferaya. Jedyne co to należy ustawić sticky session - patrz uwaga wyżej

A więc tak: tworzymy kolejny obraz - tym razem o nazwie "Dockerfile-haproxy" i kopiujemy poniższą konfiguracje:

FROM haproxy:2.3.4
COPY ./configs/haproxy.cfg /usr/local/etc/haproxy/haproxy.cfg

Nie ma tutaj raczej nic specjalnego. Tworzymy po prostu nasz obraz na bazie oficjalnego obrazu haproxy:2.3.4 i dodajemy kopiowanie pliku konfiguracyjnego. Jest to sposób zalecany zresztą w dokumentacji obrazu na Docker Hubie. Następnie definiujemy tworzenie naszego serwisu HAProxy w pliku docker-compose.yml:

haproxy:
    build:
      context: .
      dockerfile: Dockerfile-haproxy
    ports:
      - '80:80'
    hostname: lb-haproxy.local

Wskazujemy więc na nasz obraz (dockerfile) i używamy aktualnego katalogu jako kontekstu. Mapujemy też port wewnątrz kontenera (80) na port naszej maszyny (również 80). Ustawiamy też hostname.

Teraz czas na wspomniany wcześniej plik haproxy.cfg, którego kopiowanie zdefiniowaliśmy w Dockerfile. Tworzymy więc ten plik i wrzucamy następującą konfiguracje:

global
   stats timeout 30s
   daemon

defaults
   log global
   mode http
   option httplog
   option dontlognull
   timeout connect 5000
   timeout client 50000
   timeout server 50000

frontend http_front
   bind 0.0.0.0:80
   default_backend http_back

backend http_back
   balance roundrobin
   cookie JSESSIONID prefix
   server liferay-portal-node-1 liferay-portal-node-1:8080 check cookie s1
   server liferay-portal-node-2 liferay-portal-node-2:8080 check cookie s2

Jest to dość długa konfiguracja, ale co najważniejsza robi to czego potrzebujemy. Najważniejsze linijki są na końcu i zaczynają się od "backend http_back". W linijkach tych robimy dwie rzeczy:

Ustawiamy sposób rozdzielania ruchu na roundrobin - jest to po prostu jeden ze standardowych sposobów dzielenia ruchu, w którym kolejne żądania są na zmiane przydzielane do serwerów. Dokładny opis można oczywiście znaleźć chociażby na Wikipedii
Definiujemy nasze serwery oraz używamy wspomnianego wcześniej "sticky session". Jeżeli nie wiesz czym sticky session jest to już tłumaczę - chodzi o to, że jeżeli user wejdzie na naszą stronę i trafi przykładowo na NODE2 (drugą instancje) to będzie przydzielony do tego samego serwera przez cały czas trwania sesji. Jest to niezbędne, gdyż sesja nie jest dzielona czy też kopiowana między instancjami Liferaya. Dokładniejszy opis jak sticky session działa w HAProxy można znaleźć w artykule na blogu HAProxy - zachęcam do przejrzenia. Idea jest bardzo prosta więc jeżeli nigdy wcześniej nie miałeś z tym do czynienia to warto poczytać.

Uruchamiamy nasz klaster

W końcu koniec. Zdefiniowaliśmy wszystko czego potrzebowaliśmy. Mam nadzieję, że opis był zrozumiały i wiesz dlaczego zrobiliśmy to co zrobiliśmy. Teraz potrzebujemy uruchomić nasze środowisko. Możemy tego dokonać komendami poniżej:

docker-compose build # budujemy nasze całe środowisko
docker-compose up -d liferay-portal-node-1 # uruchamiamy pierwszy serwer
# Czekamy aż wystartuje. Możesz sprawdzić docker-compose logs, aby zwalidować na jakim etapie jest start serwera
docker-compose up -d liferay-portal-node-2 # uruchamiamy drugi serwer
docker-compose up -d haproxy # uruchamiamy nasze Reverse Proxy

Podczas uruchamiania możemy sprawdzić logi (docker-compose logs) i zweryfikować, że rzeczywiście instancje komunikują się między sobą:

liferay-portal-node-1_1  | 2021-01-24 23:10:59.862 INFO  [Incoming-2,liferay-channel-control,liferay-portal-node-1-3920][JGroupsReceiver:90] Accepted view [liferay-portal-node-1-3920|1] (2) [liferay-portal-node-1-3920, liferay-portal-node-2-36188]
liferay-portal-node-1_1  | 2021-01-24 23:11:00.057 INFO  [Incoming-2,liferay-channel-transport-0,liferay-portal-node-1-47303][JGroupsReceiver:90] Accepted view [liferay-portal-node-1-47303|1] (2) [liferay-portal-node-1-47303, liferay-portal-node-2-30594]

Jeżeli po uruchomieniu wszystkiego wejdziesz na serwer na port :80 zobaczysz, że zostałeś połączony do jednej z dwóch instancji (jeżeli oczywiśćie dodałeś wyświetlanie wiadomości o czym było wcześniej):

Informacja o tym na którym jesteśmy serwerze

Możesz też spróbować połączyć się do serwera z innej przeglądarki - prawdopodobnie zostaniesz połączony tym razem do drugiej instancji. Jeżeli tak to super - udało się. Niestety to nie koniec testów. Na ten moment wiemy, że:

W teorii mamy połączenie między serwerami (patrząc na logi)
HAProxy wydaję się działać bo jesteśmy przekierowywani na odpowiednie instancje. Można ewentualnie też sprawdzić cookiesy, aby to potwierdzić (szczegóły we wspomnianym wcześniej artykule o tym jak działa sticky session w HAProxy)

W praktyce nadal jednak powinniśmy dokonać kolejnych testów przykładowo:

Czy działa Elasticsearch - czy jeżeli dodamy jakiś content na node1 to czy będzie można go wyszukać na node2?
Czy połączenie rzeczywiście działa? Czy jeżeli dodamy jakiś content na node2 to czy będzie widoczny na node1?
Czy pliki Documents & Media rzeczywiście są współdzielone? Czy plik dodany na jednej z instancji będzie widoczny na drugiej?
Czy jeżeli zatrzymamy jedną z instancji - czy ruch zostanie odpowiednio przekierowany do drugiej?

Oczywiście możesz też pomyśleć o innych testach szczególnie jeżeli planujesz uruchomić podobną konfiguracje na produkcji.

Wydajność

Jeżeli uruchomisz środowisko to możesz zauważyć, że serwery nie są zbyt szybkie. Powód tego jest prosty - nie zmienialiśmy żadnych ustawień pamięci, a domyślne są dość niskie. Możesz dodać więcej pamięci poprzez stworzenie pliku configs/setenv.sh. Zawartość tego pliku można skopiować z serwera, a następnie jedynie nadpisać ustawienia dla pamięci. Następnie musisz jeszcze dodać odpowiedni wpis COPY w Dockerfile-liferay - plik ten musi być kopiowany do /opt/liferay/tomcat-8.0.32/bin/ ($LIFERAY_HOME/tomcat-8.0.32/bin/). W przykładowym repozytorium krok ten został dodany więc możesz podejrzeć jak zostało to zrobione. Dodatkowa rzecz, którą należy wziąć pod uwagę - możliwe, że potrzebne będzie zwiększenie zasobów dostępnych Dockerowi, gdyż domyślnie są one mocno ograniczone.

Na koniec

Mam nadzieję, że artykuł był zrozumiały. Całość trochę się rozciągnęła i powstało dość dużo tekstu, ale starałem się jak najbardziej wytłumaczyć co zrobiłem i dlaczego w taki a nie inny sposób. Sam projekt Docker Compose jest dość niewielki więc jeżeli tylko rozumiesz podstawy Dockera to myślę, że nie powinno być problemu z jego uruchomieniem. W artykule tym użyłem wersji 7.0.6, ale kroki są analogiczne również dla innych wersji. Raz jeszcze przypominam, że cały kod można znaleźć na repozytorum na Githubie

Jeżeli masz jakiekolwiek pytania jak zawsze zachęcam do kontaktu.

Dlaczego migracje projektów Liferayowych na wyższą wersje nie są proste cz. 2

Wed, 06 Jan 2021 00:00:00 GMT

Witam! W pierwszej części Dlaczego migracje projektów Liferayowych na wyższą wersje nie są proste przedstawiłem jak mniej więcej w ogóle wyglądają migracje w projektach Liferayowych oraz pokazałem kilka przykładów potencjalnych problemów, które mogą nas spotkać przy migracji bazy danych. W tej części postaram się pokazać kilka problemów, które mogą się pojawić podczas migrowania samego kodu czyli naszych customowych modułów m.in. portletów.

Jak migrować kod

Ale na początku - jak w ogóle zabrać się za migracje kodu? No więc zacznijmy od tego, że jeśli zdecydowałeś się rozpocząć migracje swojego projektu to punktem startowym powinna być oficjalna dokumentacja. Przede wszystkim jest kilka ścieżek i przykładowo inaczej migruje się projekt 6.x (lub wcześniejszy) a inaczej projekt, którego wersja już jest w wersji 7.x i tylko chcemy podnieść wersje do najnowszej. Ogólne zasada oczywiście jest taka, że im wyżej jesteśmy tym łatwiej będzie zmigrować. Jednocześnie im więcej mamy kodu, który wykorzystuje API Liferaya tym więcej problemów może nas spotkać. Niemniej jednak polecam rozpocząć właśnie od dokumentacji bo nakreśli ona schemat działania. Oczywiście niektóre rzeczy można by przedstawić inaczej i prawdopodobnie schemat migracji można by zmienić, aczkolwiek nie o tym ma być ten wpis.

Błędy, które mogą nas spotkać.

No więc co takiego złego może nas spotkać podczas migracji? Zdecydowanie największym problemem podczas migracji kodu jest to, że niestety nie wszystkie zmiany są udokumentowane (chociażby w tak zwanych "Breaking changes"), a jeśli są to nie wystarczająco dobrze. Co w takim razie możemy zrobić? Niestety zostaje nam przejść przez migracje oraz uczyć się na bieżąco. Oczywiście na wiele z problemów znajdziemy jakieś rozwiązania, sami też możemy zapytać na forum, a jeśli mamy wersje DXP to nawet próbować z oficjalnym wsparciem. Niemniej jednak musimy być na to gotowi. Z dobrych wiadomości mam to, że kilka z takich rzeczy (zarówno drobnostek jak i tych bardziej uciążliwych) postaram się przedstawić poniżej, tak abyście mogli się uczyć na cudzych (moich) błędach.

Uwaga! Błędy te znalazłem jakiś czas temu. Może w momencie czytania (a nawet publikacji tego postu) niektóre z tych rzeczy już są w breaing changes - nie sprawdzałem tego. Niemniej jednak pisałem w swoim czasie kilka postów na forum Liferay więc kto wie, może zostało coś dodane.

Zmiana API do pobierania zdjęć w Web Contentach

Zacznijmy od tego jak wyglądał wpis XML dla zdjęcia w Web Content:

<dynamic-content language-id="en_US" alt="" name="XXX.png" title="XXX.png" type="document" [url=http://fileEntryId="12345"><![CDATA[/documents/111/222/XXX.png/QQQQQQ-WWWW-EEEE-CCCC-DDDDDDD?t=1588696601862]]></dynamic-content>

Natomiast dla porównania 7.2:

<dynamic-content [url=http://language-id="en_US"><![CDATA[{"groupId":"126435","alt":"","name":"XXX.png","title":"XXX.png","type":"journal","uuid":"QQQQ-WWW-EEE-CCC-ec48068bbf39","fileEntryId":"716022","resourcePrimKey":"716460"}]]></dynamic-content>

Jaka jest różnica? No więc kluczowy jest brak ścieżki pliku. Zamiast tego mamy JSON'a z kilkoma informacjami o naszym zdjęciu. Jaki w tym problem? No więc taki, że częstym podejściem w 7.0 było pobieranie ścieżki do zdjęcia w następujący sposób:

final com.liferay.portal.kernel.xml.Document document = SAXReaderUtil.read(article.getContentByLocale(locale.toString()));

final String imageUrl = document.valueOf(``"//dynamic-element[@name='Image']/dynamic-content"``);

W wersji 7.2 robiąc w ten sposób kończymy z pobraniem JSON'a, który następnie ląduje w naszym SRC:

Aby do tego nie dopuścić musimy zmienić nasz kod na następujący (przykładowo):

final com.liferay.portal.kernel.xml.Document document = SAXReaderUtil.read(article.getContentByLocale(locale.toString())); final String imageJsonString = document.valueOf("//dynamic-element[@name='Image']/dynamic-content"); JSONObject imageJsonObject = JSONFactoryUtil.createJSONObject(imageJsonString); FileEntry fileEntry = PortletFileRepositoryUtil.getPortletFileEntry(imageJsonObject.getLong("fileEntryId")); String imageUrl = PortletFileRepositoryUtil.getDownloadPortletFileEntryURL(serviceContext.getThemeDisplay(), fileEntry, StringPool.BLANK);

Analogiczna zamiana może być potrzebna np. w naszym templacie napisanym w FTL, aczkolwiek przełożenie powyższego kodu Javowego nie powinno być problemem.

Warto zobaczyć ten wpis na blogu Liferaya, w którym możemy wyczytać, że zmiana ta została przeprowadzona bo developerzy sądzili, że nikt z tego i tak nie korzysta. Niestety brakuje także lepszej alternatywy w postaci np. API dzięki, któremu programiści w ogóle nie musieliby się przejmować takimi szczegółami implementacyjnymi i wspomniane rozwiązanie wielokrotnie było sugerowane jako najlepsze.

Zmiana pól w Search API

W Liferayu 7.2 czy też 7.1 nastąpiła zmiana w nazewnictwie pól w Search API. Zmiana polega na tym, że w 7.0 pole w klasie

com.liferay.portal.kernel.search.Document

Wyglądało mniej więcej tak:

ddm__keyword__328630__PublicationDate_en_US_String_sortable

W wyżej wersji natomiast wygląda tak:

ddm__keyword__328630__PublicationDate_String_sortable

Różnica? Fragment _en_US. Oczywiście ma to pewien sens - nie tłumaczymy raczej pola PublicationDate i stąd niepotrzebne rozróżnienie. Niemniej jednak może się okazać, że wyszukując w naszym np. portlecie używamy tego fragmentu w jakimś kontekście i nasz kod przestanie działać poprawnie. Słowa kluczowe dla wyszukiwania tego typu problemów to "indexSearchHelper", "Document" czy "SearchContext" a przykładowy fragment kodu może wyglądać tak:

final BooleanQuery publicationDateQuery = new BooleanQueryImpl(); publicationDateQuery.addRangeTerm(String.format(PUBLICATION_DATE_TERM_FIELD_PATTERN, newsDescriptionStructureId), sdf.format(from), sdf.format(to)); indexSearcherHelper.search(searchContext, publicationDateQuery).getDocs()

Gdzie nasz pattern to:

private static final String PUBLICATION_DATE_TERM_FIELD_PATTERN = "ddm__keyword__%s__PublicationDate_%s";

Czyli możemy wyszukiwać po nazwie pola (patrz addRangeTerm) i podawać tam nazwę pola wraz z naszym fragmentem odnośnie języka. Sam kod nadal będzie działać i nie dostaniemy żadnych błędów natomiast rezultat będzie inny gdyż wyszukujemy po nazwie pola, która nie istnieje (bo została zmieniona).

Błąd ten jest pewnie z tych rzadszych bo Search API nie jest pewnie aż tak popularne niemniej jednak może być ciężki do znalezienia ze względu na brak jakichkolwiek komunikatów o błędzie.

Uprawnienia do podglądu Webcontentów

Kolejna zmiana, której nie doszukałem się w breaking changes.

Zdjęcie widoku uprawnień dla Web Contentów

Mając webcontent z uprawnieniami jak na screenie powyżej nasz portal może zachować się różnie w zależności od wersji. Ma to związek z jednym z ustawień Liferaya dostępnym pod (w 7.2):

Control panel → configuration → system settings → web content

Konfiguracja ta nosi nazwe "Article view permissions check enabled" i za jej pomocą możemy ustawić czy Liferay powinien weryfikować uprawnienie "View" dla Web Contentów czy nie. Czyli:

Mamy przełącznik wyłączony - każdy może obejrzeć nasz WebContent chociaż uprawnienia (patrz screen wyżej) wskazują, że jedynie Owner powinien mieć taki dostęp
Mamy przełącznik włączony - weryfikacja następuje i rzeczywiście przykładowo Guest nie ma dostępu do WebContentu

Zmianą między wersjami jest to, że w wersji 7.0 domyślnie to ustawienie jest wyłączone (każdy ma dostęp), natomiast w wersji 7.2 jest domyślnie włączone.

Możemy więc mieć niespodziankę - wcześniej każdy mógł oglądać nasze WebContenty a teraz nikt nie może. Oczywiście zakładając, że nie definiowaliśmy tych uprawnień wcześniej.

Zmiana metody do pobrania aktualnego URLa w FTLu

W wersji 7.0.x mogliśmy pobierać aktualny URL używając następującego kodu:

url = request.attributes['CURRENT_URL']

Po podniesieniu naszego kodu już niestety to nie zadziała. Zamiast tego możemy użyć

url = portalUtil.getCurrentURL(request)

To akurat drobnostka, ale również nieudokumentowana.

Czy to wszystko?

Oczywiście nie. Powyższe przykłady to kilka błędów, które możemy spotkać. Niemniej jednak błędy przede wszystkim z Search API oraz z pobieraniem adresów zdjęć uważam za te idealnie pokazujące niespodziewane problemy, które mogą nas spotkać. Dla kontrastu dodałem także dwa błędy, które są zdecydowanie prostsze do znalezienia i poprawnienia, tak aby pokazać, że nie wszystkie błędy są aż tak strasznie ukryte (szczególnie jak w przypadku zmiany w Search API).

Mam nadzieję, że powyższy wpis choćiaż trochę pomoże Ci podczas migracji.

Pozdrawiam!

Dlaczego migracje projektów Liferayowych na wyższą wersje nie są proste

Sun, 18 Oct 2020 00:00:00 GMT

Cześć! W dzisiejszym wpisie chciałbym poruszyć temat migracji projektów Liferayowych między wersjami, a dokładniej przedstawić bolączki z tym związane w oparciu o własne doświadczenia. Osobiście uczestniczyłem w migracji kilku projektów - zarówno z wersji 6.2 do 7.x jak i z wersji 7.0 do 7.2 (tutaj dodatkowo z wersji CE na wersje DXP). Dodatkowo migracje te obejmowały całe spektrum "przypadków" jeśli chodzi o wielkość - były to małe moduły z dosłownie kilkoma portletami, średnie projekty z kilkoma encjami bazodanowymi i kilkunastoma portletami, ale także był jeden projekt, który zawierał dużo ponad 100 portletów i encji bazodanowych.

Właśnie na bazie tych doświadczeń chciałbym pokazać kilka przykładów tego na jakie problemy możemy się natknąć podczas migracji. Chciałbym przez to uczulić Ciebie na to, aby nie ufać w to, że automatycznie uda Ci się zmigrować projekt bo najprawdopodobniej tak nie będzie. Powiem więcej - sam musiałem w niektórych przypadkach debugować kod Liferaya bo niestety w wielu przypadkach nie pomagała ani dokumentacja, ani istniejące tematy na forum ani nawet zadanie własnego pytania. Oczywiście jeśli masz wersje DXP to jest szansa, że otrzymasz oficjalne wsparcie, aczkolwiek z doświadczenia wiem, że niewielka część portali oparta jest na płatnej wersji co, ze względu na koszty, jest całkiem zrozumiałe.

Od razu ostrzegam, że nie będzie w tym wpisie zbyt dużo kodu czy rzeczywistych przykładów bo po prostu odtworzenie ich zajęłoby zbyt dużo czasu, a kodu produkcyjnego przy którym moje problemy wystąpiły z oczywistych względów pokazać nie mogę. Niemniej jednak mam nadzieję, że uda Ci się wynieść coś pożytecznego z kilku minut poświęconych na przeczytanie poniższego tekstu.

Uwaga! W trakcie pisania okazało się, że tekstu wyszło na tyle dużo, że zdecydowałem się podzielić go na dwie części. Druga część pojawi się niebawem - po prostu przy pisaniu tego wpisu, który miał być całością uznałem, że jest już tego za dużo, a nawet nie doszedłem do "głównej" części, o której chciałem napisać czyli migracji modułów :)

Uwaga! Dostępna jest już także druga część artykułu o problemach, które mogą nas spotkać podczas migracji kodu. Zachęcam do przeczytania w następnej kolejności: Dlaczego migracje projektów Liferayowych na wyższą wersje nie są proste cz. 2

Dlaczego w ogóle aktualizować wersje?

Warto najpierw zadać sobie pytanie - po co w ogóle migrujemy? Odpowiedzi jest kilka - przede wszystkim bezpieczeństwo. Wystarczy spojrzeć na tzw. "known vulnerabilities", aby zobaczyć, że stare wersje Liferaya zawierają sporo niedociągnięć.

Inną sprawą mogą być nowości, które oferują nowsze wersje używanej technologii. W przypadku Liferaya idealnie widać to na przykładzie wersji 6.2 i 7.x (nawet 7.0) - przeskok był ogromny chociażby ze względu na przejście na OSGI.

Jak wygląda migracja w Liferayu

Tak jak pisałem wcześniej - wpis ten nie będzie instrukcją przeprowadzenia migracji bo od tego jest oficjalna dokumentacja. Nie ukrywam, że prawdopodobnie można by to przedstawić dużo lepiej niż w oficjalnej dokumentacji, ale to raczej byłby temat na cały kurs, a nie wpis na blogu ;)

Gdybyś jednak na ten moment nie był zainteresowany przedzieraniem się przez całą dokumentacje to możesz póki co przyjąć, że migracja sprowadza się w uproszczeniu do kilku punktów:

Przygotowanie naszego portalu - wszelkie kopie zapasowe, usunięcie duplikatów czy nieużywanych artykułów itp
Aktualizacja bazy danych - za pomocą skryptu
Migracja naszych modułów na nowe wersje - w przypadku migracji z 6.2 najprawdopodobniej będzie też potrzebne rozbicie aplikacji na jakiekolwiek moduły
Testy, testy i jeszcze więcej testów

I na pierwszych trzech skupię się opisując co może nam się przydarzyć.

Przygotowanie portalu

Przygotowanie portalu jest krokiem, który jest zalecany w oficjalnej dokumentacji, choć wydawałoby się, że można go pominąć? No niestety okazuję, się, że nie zawsze. Standardowo to przygotowanie portalu ma na celu oszczędzenie miejsca oraz przyspieszenie procesu migracji, aczkolwiek istnieje także drugie dno - Liferay nie zawsze radzi sobie poprawnie z starymi referencjami. Czym jest stara referencja? Przykładowo może być to jakiś stary webcontent, którego już nie używamy i dawno o nim zapomnieliśmy. W pewnym momencie ktoś usunął zdjęcie, którego ten WebContent używał. Wydaję się, że nic złego nie może się wydarzyć bo to standardowe zachowanie - nikt przecież nie analizuje zawartości wszystkich artykułów przed usunięciem zdjęcia i rzeczywiście nic złego się nie dzieje w takim wypadku.

Przechodzimy jednak do migracji naszego portalu na wyższą wersje, wszystko się nam zmigrowało, portal działa aż pewnego razu pobieramy całego LARa z serwera, żeby lokalnie odtworzyć portal i... kończymy z tak zwanym "infinite loop". Brzmi nieprawdopodobnie? A jednak, taka właśnie sytuacja mi się przydarzyła. Dodam, że pierwotnie portal był w wersji 7.0.6 CE a zmigrowany został do wersji 7.2.1 DXP. Całą historie można zobaczyć (wraz z poradami, które otrzymałem) na forum Liferaya: https://liferay.dev/forums/-/message_boards/message/119669178. Dodam tylko, że oprócz proponowanych tam rozwiązań z logami (które bardzo pomogły!) musiałem debugować kod Liferaya.

A chodziło tylko o usuniętę zdjęcie... Na obronę przyznam jedynie, że przypadek ten był specyficzny - nie zawsze usuniętę zdjęcie cokolwiek zepsuje (wręcz raczej nigdy), ale z tego co zauważyłem jedynie wtedy kiedy wrzucimy zdjęcie bezpośrednio do treści z edytora, pomijając documents & media. Może nawet muszą zajść jeszcze jakieś dodatkowe przypadki bo zdjęć miałem w tym migrowanym portalu bardzo dużo (tysiące), a tylko jedno okazało się problematyczne.

Jak szukać takich zepsutych zdjęć? Generalnie ja nie wiedziałem, że taki problem istnieje i stąd tak jak wspomniałem skończyłem na degowaniu kodu Liferaya wraz z czytaniem logów na poziomie DEBUG (sporo tego) i tak znalazłem mój zepsuty WebContent. Niemniej jednak gdybym takich przypadków miał więcej to najprawdopodobniej spróbowałbym jakiegoś narzędzia do szukania "Broken references" - generalnie chodziłoby o przeszukanie naszej strony w poszukiwaniu miejsc gdzie mamy zepsute zdjęcia (wiecie - taka mała ikonka zdjęcia, które się nie załadowało przez zły src). Niestety nie zadziała to jeśli nasz webcontent nie jest nigdzie wstawiony - wtedy można pokusić się o napisanie jakiegoś małego programu do szukania tego.

Aktualizacja bazy danych

Jeśli chodzi o aktualizacje samej bazy danych to przyznam, że jest nieźle. Twórcy tak zwanego tak zwanego "upgrade tool" zrobili dobrą robote bo nie spotkałem się z większymi problemami i to mimo migrowania naprawdę dużych baz danych (jedna z około 8 wirtualnymi instancjami a druga nawet z około 20). Napotkałem tak naprawdę jedynie dwa problemy związane stricte z migracją bazy danych, ale nie były one tragiczne w skutkach - biorąc pod uwagę jak wiele mogło się zepsuć np. w WebContentach

Wpisy konfiguracyjne JAX-RS

W jednej z migrowanych aplikacji (7.0.6 -> 7.2.1 DXP), w której użyty był JAX-RS (o którym w kontekście Liferaya można poczytać tutaj) pojawił się błąd przy starcie aplikacji i wyglądał mniej więcej tak:

Zdjęcie błędu podczas odpalania portalu z błędnym wpisem w tabeli Configuration_ związanym z JAX-RS

Związany był z niepoprawnymi wpisami w tabeli Configuration_. Wyglądały one mniej więcej tak:

com.liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguration.e7c762dd-9fed-4956-8bbf-a89ec9e3a1b8
com.liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguration.factory

Było ich więcej (jeden dla "Factory" i po jednym dla każdego rejestrowanego endpointu). Numerki też będą inne (w przypadku tego pierwszego) więc najłatwiej ich poszukać zapytaniem:

select * from Configuration_ WHERE configurationId like '%com.liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguratio%'

Rozwiązanie? Wystarczy usunąć te wpisy i się nimi na etapie migracji bazy danych. Gdy zmigrujemy nasze moduły związane z JAX-RS i je uruchomimy wszystko będzie działać poprawnie

Tabela release_

Drugim problemem, z którym się spotkałem były niewłaściwe wpisy w tabeli Release_, która krótko mówiąc przechowuję informacje o wersjach aplikacji czy modułów. Problem pojawiał się przy migracji z wersji 6.2 GA2 na wersje 7.3 GA1 - tabela release nie migrowała się poprawnie, aczkolwiek wystarczyło porównać jej zawartość z "świeżą" bazą stworzoną pod 7.3.1 i "podmienić" wpisy i wszystko działało poprawnie.

Na koniec

Tak jak wspominałem w wstępie jest to pierwszy artykułów z dwóch na temat problemów migracyjnych. W drugim wpisie opiszę temat migracji modułów gdzie problemów jest o wiele więcej - tam na pewno wręcz nie opiszę wszystkich, z którymi się spotkałem bo jest ich sporo, choć wiele z nich wynika raczej z ubogiej dokumentacji (i braków w tak zwanych "Breaking changes"), ale w większości nie są aż tak trudne do naprawienia.

I na koniec - powodzenia! :)

Gdybyś w swojej firmie szukał pomocy przy takich migracjach to zawsze zapraszam do kontaktu. Mogę pomóc przy małych migracjach jak i tych dużych, gdzie w zależności od skali możemy porozmawiać o większym zespole który mogę zaproponować.

Continuous integration i sprawdzanie jakości kodu przy użyciu Liferaya 7

Sat, 22 Aug 2020 00:00:00 GMT

Cześć! Dzisiaj chciałbym przedstawić jak można wykorzystać Jenkinsa do procesu "Continuous integration" czyli ciągłej integracji naszego kodu a także do procesu ciągłego sprawdzania jakości kodu z wykorzystaniem narzędzia SonarQube.

Postanowiłem napisać ten post gdyż jakiś czas temu spotkałem się z takim właśnie zadaniem i jak się okazało, nie ma zbyt wielu pomocnych materiałów odnośnie tego tematu.

Wymagania wstępne

Aby rozpocząć potrzebujemy kilku rzeczy:

Projektu Liferaya - na potrzeby tego postu stworzyłem prosty projekt, z którego również możesz skorzystać. Zawiera on zaledwie kilka klas, aczkolwiek powinien być wystarczający do celów "naukowych". Kod tego projektu możesz znaleźć na moim githubie.
Jenkins
SonarQube

Jenkins

Zacznijmy od Jenkinsa. Większość z czytających pewnie o tym narzędziu słyszała, ale gdybyś jednak nie spotkał się z nim wcześniej to już tłumaczę - Jenkins jest to open sourcowe narzędzie służące automatyzacji. Używany jest bardzo często do automatyzacji wszelakich zadań około programistycznych takich jak budowanie aplikacji, uruchamiania testów, a także wrzucaniu aplikacji na serwer, aczkolwiek nie ogranicza się tylko do tego i równie dobrze może zostać użyty np. do cyklicznego uruchamiania jakiegoś skryptu czy aplikacji.

Instalacja Jenkinsa nie powinna sprawić Ci żadnego problemu, a wszelkie niezbędne informacje można znaleźć na oficjalnej stronie. Jenkinsa można zainstalować zarówno lokalnie (podobnie jak każdą inną aplikacje) lub wykorzystać do tego celu Dockera. Osobiście polecam Dockera gdyż jest to świetne narzędzie, aczkolwiek możesz wybrać dowolną opcje.

SonarQube

Drugim narzędziem, którego będziemy potrzebowali jest SonarQube czyli open sourcowe narzędzie służące automatycznemu sprawdzaniu jakości naszego kodu. SonarQube może wykryć tak zwane "code smells", bugi, duplikacje kodu i inne rzeczy tego typu. Instrukcje instalacji, podobnie jak w przypadku Jenkinsa, można znaleźć na oficjalnej stronie. Po raz kolejny możesz wybrać między standardową instalacją, a Dockerem.

Integracja

Gdy już mamy wspomniane narzędzia możemy rozpocząć konfiguracje naszej integracji między Jenkinsem, SonarQubem a naszym projektem.

Generalnie to co chcemy zrobić to:

Skonfigurować projekt w SonarQube
Dodać plugin "SonarQube Scanner" w Jenkinsie, tak aby móć odpalić Sonara z poziomu Jenkinsa
Skonfigurować wyżej wymienione plugin
Stworzyć zadanie w Jenkinsa służące budowaniu naszego projektu oraz skanowaniu kodu za pomocą Sonara

Konfiguracja projektu w SonarQube

Zanim rozpoczniemy integracje potrzebujemy stworzyć projekt w SonarQubie. Aby to zrobić musimy odpalić nasz serwer Sonara (najprawdopodobniej dostępny pod adresem localhost:9000), zalogować się (domyślne dane to admin/admin) oraz kliknąć przycisk "plusika" w prawym górnym rogu.

Następnie generujemy nasz token - po prostu podajemy jakąś nazwe i klikamy "Generate". Token zostanie dla nas wygenerowany i będziemy mogli go użyć do integracji np. właśnie z Jenkinsem.

Wygenerowany token w SonarQube

Zapisz sobie wygenerowany token oraz nazwę projektu, przydadzą się one później. Na ekranie wygenerowanego tokenu możesz także kliknąć "Continue", aby zobaczyć przykłady jak można uruchomić skanowanie projektu w Gradle lub Mavenie, aczkolwiek w naszym przypadku nie będzie to potrzebne.

Dodawanie pluginu "SonarQube scanner" do Jenkinsa i jego konfiguracja

Kolejnym krokiem niezbędnym do naszej integracji jest zainstalowanie pluginu "SonarQube Scanner" w Jenkinsie. Możemy to zrobić wchodząc w (ze strony głównej):

Manage Jenkins -> Manage plugins -> Available -> Search for "SonarQube Scanner" -> zaznacz pierwszą dostępną opcje i zaznacz "Install with restart"

Następnie, po instalacji pluginu, idziemy do (z strony głównej):

Manage Jenkins -> Global tool Configuration -> W części "SonarQube Scanner" klikamy "Add SonarQube Scanner" i wpisujemy jakąs nazwę. Dla reszty opcji zostawiamy wartości domyślne. Następnie potwierdzamy naszą konfiguracje poprzez kliknięcie "Save".

Konfiguracja SonarQube Scannera w Jenkinsie

Wypełniona konfiguracja pluginu SonarQube Scanner

Kolejny krok to konfiguracja serwera SonarQube. Aby to zrobić przechodzimy do (ze strony głównej Jenkinsa):

Manage Jenkins -> Configure System -> Szukamy sekcji"SonarQube servers" i klikamy "Add SonarQube". Nazywamy nasz serwer (nazwa jedynie dla nas) oraz wprowadzamy adres URL.

Stworzenie projektu (zadania) w Jenkinsie

Jenkins oferuje nam kilka typów "projektów". Opis tych typów można znaleźć chociażby w dokumentacji lub w innych artykułach. My skupimy się na tak zwanym "Freestyle Project", który umożliwia nam zdefiniowanie różnych akcji (takich jak budowanie, testy, deployment itp), które wykonają się po kolei. Aby stworzyć taki projekt klikamy na "New item" z strony głównej i wybieramy "Freestyle project". Nazywamy go wedle uznania, a następnie klikamy "ok".

Przycisk do stworzenia nowego projektu w Jenkinsie

Nowe zadanie w Jenkinsie

Opcje nowego projektu w Jenkinsie

Ekran tworzenia nowego projektu

Gdy klikniemy ok zostaniemy przekierowani do konfiguracji stworzonego zadania. Nie będę opisywał wszystkich dostępnych ustawień, gdyż jest ich całkiem sporo a jednocześnie większość z nich jest albo prosta i jasna albo służy do bardzo specyficznych zastosowań i nie będą Ci nigdy (albo prawie nigdy) potrzebne. Gdybyś jednak chciał się zapoznać z możliwościami to przy każdej z opcji dostępny jest "Znak zapytania", na który można kliknąć, aby dowiedzieć się więcej o danym polu.

Mając stworzone zadanie warto zastanowić się co właściwie chcemy tym zadaniem osiągnąc. W naszym przypadku będziemy mieli następujące kroki:

Ściągnięcie kodu z naszego repozytorium - w moim przypadku będzie to GIT, ale równie dobrze możesz użyć np. serwera SVN
Po ściągnięciu najnowszego kodu chcemy go zbudować używająć gradle. Oczywiście równie dobrze mógłby to być maven, kroki są analogiczne i na pewno nie sprawią Ci większego problemu
Na koniec chcemy przeskanować nasz kod SonarQubem w celu sprawdzenia jego jakości

W naszym przykładzie to będzie wszystko, aczkolwiek w rzeczywistości można by zrobić dużo więcej. Przykładowo po zbudowaniu kodu można uruchomić testy (a nawet należy - bo testy zawsze warto pisać!) albo nawet pójść o krok dalej i automatycznie deployować naszą aplikacje na serwer (Continious deployment).

Ściągnięcie kodu z repozytorium

W celu automatycznego pullowania kodu z naszego repozytorium przechodzimy do sekcji "Source code management". Wybieramy rodzaj repozytorium, którego będziemy używać - w moim przypadku GIT. Musimy jeszcze dodać dane autoryzacyjne. Aby to zrobić klikamy "Add" (zakładając, że robimy to po raz pierwszy) i wybieramy "Jenkins". W panelu, który się nam pokaże wpisujemy login oraz hasło i zatwierdzamy przyciskiem add. Dane autoryzacyjne zostaną zapisane i następnym razem będziemy mogli ich użyć wybierając odpowiedni wpis z listy przy polu "Credentials".

Zdjęcie pokazujące wypełnione pole z danymi autoryzacyjnymi

Budowanie aplikacji

Teraz przechodzimy do sekcji "Build". W sekcji tej możemy dodać kroki (jeden lub więcej), które zostaną kolejno wykonane. Takim krokiem może być np. uruchomienie Gradle czy Anta, uruchomienie komendy shellowej (lub CMD w windowsie) itp. W naszym wypadku klikamy "Invoke gradle", a następnie wybieramy wersje, której chcemy użyć lub zaznaczamy użycie Gradle Wrappera. Ta druga opcja jest rekomendowana, a więc jej użyjemy. Możemy także zaznaczyć "Make gradlew executable" i tak też zrobimy. Zaznaczenie tego pola oznacza, że przed uruchomieniem gradlew zostanie zrobione coś w stylu chmod +x ./gradlew. W innym wypadku nasz ./gradlew może nie być wykonywalny i zadanie się nie powiedzie.

W sekcji "Task" wpisujemy task, który chcemy wykonać:

clean build

Uruchamianie Gradle w Jenkinsie

Skanowanie kodu przy użyciu SonarQube

Po zbudowaniu projektu, zakładając, że nie zakończy się ono błędem, chcielibyśmy uruchomić skanowanie SonarQubem. Aby to zrobi dodajemy kolejny krok klikająć na "Add Build step" tuż pod zadaniem uruchomienia gradle. Wybieramy "Execute SonarQube Scanner", następnie w części "Analysis properties" musimy wprowadzić informacje niezbędne do przeskanowania naszego projektu. Dostępnych opcji jest cała masa i można je znaleźć w dokumentacji Sonara, ale nam wystarczy zaledwie kilka:

sonar.login - wygenerowany wcześniej token
sonar.projectKey - wprowadzony "projectKey" podczas tworzenia projektu
sonar.java.binaries - definiujemy gdzie są nasze zbudowane klasy
sonar.java.libraries - lokalizacja dodatkowych bibliotek, których używamy
sonar.java.source - wersja Javy w naszym projekcie

Poniżej screen z wprowadzonymi standardowymi wartośćiami - o ile nie masz jakichś szczególnych ścieżek albo wymagań to powinny one zadziałać także u Ciebie (oczywiście poza tokenem i projectKey):

Konfiguracja SonarQube w Jenkinsie

Czas na testy!

Uruchomienie stworzonego zadania w Jenkinsie

Mamy spełnione wszystkie kroki potrzebne do uruchomienia naszego zadania. Po zapisaniu naszej konfiguracji w Jenkinsie możemy uruchomić stworzone zadanie klikając "Build now" (jeśli jesteśmy na stronie głównej musimy najpierw przejść do naszego zadania klikając na jego nazwe).

Czekamy chwile, a po wszystkim powinniśmy zobaczyć numer zadania z niebieską kropką, która wskazuje, że wszystko poszło ok:

Podgląd historii buildów

W zakładce "Build history" można zobaczyć status wcześniejszych uruchomień zadania (możesz również zauważyć, że moje ma numerek #4 - niestety poprzednie 3 nie wyszły, ale mam nadzieję, że Tobie uda się za pierwszym razem ;) )Możesz także kliknąć na numerek builda, aby przejść do zakładki, w której dostępne są szczegóły zadania takie jak np. logi z konsoli, co jest bardzo przydatne (lub wręcz niezbędne) podczas sprawdzania co poszło nie tak.

Sprawdzenie rezultatu w SonarQube

Przejdźmy do naszego projektu w aplikacji SonarQube i zobaczmy wynik naszego zadania. Jeśli jesteś na stronie głównej w SonarQubie możesz przejść do "Projects" i wejść do odpowiedniego projektu poprzez kliknięcie na jego nazwe.

Uwaga: czasami musisz poczekać chwilę zanim rezultat naszego skanu pojawi się w SonarQubie. Dzieję się tak dlatego, że Jenkins wysyła dane do SonarQube i kończy zadanie, ale SonarQube dopiero wtedy zaczyna swoje procesowanie przesłanych danych. W przypadku mojego testowego projektu rezultat będzie prawdopodobnie od razu, aczkolwiek w większych projektach jest pewne opóźnienie i trzeba mieć to na uwadze.

Następnie możesz przejśc do swojego projektu, aby zobaczyć podsumowanie wykonanego skanowania kodu:

Podsumowanie błędów

W podsumowaniu można zobaczyć dwie zakładki:

New code - pokazane są statystyki dla nowgo kodu
Overall code - podsumowanie dla całego kodu

Główna różnica polega na tym, że jeżeli mamy np. błędy, które mamy "od zawsze" to zostaną one policzone jedynie w "Overall code", ale nie w "New code". Dlaczego? Przede wszystkim dlatego, że dla dużych projektów tych błędów mogą być setki i niekoniecznie ktokolwiek będzie ja poprawiał, możemy w takiej sytuacji śledzić jedynie czy sytuacja bieżąca jest wystarczająco dobra, a błędy w starym kodzie poprawiać stopniowo.

Kolejną przydatną (lub wręcz najważniejszą) zakładką jest "Issues", która pokazuje konkretne błędy w Twoim kodzie. Możesz w niej podejrzeć każdy znaleziony błąd, a także przefiltrować błędy po krytyczności, typie, miejscu w kodzie itp. Dodatkowo możliwe jest przypisanie poszczególnych błędów do konkretnych osób czy też edycja standardowym opcji dla błędu np. jego krytyczności. Istnieje także możliwość oznaczenia błędu jako "false positive" lub "won't fix" co może być przydatne gdyż Sonar (jak każde narzędzie) czasami popełnia błędy w swojej ocenie kodu.

Problemy z kodem z Liferayowego Service Buildera

Jeśli zaczniesz przeglądać znaleziony błędy możesz zauważyć pewien problem - Sonar znajduję naprawdę dużo błędów. Są dwie opcje - albo twój kod jest naprawdę tragiczny albo coś jest nie tak. Jeśli spojrzysz na mój kod testowy to zobaczysz, że praktycznie nie ma tam kodu, a jednak Sonar znalazł sporo błędów. Przyczyna jest dość trywialna - problemem jest automatycznie wygenerowany kod przez Service Buildera. W przypadku mojego testowego projektu mam prawie 100 błędów, mimo że dodałem kod zaledwie w trzech klasach. Dużo, nawet biorąc pod uwagę, że błędy robiłem specjalnie.

Moglibyśmy oczywiście oznaczyć te błędy jako "False positive", aczkolwiek w prawdziwym projekcie nie będzie to zbyt rozsąne - liczba błędów byłaby zbyt duża. Tutaj pojawiło się prawie 100 błędów z jednej encji bazodanowej, a w prawdziwym projekcie takich encji mogą być dziesiątki, sam pracowałem przy projekcie z 150 encjami obsługiwanymi przez Service Buildera, a w Twoim projekcie może być ich jeszcze więcej.

Na szczęście istnieje inny sposób. Możemy powiedzieć Jenkinsowi, aby ignorował niektóre ścieżki przy użyciu właściwośći sonar.exclusions. Przy użyciu tego "property" możemy wybraż ścieżki do ignorowania. Wydaję się proste, aczkolwiek są z tym dwa problemy:

Jeśli używasz Liferaya 7 to prawdopodobnie masz wiele modułów (a przynajmniej powinieneś bo modularność to dobra rzecz!). To oznacza, że ciężko wskazać jedną ścieżke bo takich modułów, z automatycznie wygenerowanym kodem, może być kilkanaście.
Moglibyśmy użyć więc jakiegoś "dynamicznego" matchowania nazw, ale to też nie jest do końca proste. W teorii moglibyśmy po prostu ignorować wszystkie ścieżki kończące się na *-api oraz *-service, ale w w praktyce w modułach *-service także jest nasz kod w klasach typu *Impl.

Logiczne wydają się więc dwa rozwiązania:

Jeśli nie masz aż tylu modułów to możesz po prostu ręcznie wypisać ścieżki do ignorowania
Wymyślić jakąś "ogólną" regułe, która zadziałałaby w Twoim projekcie. Reguła ta musi być wystarczająco dokładna, aby wyeliminować wszystkie miejsca, których nie chcemy skanować, ale jednocześnie nie powinna wykluczać Twojego kodu

Ogólna reguła wykluczenia

Osobiście nie miałem komfortu pracy przy jedynie jednym czy dwóch modułach z serwisami więc wybrałem opcje numer dwa. Poniższej reguły używam w prawdziwym projekcie i mogę powiedzieć, że działa ona dobrze. Konfiguracja to:

sonar.exclusions=**/build/resources/main/META-INF/resources/**/*.jsp,**/*-service/**/model/impl/**/*.java,**/*-service/**/service/persistence/**/**/*.java,**/*-service/**/service/base/**/*.java,**/*-service/**/service/http/**/*.java,**/*-service/**/service/util/**/*.java,**/*-api/**/dto/**/*.java,**/*-api/**/exception/**/*.java,**/*-api/**/model/**/*.java,**/*-api/**/service/**/*.java

Mamy więc zdefiniowane ścieżki rozdzielone przecinkami. Używamy także dwóch dostępnych możliwośći w określaniu ścieżek:

* - zastępuję jeden lub więcej znak w nazwie pliku
** - zastępuje jeden lub więcej katalogów

Reguła ta ignoruje automatycznie wygenerowany kod zarówno w modułach *-service jak i *-api. Czy jest to reguła idealna? Niestety nie. Zawiera ona pewne założenia co do struktury twojego projektu, przykładowo ignoruje ona **/*-service/**/service/util/**/* ale równie dobrze możesz mieć moduł o nazwie przykładowo blogs-service a w środku posiadać katalog service/util z swoim kodem. Co wtedy? Niestety nie ma prostego rozwiązania. Możesz albo doprecyzować regułę do swojego przypadku albo wybrać opcje z ręcznym wskazywaniem katalogów. W większości przypadków powinna ona jednak zadziałać.

Kolejny test

Po dodaniu wspomnianej wyżej reguły rezultat uruchomienia naszego zadania w Jenkinsie powinien być zdecydowanie lepszy. W moim przypadku z 100 błędów zostało mi zaledwie 10 i rzeczywiście są one rzeczywistami błędami (czy też tak zwanymi "code smell"). Dodatkowo widzę, że posiadam jeden błąd w klasie *LocalServiceImpl co potwierdza, że reguła zadziałała poprawnie i nie ignoruje zbyt wiele.

Błędy SonarQube

Podsumowanie

Podsumowując. Stworzyliśmy zadanie w Jenkinsie, które uruchamia nasz projekt, wysyła rezultat do SonarQube. W Sonarze możemy zweryfikować "jakość" naszego kodu i sprawdzić poszczególny błędy.

W artykule tym nie poruszyłem wszystkiego bo i tak rozrósł się już za bardzo. Przykładowo nie wspominałem o tzw "Build triggers" czyli możliwości cyklicznego sprawdzania naszego repozytorium w celu sprawdzenia czy istnieje nowy kod, który można zbudować i przeskanować. W praktyce prawdopodobnie chcesz dodać taki wyzwalacz do swojego Jenkinsowego zadania. O wyzwalaczach tych możesz znaleźć wiele informacji w dokumentacji czy innych blogach.

Kolejnym krokiem automatyzacji może być automatyczne uruchomienie testów, automatyczny deployment czy np. wysyłka maili w przypadku błędów w budowaniu kodu (sekcja post-build actions w konfiguracji zadania) albo może coś jeszcze innego, specyficznego dla procesu w Twojej firmie czy twoim zespole.

Jenkins daje nam wiele możliwości i zachęcam do dokładniejszego zapoznania się z nimi, niezależnie czy do projektów w Liferayu czy jakichkolwiek innych. Warto również zwrócić uwagę na to, że istnieje masa pluginów, które pozwalają nam się integrować z różnymi narzędziami co dodatkowo poszerza możliwości Jenkinsa.

Mam nadzieję, że przydał Ci się ten artykuł i pamiętaj, że jeśli masz jakieś pytania to możesz napisać komentarz lub napisać do mnie.

Podpisywanie plików XML w Javie. Część druga - podpis pliku XML

Tue, 17 Apr 2018 00:00:00 GMT

Poniższy wpis jest drugą częścią artykułu dotyczącego podpisywania plików XML w Javie. W pierwszej części dotyczącej obsługi podpisów elektronicznych w Javie przedstawiłem, czym są podpisy elektroniczne oraz cyfrowe, a także przedstawiłem sposób, w jaki można odczytać dane certyfikatu z podpisu elektronicznego.

W drugiej części najpierw przybliżę podstawy teorii standardów podpisywania plików XML, a następnie przedstawię proces podpisywania takiego pliku w języku Java. Wpis zawiera najważniejsze części kodu - całość aplikacji demo można także znaleźć pod adresem https://github.com/RafalPydyniak/XmlDigitalSignatureDemo.

Standardy podpisów XML

Podpisywanie pliku XML polega na wygenerowaniu struktury XML, w której zawarte są informacje zarówno o podpisywanym pliku (np. hash danych, które podpisujemy), jak i informacje o samym podpisie (np. wartość podpisu). Co istotne, istnieją standardy definiujące, jak taka struktura powinna wyglądać. Takimi standardami są:

XML Signature (XMLDSig)
XAdES

XML Signature

XML Signature jest rekomendacją W3C co do tego, jak powinny wyglądać podpisy cyfrowe plików XML. Co ciekawe, mimo nazwy, standard ten pozwala podpisywać nie tylko pliki XML, ale również inne dane, które posiadają adres URL.

Warto zaznaczyć, że XML Signature określa więcej niż jeden sposób wyglądu podpisu. Możemy wyróżnić:

Enveloped Signature
Enveloping Signature
Detached Signature

Powyższe sposoby różnią się miedzy sobą sposobem reprezentowania podpisu: w Enveloped oraz Enveloping Signature podpisywane dane znajdują się bezpośrednio w pliku z podpisem, natomiast w Detached Signature wskazujemy jedynie URL, pod którym znajdują się podpisywane dane. Wszelkie szczegóły można oczywiście znaleźć w dokumencie opisującym ten standard.

XAdES

XAdES (XML Advanced Electronic Signatures) jest z kolei rozszerzeniem XML Signature definiującym format podpisu elektronicznego. Jest to standard rekomendowany przez Unię Europejską. Jego zastosowanie w Polsce to m.in. wysyłka PIT'ów drogą elektroniczną. XAdES dodaje całą gamę dodatkowych pól do podpisywanego pliku, które różnią się w zależności od wersji samego XAdES'a. Dokładny format XAdES zostanie przedstawiony w późniejszej części wpisu.

Podpisywanie pliku XML w Javie

Skoro mamy już podstawową wiedzę na temat standardów podpisów cyfrowych i elektronicznych, a także wiemy jak wyciągnąć dane o certyfikacie z podpisu elektronicznego, to możemy przystąpić do podpisania samego pliku XML.

Podpisywać będziemy XML'a o następującej zawartości:

<?xml version="1.0" encoding="UTF-8"?>
<example>
  <message>Hello World!</message>
</example>

Na początku możemy stworzyć interfejs XmlSigner:

 public interface XmlSigner {
    File sign(Document xmlToSign,File destinationFile, PrivateKey privateKey, X509Certificate certificate) throws XmlSigningException;
    File sign(File xmlToSign,File destinationFile, PrivateKey privateKey, X509Certificate certificate) throws XmlSigningException;
}

Mamy w nim dwie wersje metody sign, różniące się jedynie pierwszym parametrem - wynika to z tego, iż chcemy móc dać możliwość wskazania pliku XML do podpisu bądź też samych danych (obiektu klasy org.w3c.Document). Poza danymi w parametrach przekazujemy także certyfikat X509 oraz klucz prywatny - informacje jak wyciągnąć te dane z podpisu elektronicznego (np. Certum, KIR) znajdują się w pierwszej części artykułu.

W obu wersjach metody sign będziemy rzucać wyjątek XmlSigningException - w związku z tym, iż w demo obsługa wyjątków została pominięta to Exception ten będzie leciał zawsze gdy poleci jakikolwiek wyjątek w kodzie - w prawdziwej aplikacji chcemy oczywiście poprawnie obsługiwać wyjątki.

public class XmlSigningException extends Exception{
}

Implementacja interfejsu XmlSigner

Najważniejszym etapem tej części artykułu jest implementacja wcześniej zdefiniowanego interfejsu XmlSigner. Poniżej przedstawiam najważniejsze etapy tej implementacji.

Zacznijmy od samej metody sign:

@Override
    public File sign(Document xmlToSign,File destinationFile, PrivateKey privateKey, X509Certificate certificate) throws XmlSigningException {
        try {
            return tryToSignOrThrow(xmlToSign, destinationFile, privateKey, certificate);
        } catch (Exception e) {
            //TODO this is just a demo, in real life we want to do something better with exceptions
            e.printStackTrace();
            throw new XmlSigningException();
        }
    }

Jak widzimy zawiera ona tak naprawdę jedynie obsługę wyjątków (a przynajmniej powinna ją zawierać ;)). Dalej idąc mamy metodę tryToSignOrThrow:

private File tryToSignOrThrow(Document xmlToSign,  File resultFile, PrivateKey privateKey, X509Certificate certificate) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException, KeyException, ParserConfigurationException, MarshalException, XMLSignatureException, TransformerException, FileNotFoundException {
        XMLSignature xmlSignature = prepareXmlSignature(certificate.getPublicKey(), xmlToSign, certificate);
        Document doc = getEmptyDocument();
        DOMSignContext domSignContext = new DOMSignContext(privateKey, doc);
        domSignContext.setDefaultNamespacePrefix("ds");
        xmlSignature.sign(domSignContext);
 
        saveDocumentToFile(doc, resultFile);
        return resultFile;
    }

W kolejnych liniach tej metody wykonujemy kilka czynności:

Przygotowujemy obiekt XMLSignature (linijka 2)
Tworzymy nowy dokument, do którego zostanie zapisany wyjściowy XML (linia 3)
Przygotowujemy obiekt klasy DOMSignContext, przy użyciu, którego dokonujemy następnie podpisu (linie 4-6)
Zapisujemy końcowy XML do pliku i go zwracamy (linie 8-9)

Kroki 2-4 powyższej listy są dość proste i raczej nie wymagają dodatkowego wyjaśnienia. Kluczowy jest natomiast krok pierwszy, w którym przygotowujemy całą strukturę zgodną z formatem XAdES, którą możemy podpisać.

private XMLSignature prepareXmlSignature(PublicKey publicKey, Document xmlToSign, X509Certificate certificate) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException, KeyException, ParserConfigurationException {
        XMLSignatureFactory xmlSignFactory = XMLSignatureFactory.getInstance("DOM");
        List<XMLObject> objects = getObjectsFromData(xmlToSign, xmlSignFactory, certificate);
        SignedInfo signedInfo = getSignedInfo(xmlSignFactory);
        KeyInfo keyInfo = getKeyInfo(publicKey, xmlSignFactory, certificate);
        return xmlSignFactory.newXMLSignature(signedInfo, keyInfo, objects, "Signature", "SignatureValue");
    }
 
private List<XMLObject> getObjectsFromData(Document xmlToSign, XMLSignatureFactory xmlSignFactory, X509Certificate certificate) throws ParserConfigurationException {
        List<XMLObject> objects = new ArrayList<>();
        XMLObject dataXmlObject = prepareDataXmlObject(xmlToSign, xmlSignFactory);
        XMLObject xadesXmlObject = prepareXadesXmlObject(xmlSignFactory, certificate);
        objects.add(dataXmlObject);
        objects.add(xadesXmlObject);
 
        return objects;
    }
 
private XMLObject prepareDataXmlObject(Document xmlToSign, XMLSignatureFactory xmlSignFactory) {
        XMLStructure content = new DOMStructure(xmlToSign.getFirstChild());
        return xmlSignFactory.newXMLObject(Collections.singletonList(content), "Data", "text/xml", null);
    }
 
private XMLObject prepareXadesXmlObject(XMLSignatureFactory xmlSignFactory, X509Certificate certificate) throws ParserConfigurationException {
        Element qualifyingPropertiesElement = createXadesObject(certificate);
        return xmlSignFactory.newXMLObject(Collections.singletonList(new DOMStructure(qualifyingPropertiesElement)), null, null, null);
    }

W linijce 3 pobieramy (tworzymy) obiekty. Pierwszym z obiektów jest po prostu obiekt z samymi podpisywanymi danymi (choć potencjalnie mogłoby go nie być, a do danych moglibyśmy się odnosić poprzez adres URL - wtedy byłby to "Detached Signature", o którym pisałem wcześniej). Drugim obiektem jest natomiast struktura zdefiniowana w formacie XAdES, zawierająca dodatkowe informacje o podpisie. Tworzenie tych obiektów widać dodatkowo w linijkach 11 i 12. Samo przygotowanie pliku z danymi (w metodzie prepareDataXmlObject) jest bardzo proste i polega jedynie na stworzeniu osobnego obiektu z całością podpisywanych danych. Przygotowanie obiektu XAdES (metoda prepareXadesXmlObject) jest z kolei bardziej skomplikowane i opisane zostanie poniżej.

Przygotowanie obiektu XAdES

Pełna struktura obiektu XAdES jest następująca:

<ds:Object>
   <QualifyingProperties>
     <SignedProperties>
       <SignedSignatureProperties>
         (SigningTime)
         (SigningCertificate)
         (SignaturePolicyIdentifier)
         (SignatureProductionPlace)?
         (SignerRole)?
       </SignedSignatureProperties>
       <SignedDataObjectProperties>
         (DataObjectFormat)*
         (CommitmentTypeIndication)*
         (AllDataObjectsTimeStamp)*
         (IndividualDataObjectsTimeStamp)*
       </SignedDataObjectPropertiesSigned>
     </SignedProperties>
     <UnsignedProperties>
       </UnsignedSignatureProperties>
         (CounterSignature)*
         (SignatureTimeStamp)+
         (CompleteCertificateRefs)
         (CompleteRevocationRefs)
         ((SigAndRefsTimeStamp)*
         (RefsOnlyTimeStamp)*
         (CertificatesValues)
         (RevocationValues)
         (ArchiveTimeStamp)
       </UnsignedSignatureProperties>
     </UnsignedProperties>
   </QualifyingProperties>
 </ds:Object>

W powyższym kodzie nie wszystkie elementy są wymagane - znaki *, + oraz ? mają takie samo znaczenie jak w wyrażeniach regularnych, a co za tym idzie, wszystkie elementy oznaczone gwiazdką lub znakiem zapytania są opcjonalne. Inna sprawa - schemat, choć pobrany z oficjalnej dokumentacji, nie oddaje wszystkiego. Przykładowo, UnsignedProperties nie są wymagane, mimo że na schemacie tego nie widać. Dodatkowo niektóre z elementów istnieją tylko w wyższych wersjach XAdES'a.

Do podstawowych elementów tego obiektu należą:

QualifyingProperties - jest kontenerem dla obiektów SignedProperties i UnsignedProperties
SignedProperties - zawiera właściwości, które zostaną podpisane
UnsignedProperties - zawiera właściwości, które nie będą podpisywane

Oczywiście dokładny opis każdego z elementów (wraz z definicją XSD) można znaleźć w oficjalnym dokumencie opisującym XAdES'a.

Gdy już wiemy, co powinien zawierać podpis, możemy przejść do jego implementacji. Co istotne, w naszym podpisie zupełnie pominiemy UnsignedProperties, które zazwyczaj nie są wymagane i nie wnoszą wiele do podpisu.

Poniżej najważniejsze części kodu (reszta dostępna na Githubie):

private Element createXadesObject(X509Certificate certificate) throws ParserConfigurationException {
        Document doc = getEmptyDocument();
        Element qualifyingProperties = createQualifyingPropertiesObject(doc);
        Element signedProperties = prepareSignedPropertiesElement(doc, certificate);
        qualifyingProperties.appendChild(signedProperties);
        return qualifyingProperties;
    }
 
private Element createQualifyingPropertiesObject(Document doc) {
        Element qualifyingProperties = createElementInDocument(doc, "xades:QualifyingProperties", "QualifyingProperties");
        qualifyingProperties.setAttribute("Target", "#Signature");
        qualifyingProperties.setAttributeNS("http://www.w3.org/2000/xmlns/", "xmlns:xades", "http://uri.etsi.org/01903/v1.3.2#");
        return qualifyingProperties;
    }
 
private Element prepareSignedPropertiesElement(Document doc, X509Certificate certificate) {
        Element signedProperties = createElementInDocument(doc, "xades:SignedProperties","SignedProperties" );
 
        Element signedSignatureProperties = prepareSignedSignatureProperties(doc, certificate);
        Element signedDataObjectProperties = prepareSignedDataObjectProperties(doc);
 
        signedProperties.appendChild(signedSignatureProperties);
        signedProperties.appendChild(signedDataObjectProperties);
        return signedProperties;
    }
 
    private Element prepareSignedSignatureProperties(Document doc, X509Certificate certificate) {
        Element signedSignatureProperties = createElementInDocument(doc, "xades:SignedSignatureProperties", "SignedSignatureProperties");
        Element signingTime = prepareSigningTimeElement(doc);
        Element signingCertificate = prepareSigningCertificateElement(doc, certificate);
        signedSignatureProperties.appendChild(signingTime);
        signedSignatureProperties.appendChild(signingCertificate);
        return signedSignatureProperties;
    }
 
    private Element prepareSigningCertificateElement(Document doc, X509Certificate certificate) {
        Element signingCertificate = doc.createElement("xades:SigningCertificate");
        Element certificateElement = doc.createElement("xades:Cert");
        Element certDigest = doc.createElement("xades:CertDigest");
        certificateElement.appendChild(certDigest);
 
        Element issuerSerial = doc.createElement("xades:IssuerSerial");
        certificateElement.appendChild(issuerSerial);
        Element x509IssuerName = doc.createElement("X509IssuerName");
        issuerSerial.appendChild(x509IssuerName);
        x509IssuerName.appendChild(doc.createTextNode(certificate.getIssuerDN().getName()));
        Element x509SerialNumber = doc.createElement("X509SerialNumber");
        issuerSerial.appendChild(x509SerialNumber);
        x509SerialNumber.appendChild(doc.createTextNode(certificate.getSerialNumber().toString()));
 
        signingCertificate.appendChild(certificateElement);
        return signingCertificate;
    }
 
    private Element prepareSignedDataObjectProperties(Document doc) {
        Element signedDataObjectProperties = doc.createElement("xades:SignedDataObjectProperties");
        signedDataObjectProperties.setAttribute("Id", "SignedDataObjectProperties");
        Element dataObjectFormat = doc.createElement("xades:DataObjectFormat");
        dataObjectFormat.setAttribute("ObjectReference", "#Data-Reference");
        Element mimeType = doc.createElement("xades:MimeType");
        mimeType.appendChild(doc.createTextNode("text/xml"));
        dataObjectFormat.appendChild(mimeType);
        signedDataObjectProperties.appendChild(dataObjectFormat);
 
        Element commitmentTypeIndicationElement = doc.createElement("xades:CommitmentTypeIndication");
        signedDataObjectProperties.appendChild(commitmentTypeIndicationElement);
        Element commitmentTypeId = doc.createElement("xades:CommitmentTypeId");
        commitmentTypeIndicationElement.appendChild(commitmentTypeId);
        Element identifier = doc.createElement("xades:Identifier");
        identifier.appendChild(doc.createTextNode("http://uri.etsi.org/01903/v1.2.2#ProofOfApproval"));
        commitmentTypeId.appendChild(identifier);
        Element allSignedDataObjects = doc.createElement("xades:AllSignedDataObjects");
        commitmentTypeIndicationElement.appendChild(allSignedDataObjects);
        return signedDataObjectProperties;
    }

I kolejno:

W linijce 3 tworzymy element QualifyingProperties
W linijce 4 tworzymy element SignedProperties, który następnie dodajemy jako "dziecko" elementu QualifyingProperties w linijce 5
Samo tworzenie SignedProperties odbywa się w metodzie prepareSignedPropertiesElement. Tworzone są dwa elementy: SignedSignatureProperties oraz SignedDataObjectProperties, które następnie dodawane są pod elementem "signedProperties"

W powyższym zrzucie kodu można ponadto znaleźć informacje o tworzeniu różnych elementów, takich jak np. IssuerSerial czy SigningTime, ale są to już szczegóły implementacyjne - dokładny opis, co oznacza każdy z tworzonych elementów, można znaleźć w dokumentacji, natomiast sam proces ich tworzenia jest na tyle prosty, że raczej nie trzeba go szczegółowo opisywać. Generalna idea jest taka, że tworzymy elementy z odpowiednimi danymi i dopinamy je do innych, bardziej ogólnych elementów.

Wygenerowanie danych z standardu XML Signature

Gdy już mamy nasze obiekty, jeden z danymi, a drugi z informacjami XAdES, to następnym krokiem jest wygenerowanie elementów określonych w XML Signature. Uproszczony schemat XML Signature znajduje się poniżej:

<Signature>
  <SignedInfo>
    <CanonicalizationMethod />
    <SignatureMethod />
    <Reference>
       <Transforms />
       <DigestMethod />
       <DigestValue />
    </Reference>
    <Reference /> etc.
  </SignedInfo>
  <SignatureValue />
  <KeyInfo />
  <Object />
</Signature>

Elementy, które musimy sami wygenerować to SignedInfo oraz KeyInfo. Element SignatureValue zostanie za nas wygenerowany podczas samego podpisu, który jest realizowany przy pomocy klasy XMLSignatureFactory.

W wcześniej przytoczonym fragmencie z metodą prepareXmlSignature:

private XMLSignature prepareXmlSignature(PublicKey publicKey, Document xmlToSign, X509Certificate certificate) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException, KeyException, ParserConfigurationException {
        XMLSignatureFactory xmlSignFactory = XMLSignatureFactory.getInstance("DOM");
        List<XMLObject> objects = getObjectsFromData(xmlToSign, xmlSignFactory, certificate);
        SignedInfo signedInfo = getSignedInfo(xmlSignFactory);
        KeyInfo keyInfo = getKeyInfo(publicKey, xmlSignFactory, certificate);
        return xmlSignFactory.newXMLSignature(signedInfo, keyInfo, objects, "Signature", "SignatureValue");
    }

Po wygenerowaniu obiektów, w liniach 4-5, generowane są właśnie elementy signedInfo oraz keyInfo metodami getSignedInfo oraz getKeyInfo. Poniżej przedstawiony jest ich kod:

private SignedInfo getSignedInfo(XMLSignatureFactory xmlSignFactory) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException {
        Reference dataReference = createDataReference(xmlSignFactory, "#Data", null, "Data-Reference");
        SignatureMethod signatureMethod = xmlSignFactory.newSignatureMethod(SignatureMethod.RSA_SHA1, null);
        CanonicalizationMethod canonicalizationMethod = xmlSignFactory.newCanonicalizationMethod(CanonicalizationMethod.INCLUSIVE, (C14NMethodParameterSpec) null);
        return xmlSignFactory.newSignedInfo(canonicalizationMethod, signatureMethod, Collections.singletonList(dataReference));
    }
 
    private Reference createDataReference(XMLSignatureFactory xmlSignFactory, String s, String o, String s2) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException {
        DigestMethod digestMethod = xmlSignFactory.newDigestMethod(DigestMethod.SHA1, null);
        Transform transform = xmlSignFactory.newTransform(CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS, (TransformParameterSpec) null);
        return xmlSignFactory.newReference(s, digestMethod, Collections.singletonList(transform), o, s2);
    }
 
private KeyInfo getKeyInfo(PublicKey publicKey, XMLSignatureFactory xmlSignFactory, X509Certificate certificate) throws KeyException {
        KeyInfoFactory keyInfoFactory = xmlSignFactory.getKeyInfoFactory();
        X509Data x509Data = keyInfoFactory.newX509Data(Collections.singletonList(certificate));
        KeyValue keyValue = keyInfoFactory.newKeyValue(publicKey);
        return keyInfoFactory.newKeyInfo(Arrays.asList(keyValue, x509Data));
    }

SignedInfo zgodnie z specyfikacją zawiera referencje do podpisywanych danych oraz bardziej szczegółowe informacje o tym jak podpisywane były dane (np. algorytm generowania hasha). Najważniejsze miejsca kodu:

W linii 2 tworzona jest referencja do podpisywanych danych (którym wcześniej nadaliśmy odpowiednie ID - Data)
W linii 3 określamy algorytm hashowania danych - w naszym przypadku użyjemy RSA_SHA1
W linii 4 określamy metodę kanonizacji (Canonicalization Method), czyli algorytm transformacji, który zostanie użyty na danych przed ich podpisem
W linii 5 tworzymy ostatecznie obiekt klasy SignedInfo przy użyciu XmlSignFactory, któremu w parametrach podajemy obiekty stworzone w wcześniej opisanych liniach 2-4

Oprócz SignedInfo tworzymy także KeyInfo, czyli strukturę zawierającą informacje o użytym kluczu. Samym stworzeniem KeyInfo zajmuje się KeyInfoFactory, któremu należy jedynie dostarczyć klucz publiczny i dane certyfikatu X509.

Użycie aplikacji

Aby skorzystać z aplikacji, użyjemy poniższej klasy Main:

public class Main {
    /**
     * Just a demo - exceptions are NOT handled and they SHOULD be.
     * Exception can occur at many places like giving wrong PIN or picking not existing slot
     * @param args
     * @throws Exception
     */
    public static void main(String... args) throws Exception {
        SmartCardCertificate certificate = getCertificate();
        XmlSigner xmlSigner = new XadesXmlSigner();
        File signedFile = new File("out/signed.sig");
        xmlSigner.sign(new File("test_xml_to_sign.xml"), signedFile, certificate.getPrivateKey(), certificate.getX509Certificate());
        System.out.println("Signed file saved in: " + signedFile.getAbsolutePath());
    }
 
    private static SmartCardCertificate getCertificate() throws TokenException, IOException, CertificateException, NoSuchAlgorithmException, KeyStoreException {
        BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
 
 
        SmartCardReader smartCardReader = new GeneralSmartCardReader("CCPkiP11.dll");
        List<Token> avaliableTokens = smartCardReader.getAvaliableTokens();
        avaliableTokens.forEach(System.out::println);
        System.out.println("Pick which token to use: ");
        String slotId = br.readLine();
        System.out.println("Enter pin:");
        String pin = br.readLine();
        List<SmartCardCertificate> certificates = smartCardReader.getCertificates(Integer.parseInt(slotId), pin.toCharArray());
        for (int i=0; i<certificates.size(); i++) {
            SmartCardCertificate certificate = certificates.get(i);
            System.out.println(i+": " + certificate.getAlias());
        }
 
        System.out.println("Pick certificate:");
        String pickedCertificate = br.readLine();
 
        return certificates.get(Integer.parseInt(pickedCertificate));
    }
}

Większa część powyższej klasy, dotycząca pobierania certyfikatu z podpisu elektronicznego, pojawiła się już wcześniej w pierwszej części artykułu. Jedyne zmiany to tak naprawdę linijki 10-13, w których dokonujemy podpisu pliku "test_xml_to_sign.xml" i zapisujemy rezultat w katalogu out/ jako signed.sig.

Efekt uruchomienia aplikacji jest następujący:

Wybór certyfikatu

Początek wygląda dokładnie tak samo jak w pierwszej części artykułu - wybieramy token, wpisujemy pin, a następnie wybieramy jeden z dostępnych certyfikatów.

Następnie w tle podpisywany jest plik i otrzymujemy informacje o tym, gdzie został on zapisany:

Informacja o poprawnym zapisie podpisanego pliku

Gdy otworzymy ten plik, zobaczymy mniej więcej taką zawartość:

Zawartość podpisanego XML'a

Jeśli natomiast otworzymy ten plik w aplikacji sprawdzającej podpisy (np. Szafir), to będziemy mogli zobaczyć, że podpis rzeczywiście jest rozpoznawany i informacje o podpisującym wyświetlają się poprawnie:

Podpisany plik - widok w Szafirze

Podsumowanie

Podsumowując, w pierwszej części artykułu dowiedzieliśmy się czym właściwie są podpisu elektroniczne i czym różnią się od podpisów cyfrowych, a także udało nam się dostać do danych zapisanych na podpisie elektronicznym. W drugiej części artykułu wykorzystaliśmy natomiast dane zawarte w podpisie elektronicznym do wykonania podpisu pliku XML zgodnego z standardem XAdES. Udało nam się także zweryfikować w zewnętrznej aplikacji, że taki podpis jest poprawnie widziany i odczytywany.

Podpisywanie plików XML w Javie. Część pierwsza - obsługa podpisu elektronicznego

Thu, 08 Mar 2018 00:00:00 GMT

W poniższym artykule zaprezentuję możliwości podpisywania plików XML za pomocą podpisów elektronicznych z wykorzystaniem Javy, a także opiszę, czym właściwie są podpisy elektroniczne, oraz jakie mają zastosowania.

Artykuł składa się z dwóch części:

Podpis elektroniczny - czym jest oraz jak obsłużyć go w Javie
Podpisywanie plików XML - jakie są standardy co do tego jak powinny wyglądać podpisane pliki oraz jak wygenerować taki plik za pomocą Javy

Poniżej znajduje się pierwsza część dotycząca podpisu elektronicznego.

W artykule przedstawię kolejne kroki tworzenia aplikacji (choć w niektórych przypadkach w uproszczonej wersji, np. bez informacji o importach), ale całość można także znaleźć na Githubie pod adresem https://github.com/RafalPydyniak/XmlDigitalSignatureDemo

Podpisy elektroniczne

Podpisy elektroniczne a podpisy cyfrowe

Na początku warto rozróżnić czym różnią się podpisy elektroniczne od cyfrowych.

Podpis cyfrowy (ang. digital signature) - w uproszczeniu jest to po prostu matematyczny sposób sprawdzenia autentyczności danego pliku. Protokół podpisu cyfrowego opiera się zazwyczaj na kryptografii asymetrycznej, czyli dostępne mamy dwa klucze - publiczny oraz prywatny. Klucz prywatny służy do podpisania danych, natomiast klucz publiczny do potwierdzenia autentyczności danego pliku. Do generowania kluczy używa się zazwyczaj protokołu RSA lub DSA.

Podpis elektroniczny (ang. electronic signature) - w porównaniu do podpisu cyfrowego termin ten odnosi się do całego mechanizmu składania podpisu pod plikami w formie elektronicznej. Plik podpisany elektronicznie niesie ze sobą takie same skutki prawne jak podpis własnoręczny, choć dokładne regulacje prawne mogą się różnić w poszczególnych państwach. Podpis elektroniczny jest zazwyczaj realizowany za pomocą podpisu cyfrowego w celu zapewnienia jego autentyczności.

Podsumowując, podpisy cyfrowe oraz podpisy elektroniczne nie są tym samym, jednak należy mieć na uwadze, że w niektórych źródłach terminy te w niewłaściwy sposób używane są zamiennie.

Sam proces generowania i sprawdzania autentyczności podpisów cyfrowych jest stosunkowo prosty i jego uproszczony opis można znaleźć nawet na Wikipedii.

Do czego mogą być użyte podpisy elektroniczne

Podpisy elektroniczne mają taką samą moc prawną jak podpisy własnoręczne. Za ich pomocą można na przykład podpisać umowy (co potwierdza art. 78 Kodeksu Cywilnego), załatwić sprawy urzędowe przez Internet, czy też podpisać deklaracje podatkową.

Właśnie do tego ostatniego, czyli do podpisywania deklaracji podatkowych, może się przydać możliwość podpisywania plików XML. Ministerstwo Finansów udostępnia bramką E-Deklaracje, za pomocą której można złożyć deklaracje online. Bramka ta przyjmuje podpisane pliki XML, a w zamian otrzymujemy identyfikator naszej przesyłki, dzięki któremu możemy śledzić status wysyłki, a następnie pobrać dla niej UPO czyli potwierdzenie złożenia deklaracji podatkowej przez Internet.

Obsługa podpisu elektronicznego w Javie - przykład

Biblioteki oraz standard PKCS

Do obsługi podpisu elektronicznego wykorzystamy bibliotekę IAIK PKCS#11, choć możliwe jest także skorzystanie z implementacji Sun PKCS#11, która jednak według mojej najlepszej wiedzy nie oferuje tak wiele jak IAIK.

Warto na początku wspomnieć także o tym, czym jest PKCS#11. Sam akronim PKCS oznacza "Public Key Cryptography Standards" i jest zbiorem standardów kryptograficznych publikowanych przez firmę RSA Security. PKCS#11 jest własnie jednym z tych standardów i dotyczy interfejsu do obsługi tokenów kryptograficznych, takich jak karty z podpisami elektronicznymi, na których znajduje się certyfikat do podpisu elektronicznego. Certyfikaty te wydawane są w Polsce przez kilka instytucji na przykład KIR.

Co chcemy uzyskać

Początkowo określimy to co właściwie chcemy uzyskać. W naszym podpisie elektronicznym zapisany jest certyfikat oraz klucz prywatny, które razem pozwalają nam dokonać podpisu elektronicznego i właśnie te dane chcemy pobrać z naszego urządzenia.

Certyfikat ten będziemy reprezentować przez następującą klasę:

public class SmartCardCertificate {
    private String alias;
    private X509Certificate x509Certificate;
    private PrivateKey privateKey;

    public SmartCardCertificate(String alias, X509Certificate x509Certificate, PrivateKey privateKey) {
        this.alias = alias;
        this.x509Certificate = x509Certificate;
        this.privateKey = privateKey;
    }

    public String getAlias() {
        return alias;
    }

    public X509Certificate getX509Certificate() {
        return x509Certificate;
    }

    public PrivateKey getPrivateKey() {
        return privateKey;
    }

    @Override
    public String toString() {
        return "SmartCardCertificate{" +
                "alias='" + alias + '\'' +
                ", x509Certificate=" + x509Certificate +
                ", privateKey=" + privateKey +
                '}';
    }
}

Musimy jednak wiedzieć, że w systemie możemy mieć kilka tzw. tokenów, z których każdy może zawierać jeden lub więcej certyfikatów. Przykładowo, w podpisie KIR system wykrywa aż cztery tokeny, z których tylko na jednym dostępny jest certyfikat. Każdy token jest przypisany do danego "slotu" w systemie.

Aby obsłużyć takie sytuacje, chcemy:

Pobrać listę tokenów (wraz z informacją o slocie, na którym się on znajduje)
Pobrać listę certyfikatów dla danego tokenu (a dokładniej slotu, pod który jest podpięty ten token)

Zdefiniujmy więc interfejs, który pozwoli nam zrealizować oba te cele:

public interface SmartCardReader {
    List<Token> getAvaliableTokens() throws TokenException;
    List<SmartCardCertificate> getCertificates(long slotId, char[] pin) throws CertificateException, NoSuchAlgorithmException, IOException, KeyStoreException;
}

Wcześniej zdefiniowaliśmy już klasę SmartCardCertificate, więc aby ten kod był kompletny, zdefiniujemy jeszcze klasę Token (dla przejrzystości pominąłem gettery):

public class Token {
    private long slotId;
    private String label;

    public Token(long slotId, String label) {
        this.slotId = slotId;
        this.label = label;
    }

    @Override
    public String toString() {
        return slotId + ": " + label;
    }
}

Za pomocą takiego interfejsu możemy już obsłużyć właściwie całą komunikację z naszym podpisem elektronicznym. Zanim przejdziemy do implementacji tego interfejsu, możemy napisać metodę Main, która pobierze i wyświetli certyfikat.

Czyli po kolei:

Pobieramy listę dostępnych tokenów za pomocą metody getAvaliableTokens() wraz z informacją, na którym slocie się znajdują.
Dajemy użytkownikowi możliwość wybrania interesującego go slotu.
Pobieramy listę certyfikatów dostępnych na tym slocie za pomocą getCertificates(long slotId, char[] pin), jako parametr podajemy wybrany slot, a także PIN do tokenu na wybranym slocie.
Wybieramy jeden z dostępnych certyfikatów.
Na ten moment tylko wyświetlamy informacje o wybranym certyfikacie.

Metoda main realizująca wszystkie powyższe punkty wygląda następująco (klasę GeneralSmartCardReader zdefiniujemy za chwile):

public static void main(String... args) throws Exception {
    SmartCardCertificate certificate = getCertificate();
    System.out.println(certificate);
}
private static SmartCardCertificate getCertificate() throws TokenException, IOException, CertificateException, NoSuchAlgorithmException, KeyStoreException {
    BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
    SmartCardReader smartCardReader = new GeneralSmartCardReader("CCPkiP11.dll");
    List<Token> avaliableTokens = smartCardReader.getAvaliableTokens();
    avaliableTokens.forEach(System.out::println);
    System.out.println("Pick which token to use: ");
    String slotId = br.readLine();
    System.out.println("Enter pin:");
    String pin = br.readLine();
    List<SmartCardCertificate> certificates = smartCardReader.getCertificates(Integer.parseInt(slotId), pin.toCharArray());
    for (int i=0; i<certificates.size(); i++) {
        SmartCardCertificate certificate = certificates.get(i);
        System.out.println(i+": " + certificate.getAlias());
    }

    System.out.println("Pick certificate:");
    String pickedCertificate = br.readLine();

    return certificates.get(Integer.parseInt(pickedCertificate));
}

Warto zaznaczyć, że całość odbywa się poprzez konsolę, przez którą podajemy między innymi slot, pin, czy też wybrany certyfikat. Obsługa wyjątków została celowo pominięta, choć oczywiście w rzeczywistości powinny one zostać obsłużone. Jako że jednak jest to tylko i wyłącznie proste demo, to możemy sobie pozwolić na takie niedoskonałości.

Główny element, czyli klasa GeneralSmartCardReader komunikująca się z podpisem

Klasa GeneralSmartCardReader to po prostu implementacja wcześniej zdefiniowanego interfejsu SmartCardReader. Dodatkowo dodajemy pole driver i przypisujemy je w konstruktorze. W polu tym będziemy zapisywać informacje o tym, jaka biblioteka powinna zostać użyta do odczytywania danych z karty. Biblioteki te różnią się w zależności od podpisu elektronicznego i tak przykładowo dla:

KIR - driver nazywa się CCPkiP11.dll
Sigillum/PWPW - analogicznie jak wyżej - jest to związane z tym, iż KIR oraz Sigillum/PWPW używają tych samych kart
Certum - cryptoCertum3PKCS.dll

Biblioteki te znajdują się w katalogach z oprogramowaniem do danego podpisu. Driver do KIR'a (a więc i do Sigillum/PWPW) zostanie także dołączony do aplikacji demo na Githubie.

public class GeneralSmartCardReader implements SmartCardReader {
    private final String driver;

    public GeneralSmartCardReader(String driver) {
        this.driver = driver;
    }

    @Override
    public Lis<Token> getAvaliableTokens() throws TokenException {
        //TODO
    }

    @Override
    public List<SmartCardCertificate> getCertificates(long slotId, char[] pin) throws CertificateException, NoSuchAlgorithmException, IOException, KeyStoreException {
       //TODO
    }
}

Zaczniemy od pierwszej metody, służącej do pobrania tokenów:

    public List<Token> getAvaliableTokens() throws TokenException {
        Properties properties = new Properties();
        properties.put("PKCS11_NATIVE_MODULE", driver);
        Module module = IAIKPkcs11.getModule(properties);
        Slot[] slotList = module.getSlotList(true);
        List<Token> tokens = Arrays.stream(slotList).map(slot -> {
            try {
                return new Token(slot.getSlotID(), slot.getToken().getTokenInfo().getLabel());
            } catch (TokenException e) {
                return null;
            }
        }).filter(Objects::nonNull).collect(Collectors.toList());
        return tokens;
    }

Po kolei:

W linijce 4 musimy pobrać odpowiedni moduł do obsługi interfejsu PKCS#11. Aby tego dokonać, jako parametr musimy podać listę propertiesów, w której zawarta jest nazwa modułu (czyli właściwie biblioteki). Propertiese tworzymy w linijkach 2,3.
W linijce 5 pobieramy listę slotów odczytanych z tego modułu. Parametr true oznacza, że pobieramy tylko sloty, na których znajduje się jakiś token.
W linjkach 6-12 pobieramy listę tokenów. Dla każdego slotu pobieramy numer slotu oraz opis znajdującego się na nim tokenu. Na podstawie tych informacji tworzymy wcześniej zdefiniowane obiekty klasy Token, które następnie zwracamy.

Mając listę tokenów możemy dać użytkownikowi wybór co do tego, który z nich ma zostać użyty. Przejdźmy teraz do etapu pobrania certyfikatów. Poniżej znajduje się cały kod:

@Override
    public List<SmartCardCertificate> getCertificates(long slotId, char[] pin) throws CertificateException, NoSuchAlgorithmException, IOException, KeyStoreException {
        Security.insertProviderAt(new IAIK(), 2);
        KeyStore keyStore = getPKCS11KeyStore(driver, pin, slotId);
        return getCertificatesFromKeystore(keyStore);
    }

    private KeyStore getPKCS11KeyStore(String driver, char[] pin, long slotId) throws CertificateException, NoSuchAlgorithmException, IOException {
        Properties properties = getProperties(driver, pin, slotId);
        IAIKPkcs11 provider = new IAIKPkcs11(properties);
        Security.insertProviderAt(provider, 2);
        Properties loginProperties = new Properties();
        DefaultLoginManager loginManager = new DefaultLoginManager(loginProperties);
        provider.setLoginManager(loginManager);
        provider.getTokenManager().getKeyStore();
        KeyStore keyStore = provider.getTokenManager().getKeyStore();
        keyStore.load(null, pin);
        return keyStore;
    }

    private Properties getProperties(String driver, char[] pin, long slotID) {
        Properties properties = new Properties();
        properties.setProperty(Constants.KEY_STORE_SUPPORT_PROVIDER, "IAIK");
        properties.setProperty(Constants.SESSION_POOL_MAX_SIZE, "100");
        properties.setProperty(Constants.MULTI_THREAD_INIT, "true");
        properties.setProperty(Constants.LOGIN_KEYSTORE_SESSION_ON_DEMAND, "false");
        properties.setProperty(Constants.PKCS11_NATIVE_MODULE, driver);
        properties.setProperty(Constants.CHECK_MECHANISM_SUPPORTED, "true");
        properties.setProperty(Constants.USER_PIN, String.valueOf(pin));
        properties.setProperty(Constants.SLOT_ID, String.valueOf(slotID));
        return properties;
    }

     /**
     * Returns certificates on keystore.
     * Keep in mind that this method is just a sample method so not all exceptions are handled properly!
     * @param keyStore
     * @return
     * @throws KeyStoreException
     */
    private List<SmartCardCertificate> getCertificatesFromKeystore(KeyStore keyStore) throws KeyStoreException {
        return Collections.list(keyStore.aliases()).stream().map(alias -> {
            try {
                Key key = keyStore.getKey(alias, null);
                if (key instanceof RSAPrivateKey) {
                    Certificate[] certificateChain = keyStore.getCertificateChain(alias);

                    X509Certificate signerCertificate = (X509Certificate) certificateChain\[0\];
                    boolean[] keyUsage = signerCertificate.getKeyUsage();
                    if ((keyUsage == null) || keyUsage\[0\] || keyUsage\[1\]) {
                        return new SmartCardCertificate(alias, signerCertificate, (PrivateKey) key);
                    }
                }
                return null;
            } catch (Exception e) {
                throw new RuntimeException();
            }
        }).filter(Objects::nonNull).collect(Collectors.toList());
    }

Najważniejsze części pobierania listy certyfikatów:

W linijce 4 pobieramy obiekt KeyStore, w którym przechowywane są klucze oraz certyfikaty. Całe pobranie jest stosunkowo proste i odbywa się w metodzie getPKCS11KeyStore.
W metodzie getProperties określamy listę parametrów potrzebną do stworzenia Providera IAIKPkcs11, którego następnie użyjemy do pobrania obiektu KeyStore. W parametrach podajemy m.in. driver, pin, a także wybrany slot.
W metodzie getCertificatesFromKeystore (wywoływanej w linijce 5) pobieramy listę obiektów wcześniej stworzonej klasy SmartCardCertificate. Keystore posiada w sobie jeden lub więcej aliasów - dla każdego z tych aliasów zapisujemy sam alias, klucz prywatny oraz certyfikat X509.

Efekt końcowy - użycie aplikacji

Odpalając aplikację z wcześniej zdefiniowanej metody main, na początku zostaniemy poproszeni o wybranie jednego z tokenów.

Wybór tokenu

Następnie wpisujemy pin.

I na koniec z listy dostępnych certyfikatów wybieramy ten, który nas interesuje. Następnie jego zawartość jest wyświetlana na ekranie.

Wybór certyfikatu

Co dalej?

Na podstawie pobranych certyfikatów (a dokładniej X509 oraz klucza prywatnego) możemy już dokonywać podpisów. W następnej części artykułu, dostępnej pod adresem https://pydyniak.pl/podpisywanie-plikow-xml-w-javie-2/, opiszę sposób podpisu plików XML, ale oczywiście tak pobrane dane można użyć także do innych celów np. podpisu innego typu plików.