Halaman ini memberikan detail untuk membantu pelaksana Keymaster HAL. Ini mencakup setiap tag di HAL, di versi Keymaster mana tag tersedia, dan apakah tag dapat diulang. Kecuali seperti yang disebutkan dalam deskripsi tag, semua tag di bawah ini digunakan selama pembuatan kunci untuk menentukan karakteristik kunci.
Untuk Keymaster 4, tag ditentukan di 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 fungsi, lihat halaman Fungsi Keymaster .
Tag::ACTIVE_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu di mana kunci menjadi aktif. Sebelumnya, upaya apa pun untuk menggunakan kunci gagal dengan ErrorCode::KEY_NOT_YET_VALID .
Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.
Menandai::ALGORITMA
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan algoritme kriptografi yang digunakan kuncinya.
Nilai yang mungkin ditentukan oleh pencacahan 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::ALL_APPLICATIONS
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Dicadangkan untuk penggunaan di masa mendatang.
Tag::IZINKAN_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 tidak diharapkan dapat menyediakan akses aman ke sensor pada tubuh, atau bahwa sensor pada tubuh sangat aman, jadi ini diharapkan menjadi fitur murni yang didukung perangkat lunak.
Tag::ALL_USERS
Versi : 3, 4
Dapat diulang ? TIDAK
Dicadangkan untuk penggunaan di masa mendatang.
Tag::APPLICATION_DATA
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Saat disediakan untuk generateKey atau importKey , tag ini menentukan data yang diperlukan selama semua penggunaan kunci. Secara khusus, panggilan ke exportKey dan getKeyCharacteristics harus memberikan nilai yang sama ke parameter clientId , dan panggilan ke begin harus menyediakan tag ini dan data terkait yang sama sebagai bagian dari kumpulan inParams . Jika data yang benar tidak diberikan, fungsi mengembalikan ErrorCode::INVALID_KEY_BLOB .
Konten tag ini terikat pada kunci secara kriptografis , artinya tidak mungkin bagi musuh yang memiliki akses ke semua rahasia dunia yang aman tetapi tidak memiliki akses ke konten tag untuk mendekripsi kunci tanpa memaksa tag konten, yang dapat dicegah oleh aplikasi dengan menentukan konten entropi yang cukup tinggi.
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::APPLICATION_ID
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Saat disediakan untuk generateKey atau importKey , tag ini menentukan data yang diperlukan selama semua penggunaan kunci. Secara khusus, panggilan ke exportKey dan getKeyCharacteristics harus memberikan nilai yang sama di parameter clientId , dan panggilan ke begin harus menyediakan tag ini dan data terkait yang sama sebagai bagian dari kumpulan inParams . Jika data yang benar tidak diberikan, fungsi 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 (tanpa memaksa isi tag ).
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
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, tetapi digunakan dalam komputasi tag GCM.
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_APPLICATION_ID
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk mengidentifikasi sekumpulan kemungkinan aplikasi yang salah satunya telah memulai pengesahan kunci.
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_CHALLENGE
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk memberikan tantangan dalam pengesahan.
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_BRAND
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama merek perangkat, seperti yang ditampilkan oleh Build.BRAND di Android. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_DEVICE
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama perangkat perangkat, seperti yang ditampilkan oleh Build.DEVICE di Android. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_IMEI
Versi : 3, 4
Dapat diulang ? Ya
Menyediakan IMEI untuk semua radio di perangkat. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_MANUFACTURER
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama pabrikan perangkat, seperti yang ditampilkan oleh Build.MANUFACTURER di Android. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_MEID
Versi : 3, 4
Dapat diulang ? Ya
Menyediakan MEID untuk semua radio di perangkat. Kolom ini hanya akan disetel saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_MODEL
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama model perangkat, seperti yang ditampilkan oleh Build.MODEL di Android. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_PRODUCT
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nama produk perangkat, seperti yang ditampilkan oleh Build.PRODUCT di Android. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::ATTESTATION_ID_SERIAL
Versi : 3, 4
Dapat diulang ? TIDAK
Memberikan nomor seri perangkat. Kolom ini disetel hanya saat meminta pengesahan pengenal perangkat.
Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() sebelumnya dipanggil dan perangkat tidak dapat lagi mengesahkan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini akan gagal dengan ErrorCode::CANNOT_ATTEST_IDS .
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::AUTH_TIMEOUT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan waktu dalam detik di mana kunci diotorisasi untuk digunakan, setelah autentikasi. Jika Tag::USER_SECURE_ID ada dan tag ini tidak ada, kunci memerlukan autentikasi untuk setiap penggunaan (lihat mulai untuk detail alur autentikasi per operasi).
Nilainya adalah bilangan bulat 32-bit yang menentukan waktu dalam detik setelah autentikasi berhasil dari pengguna yang ditentukan oleh Tag::USER_SECURE_ID dengan metode autentikasi yang ditentukan oleh Tag::USER_AUTH_TYPE agar kunci dapat digunakan.
Tag::AUTH_TOKEN
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menyediakan token autentikasi untuk begin , update atau finish , 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 pencacahan 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 meminta agar kunci dapat digunakan dalam kondisi yang ditentukan. Itu perlu dikembalikan dengan karakteristik kunci dari generateKey dan getKeyCharacteristics . Jika penelepon menentukan Tag::BLOB_USAGE_REQUIREMENTS dengan nilai KeyBlobUsageRequirements::STANDALONE trustlet mengembalikan gumpalan kunci yang dapat digunakan tanpa dukungan sistem file. Ini penting untuk perangkat dengan disk terenkripsi, di mana sistem file mungkin tidak tersedia hingga setelah kunci Keymaster digunakan untuk mendekripsi disk.
Tag::BLOCK_MODE
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan mode sandi blok yang dapat digunakan dengan kunci. Tag ini hanya relevan dengan kunci AES.
Nilai yang mungkin ditentukan oleh pencacahan 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 begin . Jika mode yang ditentukan tidak dalam mode yang terkait dengan kunci, operasi akan gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::BOOT_PATCHLEVEL
Versi : 4
Tag::BOOT_PATCHLEVEL menentukan tingkat tambalan keamanan boot image (kernel) yang dapat digunakan dengan kunci. Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA. Upaya apa pun untuk menggunakan kunci dengan nilai Tag::BOOT_PATCHLEVEL berbeda dari patchlevel sistem yang sedang berjalan 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 tahun empat digit dari pembaruan terakhir, MM adalah bulan dua digit, dan DD adalah hari dua digit dari pembaruan terakhir. Misalnya, untuk kunci yang dibuat di perangkat Android yang terakhir diperbarui pada 5 Juni 2018, nilainya adalah 20180605. Jika hari tidak diketahui, 00 dapat diganti.
Selama setiap booting, bootloader harus menyediakan level tambalan citra booting 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.
Tag ini boolean, jadi nilai yang mungkin adalah true (jika tag ada) dan false (jika tag tidak ada).
Upaya apa pun 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 penelepon dapat memberikan nonce untuk operasi yang membutuhkan 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 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.
Menandai::CERMINAN
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan algoritme 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 pencacahan 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 begin . 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 ke depannya, 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 pencacahan 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 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 dibuat harus berisi ID unik perangkat dengan cakupan aplikasi dan batas 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).
Tag::UKURAN_KUNCI
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan ukuran, dalam bit, kunci, mengukur dengan cara normal untuk algoritme kunci. Misalnya, untuk kunci RSA, Tag::KEY_SIZE menentukan ukuran modulus publik. Untuk kunci AES menentukan panjang bahan kunci rahasia.
Tag::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 adalah kelipatan dari 8 dan setidaknya sebesar nilai Tag::MIN_MAC_LENGTH yang terkait dengan kunci.
Tag::MAX_USES_PER_BOOT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan berapa kali maksimum kunci dapat digunakan di antara reboot sistem. Ini adalah mekanisme lain untuk membatasi penggunaan kunci.
Nilainya adalah bilangan bulat 32-bit yang mewakili penggunaan per boot.
Saat kunci dengan tag ini digunakan dalam operasi, penghitung terkait kunci harus ditambahkan selama panggilan mulai . Setelah penghitung kunci melebihi nilai ini, semua upaya selanjutnya untuk menggunakan kunci gagal dengan ErrorCode::MAX_OPS_EXCEEDED , hingga perangkat dimulai ulang. Ini menyiratkan bahwa trustlet menyimpan tabel penghitung penggunaan untuk kunci dengan tag ini. Karena memori Keymaster seringkali terbatas, tabel ini dapat memiliki ukuran maksimum tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini saat tabel penuh. Tabel harus menampung setidaknya 16 kunci. Jika operasi gagal karena tabel penuh, Keymaster mengembalikan ErrorCode::TOO_MANY_OPERATIONS .
Tag::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 adalah kelipatan dari 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. Ini dapat digunakan untuk membatasi penggunaan kunci dalam konteks di mana penggunaan tak terbatas dapat mengaktifkan serangan brute force.
Nilainya adalah bilangan bulat 32-bit yang mewakili detik antara operasi yang diizinkan.
Saat kunci dengan tag ini digunakan dalam suatu operasi, mulai pengatur waktu selama panggilan selesai atau batalkan . 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 menyiratkan bahwa trustlet menyimpan tabel penghitung penggunaan untuk kunci dengan tag ini. Karena memori Keymaster seringkali terbatas, tabel ini dapat memiliki ukuran maksimum tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini saat tabel penuh. Tabel harus mengakomodasi setidaknya 32 kunci yang sedang digunakan dan secara agresif menggunakan kembali slot tabel saat 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 otentikasi tidak diperlukan 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).
Menandai::NONCE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Memberikan atau mengembalikan nonce atau Initialization Vector (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 dengan panjang sewenang-wenang. Panjang yang diizinkan bergantung pada mode: panjang nonce GCM adalah 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.
Master kunci 3 Nilai yang mungkin ditentukan dalam android::hardware::keymaster::v3_0::KeyOrigin :
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Keymaster 2 dan 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 tidak hanya bergantung pada nilai tetapi pada apakah itu ditemukan dalam daftar karakteristik yang didukung perangkat keras atau perangkat lunak.
GENERATED menunjukkan bahwa Keymaster membuat kunci. Jika dalam daftar yang didukung perangkat keras, kunci dibuat di perangkat keras yang aman dan terikat perangkat keras secara permanen. Jika dalam daftar yang didukung perangkat lunak, kunci dibuat di SoftKeymaster dan tidak terikat perangkat keras.
DERIVED menunjukkan bahwa kunci 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, itu terikat perangkat keras secara permanen, meskipun salinan di luar perangkat keras aman mungkin ada. Jika dalam daftar penerapan perangkat lunak, kuncinya diimpor ke SoftKeymaster dan tidak terikat perangkat keras.
UNKNOWN seharusnya hanya muncul dalam daftar yang menggunakan perangkat keras. Ini menunjukkan bahwa kuncinya terikat pada perangkat keras, tetapi 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 di mana kunci kedaluwarsa untuk tujuan penandatanganan dan enkripsi. Setelah itu, upaya apa pun untuk menggunakan kunci dengan KeyPurpose::SIGN atau KeyPurpose::ENCRYPT disediakan untuk memulai 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 TA keymaster, tetapi ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA.
Nilai tag adalah bilangan bulat dalam bentuk YYYYMM, dengan YYYY adalah tahun empat digit dari pembaruan terakhir dan MM adalah bulan dua digit dari pembaruan terakhir. Misalnya, untuk kunci yang dibuat di perangkat Android yang terakhir diperbarui pada Desember 2015, nilainya adalah 201512.
Kunci yang memiliki level tambalan berbeda dari level tambalan saat ini tidak dapat digunakan. Upaya untuk menggunakan kunci seperti itu menyebabkan begin , getKeyCharacteristics , atau exportKey untuk mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat Pengikatan Versi untuk detail lebih lanjut.
Menandai::OS_VERSION
Versi : 2, 3, 4
Dapat diulang ? TIDAK
Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA.
Nilai tag adalah bilangan bulat dalam bentuk MMmmss, dengan 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.
Menandai::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 pencacahan 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 verifikasi/penandatanganan 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 akan gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::TUJUAN
Versi : 1, 2, 3, 4
Dapat diulang ? Ya
Menentukan serangkaian tujuan yang dapat digunakan kunci.
Nilai yang mungkin ditentukan oleh pencacahan 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 banyak nilai, meskipun suatu operasi memiliki tujuan tunggal. Saat fungsi mulai dipanggil untuk memulai operasi, tujuan operasi ditentukan. Jika tujuan yang ditentukan untuk operasi tidak diotorisasi 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).
Tag::ROLLBACK_RESISTANT
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menandakan bahwa key tahan rollback, artinya ketika dihapus oleh deleteKey atau deleteAllKeys , key dijamin akan dihapus secara permanen dan tidak dapat digunakan. Ada kemungkinan 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).
Tag::ROOT_OF_TRUST
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan root of trust , 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 utama.
Tag::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 mungkin mendukung nilai wajar lainnya, khususnya nilai 3. Jika tidak ada eksponen yang ditentukan atau jika eksponen yang ditentukan tidak didukung, pembuatan kunci akan gagal dengan ErrorCode::INVALID_ARGUMENT .
Tag::ID_UNIK
Versi : 3, 4
Dapat diulang ? TIDAK
Digunakan untuk memberikan ID unik dalam pengesahan.
Nilainya adalah gumpalan, array byte dengan panjang sewenang-wenang.
Tag::USAGE_EXPIRE_DATETIME
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan tanggal dan waktu di mana kunci kedaluwarsa untuk tujuan verifikasi dan dekripsi. Setelah itu, upaya apa pun untuk menggunakan kunci dengan KeyPurpose::VERIFY atau KeyPurpose::DECRYPT disediakan untuk memulai dengan ErrorCode::KEY_EXPIRED .
Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.
Tag::USER_AUTH_TYPE
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan jenis autentikator pengguna yang dapat digunakan untuk mengotorisasi kunci ini. Saat Keymaster diminta untuk melakukan operasi dengan kunci dengan tag ini, Keymaster 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 mengonversi bilangan bulat yang dipesan jaringan menjadi bilangan bulat yang dipesan host dan auth_type_tag_value adalah nilai dari tag ini.
Nilainya adalah bitmask integer 32-bit dari nilai-nilai dari pencacahan:
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;
Tag::USER_SECURE_ID
Versi : 1, 2, 3, 4
Dapat diulang ? TIDAK
Menentukan bahwa kunci hanya dapat digunakan di bawah status 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 dimulai dengan Tag::AUTH_TOKEN ) untuk mengotorisasi penggunaan kunci. Panggilan apa pun untuk memulai dengan kunci dengan tag ini yang tidak memberikan token autentikasi, atau menyediakan 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. Kalau tidak, operasi gagal dengan ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Tag::VENDOR_PATCHLEVEL
Versi : 4
Tag ini menentukan tingkat tambalan keamanan gambar vendor yang dapat digunakan dengan kunci. Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA. Upaya apa pun untuk menggunakan kunci dengan nilai Tag::VENDOR_PATCHLEVEL yang berbeda dari patchlevel sistem yang sedang berjalan 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 tahun empat digit dari pembaruan terakhir, MM adalah bulan dua digit, dan DD adalah hari dua digit dari pembaruan terakhir. Misalnya, untuk kunci yang dibuat di perangkat Android yang terakhir diperbarui pada 5 Juni 2018, nilainya adalah 20180605.
HAL IKeymasterDevice harus membaca patchlevel vendor saat ini dari properti sistem ro.vendor.build.security_patch dan mengirimkannya ke lingkungan yang aman saat HAL pertama kali dimuat (mekanisme ditentukan oleh implementasi). Lingkungan aman tidak boleh menerima patchlevel lain hingga setelah booting berikutnya.
Harus didukung perangkat keras.