Informacje o strukturze keymaster2_device

Przerywa operacje kryptograficzną rozpoczętą za pomocą funkcji begin() , uwalniając wszystkie zasoby wewnętrzne i unieważniając operation_handle .

Definicja w wierszu 415 pliku keymaster2.h .

Dodaje entropię do RNG używanego przez menedżera kluczy. Entropia dodana za pomocą tej metody nie jest jedynym źródłem entropii, a funkcja mieszania musi być bezpieczna w tym sensie, że jeśli generator losowych liczb (z dowolnego źródła) zostanie zasilony danymi, których atakujący nie może przewidzieć (ani kontrolować), to wyjście generatora będzie nie do odróżnienia od losowych danych. Jeśli entropia z dowolnego źródła jest dobra, wynik będzie dobry.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	dane	losowe dane do zmieszania.
[in]	data_length	Długość: data

Definicja w wierszu 74 pliku keymaster2.h .

Generuje podpisany łańcuch certyfikatów X.509, który potwierdza obecność key_to_attest w keymaster (TODO(swillden): Describe certificate contents in more detail). Certyfikat będzie zawierać rozszerzenie z OID 1.3.6.1.4.1.11129.2.1.17 i wartość zdefiniowaną w <TODO:swillden – insert link here>, która zawiera opis klucza.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	key_to_attest	Klucz główny, dla którego zostanie wygenerowany certyfikat oświadczenia.
[in]	attest_params	Parametry określające sposób przeprowadzania weryfikacji. Obecnie jedynym parametrem jest KM_TAG_ALGORITHM, który musi być równy KM_ALGORITHM_EC lub KM_ALGORITHM_RSA. Wybierz, który z kluczy uwierzytelniania ma być używany do podpisywania certyfikatu.
[out]	cert_chain	Tablica certyfikatów X.509 w formacie DER. Pierwszy będzie certyfikat dla domeny key_to_attest . Pozostałe wpisy będą łańcuchowo łączyć się z katalogiem głównym. Wywołujący przejmuje własność i musi zwolnić zasoby za pomocą polecenia keymaster_free_cert_chain.

Definicja w wierszu 239 pliku keymaster2.h .

Rozpoczyna operację kryptograficzną przy użyciu określonego klucza. Jeśli wszystko jest w porządku, begin() zwróci KM_ERROR_OK i utworzy uchwyt operacji, który musi zostać przekazany do kolejnych wywołań funkcji update() , finish() lub abort() .

Każde wywołanie funkcji begin() musi być połączone z kolejną funkcją finish() lub abort() , aby umożliwić implementacji klucza głównego wyczyszczenie stanu operacji wewnętrznej. Nieprzestrzeganie tej zasady może spowodować wyciek wewnętrznego stanu lub innych zasobów wewnętrznych, a w konsekwencji wywołanie funkcji begin() z wartością KM_ERROR_TOO_MANY_OPERATIONS, gdy zabraknie miejsca na operacje. Każdy wynik inny niż KM_ERROR_OK zwracany przez begin() , update() lub finish() oznacza domyślne przerwanie operacji, w której przypadku abort() nie musi być wywoływany (a jeśli zostanie, zwróci wartość KM_ERROR_INVALID_OPERATION_HANDLE).

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	cel	Cel operacji: KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN lub KM_PURPOSE_VERIFY. Pamiętaj, że w przypadku trybów AEAD szyfrowanie i odszyfrowanie oznaczają odpowiednio podpisywanie i weryfikację, ale powinny być określone jako KM_PURPOSE_ENCRYPT i KM_PURPOSE_DECRYPT.
[in]	klucz	Klucz używany do wykonania operacji. key musi mieć cel zgodny z  purpose i wszystkie wymagania dotyczące jego użycia muszą być spełnione, w przeciwnym razie funkcja begin() zwróci odpowiedni kod błędu.
[in]	in_params	Dodatkowe parametry operacji. Jest on zwykle używany do przekazywania danych uwierzytelniania za pomocą parametru KM_TAG_AUTH_TOKEN. Jeśli podczas generowania zostały podane parametry KM_TAG_APPLICATION_ID lub KM_TAG_APPLICATION_DATA, muszą one zostać podane tutaj. W przeciwnym razie operacja zakończy się niepowodzeniem z powodu błędu KM_ERROR_INVALID_KEY_BLOB. W przypadku operacji, które wymagają nonce lub IV, w przypadku kluczy wygenerowanych za pomocą tagu KM_TAG_CALLER_NONCE parametry in_params mogą zawierać tag KM_TAG_NONCE.
[out]	out_params	Parametry wyjściowe. Służy do zwracania dodatkowych danych z inicjalizacji operacji, w szczególności do zwracania IV lub nonce z operacji, które generują IV lub nonce. Wywołujący staje się właścicielem tablicy parametrów wyjściowych i musi ją zwolnić za pomocą funkcji keymaster_free_param_set() . Jeśli nie ma parametrów wyjściowych, parametr out_params może mieć wartość NULL. Jeśli parametr out_params ma wartość NULL, a parametry wyjściowe są generowane, funkcja begin() zwróci wartość KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	Nowo utworzony identyfikator operacji, który musi zostać przekazany do funkcji update() , finish() lub abort() . Jeśli operation_handle ma wartość NULL, funkcja begin() zwróci KM_ERROR_OUTPUT_PARAMETER_NULL.

