Sprzętowe zabezpieczenie oprogramowania lockey i2c dokumentacja programisty i API Data dokumentu 10.11.2015
Spis treści Informacje o produkcie...3 Nowy lockey...6 O czym warto wiedzieć...7 Inicjalizacja lockey...8 API...9 Przegląd klas ClockeyEnum, Clockey...10 ClockeyEnum...11 Enumeracja...12 Pominięcie enumeracji...13 Enumerate...14 Next...15 Size...16 Clockey...17 Initialize...19 Reset...20 SetTo...21 GetInfo...22 HasFeature...23 GetUserId...24 Login...25 Logout...27 ReadByte...28 WriteByte...29 ReadMemo...30 WriteMemo...31 ReadRTC...32 WriteRTC...33 WriteKey...34 ProtectKey...35 Encrypt...36 Decrypt...37 GenRand...38 Status metod...39 ELockeyStatus...40 2
Informacje o produkcie Zastosowanie wprowadza sprzętową ochronę oprogramowania przed nielegalnym użytkowaniem. Dzięki wbudowanej pamięci i dostarczanemu API, programista, może zaplanować i wprowadzić model licencjonowania. Tam gdzie wymagana jest szczególna ochrona informacji lub transmisji danych z pomocą przychodzi sprzętowy mechanizm szyfrowania danych. Produkt został zaprojektowany specjalnie pod kątem platformy Raspberry Pi, gdzie zachodzi problem ochrony autorskiej aplikacji przed nielegalnym kopiowaniem oraz łatwym klonowaniem końcowego urządzenia. posiada sprzętowy zegar RTC podtrzymywany bateryjnie. Reasumując, jest produktem łatwym w implementacji nawet dla początkujących programistów, a wykorzystuje zaawansowane mechanizmy kryptograficzne czuwające nad bezpieczeństwem zabezpieczanych aplikacji. Komunikacja i bezpieczeństwo komunikuje się za pomocą magistrali I²C. Aby wykluczyć możliwość podsłuchu transmisji na jakimkolwiek etapie, wprowadzono szyfrowaną i podpisywaną sesję komunikacyjną pomiędzy zabezpieczaną aplikacją a lockey-em. lockey posiada programowalne hasła (klucze) komunikacyjne które są nadawane w procesie jego inicjalizacji. Między innymi przy ich pomocy tworzony jest unikalny tajny i bezpieczny kanał szyfrowany, w którym przebiega komunikacja z lockey-em. Hasła komunikacyjne tworzone i zapisywane są przez twórcę aplikacji. Tylko i wyłącznie znając je, można np. odczytać/zapisać zawartość pamięci lockey. Nie ma żadnej innej metody na poznanie jego zawartości. Oznacza to m.in., że nawet my, jako producent, nie mamy możliwości dostępu do zawartości pamięci lockey-ów naszych klientów. lockey jest również sprzętowym szyfratorem danych. Umożliwia szyfrowanie danych przy użyciu tajnego klucza szyfrowania. Użytym algorytmem szyfrowania jest AES-128 (Rijndael). Jest to symetryczny szyfr blokowy, który w drodze konkursu został wybrany przez amerykański instytut NIST jako standard kryptograficzny (FIPS-197). Użycie właśnie takiego algorytmu gwarantuje odporność lockey na łamanie haseł szyfru metodą siłową (złamanie szyfru może wynieść nawet ponad 10 mld lat, przy obliczeniach dokonywanych na milionie komputerów, potrafiących wykonać miliard prób na sekundę). 3
Parametry Pamięć Dostępne komórki pamięci do dowolnego wykorzystania, z możliwością odczytu/zapisu wybranych bajtów lub bloków o wybranej długości. RTC zegar czasu rzeczywistego Posiada podtrzymanie bateryjne, odmierza czas nawet po wyłączeniu zasilania dla urządzenia. Szyfrowanie AES Sprzętowe szyfrowanie danych tajnym kluczem zapisywanym w lockey. (bez możliwości jego odczytu) Sprzętowy generator liczb pseudolosowych Generuje przy użyciu lockey, losowe 16- to bajtowe bloki danych. Hasło komunikacji logowania Programowane hasło dostępu do lockey. Umożliwia nawiązanie komunikacji i dostęp do jego zasobów. Hasło resetu - przywracające ustawienia fabryczne Programowane hasło. Przywraca stan fabryczny lockey. Identyfikator Programowany identyfikator ułatwiający odnalezienie właściwego lockey przy wielu podpiętych do portu USB. Numer seryjny Niepowtarzalny numer seryjny, nadany podczas produkcji przez producenta. 4 KB dzień, miesiąc rok, godziny, minuty, sekundy możliwość zapisu w lockey do 4 kluczy szyfrowania (klucze AES - 128 bitowe) tak 32 bajtowa tablica (klucz) lub hasło tekstowe * 32 bajtowa tablica (klucz) lub hasło tekstowe* 4 bajty 4 bajty *Hasło tekstowe jest wewnętrznie zamieniane poprzez procedury API na tablicę 32 bajtową. 4
Poniższy schemat przedstawia wewnętrzną organizację lockey. 1 2 3 Obszar dostępny bez logowania. Zapisane są w nim informacje takie jak : numer seryjny wersja oprogramowania lockey właściwości lockey np. czy posiada : pamięć i jaki jest jej rozmiar sprzętowe szyfrowanie i jaką liczbę kluczy AES generator liczb losowych RTC Obszar silnie chroniony z możliwością dostępu tylko i wyłącznie po zalogowaniu do lockey. W nim znajdują się wszystkie ważne zasoby takie jak pamięć, RTC, klucze szyfrowania AES, generator liczb pseudolosowych. Mechanizm przywracania ustawień fabrycznych. Umożliwia przywrócenie ustawień fabrycznych, warunkiem jednak jest użycie prawidłowego hasła resetu. 4 Identyfikator lockey - pomocny podczas szybkiego wyszukiwania lockey przy wielu podpiętych do portu USB komputera. 5
Nowy lockey Każdy nowy lockey wymaga wstępnej inicjalizacji aby możliwa była z nim komunikacja czyli użycie we własnej aplikacji. Inicjalizację należy przeprowadzić programem lockeyedit z pakietu programów dedykowanych do klucza. Inicjalizacja możliwa również jest z poziomu kodu i funkcji API. Przykład w zależności od platformy/systemu operacyjnego i języka programowania znajdziesz w paczce z dedykowanym oprogramowaniem dla lockey. Pobierz najnowsze oprogramowanie oraz przykłady ze strony www.lockey.pl 6
O czym warto wiedzieć Proces inicjalizacji zapisuje do lockey : 1) Hasło (klucz) komunikacji, odpowiedzialne za logowanie i dostęp do lockey. Bez jego znajomości, nie będzie możliwe późniejsze użycie lockey. 2) Hasło (klucz) resetu odpowiedzialne za przywrócenie ustawień fabrycznych, czyli przywrócenie parametrów takich jak po zakupie nowego lockey. 3) Opcjonalnie możliwe jest nadanie własnego identyfikatora. Ułatwi on wyszukanie właściwego lockey przy wielu podłączonych do portów USB komputera. 7
Inicjalizacja lockey Do nauki API oraz testów, zalecamy przeprowadzić inicjalizację w oparciu o proste i ogólnie znane hasła zapisane w projekcie demonstracyjnym. W każdym momencie będzie istniała możliwość przywrócenia ustawień fabrycznych dla lockey i ponowna inicjalizacja z dowolnymi, tajnymi hasłami. W tym celu należy wykonać kroki : 1) Podłączyć, należy również zadbać aby nie był podpięty żaden lockey w wersji USB! 2) Uruchomić edytor lockeyedit. 3) W menu edytora wybrać Plik/Otwórz projekt i wczytać dołączony projekt demonstracyjny demo_lockeyi2c.lkp Na rozwijanej liście w części okna Lockey/Dostępne pojawi się lockey, który został podpięty do magistrali I²C. 4) Kliknąć na zakładkę Inicjalizacja/Reset 5) Nacisnąć przycisk Inicjalizuj lockey i poczekać na zakończenie inicjalizacji. UWAGA Pamiętaj, nieznajomość haseł po inicjalizacji lockey-a jest równoznaczna z : - całkowitym brakiem dostępu do lockey - brakiem możliwości przywrócenia ustawień fabrycznych lockey-a Ze względu na długość tablic haseł i siłę użytego algorytmu AES, nie przyjmuje się sytuacji złamania haseł znanymi metodami w rozsądnym czasie (przy założeniu, że podczas inicjalizacji lockey-a zostały użyte, mocne hasła w postaci tablic wypełnionych wartościami losowymi). Statystycznie potrzebny czas na wykonanie skutecznego ataku siłowego to rząd znacznie większy od kilku mld-ów lat. Podczas inicjalizacji nie wolno odłączać lockey-a oraz wyłączać zasilania urządzenia! 8
API
Przegląd klas ClockeyEnum, Clockey Obsługa lockey bazuje na dwóch klasach ściśle ze sobą powiązanych. Są nimi : ClockeyEnum Klasa przeznaczona do enumeracji (wyszukiwania) podpiętych do komputera lockey. Zawiera ona metody oraz właściwości : Enumerate Next Inicjuje procedure enumeracji, sprawdza czy do komputera został podpięty lockey. Zwraca wskaźnik na obiekt klasy Clockey obsługujący podpięty do portu USB lockey. Size Liczba podpiętych do komputera lockey. Klasa przeznaczona do bezpośredniej komunikacji i obsługi lockey. Zawiera metody : Initialize Reset Inicjalizuje nowy lockey i przywraca ustawienia fabryczne. SetTo Ustawia odwołanie obiektu do wybranego lockey. Wymaga podania numeru seryjnego lockey z którym obiekt ma zostać powiązany. Clockey GetInfo HasFeature GetUserId Login Logout ReadByte WriteByte ReadMemo WriteMemo Odczyt parametrów lockey. Nawiązuje i zamyka sesję (komunikację) z lockey. Metody wykonujące operacje na pamięci lockey. Odczyt/zapis pojedynczych bajtów jak i bloków o wybranej długości. WriteRTC, ReadRTC Metody przeznaczone do ustawienia i odczytu zegara czasu rzeczywistego. WriteKey ProtectKey Encrypt Decrypt Metody obsługujące sprzętowe szyfrowanie i deszyfrowanie przy pomocy lockey. Metod można użyć tylko z lockey-em ze sprzętowym szyfrowaniem AES np. lockey4, lockey8 GenRand Metoda obsługująca sprzętowy generator liczb pseudolosowych. 10
ClockeyEnum
Enumeracja ClockeyEnum jest klasą przeznaczoną do enumeracji (wyszukiwania) podpiętych do komputera lockey. Enumeracja umożliwia : sprawdzenie czy do magistrali I²C lub portu USB został podłączony jakikolwiek lockey. stworzenie obiektu lub wielu obiektów na bazie klasy Clockey obsługujących podłączone do komputera lockey-e. Poniżej przedstawiono przykładowy algorytm enumeracji wyszukujący pierwszy lockey: 12
Jeżeli konieczna jest obsługa wielu lockey-ów, enumerację należy powtórzyć w pętli, wywołując samą metodę Next. Obiekt enumeratora należy zwolnić dopiero po wykonaniu wszystkich niezbędnych operacji. Pamiętaj Enumeracja jest zawsze konieczna jeżeli zachodzi potrzeba sprawdzenia czy jakikolwiek lockey został podpięty do komputera lub jeżeli nie jest znany numer seryjny lockey-a z którym należy się skomunikować. Pominięcie enumeracji Jeżeli numer seryjny lockey-a jest znany, możliwe jest utworzenie obiektu na podstawie klasy Clockey i dalsza komunikacja z lockey-em. W tym celu po stworzeniu obiektu należy wykorzystać metodę SetTo opisaną w dalszej części dokumentacji, pomijając enumerację. Podejście z ominięciem enumeracji może być bardzo dobrym rozwiązaniem w zamkniętych platformach i systemach, gdzie zabezpieczana aplikacja pracuje tylko i wyłącznie z jednym konkretnym lockey-em. Metoda jednak nie jest zalecana przy zabezpieczaniu aplikacji, która ma współpracować z dowolnym lockey-em przeznaczonym dla niej. 13
Enumerate lockey lockey4 lockey8 Parametry userid Metoda inicjuje procedurę enumeracji wyszukiwania lockey, które są podpięte.metoda enumeruje klucz wpięty w magistralę I²C oraz klucze w podłączone do portów USB. Opcjonalnie - identyfikator nadany podczas inicjalizacji metodą Initialize. Jeżeli podczas enumeracji mają być brane pod uwagę tylko lockey-e z konkretnym identyfikatorem, w tym miejscu należy go przekazać. Jeżeli enumerator ma za zadanie wyszukać wszystkie podłączone lockey-e należy przekazać wartość 0. usermask Maska informująca enumerator, które bity w parametrze userid muszą być zgodne, podczas wyszukiwania lockey-ów. Przykładowo, jeżeli zachodzi konieczność wyszukania lockey-a z konkretnym userid, jako maskę należy przekazać wartość 0xFFFFFFFF. (co jest równoznaczne z koniecznością zgodności wszystkich bitów userid) Jeżeli parametr userid nie ma być brany pod uwagę a enumerator ma za zadanie wyszukać wszystkie podłączone lockey-e, należy przekazać 0. Zwracany status ELockeyStatus ELKOK - odnaleziono przynajmniej jeden lockey. Status różny od ELKOK - nie odnaleziono, żadnego lockey-a. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus Enumerate(uint32_t uid, uint32_t umask); 14
Next lockey lockey4 lockey8 Metoda zwraca kolejny wskaźnik na obiekt typu Clockey. Jeżeli do komputera podłączonych jest wiele lockey-ów, metodę należy wywoływać w pętli do momentu zwrócenia przez metodę wartości NULL. Zwracane wartości Clockey* Wskaźnik na obiekt obsługujący odnaleziony lockey - podłączony do portu USB komputera. NULL Nie odnaleziono kolejnego lockey-a. Przykład deklaracji dla Clockey* Next(void); 15
Size lockey lockey4 lockey8 Właściwość tylko do odczytu. Liczba lockey-ów, podłączonych do portów komputera. (z uwzględnieniem identyfikatora i maski przekazanej do metody Enumerate). Zwracane wartości uint32_t Liczba podłączonych lockey-ów. Przykład deklaracji dla uint32_t Size(void); 16
Clockey
Klasa Clockey przeznaczona jest do obsługi/komunikacji z podłączonym lockey-em. Przy jej użyciu możliwy jest zapis/odczyt pamięci, skorzystanie z zegara RTC lockey-a, sprzętowe szyfrowanie/deszyfrowanie oraz dostęp do sprzętowego generatora liczb pseudolosowych. Przykładowy algorytm komunikacji z lockey na bazie klasy Clockey, przedstawiono poniżej: 18
Initialize lockey lockey4 lockey8 Metoda zapisuje w lockey-u: hasło (klucz) wymagane do komunikacji hasło (klucz) przywracające ustawienia fabryczne opcjonalnie - numer identyfikacji Metody tej można użyć tylko na niezainicjalizowanym lockey-u, czyli w takim stanie, w jakim znajduje się po dostarczeniu od producenta lub jeśli dokonano przywrócenia ustawień fabrycznych poprzez metodę Reset. Metoda istnieje w dwóch wersjach. Oprócz wersji podstawowej oczekującej haseł w postaci dwóch tablic 32 bajtowych (tzw. kluczy), przyjmuje również hasła w postaci tekstowej (zmienna typu string). Parametry loginkey Hasło (klucz), które będzie wymagane do nawiązania komunikacji z lockey. resetkey Hasło resetowania, które będzie wymagane w przyszłości do przywrócenia ustawień fabrycznych lockey-a. userid Opcjonalny, własny identyfikator dla lockey. Zwracany status ELockeyStatus ELKOK - lockey został zainicjalizowany. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus Initialize(const char* loginpass, const char* resetpass, uint32_t userid); ELockeyStatus Initialize(const uint8_t loginkey[lk_key_length], const uint8_t resetkey[lk_key_length], uint32_t userid); 19
Reset lockey lockey4 lockey8 Metoda przywraca ustawienia fabryczne, usuwając z lockey : hasła komunikacji i resetu dane z pamięci klucze szyfrowania identyfikator Wymaga podania hasła przekazanego w argumencie resetpass metody Initialize. Metoda istnieje w dwóch wersjach. Oprócz wersji podstawowej oczekującej hasła w postaci tablicy 32 bajtowej (tzw. klucza), przyjmuje również hasło w postaci tekstowej (zmienna typu string). Parametry resetkey Hasło wymagane do przywrócenia ustawień fabrycznych. Zwracany status ELockeyStatus ELKOK - wywołanie zakończyło się powodzeniem a lockey został zresetowany. Przywrócono ustawienia fabryczne. Możliwe jest ponowne zainicjalizowanie poprzez Initialize. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus Reset(const char* resetpass); ELockeyStatus Reset(const uint8_t key[lk_key_length]); 20
SetTo lockey lockey4 lockey8 Po użyciu metody, pozostałe metody (np. Login, ReadByte itd. ) będą odwoływać się do lockey, o przekazanym numerze seryjnym w argumencie keyid. Zalecanym użyciem metody jest moment tuż po stworzeniu obiektu na bazie klasy Clockey, bez przeprowadzenia wcześniejszej enumeracji. Parametry keyid Numer seryjny lockey. Zwracany status ELockeyStatus ELKOK Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus SetTo(KEYID keyid); 21
GetInfo lockey lockey4 lockey8 Metoda zwraca wartość wybranego parametru lockey. Używana do odczytu np. wielkości pamięci, liczby kluczy szyfrowania, maksymalnego buforu zapisu danych do pamięci. Parametry what Zmienna typu enumerowanego ElockeyInfo : ELKSerialNo numer seryjny lockey, nadany przez producenta. ELKFeatures informacja o zaimplementowanych mechanizmach w lockey, takich jak pamięć, klucze szyfrowania, generator liczb losowych (patrz również HasFeature). ELKApiVer wersja API, którą obsługuje lockey. ELKMemoSize rozmiar pamięci. ELKWriteBufSize maksymalny, dozwolony rozmiar bufora zapisu, przekazywanego w metodzie WriteMemo. ELKCryptKeys liczba kluczy szyfrowania AES. Zwracane wartości Zmienna typu uint32_t Odczytana wartość parametru. Przykład deklaracji dla uint32_t GetInfo(ELockeyInfo what); 22
HasFeature lockey lockey4 lockey8 Parametry Metoda sprawdza czy w lockey jest zaimplementowana wybrana funkcjonalność. what Zmienna typu enumerowanego ELockeyFeature : ELKFeatMemo sprawdza czy lockey posiada pamięć. ELKFeatRand - sprawdza czy lockey posiada sprzętowy generator liczb pseudolosowych. ELKFeatCrpt sprawdza czy lockey posiada sprzętowe szyfrowanie AES. ELKFeatHrtc sprawdza czy lockey posiada sprzętowy zegar RTC. Zwracane wartości TRUE W lockey jest zaimplementowana dana funkcjonalność. FALSE W lockey nie jest zaimplementowana dana funkcjonalność. Przykład deklaracji dla bool HasFeature(ELockeyFeature what); 23
GetUserId lockey lockey4 lockey8 Parametry userid Metoda odczytuje identyfikator nadany podczas inicjalizacji lockey. Zmienna do której zostanie odczytany identyfikator. Zwracane wartości userid Identyfikator lockey, nadany podczas inicjalizacji. Zwracany status ELockeyStatus ELKOK Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla bool GetUserId(uint32_t* userid); 24
Login lockey lockey4 lockey8 Metoda przy pomocy której następuje logowanie do lockey-a (nawiązanie komunikacji). Logowanie jest niezbędne do przeprowadzenia dowolnej czynności np. odczytu/zapisu pamięci, szyfrowania/deszyfrowania. Metoda występuje w dwóch wersjach : pierwsza oczekuje jako parametr podania tablicy 32 bajtowej z hasłem do zalogowania (klucza). druga wersja metody oczekuje jako parametr hasła tekstowego. Po pomyślnym zalogowaniu, pomiędzy aplikacją a lockey-em zostaje utworzone szyfrowane połączenie zwane sesją. Przesył danych do i z lockey-a odbywa się w jej obrębie i jest poufny. Podczas trwania sesji, dostęp do lockey-a z innych procesów jest niemożliwy. Należy pamiętać, że inny proces może również potrzebować dostępu do lockey-a. Dlatego po zakończeniu czynności (np. odczyt pamięci), wskazane jest natychmiastowe wylogowanie (zamknięcie sesji) poprzez metodę Logout. Jeśli to w ogóle nie nastąpi po upływie kilku sekund od ostatniej komunikacji, lockey sam zakończy sesję. Status kolejnych operacji bez powtórnego zalogowania będzie zwracany jako ELKSessionNotActive. Parametry key Hasło wymagane do nawiązania komunikacji z lockey-em, ustawione poprzez Initialize. Zwracany status ELockeyStatus ELKOK - wywołanie zakończyło się powodzeniem - sesja została otwarta. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. 25
Przykład deklaracji dla ELockeyStatus Login(const char* spass); ELockeyStatus Login(const uint8_t key[lk_key_length]); 26
Logout lockey lockey4 lockey8 Zwracany status Metoda kończy komunikację z lockey-em oraz zwalnia użyte zasoby. Metoda nie zwraca statusu. Przykład deklaracji dla void Logout(void); 27
ReadByte lockey lockey4 lockey8 Parametry offset Metoda odczytuje komórkę pamięci z lockey-a. Wymaga wcześniejszego zalogowania poprzez Login. Adres w pamięci lockey z którego nastąpi odczyt. data Zmienna do której zostanie zapisana wartość odczytanej komórki pamięci. Zwracane wartości data Wartość komórki pamięci. Zwracany status ELockeyStatus ELKOK poprawnie odczytano komórkę pamięci. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus ReadByte(uint16_t offset, uint8_t* data); 28
WriteByte lockey lockey4 lockey8 Parametry offset Metoda zapisuje wartość do pojedynczej komórki pamięci w lockey-u. Wymaga wcześniejszego zalogowania poprzez metodę Login. Adres w pamięci lockey-a pod który nastąpi zapis wartości. data Wartość, która zostanie zapisana do pamięci lockey-a pod wskazany adres. Zwracany status ELockeyStatus ELKOK poprawnie zapisano wartość do komórki pamięci. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus WriteByte(uint16_t offset, uint8_t data); 29
ReadMemo lockey lockey4 lockey8 Parametry offset Metoda odczytuje blok pamięci z lockey-a. Wymaga wcześniejszego zalogowania poprzez Login. Adres w pamięci lockey-a od którego nastąpi odczyt. buffer Tablica z zarezerwowanym miejscem na wartości z odczytu pamięci. Tablica nie może być mniejsza od wartości przekazanej w polu length. length Liczba komórek do odczytu z pamięci lockey-a. Suma offset + length nie może być większa od wielkości pamięci w lockey. Rozmiar pamięci można sprawdzić metodą GetInfo z parametrem ELKMemoSize. Zwracane wartości buffer Tablica z odczytanymi wartościami komórek pamięci. Zwracany status ELockeyStatus ELKOK pamięć odczytana poprawnie. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus ReadMemo(uint16_t offset, uint8_t* buffer, uint16_t length); 30
WriteMemo lockey lockey4 lockey8 Parametry offset Metoda zapisuje wartości z tablicy buffer do pamięci lockey-a. Wymaga wcześniejszego zalogowania poprzez metodę Login. Adres w pamięci lockey-a od którego nastąpi zapis wartości z tablicy buffer. buffer Tablica wypełniona wartościami do zapisu w pamięci lockey-a. Tablica nie może być mniejsza od wartości przekazanej w polu length. length Liczba komórek do zapisu w pamięci lockey. Nie może być większa niż maksymalny bufor zapisu (wartość zwrócona przez metodę GetInfo z parametrem ELKWriteBufSize). Suma offset + length nie może być większa od wielkości pamięci w lockey. Rozmiar pamięci można sprawdzić metodą GetInfo z parametrem ELKMemoSize. Zwracany status ELockeyStatus ELKOK pamięć zapisana poprawnie. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus WriteMemo(uint16_t offset, const uint8_t* buffer, uint16_t length); 31
ReadRTC Metoda odczytuje datę oraz godzinę z zegara RTC lockey-a. Wymaga wcześniejszego zalogowania poprzez Login. Parametry data Tablica o długości 6-ciu bajtów do której zostanie odczytany czas zegara RTC Zwracane wartości data Odczytany czas z zegara RTC. Kolejność począwszy od pierwszego indeksu tablicy: sekunda, minuta, godzina, dzień, miesiąc, rok. Rok liczony jest od 2000. Przykładowo odczytanie wartości 15 oznacza rok 2015. Zwracany status ELockeyStatus ELKOK poprawnie odczytano RTC. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus ReadRTC(uint8_t data[6]); 32
WriteRTC Metoda zapisuje datę oraz godzinę do zegara RTC lockey-a. Wymaga wcześniejszego zalogowania poprzez metodę Login. Parametry data Tablica 6-ciu bajtów zawierająca godzinę i datę, która będzie zapisana do zegara RTC. Kolejność począwszy od pierwszego indeksu tablicy: sekunda, minuta, godzina, dzień, miesiąc, rok. Rok liczony jest od 2000. Przykładowo aby zapisać rok 2015 należy na polu roku w przekazywanej tablicy zapisać 15. Zwracany status ELockeyStatus ELKOK poprawnie zapisano zegar RTC. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus WriteRTC(uint8_t data[6]); 33
WriteKey lockey4 lockey8 Metoda zapisuje do tablicy kluczy w lockey-u, 128 bitowy klucz szyfrowania AES. Uwaga! Ze względu na zachowanie najwyższego poziomu bezpieczeństwa możliwy jest tylko zapis klucza szyfrowania i tylko w miejsce nie zabezpieczone przed zapisem poprzez metodę ProtectKey. Wymaga wcześniejszego zalogowania poprzez Login. Parametry keynumber Indeks pod który zostanie zapisany klucz AES w tablicy kluczy szyfrowania. key Klucz AES, który ma zostać zapisany do lockey-a (tablica 16-to bajtowa). Zwracany status ELockeyStatus ELKOK zapis klucza AES zakończony powodzeniem. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus WriteKey(uint8_t keynumber, const uint8_t key[lk_aes_length]); 34
ProtectKey lockey4 lockey8 Metoda włącza dla wybranego klucza szyfrowania ochronę przed zapisem. Po jej użyciu nadpisanie chronionego klucza AES w lockey-u nie jest możliwe. Ochrona pozostaje do chwili przywrócenia ustawień fabrycznych metodą Reset. Wymaga wcześniejszego zalogowania poprzez Login. Parametry keynumber Indeks klucza AES w tablicy kluczy szyfrowania. Zwracany status ELockeyStatus ELKOK ochrona przed zapisem została ustawiona. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ElockeyStatus ProtectKey(uint8_t keynumber); 35
Encrypt lockey4 lockey8 Metoda przesyła do lockey-a pojedynczy blok danych (o stałej wielkości 16-tu bajtów) w celu zaszyfrowania kluczem AES. Klucz AES należy wcześniej jednorazowo zapisać metodą WriteKey. Wymaga wcześniejszego zalogowania poprzez Login. Parametry keynumber Indeks klucza AES w tablicy kluczy szyfrowania. data Tablica 16-tu bajtów z danymi do zaszyfrowania. Zwracane wartości data Zaszyfrowane dane kluczem AES o indeksie keynumber. Zwracany status ELockeyStatus ELKOK szyfrowanie danych zakończone powodzeniem. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus Encrypt(uint8_t keynumber, uint8_t data[lk_aes_length]); 36
Decrypt lockey4 lockey8 Metoda przesyła do lockey-a pojedynczy blok danych (o stałej wielkości 16-tu bajtów) w celu odszyfrowania przy użyciu klucza AES. Klucz AES należy wcześniej jednorazowo zapisać metodą WriteKey. Wymaga wcześniejszego zalogowania poprzez Login. Parametry keynumber Indeks klucza AES w tablicy kluczy szyfrowania. data Tablica 16-tu bajtów z danymi do odszyfrowania. Zwracane wartości data Dane odszyfrowane kluczem AES o indeksie keynumber. Zwracany status ELockeyStatus ELKOK deszyfrowanie danych zakończone powodzeniem. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus Decrypt(uint8_t keynumber, uint8_t data[lk_aes_length]); 37
GenRand lockey4 lockey8 Metoda generuje w lockey-u i pobiera pseudolosowy blok danych o rozmiarze 16-tu bajtów. Wymaga wcześniejszego zalogowania poprzez Login. Parametry random Tablica 16-tu bajtów do której zostaną zapisane pseudolosowe wartości. Zwracane wartości random Tablica 16-tu bajtów z losowymi wartościami. Zwracany status ELockeyStatus ELKOK generowanie bloku danych zakończone powodzeniem. Status różny od ELKOK. Należy przeprowadzić dalszą analizę, patrz rozdział Status metod. Przykład deklaracji dla ELockeyStatus GenRand(uint8_t random[lk_aes_length]); 38
Status metod
ELockeyStatus Status został zdefiniowany w typie enumerowanym ELockeyStatus. W tabeli poniżej zebrano i opisano możliwe wartości zwracane przez metody klas ClockeyEnum oraz Clockey. Możliwe wartości ELKOK, ELKNoError Wywołanie zakończyło się powodzeniem. ELKErrCom Wystąpił błąd komunikacji z lockey-em. ELKErrKey Ogólny błąd lockey. ELKSessionNotActive Sesja nie została otwarta lub jej czas upłynął. Status zwracany jest w przypadkach : wystąpiła próba użycia metody wymagającej wcześniejszego zalogowania do lockey nastąpiło zalogowanie do lockey-a jednak przez ostatnie kilka sekund nie wykonano żadnej operacji np. odczytu/zapisu pamięci itp., efektem czego sesja została automatycznie zamknięta (nastąpiło autowylogowanie) wystąpił przestój w obsłudze USB ze strony komputera, efektem czego sesja została automatycznie zamknięta Przy wystąpieniu statusu ELKSessionNotActive zalecane jest ponowienie logowania i powtórna próba wykonania operacji na lockey-u. ELKWrongState lockey znajduje się w nieodpowiednim stanie dla żądanej operacji. Status zwracany jest np. przy próbie powtórnej inicjalizacji, bez wcześniejszego przywrócenia ustawień fabrycznych. ELKBadParam Przekazano nieprawidłowe parametry przy wywołaniu metody. 40
ELKKeyNotFound lockey nie został odnaleziony. Status zwracany jest przy próbie odwołania się do lockey-a, który nie jest fizycznie podłączony do portu USB komputera. Przykładowo użyto metody SetTo z numerem seryjnym lockey-a, który nie jest podpięty do portu USB. ELKVerifyFailed Nieudana weryfikacja. Status zwracany jest w przypadku gdy weryfikacja zapisanej pamięci w lockey-u nie przebiegła poprawnie. ELKNotSupported lockey nie obsługuje danej właściwości. Status zwracany jest w przypadku gdy występuje próba użycia np. sprzętowego szyfrowania lockey-em nie posiadającym takiej właściwości. ELKWriteProtected Ochrona przed zapisem dla wybranego klucza szyfrowania jest włączona. Status zwracany jest w przypadku gdy nie można zapisać klucza szyfrowania lub ustawić ochrony przed zapisem. Ochrona została włączona już wcześniej. ELKErrRTC Problem z zegarem czasu rzeczywistego. Status zwracany w przypadku gdy zegar RTC nie został jeszcze ustawiony po inicjalizacji lockey-a lub w przypadku jeśli wystąpił problem z podtrzymaniem bateryjnym np. : wyjmowano baterię bateria jest zużyta i kwalifikuje się do wymiany 41
www: www.lockey.pl Pomoc techniczna: serwis@lockey.pl SaPiTech 2015