MultiInfo Certyfikat dostępu do usługi
Spis treści 1 Wstęp... 4 2 Certyfikaty Klienckie... 4 3 Generowanie certyfikatu podpisanego przez MultiInfo CA... 5 3.1 Oprogramowanie... 5 3.2 Sposób generowania certyfikatu przez XCA... 5 3.2.1 Instalacja i uruchomienie programu... 5 3.2.2 Stworzenie bazy danych... 5 3.2.3 Generowanie kluczy... 6 3.2.4 Stworzenie certyfikatu... 7 3.2.5 Eksport... 13 3.2.6 Podpisanie certyfikatu przez Polkomtel (MultiInfo CA)... 14 3.2.7 Import podpisanego certyfikatu... 15 3.2.8 Eksport certyfikatu prywatnego... 17 4 Instalacja certyfikatu w przeglądarce... 18 5 Wykorzystanie certyfikatów... 20 6 Logowanie się za pomocą certyfikatu (tylko dla dostępu do panelu z poziomu przeglądarki)... 21 7 Odnowienie certyfikatu... 22 8 Ważność certyfikatu... 23 wersja 3.0.4 Polkomtel S.A. Wszelkie prawa zastrzeżone
wersja 3.0.4 Polkomtel S.A. Wszelkie prawa zastrzeżone
1 Wstęp Niniejszy dokument jest specyfikacją certyfikatu Klienta oraz zawiera szczegółowy opis generowania certyfikatu. 2 Certyfikaty Klienckie Uzyskanie dostępu do interfejsu programistycznego API, platformy Multiinfo, wymaga posiadania prawidłowego certyfikatu klienckiego. Rekomendowane jest aby certyfikat klienta podpisany był przez jedno z dwu autoryzowanych centrów certyfikacyjnych: Thawte lub VeriSign. Dopuszczone jest wykorzystanie certyfikatu wygenerowanego i podpisanego przez Polkomtel S.A. Pole CN podmiotu certyfikatu powinno zawierać parametr login służącym do weryfikacji dostępu. Dodatkowo, do przejścia pomyślnej weryfikacji należy dostarczyć do Polkomtel następujące informacje o certyfikacie: wystawca, pola CN,O,L,C, podmiot, pola CN,O,L,C, odcisk palca. Wymagania Polkomtel dotyczące wygenerowanych i dostarczony przez klienta części publicznych certyfikatu głównego: 1. Pola certyfikatu zawierają odpowiednio: CN - login użytkownika w systemie MultiInfo, dla którego generowany jest certyfikat (pole weryfikowane przez aplikację) O - nazwa firmy użytkownika (pole weryfikowane przez aplikację) L - miasto, w którym ma siedzibę firma (pole weryfikowane przez aplikację) C - standardowy skrót kraju użytkownika (PL) (pole weryfikowane przez aplikację) E - adres mailowy osoby kontaktowej (użytkownika) 2. Skrót, zwany potocznie odciskiem palca (ang. fingerprint) wykonany przy pomocy funkcji jednokierunkowej SHA-1 3. Ważność certyfikatu - maksymalnie dwa lata 4. Długość klucza - 2048 bit, algorytm RSA Polkomtel S.A. Wszelkie prawa zastrzeżone 4 / 23
3 Generowanie certyfikatu podpisanego przez MultiInfo CA 3.1 Oprogramowanie Do generowania certyfikatu podpisanego przez klienta zalecane jest użycie programu XCA. Oprogramowanie to jest proste w użyciu i zostało przetestowane z usługą Multiinfo. Oprogramowanie dostępne jest pod adresem: http://sourceforge.net/projects/xca i rozpowszechniane jest na licencji BSD. 3.2 Sposób generowania certyfikatu przez XCA Opis generowania certyfikatów dotyczy oprogramowania XCA w wersji 0.6.4 lub nowszej. 3.2.1 Instalacja i uruchomienie programu Oprogramowanie XCA należy pobrać ze strony projektu umieszczonej na serwerze Sourceforge pod adresem http://sourceforge.net/projects/xca. Przebieg instalacji w systemie MS Windows wykonujemy w standardowy sposób za pomocą instalatora i postępujemy zgodnie z instrukcją kreatora instalacji. Po zainstalowaniu programu uruchamiamy go wybierając: START -> Programy -> xca -> xca Po uruchomieniu programu postępujemy zgodnie z poniższymi wskazówkami 3.2.2 Stworzenie bazy danych W pierwszej kolejności należy stworzyć bazę danych w której będą przechowywane klucze i certyfikaty. Bazę danych tworzymy wybierając w programie: File -> New DataBase Polkomtel S.A. Wszelkie prawa zastrzeżone 5 / 23
Następnie podajemy nazwę pliku i wybieramy lokalizację na dysku oraz wciskamy klawisz Zapisz. W kolejnym kroku będziemy poproszeni o podanie hasła zabezpieczającego do bazy. Nowe hasło wpisujemy dwukrotnie w celu weryfikacji. Zalecane jest aby baza zabezpieczona została hasłem w celu ochrony przed niepowołanym dostępem. 3.2.3 Generowanie kluczy Celem wygenerowania kluczy certyfikatu należy postępować zgodnie z poniższymi wskazówkami. W pierwszej kolejności przechodzimy do zakładki Private Keys. Wybieramy przycisk New key z listy po prawej stronie panelu w celu wygenerowania pary kluczy: publicznego i prywatnego. Następnie zostaniemy poproszeni o wpisanie: Polkomtel S.A. Wszelkie prawa zastrzeżone 6 / 23
nazwy klucza (Name) dowolna nazwa (proponowane nazwa użytkownika w MultiInfo); rozmiar klucza (Keysize) 2048 bitów; typ klucza (Keytype) koniecznie RSA. Po wpisaniu danych wciskamy przycisk Create. Po wykonaniu powyższych czynności zostaną utworzone klucze co pokazuje poniższy rysunek. 3.2.4 Stworzenie certyfikatu W dalszym kroku po utworzeniu kluczy przystępujemy do stworzenia Żądania podpisania certyfikatu. W tym celu przechodzimy do zakładki Certificate signing requests. Polkomtel S.A. Wszelkie prawa zastrzeżone 7 / 23
W celu stworzenia certyfikatu wybieramy przycisk z lewej strony panelu New Request. Pojawi się następne nowe okno w którym należy wypełnić poszczególne zakładki w poniży sposób. W zakładce Source wypełniamy pola: pole Signature algorithm - koniecznie wybieramy SHA 1. pole Template for the New certificate koniecznie wybieramy szablon o nazwie HTTPS_client, a następnie wciskamy przycisk Apply. Polkomtel S.A. Wszelkie prawa zastrzeżone 8 / 23
Następnie w kolejnym kroku przechodzimy do zakładki Subject, gdzie należy wypełnić dane zgodnie z poniższymi wytycznymi: pole Internal name wpisujemy nazwę użytkownika wykorzystywanego w oprogramowaniu MultiInfo pole Country Code obowiązkowo wpisujemy PL pole State or Province obowiązkowo wpisujemy nazwę województwa siedziby Klienta (np. Mazowieckie) pole Locality obowiązkowo wpisujemy nazwą miejscowości siedziby Klienta (np. Warszawa) pole Organisation obowiązkowo wpisujemy nazwę firmy Klienta (w przykładzie Nazwa Firmy ) pole Organ. Unit obowiązkowo wpisujemy nazwę firmy Klienta, tak samo jak w powyższym polu pole Common name obowiązkowo wpisujemy nazwę użytkownika login dla systemu Multiinfo (w przykładzie nazwa.uzytkownika ) pole E-mail adress wpisujemy adres e-mail użytkownika systemu Multiinfo wykorzystującego ten certyfikat (nazwa@<domena_firmy) Pozostałe pola pozostawiamy bez zmian a pole Private key powinno wskazywać na klucze wygenerowane w poprzednim kroku. Przykładowe wypełnienie pól znajduje się na poniższym rysunku. Polkomtel S.A. Wszelkie prawa zastrzeżone 9 / 23
W kolejnym kroku przechodzimy do zakładki Extensions. Krytycznym polem jest Type w ramce Basic Contrains. Pole to powinno mieć ustawiony parametr End Entity. Polkomtel S.A. Wszelkie prawa zastrzeżone 10 / 23
Pozostałe pola pozostawiamy bez zmian zgodnie z poniższym rysunkiem. Przechodzimy do zakładki Key Usage i wybieramy następujące pozycje zgodnie z poniższym rysunkiem. Polkomtel S.A. Wszelkie prawa zastrzeżone 11 / 23
Po zaznaczeniu odpowiednich pół należy przejść do zakładki Netscape. Pola w tej zakładce powinny być zgodne z poniższym rysunkiem a następnie wcisnąć przycisk OK. Polkomtel S.A. Wszelkie prawa zastrzeżone 12 / 23
Po przeprowadzeni powyższych czynności Żądanie podpisania certyfikatu powinno być widoczne w aplikacji w zakładce Certificate signinig request. 3.2.5 Eksport W zakładce Certificate signinig request widoczny jest certyfikat, który zostały stworzony w powyższym punkcie. Należy go wyeksportować. W tym celu należy zaznaczyć certyfikat i wcisnąć przycisk Export. Pojawi się nowe okienko, w którym należy: wybrać typ certyfikatu w polu Export Format obowiązkowo należy wybrać opcję PEM, Polkomtel S.A. Wszelkie prawa zastrzeżone 13 / 23
w polu Filename wskazać nazwę pliku i miejsce na dysku gdzie eksportowany certyfikat zostanie zapisany. Wciśnięcie przycisku OK spowoduje wyeksportowanie certyfikatu i zapisanie go we wskazanej lokalizacji. Wyeksportowany plik zawiera żądanie podpisania certyfikatu Klienta, który należy przekazać do Plusa zgonie z rozdziałem następnym. 3.2.6 Podpisanie certyfikatu przez Polkomtel (MultiInfo CA) Wyeksportowany plik należy przekazać do Plus a do swojego opiekuna lub osoby, która jest odpowiedzialna za uruchomienia usługi po stronie Polkomtel. Klient w odpowiedzi otrzyma automatycznie podpisany certyfikat z dedykowanego maila (ExchangeEvents@polkomtel.com.pl). Nie należy odpowiadać na tego maila. Wiadomość ta będzie zawierać dwa pliki: Nazwa.cer certyfikat klienta, który został podpisany Nazwa.p7b pełna ścieżka certyfikacyjna (CA + certyfikat klienta) Polkomtel S.A. Wszelkie prawa zastrzeżone 14 / 23
Gdzie Nazwa jest to numer identyfikacyjny certyfikatu w systemie Polkomtel. 3.2.7 Import podpisanego certyfikatu Po otrzymaniu z Polkomtel S.A. podpisanego certyfikatu oraz CA MultiInfo należy zaimportować je do aplikacji XCA. W pierwszej kolejności trzeba nagrać otrzymane pliki na lokalny dysk. Następnie otworzyć aplikację XCA wraz z bazą z której był generowany request do podpisu wysłany do Polkomtel. W kolejnym kroku należy wcisnąć przycisk Import PKCS#7, a następnie wybrać plik,który został nagrany na dysku lokalnym o rozszerzeniu p7b. Wszystkie CA oraz certyfikat zostanie automatycznie zaimportowany do aplikacji XCA oraz pojawią się one w okienku Certificates. Polkomtel S.A. Wszelkie prawa zastrzeżone 15 / 23
Następnie należy kliknąć prawym przyciskiem myszki na wszystkich pozycjach osobno, kliknąć w menu pole Trust, a w okienku, które się pojawi należy zaznaczyć opcję Always trust his certificate. Polkomtel S.A. Wszelkie prawa zastrzeżone 16 / 23
3.2.8 Eksport certyfikatu prywatnego W tym kroku należy wyeksportować certyfikat prywatny klienta, który będzie zawierał dodatkowo klucz prywatny Klienta. Sposób i format eksportu certyfikatu lub kluczy należy dostosować do aktualnych potrzeb i środowiska programistycznego Klienta, w którym realizowana będzie aplikacja korzystająca z API systemu Multiinfo. Poniższy opis przedstawia sposób eksportu certyfikatu, który może być później zainstalowany w przeglądarce klienta. Należy wejść do zakładki i zaznaczyć certyfikat dla danego użytkownika. Po jego zaznaczeniu i wciśnięciu przycisku Export pojawi się nowe okienko, w którym należy: wybrać typ certyfikatu w polu Export Format obowiązkowo należy wybrać opcję PKCS #12 with Certificate chain, wskazać nazwę pliku i miejsce na dysku gdzie eksportowany certyfikat zostanie zapisany. Wciśnięcie przycisku OK. Wciśnięcie przycisku OK spowoduje wyeksportowanie certyfikatu i zapisanie go we wskazanej lokalizacji. Polkomtel S.A. Wszelkie prawa zastrzeżone 17 / 23
4 Instalacja certyfikatu w przeglądarce Celem logowania się poprzez certyfikat (w przeglądarce, API) należy: zaimportować Polkomtel S.A. Root Authority do przeglądarki zaimportować Polkomtel MultiInfo CA do przeglądarki zaimportować klucz prywatny do przeglądarki W celu zaimportowania Polkomtel S.A. Root Authority oraz Polkomtel MultiInfo CA należy kliknąć dwa razy na danym CA. Pojawi się okienko certyfikatu (takie jak powyżej), a następnie należy wybrać opcję Zainstaluj certyfikat. Polkomtel S.A. Wszelkie prawa zastrzeżone 18 / 23
Zostanie uruchomiony kreator instalowanie certyfikatu. Należy klikać przycisk Dalej, aż dojdzie się do opcji zakończ. W celu zaimportowania certyfikatu z kluczem prywatnym (rozszerzenie pliku certyfikatu to p12) należy dwa razy kliknąć na certyfikacie oraz przejść przez proces instalacji analogiczny jak przy instalacji CA dedykowanych dla MultiInfo. W trakcie importu nie należy zaznaczać chceckbox ów związanych z możliwością eksportowania certyfikatów oraz ustawienia silnej ochrony certyfikatu. Pola te muszą być puste zgodnie z poniższym rysunkiem. Polkomtel S.A. Wszelkie prawa zastrzeżone 19 / 23
Następnie w przeglądarce (IE) w opcjach internetowych > Zawartość > Certyfikaty można zobaczyć czy certyfikaty zostały zaimportowane. 5 Wykorzystanie certyfikatów W zależności od zastosowania certyfikatu, narzędzi wykorzystywanych do kontaktu z MultiInfo, opisany w rozdziale 3.2.8 sposób eksportu certyfikatu może wymagać modyfikacji. Poniżej opisano typowe zastosowania oraz sposób wykonania eksportu. Łączenie się z MultiInfo za pomocą przeglądarki Internet Explorer bez zmian PHP - w polu Export Format należy wtedy wybrać opcję PEM Cert + key C#/VisualStudio bez zmian (certyfikat należy zainstalować w repozytorium Windows, a następnie otworzyć i wyszukać to repozytorium z wykorzystaniem bibliotek standardowych.net) Java bez zmian, szczegóły znajdują się w przykładach Polkomtel S.A. Wszelkie prawa zastrzeżone 20 / 23
6 Logowanie się za pomocą certyfikatu (tylko dla dostępu do panelu z poziomu przeglądarki) W celu zalogowania się do systemu MultiInfo, korzystając z przeglądarki należy otworzyć następujący adres: https://www.multiinfo.plus.pl/logincrt4/ Zostaniemy zapytani o wybór certyfikatu klienckiego: Po wybraniu właściwego, naciśnięciu OK, przejdziemy do właściwego procesu logowania. Należy wprowadzić login i hasło, kliknąć ZALOGUJ. Po poprawnej weryfikacji tych parametrów zostaniemy przekierowani na główną stronę aplikacji. Polkomtel S.A. Wszelkie prawa zastrzeżone 21 / 23
7 Odnowienie certyfikatu Certyfikaty, zgodnie z powyższą instrukcją, wystawiane są na okres 2 lat (okres ważności certyfikatu). Data upłynięcia ważności certyfikatu oznacza automatyczne zablokowanie możliwość korzystania z danego certyfikatu (logowanie www lub dostęp przez API). W celu odnowienia obecnie wykorzystywanego certyfikatu należy postępować zgodnie z niniejszą instrukcją proces jest analogiczny do wystawiania nowego certyfikatu. Istotnym jest tylko fakt wpisania w polu CN podmiotu obecnego loginu z MultiInfo dla którego wykorzystywany ma być certyfikat. Ostatnią czynnością, która umożliwi poprawne wykorzystanie nowego certyfikatu, jest modyfikacja ustawień autoryzacji danego użytkownika w oprogramowaniu MultiInfo. W tym celu należy zalogować się do Systemu z prawami administratora, przejść do edycji użytkownika. Następnie w zakładce Autentykacja zmienić odpowiednie pola powinny być zgodne z polami z nowego certyfikatu. W trakcie uzupełniania pół w zakładce Autentykacja należy zostawić puste poniższe pola: O Wystawcy L Wystawcy C Wystawcy Pozostałe pola muszą być identyczne z polami znajdującymi się w otrzymanym certyfikacie z Polkomtel. Polkomtel S.A. Wszelkie prawa zastrzeżone 22 / 23
8 Ważność certyfikatu Certyfikaty są wystawiane na 2 lata. W usłudze MultiInfo został zaimplementowany mechanizm automatycznego powiadamiania administratorów klienta o końcu ważności certyfikatów. Każdy Administrator otrzyma wiadomość na 30, 7 i 2 dni przed końcem ważności certyfikatu o dacie jego wygaśnięcia oraz konieczności jego odnowienia. W celu odnowienia certyfikatu należy postępować zgodnie z pkt 7 niniejszej dokumentacji. Dodatkowo każdy Administrator może zobaczyć datę wygaśnięcia certyfikatu danego usera w trakcie edycji użytkownika w zakładce Autentykacja pole Ważność certyfikatu Polkomtel S.A. Wszelkie prawa zastrzeżone 23 / 23