Definicja w wierszu 332 pliku keymaster2.h .

Typowe metody korzystania z urządzenia Keymaster Ta musi być pierwszym elementem klucza keymaster_device, ponieważ użytkownicy tej struktury będą rzutować hw_device_t do wskaźnika keymaster_device w kontekstach, w których wiadomo, że hw_device_t odwołuje się do klucza keymaster_device.

Definicja w wierszu 35 pliku keymaster2.h .

Konfiguruje Keymaster. Tę metodę należy wywołać raz po otwarciu urządzenia i przed jego użyciem. Służy do przekazywania kluczowi głównemu wartości KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL. Dopóki ta metoda nie zostanie wywołana, wszystkie inne metody będą zwracać wartość KM_ERROR_KEYMASTER_NOT_CONFIGURED. Wartości podane za pomocą tej metody są akceptowane przez Keymastera tylko raz podczas uruchamiania. Kolejne wywołania zwrócą wartość KM_ERROR_OK, ale nie będą robić nic.

Jeśli implementacja klucza głównego znajduje się na bezpiecznym sprzęcie, a wartości wersji systemu operacyjnego i poziomu poprawki nie pasują do wartości przekazanych przez bootloader do bezpiecznego sprzętu (lub bootloader nie przekazał żadnych wartości), ta metoda zwróci KM_ERROR_INVALID_ARGUMENT, a wszystkie inne metody będą nadal zwracać KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Definicja w wierszu 58 pliku keymaster2.h .

Definicja w wierszu 37 pliku keymaster2.h .

Usuwa wszystkie klucze z magazynu kluczy sprzętowych. Używany, gdy repozytorium kluczy jest całkowicie resetowane. Po wywołaniu tej funkcji nie będzie można używać wcześniej wygenerowanych ani zaimportowanych kluczy BLOB w żadnych operacjach.

Ta funkcja jest opcjonalna i w przypadku braku implementacji powinna być ustawiona na NULL.

Parametry

[in]

dev

Struktura urządzenia Keymaster

Definicja w wierszu 288 pliku keymaster2.h .

Usuwa klucz lub parę kluczy powiązaną z kluczem blob. Po wywołaniu tej funkcji nie będzie można użyć klucza do żadnych innych operacji. Można je stosować do kluczy z obcych źródeł zaufania (kluczy, których nie można używać w ramach bieżącego źródła zaufania).

Ta funkcja jest opcjonalna i w przypadku braku implementacji powinna być ustawiona na NULL.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	klucz	Klucz do usunięcia.

Definicja w wierszu 276 pliku keymaster2.h .

Eksportuje klucz publiczny lub symetryczny, zwraca tablicę bajtów w określonym formacie.

Pamiętaj, że eksport klucza symetrycznego jest dozwolony tylko wtedy, gdy klucz został utworzony za pomocą parametru KM_TAG_EXPORTABLE, i tylko wtedy, gdy wszystkie wymagania dotyczące użycia klucza (np. uwierzytelniania) są spełnione.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	export_format	Format, który ma być użyty do wyeksportowania klucza.
[in]	key_to_export	Klucz do wyeksportowania.
[in]	client_id	Blob identyfikatora klienta, który musi być zgodny z blobem podanym w polu KM_TAG_APPLICATION_ID podczas generowania klucza (jeśli występuje).
[in]	app_data	Blob danych aplikacji, który musi być zgodny z blobem podanym w polu KM_TAG_APPLICATION_DATA podczas generowania klucza (jeśli występuje).
[out]	export_data	Wyeksportowany materiał klucza. Rozmówca staje się właścicielem.

Definicja w wierszu 213 pliku keymaster2.h .

