keymaster2_device Odniesienie do struktury
#include < keymaster2.h >
szczegółowy opis
Definicja urządzenia Keymaster2
Definicja w linii 28 pliku keymaster2.h .
Dokumentacja terenowa
| keymaster_error_t (* abort)(const struktura keymaster2_device *dev, keymaster_operacja_handle_t operacja_handle) |
Przerywa operację kryptograficzną rozpoczętą za pomocą metody Begin() , zwalniając wszystkie zasoby wewnętrzne i unieważniając operation_handle .
Definicja w linii 415 pliku keymaster2.h .
| keymaster_error_t (* add_rng_entropy)(const struktura keymaster2_device *dev, const uint8_t *data, size_t długość_danych) |
Dodaje entropię do RNG używanego przez klucznika. Gwarantujemy, że entropia dodana tą metodą nie będzie jedynym wykorzystywanym źródłem entropii, a funkcja miksowania musi być bezpieczna w tym sensie, że jeśli do RNG zostanie zaszczepiony (z dowolnego źródła) jakimikolwiek danymi, których osoba atakująca nie będzie w stanie przewidzieć (lub kontrola), wówczas wyjście RNG jest nie do odróżnienia od losowego. Zatem jeśli entropia z dowolnego źródła jest dobra, wynik będzie dobry.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] dane Losowe dane do zmieszania. [W] długość_danych Długość data.
Definicja w linii 74 pliku keymaster2.h .
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
Generuje podpisany łańcuch certyfikatów X.509 potwierdzający obecność key_to_attest w kluczu głównym (TODO(swillden): Opisz zawartość certyfikatu bardziej szczegółowo). Certyfikat będzie zawierał rozszerzenie o identyfikatorze OID 1.3.6.1.4.1.11129.2.1.17 i wartości zdefiniowanej w <TODO:swillden – wstaw link tutaj>, który zawiera opis klucza.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] klucz_do_atestu Klucz główny klucza, dla którego zostanie wygenerowany certyfikat zaświadczający. [W] atest_params Parametry określające sposób przeprowadzenia atestacji. Obecnie jedynym parametrem jest KM_TAG_ALGORITHM, który musi mieć wartość KM_ALGORITHM_EC lub KM_ALGORITHM_RSA. Spowoduje to wybranie, który z udostępnionych kluczy zaświadczenia będzie używany do podpisania certyfikatu. [na zewnątrz] łańcuch certyfikatów Tablica certyfikatów X.509 zakodowanych w formacie DER. Pierwszy będzie certyfikatem dla key_to_attest. Pozostałe wpisy zostaną połączone z powrotem do katalogu głównego. Osoba wywołująca przejmuje na własność i musi zwolnić przydział z keymaster_free_cert_chain.
Definicja w linii 239 pliku keymaster2.h .
| keymaster_error_t (* początek)(const struktura keymaster2_device *dev, keymaster_cel_t cel, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operacja_handle_t *operacja_handle) |
Rozpoczyna operację kryptograficzną przy użyciu określonego klucza. Jeśli wszystko jest w porządku, funkcja Begin() zwróci KM_ERROR_OK i utworzy uchwyt operacji, który należy przekazać kolejnym wywołaniom funkcji update() , Finish() lub abort() .
Bardzo ważne jest, aby każde wywołanie metody Begin() było połączone z kolejnym wywołaniem metody finish() lub abort() , aby umożliwić implementacji klucza głównego wyczyszczenie wszelkich wewnętrznych stanów operacji. Niezastosowanie się do tego może spowodować wyciek wewnętrznej przestrzeni stanów lub innych zasobów wewnętrznych i ostatecznie spowodować, że funkcja Begin() zwróci KM_ERROR_TOO_MANY_OPERATIONS, gdy zabraknie miejsca na operacje. Każdy wynik inny niż KM_ERROR_OK z funkcji Begin() , update() lub Finish() domyślnie przerywa operację, w którym to przypadku funkcja abort() nie musi być wywoływana (i zwróci KM_ERROR_INVALID_OPERATION_HANDLE, jeśli zostanie wywołana).
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] zamiar Cel operacji, jeden z KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN lub KM_PURPOSE_VERIFY. Należy zauważyć, że w przypadku trybów AEAD szyfrowanie i deszyfrowanie oznaczają odpowiednio podpisywanie i weryfikację, ale należy je określić jako KM_PURPOSE_ENCRYPT i KM_PURPOSE_DECRYPT. [W] klucz Klucz, który ma zostać użyty do operacji. keymusi mieć cel zgodny zpurposei wszystkie wymagania dotyczące jego użycia muszą być spełnione, w przeciwnym razie funkcja Begin() zwróci odpowiedni kod błędu.[W] in_parametry Dodatkowe parametry operacji. Jest to zwykle używane do dostarczania danych uwierzytelniających za pomocą KM_TAG_AUTH_TOKEN. Jeśli podczas generowania podano KM_TAG_APPLICATION_ID lub KM_TAG_APPLICATION_DATA, należy je podać tutaj, w przeciwnym razie operacja zakończy się niepowodzeniem z powodu KM_ERROR_INVALID_KEY_BLOB. W przypadku operacji wymagających wartości jednorazowej lub IV, na kluczach wygenerowanych za pomocą KM_TAG_CALLER_NONCE, in_params może zawierać znacznik KM_TAG_NONCE. [na zewnątrz] parametry_wyjściowe 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. Osoba wywołująca przejmuje tablicę parametrów wyjściowych i musi ją zwolnić za pomocą metody keymaster_free_param_set() . out_params można ustawić na NULL, jeśli nie są oczekiwane żadne parametry wyjściowe. Jeśli out_params ma wartość NULL i wygenerowano parametry wyjściowe, funkcja Begin() zwróci KM_ERROR_OUTPUT_PARAMETER_NULL. [na zewnątrz] uchwyt_operacji Nowo utworzony uchwyt operacji, który należy przekazać do update() , Finish() lub abort() . Jeśli uchwyt_operacji ma wartość NULL, funkcja Begin() zwróci KM_ERROR_OUTPUT_PARAMETER_NULL.
Definicja w linii 332 pliku keymaster2.h .
| struktura hw_device_t wspólna |
Typowe metody urządzenia keymaster. Musi to być pierwszy element elementu keymaster_device, ponieważ użytkownicy tej struktury będą rzutować wskaźnik hw_device_t na wskaźnik keymaster_device w kontekstach, w których wiadomo, że hw_device_t odwołuje się do urządzenia keymaster_device.
Definicja w linii 35 pliku keymaster2.h .
| keymaster_error_t (*configure)(const struktura keymaster2_device *dev, const keymaster_key_param_set_t *params) |
Konfiguruje keymastera. Metodę tę należy wywołać jednokrotnie po otwarciu urządzenia i przed jego użyciem. Służy do udostępniania kluczy KM_TAG_OS_VERSION i KM_TAG_OS_PATCHLEVEL. Dopóki ta metoda nie zostanie wywołana, wszystkie inne metody zwrócą KM_ERROR_KEYMASTER_NOT_CONFIGURED. Wartości dostarczone tą metodą są akceptowane przez keymastera tylko raz na rozruch. Kolejne wywołania zwrócą KM_ERROR_OK, ale nic nie zrobią.
Jeśli implementacja klucza głównego odbywa się na bezpiecznym sprzęcie, a podane wartości wersji systemu operacyjnego i poziomu poprawek nie odpowiadają wartościom dostarczonym do bezpiecznego sprzętu przez program ładujący (lub jeśli program ładujący nie dostarczył wartości), wówczas ta metoda zwróci KM_ERROR_INVALID_ARGUMENT i wszystkie inne metody będą nadal zwracać KM_ERROR_KEYMASTER_NOT_CONFIGURED.
Definicja w linii 58 pliku keymaster2.h .
| pusty* kontekst |
Definicja w linii 37 pliku keymaster2.h .
| keymaster_error_t (* usuń_all_keys)(stała struktura keymaster2_device *dev) |
Usuwa wszystkie klucze ze sprzętowego magazynu kluczy. Używane, gdy magazyn kluczy jest całkowicie resetowany. Po wywołaniu tej funkcji nie będzie możliwe wykorzystanie do jakichkolwiek operacji wcześniej wygenerowanych lub zaimportowanych kluczowych obiektów typu blob.
Ta funkcja jest opcjonalna i powinna mieć wartość NULL, jeśli nie jest zaimplementowana.
- Parametry
[W] rozw Struktura urządzenia głównego klucza.
Definicja w linii 288 pliku keymaster2.h .
| keymaster_error_t (* Delete_key)(const struktura keymaster2_device *dev, const keymaster_key_blob_t *key) |
Usuwa klucz lub parę kluczy skojarzoną z obiektem BLOB klucza. Po wywołaniu tej funkcji nie będzie możliwe wykorzystanie klawisza do jakichkolwiek innych operacji. Można zastosować do kluczy z obcych źródeł zaufania (klucze nie nadają się do użycia w bieżącym katalogu głównym zaufania).
Ta funkcja jest opcjonalna i powinna mieć wartość NULL, jeśli nie jest zaimplementowana.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] klucz Klucz do usunięcia.
Definicja w linii 276 pliku keymaster2.h .
| keymaster_error_t (*export_key)(const struct keymaster2_device *dev, keymaster_key_format_t eksport_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data) |
Eksportuje klucz publiczny lub symetryczny, zwracając tablicę bajtów w określonym formacie.
Należy pamiętać, że eksport klucza symetrycznego jest dozwolony tylko wtedy, gdy klucz został utworzony za pomocą KM_TAG_EXPORTABLE i tylko wtedy, gdy spełnione są wszystkie wymagania dotyczące użycia klucza (np. uwierzytelnienia).
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] format_eksportu Format używany do eksportowania klucza. [W] klucz_do_eksportu Klucz do eksportu. [W] Identyfikator klienta Obiekt BLOB identyfikatora klienta, który musi odpowiadać obiektowi BLOB podanemu w KM_TAG_APPLICATION_ID podczas generowania klucza (jeśli istnieje). [W] dane aplikacji Obiekt blob danych aplikacji, który musi być zgodny z obiektem blob podanym w KM_TAG_APPLICATION_DATA podczas generowania klucza (jeśli istnieje). [na zewnątrz] dane_eksportu Eksportowany kluczowy materiał. Osoba dzwoniąca przejmuje własność.
Definicja w linii 213 pliku keymaster2.h .
| keymaster_error_t (* wykończenie)(const struct keymaster2_device *dev, keymaster_operacja_handle_toperacja_handle , const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *podpis, keymaster_key_param_set_t *out_params, keymaster_blob_t *wyjście) |
Kończy operację kryptograficzną rozpoczętą za pomocą funkcji Begin() i unieważnia operation_handle .
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] uchwyt_operacji Uchwyt operacji zwrócony przez Begin() . Ten uchwyt zostanie unieważniony. [W] in_parametry Dodatkowe parametry operacji. W trybach AEAD służy do określenia KM_TAG_ADDITIONAL_DATA, ale tylko wtedy, gdy do update() nie podano żadnych danych wejściowych. [W] wejście Dane do przetworzenia zgodnie z parametrami ustalonymi w wywołaniu metody Begin() . Finish() musi zużyć wszystkie dostarczone dane lub zwrócić KM_ERROR_INVALID_INPUT_LENGTH. [W] podpis Podpis do sprawdzenia, jeśli cel określony w wywołaniu Begin() to KM_PURPOSE_VERIFY. [na zewnątrz] wyjście Dane wyjściowe, jeśli istnieją. Osoba wywołująca przejmuje własność przydzielonego buforu.
Jeśli kończąca się operacja polega na weryfikacji podpisu lub odszyfrowaniu i weryfikacji w trybie AEAD nie powiedzie się , funkcja Finish() zwróci KM_ERROR_VERIFICATION_FAILED.
Definicja w linii 405 pliku keymaster2.h .
| flagi uint32_t |
Zobacz flagi zdefiniowane dla keymaster0_devices::flags w keymaster_common.h . Używany tylko w celu zapewnienia kompatybilności wstecznej; Urządzenia sprzętowe Keymaster2 muszą ustawić tę wartość na zero.
Definicja w linii 43 pliku keymaster2.h .
| keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
Generuje klucz lub parę kluczy, zwracając obiekt blob klucza i/lub opis klucza.
Parametry generowania klucza są zdefiniowane jako pary tag główny/wartość klucza, podane w params . Pełną listę znajdziesz w keymaster_tag_t. Niektóre wartości, które są zawsze wymagane do generowania przydatnych kluczy, to:
- KM_TAG_ALGORITHM;
- KM_TAG_PURPOSE; I
- (KM_TAG_USER_SECURE_ID i KM_TAG_USER_AUTH_TYPE) lub KM_TAG_NO_AUTH_REQUIRED.
Zasadniczo należy określić KM_TAG_AUTH_TIMEOUT, chyba że istnieje 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 określić KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH i KM_TAG_DIGEST.
Nie można określić następujących tagów; ich wartości zostaną dostarczone przez implementację.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] parametry Tablica parametrów generowania klucza [na zewnątrz] klucz_blob zwraca wygenerowany klucz. key_blobnie może mieć wartości NULL. Osoba wywołująca przejmuje własność key_blob->key_material i musi go zwolnić().[na zewnątrz] cechy zwraca charakterystykę klucza, który został wygenerowany, jeśli ma wartość różną od NULL. Jeśli nie ma wartości NULL, osoba wywołująca przejmuje własność i musi zwolnić przydział za pomocą keymaster_free_characteristics() . Należy pamiętać, że KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.
Definicja w linii 112 pliku keymaster2.h .
| keymaster_error_t (* get_key_characteristics)(const struktura keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *characteristics) |
Zwraca charakterystykę określonego klucza lub KM_ERROR_INVALID_KEY_BLOB, jeśli key_blob jest nieprawidłowy (implementacje muszą w pełni zweryfikować integralność klucza). id_klienta i dane_aplikacji muszą być identyfikatorami i danymi podanymi podczas generowania lub importowania klucza lub puste, jeśli podczas generowania nie podano KM_TAG_APPLICATION_ID i/lub KM_TAG_APPLICATION_DATA. Wartości te nie są uwzględniane w zwracanych cechach. Osoba wywołująca przejmuje własność przydzielonego obiektu charakterystyki, który musi zostać zwolniony za pomocą metody keymaster_free_characteristics() .
Należy pamiętać, że KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] klucz_blob Klucz do odzyskania cech. [W] Identyfikator klienta Dane identyfikatora klienta lub NULL, jeśli nie są powiązane. [W] identyfikator_aplikacji Dane aplikacji lub NULL, jeśli nie są powiązane. [na zewnątrz] cechy Kluczowe cechy. Nie może mieć wartości NULL. Osoba wywołująca przejmuje własność treści i musi zwolnić przydział za pomocą keymaster_free_characteristics() .
Definicja w linii 139 pliku keymaster2.h .
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
Importuje klucz lub parę kluczy, zwracając obiekt blob klucza i/lub opis klucza.
Większość kluczowych parametrów importu jest zdefiniowanych jako pary znacznik kluczowy/wartość, podane w „params”. Pełną listę znajdziesz w keymaster_tag_t. Wartości, które są zawsze wymagane do importu przydatnych kluczy to:
- KM_TAG_ALGORITHM;
- KM_TAG_PURPOSE; I
- (KM_TAG_USER_SECURE_ID i KM_TAG_USER_AUTH_TYPE) lub KM_TAG_NO_AUTH_REQUIRED.
Zasadniczo należy określić KM_TAG_AUTH_TIMEOUT. Jeśli nie określono, użytkownik będzie musiał uwierzytelniać się przy każdym użyciu.
Następujące tagi przyjmą wartości domyślne, jeśli nie zostaną określone:
- KM_TAG_KEY_SIZE będzie domyślnie odpowiadał rozmiarowi dostarczonego klucza.
- KM_TAG_RSA_PUBLIC_EXPONENT domyślnie przyjmie wartość z podanego klucza (dla kluczy RSA)
Nie można określić następujących tagów; ich wartości zostaną dostarczone przez implementację.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] parametry Parametry definiujące importowany klucz. [W] liczba_parametrów Liczba wpisów w params.[W] format_klucza określa format danych klucza w key_data. [na zewnątrz] klucz_blob Służy do zwracania nieprzezroczystego obiektu typu blob klucza. Musi mieć wartość różną od NULL. Osoba wywołująca przejmuje własność zawartego materiału klucza. [na zewnątrz] cechy Służy do zwracania charakterystyki zaimportowanego klucza. Może mieć wartość NULL. W takim przypadku nie zostaną zwrócone żadne cechy. Jeśli wartość jest różna od NULL, osoba wywołująca przejmuje własność zawartości i musi zwolnić przydział za pomocą keymaster_free_characteristics() . Należy pamiętać, że KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA nigdy nie są zwracane.
Definicja w linii 186 pliku keymaster2.h .
| keymaster_error_t (* aktualizacja)(const struct keymaster2_device *dev, keymaster_operacja_handle_toperacja_handle , const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
Dostarcza dane i ewentualnie odbiera dane wyjściowe z trwającej operacji kryptograficznej rozpoczętej za pomocą metody Begin() .
Jeśli uchwyt_operacji jest nieprawidłowy, update() zwróci KM_ERROR_INVALID_OPERATION_HANDLE.
update() może nie zużyć wszystkich danych znajdujących się w buforze danych. update() zwróci ilość zużytą w *data_consumed. Osoba wywołująca powinna przekazać niewykorzystane dane w kolejnym połączeniu.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] uchwyt_operacji Uchwyt operacji zwrócony przez Begin() . [W] in_parametry Dodatkowe parametry operacji. W trybach AEAD służy do określenia KM_TAG_ADDITIONAL_DATA. Należy pamiętać, że dodatkowe dane mogą być dostarczane w wielu wywołaniach update() , ale tylko do czasu dostarczenia danych wejściowych. [W] wejście Dane do przetworzenia zgodnie z parametrami ustalonymi w wywołaniu metody Begin() . Należy pamiętać, że funkcja update() może, ale nie musi, zużyć wszystkie dostarczone dane. Zobacz input_consumed.[na zewnątrz] dane wejściowe_zużyte Ilość danych zużytych przez update() . Jeśli jest to mniej niż podana kwota, wywołujący powinien podać resztę w kolejnym wywołaniu update() . [na zewnątrz] parametry_wyjściowe Parametry wyjściowe. Służy do zwracania dodatkowych danych z operacji. Osoba wywołująca przejmuje tablicę parametrów wyjściowych i musi ją zwolnić za pomocą metody keymaster_free_param_set() . out_params można ustawić na NULL, jeśli nie są oczekiwane żadne parametry wyjściowe. Jeśli out_params ma wartość NULL i wygenerowano parametry wyjściowe, funkcja Begin() zwróci KM_ERROR_OUTPUT_PARAMETER_NULL. [na zewnątrz] wyjście Dane wyjściowe, jeśli istnieją. Osoba wywołująca przejmuje własność przydzielonego buforu. dane wyjściowe nie mogą mieć wartości NULL.
Należy zauważyć, że funkcja update() może nie udostępniać żadnych danych wyjściowych, w takim przypadku dane wyjściowe->data_length będą wynosić zero, a dane wyjściowe->dane mogą mieć długość NULL lub zerową długość (więc osoba wywołująca powinna zawsze je zwolnić).
Definicja w linii 376 pliku keymaster2.h .
| keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key) |
Uaktualnia stary klucz. Klucze mogą stać się „stare” na dwa sposoby: Keymaster może zostać zaktualizowany do nowej wersji lub system może zostać zaktualizowany w celu unieważnienia wersji systemu operacyjnego i/lub poziomu poprawki. W obu przypadkach próby użycia starego klucza spowodują zwrócenie przez klucznika komunikatu KM_ERROR_KEY_REQUIRES_UPGRADE. Następnie należy wywołać tę metodę, aby zaktualizować klucz.
- Parametry
[W] rozw Struktura urządzenia głównego klucza. [W] klucz_do_aktualizacji Klucz główny do aktualizacji. [W] parametry_aktualizacji Parametry potrzebne do ukończenia aktualizacji. W szczególności wymagane będą KM_TAG_APPLICATION_ID i KM_TAG_APPLICATION_DATA, jeśli zostały zdefiniowane dla klucza. [na zewnątrz] uaktualniony_klucz Ulepszony kluczowy obiekt blob.
Definicja w linii 260 pliku keymaster2.h .
Dokumentacja tej struktury została wygenerowana z następującego pliku:
- hardware/libhardware/include/hardware/ keymaster2.h