Halaman ini memberikan rincian untuk membantu pelaksana HAL Keymaster. Ini mencakup setiap tag di HAL, di versi Keymaster mana tag tersebut tersedia, dan apakah tag tersebut dapat diulang. Kecuali sebagaimana tercantum dalam deskripsi tag, semua tag di bawah ini digunakan selama pembuatan kunci untuk menentukan karakteristik kunci.
Untuk Keymaster 4, tag didefinisikan dalam platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , seperti 3.0/types.hal untuk Keymaster 3 dan 4.0/types.hal untuk Keymaster 4. Untuk Keymaster 2 dan di bawahnya, tag didefinisikan dalam platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Untuk mengetahui fungsinya, lihat halaman Fungsi Keymaster .
Tandai::ACTIVE_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu saat kunci menjadi aktif. Sebelum waktu ini, segala upaya untuk menggunakan kunci gagal dengan ErrorCode::KEY_NOT_YET_VALID .
Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.
Label::ALGORITMA
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan algoritma kriptografi yang menggunakan kunci tersebut.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Tag::SEMUA_APLIKASI
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Dicadangkan untuk penggunaan di masa mendatang.
Tandai::ALLOW_WHILE_ON_BODY
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Tag ini hanya berlaku untuk perangkat Android Wear dengan sensor pada tubuh. Pada titik ini, TEE mana pun tidak diharapkan dapat memberikan akses aman ke sensor pada tubuh, atau sensor pada tubuh sangat aman, jadi ini diharapkan merupakan fitur yang murni didukung oleh perangkat lunak.
Tandai::SEMUA_PENGGUNA
Versi : 3, 4
Dapat diulang ? TIDAK
Dicadangkan untuk penggunaan di masa mendatang.
Menandai::APPLICATION_DATA
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Saat diberikan ke generateKey atau importKey , tag ini menentukan data yang diperlukan selama seluruh penggunaan kunci. Secara khusus, panggilan ke eksporKey dan getKeyCharacteristics harus memberikan nilai yang sama ke parameter clientId , dan panggilan untuk memulai perlu memberikan tag ini dan data terkait yang sama sebagai bagian dari kumpulan inParams . Jika data yang benar tidak diberikan, fungsi akan mengembalikan ErrorCode::INVALID_KEY_BLOB .
Konten tag ini terikat pada kunci secara kriptografis , yang berarti musuh yang memiliki akses ke semua rahasia dunia yang aman tetapi tidak memiliki akses ke konten tag tidak boleh mendekripsi kunci tanpa melakukan brute force pada tag tersebut. konten, yang dapat dicegah oleh aplikasi dengan menentukan konten dengan entropi yang cukup tinggi.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::APPLICATION_ID
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Saat diberikan ke generateKey atau importKey , tag ini menentukan data yang diperlukan selama seluruh penggunaan kunci. Secara khusus, panggilan ke eksporKey dan getKeyCharacteristics harus memberikan nilai yang sama dalam parameter clientId , dan panggilan untuk memulai perlu memberikan tag ini dan data terkait yang sama sebagai bagian dari kumpulan inParams . Jika data yang benar tidak diberikan, fungsi akan mengembalikan ErrorCode::INVALID_KEY_BLOB .
Konten tag ini terikat pada kunci secara kriptografis , artinya musuh yang dapat mengakses semua rahasia dunia yang aman—tetapi tidak memiliki akses ke konten tag—tidak dapat mendekripsi kunci tersebut (tanpa melakukan brute force pada konten tag ).
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ASSOCIATED_DATA
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menyediakan "data terkait" untuk enkripsi atau dekripsi AES-GCM. Tag ini disediakan untuk memperbarui dan menentukan data yang tidak dienkripsi/didekripsi, namun digunakan dalam komputasi tag GCM.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_APPLICATION_ID
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk mengidentifikasi serangkaian kemungkinan penerapan yang pengesahan kuncinya telah dimulai.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_CHALLENGE
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk memberikan tantangan dalam pengesahan.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Menandai::ATTESTATION_ID_BRAND
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama merek perangkat, seperti yang ditampilkan oleh Build.BRAND di Android. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_ID_DEVICE
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama perangkat perangkat, seperti yang dikembalikan oleh Build.DEVICE di Android. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_ID_IMEI
Versi : 3, 4
Dapat diulang ? Ya
Menyediakan IMEI untuk semua radio di perangkat. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_ID_MANUFACTURER
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama pabrikan perangkat, seperti yang dikembalikan oleh Build.MANUFACTURER di Android. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Menandai::ATTESTATION_ID_MEID
Versi : 3, 4
Dapat diulang ? Ya
Menyediakan MEID untuk semua radio di perangkat. Bidang ini hanya akan disetel saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Menandai::ATTESTATION_ID_MODEL
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama model perangkat, seperti yang dihasilkan oleh Build.MODEL di Android. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_ID_PRODUK
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama produk perangkat, seperti yang dihasilkan oleh Build.PRODUCT di Android. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Tag::ATTESTATION_ID_SERIAL
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nomor seri perangkat. Bidang ini disetel hanya saat meminta pengesahan pengidentifikasi perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Menandai::AUTH_TIMEOUT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan waktu dalam detik dimana kunci diotorisasi untuk digunakan, setelah otentikasi. Jika Tag::USER_SECURE_ID ada dan tag ini tidak ada, maka kunci memerlukan autentikasi untuk setiap penggunaan (lihat permulaan untuk detail alur autentikasi per operasi).
Nilainya adalah bilangan bulat 32-bit yang menentukan waktu dalam hitungan detik setelah autentikasi berhasil dari pengguna yang ditentukan oleh Tag::USER_SECURE_ID dengan metode autentikasi yang ditentukan oleh Tag::USER_AUTH_TYPE sehingga kunci dapat digunakan.
Menandai::AUTH_TOKEN
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Memberikan token autentikasi untuk memulai , memperbarui , atau menyelesaikan , untuk membuktikan autentikasi pengguna untuk operasi kunci yang memerlukannya (kunci memiliki Tag::USER_SECURE_ID ).
Nilainya adalah gumpalan yang berisi struktur hw_auth_token_t .
Tag::BLOB_USAGE_REQUIREMENTS
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan kondisi lingkungan sistem yang diperlukan agar kunci yang dihasilkan dapat digunakan.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
Tag ini dapat ditentukan selama pembuatan kunci untuk mengharuskan kunci tersebut dapat digunakan dalam kondisi yang ditentukan. Itu perlu dikembalikan dengan karakteristik utama dari generateKey dan getKeyCharacteristics . Jika pemanggil menentukan Tag::BLOB_USAGE_REQUIREMENTS dengan nilai KeyBlobUsageRequirements::STANDALONE trustlet mengembalikan gumpalan kunci yang dapat digunakan tanpa dukungan sistem file. Hal ini penting untuk perangkat dengan disk terenkripsi, yang sistem filenya mungkin tidak tersedia hingga kunci Keymaster digunakan untuk mendekripsi disk.
Menandai::BLOCK_MODE
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan mode cipher blok yang dapat digunakan kuncinya. Tag ini hanya relevan untuk kunci AES.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
Tag ini dapat diulang, dan untuk operasi kunci AES tentukan mode dalam argumen additionalParams dari mulai . Jika mode yang ditentukan tidak berada dalam mode yang terkait dengan kunci, operasi akan gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Menandai::BOOT_PATCHLEVEL
Versi : 4
Tag::BOOT_PATCHLEVEL menentukan tingkat patch keamanan image boot (kernel) yang dapat digunakan dengan kunci tersebut. Tag ini tidak pernah dikirim ke keymaster TA, namun ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA. Setiap upaya untuk menggunakan kunci dengan nilai Tag::BOOT_PATCHLEVEL yang berbeda dari patchlevel sistem yang sedang berjalan akan menyebabkan begin() , getKeyCharacteristics() atau exportKey() mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat upgradeKey() untuk detailnya.
Nilai tag adalah bilangan bulat dalam bentuk YYYYMMDD, dengan YYYY adalah empat digit tahun pembaruan terakhir, MM adalah dua digit bulan, dan DD adalah dua digit hari pembaruan terakhir. Misalnya, untuk kunci yang dibuat pada perangkat Android yang terakhir diperbarui pada tanggal 5 Juni 2018, nilainya adalah 20180605. Jika hari tidak diketahui, 00 dapat diganti.
Selama setiap boot, bootloader harus menyediakan tingkat patch image boot ke lingkungan aman (mekanisme ditentukan oleh implementasi).
Harus didukung perangkat keras.
Tag::BOOTLOADER_ONLY
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan hanya bootloader yang dapat menggunakan kunci tersebut.
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Segala upaya untuk menggunakan kunci dengan Tag::BOOTLOADER_ONLY dari sistem Android gagal dengan ErrorCode::INVALID_KEY_BLOB .
Tag::CALLER_NONCE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan bahwa pemanggil dapat menyediakan nonce untuk operasi yang tidak memerlukan nonce.
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Tag ini hanya digunakan untuk kunci AES, dan hanya relevan untuk mode blok CBC, CTR, dan GCM. Jika tag tidak ada, penerapan harus menolak operasi apa pun yang menyediakan Tag::NONCE untuk memulai dengan ErrorCode::CALLER_NONCE_PROHIBITED .
Tag::CREATION_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu pembuatan kunci, dalam milidetik sejak 1 Januari 1970. Tag ini bersifat opsional dan hanya bersifat informasi.
Tag:: PENCERNAAN
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan algoritma intisari yang dapat digunakan dengan kunci untuk melakukan operasi penandatanganan dan verifikasi. Tag ini relevan dengan kunci RSA, ECDSA, dan HMAC.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_DIGEST_NONE = 0,
KM_DIGEST_MD5 = 1,
KM_DIGEST_SHA1 = 2,
KM_DIGEST_SHA_2_224 = 3,
KM_DIGEST_SHA_2_256 = 4,
KM_DIGEST_SHA_2_384 = 5,
KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;
Tag ini dapat diulang. Untuk operasi penandatanganan dan verifikasi, tentukan intisari dalam argumen additionalParams dari mulai . Jika intisari yang ditentukan tidak ada dalam intisari yang terkait dengan kunci, operasi akan gagal dengan ErrorCode::INCOMPATIBLE_DIGEST .
Menandai::EC_CURVE
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Di Keymaster 1, kurva yang digunakan untuk kunci EC ditebak dari ukuran kunci yang ditentukan. Untuk meningkatkan fleksibilitas di masa mendatang, Keymaster 2 memperkenalkan cara eksplisit untuk menentukan kurva. Permintaan pembuatan kunci EC mungkin memiliki Tag::EC_CURVE , Tag::KEY_SIZE , atau keduanya.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Keymaster 2 dan sebelumnya
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Jika permintaan pembuatan hanya berisi Tag::KEY_SIZE , kembali ke logika Keymaster 1, pilih kurva NIST yang sesuai.
Jika permintaan hanya berisi Tag::EC_CURVE , gunakan kurva yang ditentukan. Untuk Keymaster 3 dan yang lebih baru, kurva ditentukan di EcCurve . Untuk Keymaster 2 dan versi sebelumnya, kurva ditentukan di keymaster_ec_curve_t .
Jika permintaan berisi keduanya, gunakan kurva yang ditentukan oleh Tag::EC_CURVE , dan validasi bahwa ukuran kunci yang ditentukan sesuai untuk kurva tersebut. Jika tidak, kembalikan ErrorCode::INVALID_ARGUMENT .
Tag::INCLUDE_UNIQUE_ID
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Tag ini ditentukan selama pembuatan kunci untuk menunjukkan bahwa sertifikat pengesahan untuk kunci yang dihasilkan harus berisi ID unik perangkat dengan cakupan aplikasi dan terikat waktu, seperti yang ditentukan oleh Tag::UNIQUE_ID .
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Menandai::KEY_SIZE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan ukuran, dalam bit, kunci, mengukur dengan cara normal untuk algoritma kunci. Misalnya, untuk kunci RSA, Tag::KEY_SIZE menentukan ukuran modulus publik. Untuk kunci AES, ini menentukan panjang material kunci rahasia.
Label::MAC_LENGTH
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Memberikan panjang tag autentikasi MAC atau GCM yang diminta, dalam bit.
Nilainya adalah panjang MAC dalam bit. Ini merupakan kelipatan 8 dan setidaknya sebesar nilai Tag::MIN_MAC_LENGTH yang terkait dengan kunci.
Menandai::MAX_USES_PER_BOOT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan berapa kali kunci dapat digunakan secara maksimal di antara reboot sistem. Ini adalah mekanisme lain untuk membatasi penggunaan kunci.
Nilainya adalah bilangan bulat 32-bit yang mewakili penggunaan per boot.
Ketika kunci dengan tag ini digunakan dalam suatu operasi, penghitung yang terkait dengan kunci harus bertambah selama panggilan awal . Setelah penghitung kunci melampaui nilai ini, semua upaya berikutnya untuk menggunakan kunci tersebut gagal dengan ErrorCode::MAX_OPS_EXCEEDED , hingga perangkat dimulai ulang. Ini berarti bahwa trustlet menyimpan tabel penggunaan counter untuk kunci dengan tag ini. Karena memori Keymaster seringkali terbatas, tabel ini dapat memiliki ukuran maksimum yang tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini ketika tabel penuh. Meja harus menampung setidaknya 16 kunci. Jika operasi gagal karena tabel penuh, Keymaster mengembalikan ErrorCode::TOO_MANY_OPERATIONS .
Label::MIN_MAC_LENGTH
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Tag ini menentukan panjang minimum MAC yang dapat diminta atau diverifikasi dengan kunci ini untuk kunci HMAC dan kunci AES yang mendukung mode GCM.
Nilai ini adalah panjang MAC minimum, dalam bit. Ini merupakan kelipatan 8. Untuk kunci HMAC, nilainya minimal 64. Untuk kunci GCM, nilainya minimal 96 dan tidak lebih dari 128.
Tag::MIN_SECONDS_BETWEEN_OPS
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan jumlah waktu minimum yang berlalu antara operasi yang diizinkan menggunakan kunci. Hal ini dapat digunakan untuk membatasi penggunaan kunci dalam konteks di mana penggunaan tanpa batas dapat memungkinkan serangan brute force.
Nilainya adalah bilangan bulat 32-bit yang mewakili detik antara operasi yang diizinkan.
Ketika kunci dengan tag ini digunakan dalam suatu operasi, mulailah pengatur waktu selama panggilan selesai atau dibatalkan . Setiap panggilan untuk memulai yang diterima sebelum pengatur waktu menunjukkan bahwa interval yang ditentukan oleh Tag::MIN_SECONDS_BETWEEN_OPS telah berlalu gagal dengan ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Ini berarti bahwa trustlet menyimpan tabel penggunaan counter untuk kunci dengan tag ini. Karena memori Keymaster seringkali terbatas, tabel ini dapat memiliki ukuran maksimum yang tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini ketika tabel penuh. Tabel harus mengakomodasi setidaknya 32 kunci yang sedang digunakan dan secara agresif menggunakan kembali slot tabel ketika interval penggunaan minimum kunci berakhir. Jika operasi gagal karena tabel penuh, Keymaster mengembalikan ErrorCode::TOO_MANY_OPERATIONS .
Tag::NO_AUTH_REQUIRED
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan bahwa tidak diperlukan otentikasi untuk menggunakan kunci ini. Tag ini saling eksklusif dengan Tag::USER_SECURE_ID .
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Tag::NONCE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menyediakan atau mengembalikan nonce atau Inisialisasi Vektor (IV) untuk enkripsi atau dekripsi AES GCM, CBC, atau CTR. Tag ini disediakan untuk memulai selama operasi enkripsi dan dekripsi. Ini hanya disediakan untuk memulai jika kuncinya memiliki Tag::CALLER_NONCE . Jika tidak disediakan, nonce atau IV yang sesuai akan dibuat secara acak oleh Keymaster dan dikembalikan dari awal.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah. Panjang yang diperbolehkan bergantung pada mode: nonce GCM panjangnya 12 byte; CBC dan CTR IV panjangnya 16 byte.
Menandai:: ASAL
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan di mana kunci dibuat, jika diketahui. Tag ini mungkin tidak ditentukan selama pembuatan atau impor kunci, dan harus ditambahkan ke karakteristik kunci oleh trustlet.
Pemimpin kunci 3 Nilai yang mungkin ditentukan di android::hardware::keymaster::v3_0::KeyOrigin :
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Keymaster 2 dan versi sebelumnya Nilai yang mungkin ditentukan dalam keymaster_origin_t :
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
Arti penuh dari nilai tersebut tidak hanya bergantung pada nilai tetapi juga pada apakah nilai tersebut ditemukan dalam daftar karakteristik yang didukung perangkat keras atau yang didukung perangkat lunak.
GENERATED menunjukkan bahwa Keymaster menghasilkan kunci. Jika ada dalam daftar yang didukung perangkat keras, kunci dibuat di perangkat keras yang aman dan terikat pada perangkat keras secara permanen. Jika ada dalam daftar yang didukung perangkat lunak, kunci dibuat di SoftKeymaster dan tidak terikat pada perangkat keras.
DERIVED menunjukkan bahwa kunci tersebut diturunkan di dalam Keymaster. Kemungkinan ada di luar perangkat.
IMPORTED menunjukkan bahwa kunci dibuat di luar Keymaster dan diimpor ke Keymaster. Jika ada dalam daftar yang didukung perangkat keras, maka perangkat keras tersebut terikat secara permanen, meskipun salinan di luar perangkat keras yang aman mungkin ada. Jika dalam daftar yang menerapkan perangkat lunak, kunci telah diimpor ke SoftKeymaster dan tidak terikat pada perangkat keras.
UNKNOWN seharusnya hanya muncul dalam daftar yang didukung perangkat keras. Hal ini menunjukkan bahwa kunci tersebut terikat pada perangkat keras, namun tidak diketahui apakah kunci tersebut awalnya dibuat di perangkat keras yang aman atau diimpor. Ini hanya terjadi ketika perangkat keras keymaster0 digunakan untuk meniru layanan keymaster1.
Tag::ORIGINATION_EXPIRE_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu masa berlaku kunci untuk tujuan penandatanganan dan enkripsi. Setelah waktu ini, segala upaya untuk menggunakan kunci dengan KeyPurpose::SIGN atau KeyPurpose::ENCRYPT yang disediakan untuk memulai gagal dengan ErrorCode::KEY_EXPIRED .
Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.
Menandai::OS_PATCHLEVEL
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Tag ini tidak pernah dikirim ke keymaster TA, namun ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA.
Nilai tag adalah bilangan bulat dalam bentuk YYYYMM, dengan YYYY adalah empat digit tahun pembaruan terakhir dan MM adalah dua digit bulan pembaruan terakhir. Misalnya, untuk kunci yang dibuat pada perangkat Android yang terakhir diperbarui pada bulan Desember 2015, nilainya akan menjadi 201512.
Kunci yang memiliki level patch berbeda dari level patch saat ini tidak dapat digunakan. Upaya untuk menggunakan kunci tersebut menyebabkan Begin , getKeyCharacteristics , atau exportKey mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat Pengikatan Versi untuk lebih jelasnya.
Menandai::OS_VERSION
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Tag ini tidak pernah dikirim ke keymaster TA, namun ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA.
Nilai tag adalah bilangan bulat dengan bentuk MMmmss, dimana MM adalah nomor versi mayor, mm adalah nomor versi minor, dan ss adalah nomor versi sub-minor. Misalnya, untuk kunci yang dibuat di Android versi 4.0.3, nilainya adalah 040003.
Tag::PADDING
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan mode padding yang dapat digunakan dengan kunci. Tag ini relevan dengan kunci RSA dan AES.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class PaddingMode : uint32_t {
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_PAD_NONE = 1,
KM_PAD_RSA_OAEP = 2,
KM_PAD_RSA_PSS = 3,
KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
KM_PAD_PKCS7 = 64,
} keymaster_padding_t;
PaddingMode::RSA_OAEP dan PaddingMode::RSA_PKCS1_1_5_ENCRYPT hanya digunakan untuk kunci enkripsi/dekripsi RSA dan menentukan padding RSA PKCS#1v2 OAEP dan padding acak RSA PKCS#1 v1.5. PaddingMode::RSA_PSS dan PaddingMode::RSA_PKCS1_1_5_SIGN hanya digunakan untuk kunci penandatanganan/verifikasi RSA dan menentukan padding PSS RSA PKCS#1v2 dan padding deterministik RSA PKCS#1 v1.5.
PaddingMode::NONE dapat digunakan dengan kunci RSA atau AES. Untuk kunci AES, jika PaddingMode::NONE digunakan dengan mode blok ECB atau CBC dan data yang akan dienkripsi atau didekripsi bukan kelipatan dari ukuran blok AES, panggilan untuk menyelesaikan gagal dengan ErrorCode::INVALID_INPUT_LENGTH .
PaddingMode::PKCS7 hanya dapat digunakan dengan kunci AES, dan hanya dengan mode ECB dan CBC.
Tag ini dapat diulang. Mode padding harus ditentukan dalam panggilan untuk memulai . Jika mode yang ditentukan tidak diotorisasi untuk kunci, operasi gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::TUJUAN
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan serangkaian tujuan penggunaan kunci.
Nilai yang mungkin ditentukan oleh enumerasi berikut:
Keymaster 3
enum class KeyPurpose : uint32_t {
ENCRYPT = 0,
DECRYPT = 1,
SIGN = 2,
VERIFY = 3,
DERIVE_KEY = 4, // since 3.0
WRAP_KEY = 5, // since 3.0
};
Keymaster 2 dan sebelumnya
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Tag ini dapat diulang; kunci dapat dihasilkan dengan beberapa nilai, meskipun suatu operasi memiliki satu tujuan. Ketika fungsi mulai dipanggil untuk memulai operasi, tujuan operasi ditentukan. Jika tujuan yang ditentukan untuk operasi tidak diizinkan oleh kunci, operasi akan gagal dengan ErrorCode::INCOMPATIBLE_PURPOSE .
Tag::RESET_SINCE_ID_ROTATION
Versi : 3, 4
Dapat diulang ? TIDAK
Menentukan apakah perangkat telah dikembalikan ke setelan pabrik sejak rotasi ID unik terakhir. Digunakan untuk pengesahan kunci.
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Menandai::ROLLBACK_RESISTANT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menunjukkan bahwa kunci tersebut tahan rollback, artinya ketika dihapus oleh deleteKey atau deleteAllKeys , kunci tersebut dijamin akan terhapus secara permanen dan tidak dapat digunakan. Ada kemungkinan bahwa kunci tanpa tag ini dapat dihapus dan kemudian dipulihkan dari cadangan.
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Tandai::ROOT_OF_TRUST
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan akar kepercayaan , kunci yang digunakan oleh boot terverifikasi untuk memvalidasi sistem operasi yang di-boot (jika ada). Tag ini tidak pernah diberikan atau dikembalikan dari Keymaster dalam karakteristik kunci.
Menandai::RSA_PUBLIC_EXPONENT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan nilai eksponen publik untuk pasangan kunci RSA. Tag ini hanya relevan untuk kunci RSA, dan diperlukan untuk semua kunci RSA.
Nilainya adalah bilangan bulat tak bertanda 64-bit yang memenuhi persyaratan eksponen publik RSA. Nilai ini harus berupa bilangan prima. Trustlet mendukung nilai 2^16+1 dan dapat mendukung nilai masuk akal lainnya, khususnya nilai 3. Jika tidak ada eksponen yang ditentukan atau jika eksponen yang ditentukan tidak didukung, pembuatan kunci gagal dengan ErrorCode::INVALID_ARGUMENT .
Tag::UNIQUE_ID
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk memberikan ID unik dalam pengesahan.
Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.
Label::USAGE_EXPIRE_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu masa berlaku kunci untuk tujuan verifikasi dan dekripsi. Setelah waktu ini, setiap upaya untuk menggunakan kunci dengan KeyPurpose::VERIFY atau KeyPurpose::DECRYPT yang disediakan untuk memulai gagal dengan ErrorCode::KEY_EXPIRED .
Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.
Menandai::USER_AUTH_TYPE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan jenis pengautentikasi pengguna yang dapat digunakan untuk mengotorisasi kunci ini. Saat Keymaster diminta untuk melakukan operasi dengan kunci dengan tag ini, Keymaster akan menerima token autentikasi, dan bidang authenticator_type token harus cocok dengan nilai dalam tag. Misalnya, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , di mana ntoh adalah fungsi yang mengubah bilangan bulat yang dipesan jaringan menjadi bilangan bulat yang dipesan host dan auth_type_tag_value adalah nilai dari tag ini.
Nilainya adalah bitmask bilangan bulat 32-bit yang berisi nilai dari enumerasi:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 dan sebelumnya
typedef enum {
HW_AUTH_NONE = 0,
HW_AUTH_PASSWORD = 1 << 0,
HW_AUTH_FINGERPRINT = 1 << 1,
// Additional entries should be powers of 2.
HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;
Tandai::USER_SECURE_ID
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan bahwa kunci hanya dapat digunakan dalam kondisi autentikasi pengguna aman tertentu. Tag ini saling eksklusif dengan Tag::NO_AUTH_REQUIRED .
Nilainya adalah bilangan bulat 64-bit yang menentukan nilai status kebijakan autentikasi yang harus ada dalam token autentikasi (disediakan untuk diawali dengan Tag::AUTH_TOKEN ) untuk mengotorisasi penggunaan kunci. Panggilan apa pun yang dimulai dengan kunci dengan tag ini yang tidak memberikan token autentikasi, atau memberikan token autentikasi tanpa nilai status kebijakan yang cocok, akan gagal.
Tag ini dapat diulang. Jika salah satu nilai yang diberikan cocok dengan nilai status kebijakan apa pun dalam token autentikasi, kunci tersebut diotorisasi untuk digunakan. Jika tidak, operasi akan gagal dengan ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Tag::VENDOR_PATCHLEVEL
Versi : 4
Tag ini menentukan tingkat patch keamanan gambar vendor yang dapat digunakan kuncinya. Tag ini tidak pernah dikirim ke keymaster TA, namun ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA. Setiap upaya untuk menggunakan kunci dengan nilai Tag::VENDOR_PATCHLEVEL yang berbeda dari patchlevel sistem yang berjalan saat ini harus menyebabkan begin() , getKeyCharacteristics() atau exportKey() mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat upgradeKey() untuk detailnya.
Nilai tag adalah bilangan bulat dalam bentuk YYYYMMDD, dengan YYYY adalah empat digit tahun pembaruan terakhir, MM adalah dua digit bulan, dan DD adalah dua digit hari pembaruan terakhir. Misalnya, untuk kunci yang dibuat pada perangkat Android yang terakhir diperbarui pada tanggal 5 Juni 2018, nilainya akan menjadi 20180605.
HAL IKeymasterDevice harus membaca level patch vendor saat ini dari properti sistem ro.vendor.build.security_patch dan mengirimkannya ke lingkungan aman saat HAL pertama kali dimuat (mekanisme ditentukan oleh implementasi). Lingkungan aman tidak boleh menerima tingkat patch lain hingga boot berikutnya.
Harus didukung perangkat keras.