Kończy operację kryptograficzną rozpoczętą za pomocą funkcji begin() i unieważnia operation_handle .

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	operation_handle	Identyfikator operacji zwrócony przez funkcję begin() . Ten nick zostanie unieważniony.
[in]	in_params	Dodatkowe parametry operacji. W przypadku trybów AEAD służy do określania parametru KM_TAG_ADDITIONAL_DATA, ale tylko wtedy, gdy nie podano żadnych danych wejściowych do funkcji update() .
[in]	wejście	Dane do przetworzenia zgodnie z parametrami określonymi w wywołaniu funkcji begin() . finish() musi zużyć wszystkie dostarczone dane lub zwrócić KM_ERROR_INVALID_INPUT_LENGTH.
[in]	podpis	Podpis do zweryfikowania, jeśli cel określony w wywołaniu begin() to KM_PURPOSE_VERIFY.
[out]	output	Dane wyjściowe (jeśli występują). Użytkownik wywołujący przejmuje własność przydzielonego bufora.

Jeśli zakończona operacja to weryfikacja podpisu lub deszyfrowanie w trybie AEAD i nie powiodła się, finish() zwróci KM_ERROR_VERIFICATION_FAILED.

Definicja w wierszu 405 pliku keymaster2.h .

Zobacz flagi zdefiniowane dla keymaster0_devices::flags w pliku keymaster_common.h . Używane tylko do zapewnienia zgodności wstecznej. Urządzenia sprzętowe keymaster2 muszą mieć ustawioną wartość 0.

Definicja w wierszu 43 pliku keymaster2.h .

Generuje klucz lub parę kluczy, zwracając klucz blob lub jego opis.

Parametry generowania kluczy są definiowane jako pary tagów kluczy/wartości podawane w formacie params . Pełną listę znajdziesz w kluczu master_tag_t. Oto wartości, które są zawsze wymagane do generowania przydatnych kluczy:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; i
• (KM_TAG_USER_SECURE_ID i KM_TAG_USER_AUTH_TYPE) lub KM_TAG_NO_AUTH_REQUIRED.

Wartość KM_TAG_AUTH_TIMEOUT powinna być zwykle określona, chyba że występuje parametr KM_TAG_NO_AUTH_REQUIRED, w przeciwnym razie użytkownik będzie musiał uwierzytelniać się przy każdym użyciu.

W przypadku algorytmów, które ich wymagają, należy podać parametry KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH i KM_TAG_DIGEST.

Nie można określić tych tagów – ich wartości zostaną podane przez implementację.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	params	Tablica parametrów generowania klucza
[out]	key_blob	zwraca wygenerowany klucz. key_blob nie może zawierać wartości NULL. Wywołujący przejmuje prawo własności key_blob->key_material i musi go zwolnić.
[out]	cechy	zwraca właściwości klucza, który został wygenerowany, jeśli nie jest to wartość NULL. Jeśli wartość jest różna od NULL, wywołujący staje się właścicielem i musi zwolnić pamięć za pomocą funkcji keymaster_free_characteristics() . Pamiętaj, że parametry KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.

Definicja w wierszu 112 pliku keymaster2.h .

Zwraca właściwości określonego klucza lub KM_ERROR_INVALID_KEY_BLOB, jeśli klucz_blob jest nieprawidłowy (implementacje muszą w pełni weryfikować integralność klucza). Wartości client_id i app_data muszą być identyczne z wartościami podanymi podczas generowania lub importowania klucza albo puste, jeśli podczas generowania nie podano wartości KM_TAG_APPLICATION_ID ani KM_TAG_APPLICATION_DATA. Te wartości nie są uwzględniane w zwracanych cechach. Wywołujący przejmuje własność przydzielonego obiektu z cechami, który musi zostać zwolniony za pomocą funkcji keymaster_free_characteristics() .

Pamiętaj, że parametry KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	key_blob	Klucz do pobierania właściwości.
[in]	client_id	Dane identyfikatora klienta lub NULL, jeśli nie ma powiązanego identyfikatora.
[in]	app_id	Dane aplikacji lub NULL, jeśli nie ma powiązanych danych.
[out]	cechy	kluczowe cechy; Nie może zawierać wartości NULL. Wywołujący przejmuje własność zawartości i musi ją zwolnić za pomocą funkcji keymaster_free_characteristics() .

Definicja w wierszu 139 pliku keymaster2.h .

Importuje klucz lub parę kluczy, zwracając klucz blob lub jego opis.

Większość parametrów importu kluczy jest definiowana jako pary tagów i wartości w kluczu głównym, które są podawane w sekcji „params”. Pełną listę znajdziesz w kluczu master_tag_t. Wartości, które są zawsze wymagane do importowania przydatnych kluczy:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; i
• (KM_TAG_USER_SECURE_ID i KM_TAG_USER_AUTH_TYPE) lub KM_TAG_NO_AUTH_REQUIRED.

Wartość KM_TAG_AUTH_TIMEOUT powinna być zwykle określona. Jeśli nie zostanie podany, użytkownik będzie musiał uwierzytelnić się przy każdym użyciu.

Jeśli nie podasz wartości tych tagów, zostaną one zastąpione wartościami domyślnymi:

• KM_TAG_KEY_SIZE przyjmie domyślnie rozmiar podanego klucza.
• KM_TAG_RSA_PUBLIC_EXPONENT przyjmie domyślnie wartość w podanej parze kluczy (w przypadku kluczy RSA).

Nie można określić tych tagów – ich wartości zostaną podane przez implementację.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	params	Parametry definiujące importowany klucz.
[in]	params_count	Liczba wpisów w  params .
[in]	key_format	określa format danych klucza w key_data.
[out]	key_blob	Służy do zwrócenia zaciemnionego klucza. Nie może zawierać wartości NULL. Wywołujący przejmuje własność zawartego klucza_materialu.
[out]	cechy	Służy do zwracania właściwości zaimportowanego klucza. Może być NULL, co oznacza, że nie zostaną zwrócone żadne cechy. Jeśli nie jest równy NULL, wywołujący staje się właścicielem zawartości i musi ją zwolnić za pomocą funkcji keymaster_free_characteristics() . Pamiętaj, że parametry KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.

Definicja w wierszu 186 pliku keymaster2.h .

Przekazuje dane do bieżącej operacji kryptograficznej rozpoczętej za pomocą funkcji begin() i być może otrzymuje dane wyjściowe z tej operacji.

Jeśli operation_handle jest nieprawidłowy, update() zwróci KM_ERROR_INVALID_OPERATION_HANDLE.

update() może nie wykorzystać wszystkich danych dostarczonych w buforze danych. update() będzie zwracać ilość zużytą w *data_consumed. Wywołujący powinien przekazać niewykorzystane dane w kolejnych wywołaniach.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	operation_handle	Identyfikator operacji zwrócony przez funkcję begin() .
[in]	in_params	Dodatkowe parametry operacji. W przypadku trybów AEAD służy do określania parametru KM_TAG_ADDITIONAL_DATA. Pamiętaj, że dodatkowe dane mogą być przekazywane w kilku wywołaniach funkcji update() , ale tylko do momentu przekazania danych wejściowych.
[in]	wejście	Dane do przetworzenia zgodnie z parametrami określonymi w wywołaniu funkcji begin() . Pamiętaj, że funkcja update() może, ale nie musi zużyć wszystkich podanych danych. Zobacz: input_consumed .
[out]	input_consumed	Ilość danych wykorzystanych przez funkcję update() . Jeśli jest ona mniejsza od podawanej kwoty, wywołujący powinien podać resztę w kolejnym wywołaniu metody update() .
[out]	out_params	Parametry wyjściowe. Służy do zwracania dodatkowych danych z operacji. Wywołujący staje się właścicielem tablicy parametrów wyjściowych i musi ją zwolnić za pomocą funkcji keymaster_free_param_set() . Jeśli nie ma parametrów wyjściowych, parametr out_params może mieć wartość NULL. Jeśli parametr out_params ma wartość NULL, a parametry wyjściowe są generowane, funkcja begin() zwróci wartość KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Dane wyjściowe (jeśli występują). Element wywołujący przejmuje prawo własności do przypisanego bufora. Wartość wyjściowa nie może być równa NULL.

Pamiętaj, że funkcja update() może nie zwracać żadnego wyniku. W takim przypadku długość danych w wyjściu funkcji będzie równa 0, a dane w wyjściu mogą być równe NULL lub mieć długość 0 (dlatego wywołujący musi je zawsze zwalniać za pomocą funkcji free()).

Definicja w wierszu 376 pliku keymaster2.h .

Uaktualnia stary klucz. Klucze mogą stać się „nieaktualne” na 2 sposoby: Keymaster może zostać zaktualizowany do nowej wersji lub system może zostać zaktualizowany w sposób, który unieważnia wersję systemu operacyjnego lub poziom poprawki. W obu przypadkach próby użycia starego klucza spowodują, że keymaster zwróci wartość KM_ERROR_KEY_REQUIRES_UPGRADE. Następnie należy wywołać tę metodę, aby uaktualnić klucz.

Parametry

[in]	dev	Struktura urządzenia Keymaster
[in]	key_to_upgrade	Klucz mastera, który ma zostać uaktualniony.
[in]	upgrade_params	Parametry potrzebne do ukończenia uaktualnienia. W szczególności wymagane będą parametry KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA, jeśli zostały zdefiniowane dla klucza.
[out]	upgraded_key	Blob z uaktualnionym kluczem.

Definicja w wierszu 260 pliku keymaster2.h .