Tag otorisasi Keymaster

Halaman ini memberikan detail untuk membantu penyelenggara Keymaster HAL. Panduan ini mencakup setiap tag di HAL, versi Keymaster yang memiliki tag tersebut dan apakah tag dapat diulang. Kecuali seperti yang tercantum dalam deskripsi tag, semua tag di bawah 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 yang lebih lama, tag didefinisikan di platform/hardware/libhardware/include/hardware/keymaster_defs.h.

Untuk fungsi, lihat Keymaster Functions.

Tag::ACTIVE_DATETIME

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan tanggal dan waktu saat kunci menjadi aktif. Sebelumnya setiap waktu, upaya apa pun untuk menggunakan kunci tersebut akan gagal dengan ErrorCode::KEY_NOT_YET_VALID.

Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.

Tag::ALGORITHM

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan algoritma kriptografi yang menggunakan kunci tersebut.

Nilai yang memungkinkan ditentukan oleh enumerasi berikut:

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 dan yang lebih lama 
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

Disimpan untuk penggunaan di masa mendatang.

Tag::ALLOW_WHILE_ON_BODY

Versi: 2, 3, 4

Dapat diulang? Tidak

Tag ini hanya berlaku untuk perangkat Android Wear dengan sensor di tubuh. Pada saat ini, TEE tidak diharapkan dapat memberikan akses aman ke sensor pada tubuh, atau sensor pada tubuh sangat aman, sehingga hal ini diharapkan menjadi fitur yang sepenuhnya diterapkan oleh software.

Tag::ALL_USERS

Versi: 3, 4

Dapat diulang? Tidak

Disimpan untuk penggunaan di masa mendatang.

Tag::APPLICATION_DATA

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Jika diberikan ke 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 memberikan tag ini dan data terkait yang sama sebagai bagian dari kumpulan inParams. Jika data yang benar tidak diberikan, fungsi akan menampilkan ErrorCode::INVALID_KEY_BLOB.

Konten tag ini terikat dengan kunci secara kriptografi, Artinya, tidak mungkin ada musuh yang memiliki akses ke semua rahasia dunia yang aman, tetapi tidak memiliki akses ke isi tag untuk membongkar enkripsi kunci tanpa melakukan brute-force pada konten tag, yang dapat dicegah aplikasi dengan menentukan konten dengan entropi yang cukup tinggi.

Nilainya adalah blob, array byte dengan panjang arbitrer.

Tag::APPLICATION_ID

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Jika diberikan ke generateKey atau importKey, tag ini menentukan data yang diperlukan selama semua penggunaan kunci. Di beberapa khususnya, panggilan ke exportKey dan getKeyCharacteristics harus memberikan nilai yang sama dalam parameter clientId, dan panggilan ke memulai harus menyediakan tag ini serta data terkait yang sama sebagai bagian dari inParams disetel. Jika tidak ada data yang benar, {i>function<i} akan menampilkan ErrorCode::INVALID_KEY_BLOB.

Konten tag ini terikat dengan kunci secara kriptografis, yang berarti bahwa penyerang yang dapat mengakses semua rahasia dunia yang aman—tetapi tidak memiliki akses ke konten tag—tidak dapat mendekripsi kunci (tanpa melakukan brute force pada konten tag).

Nilainya adalah blob, array byte dengan panjang arbitrer.

Tag::ASSOCIATED_DATA

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menyediakan "data terkait" untuk enkripsi atau dekripsi AES-GCM. Tag ini yang diberikan untuk memperbarui dan menentukan data yang tidak dienkripsi/didekripsi, tetapi digunakan dalam komputasi tag GCM.

Nilainya adalah blob, array byte dengan panjang arbitrer.

Tag::ATTEstation_APPLICATION_ID

Versi: 3, 4

Dapat diulang? Tidak

Digunakan untuk mengidentifikasi kumpulan aplikasi yang mungkin digunakan telah memulai pengesahan kunci.

Nilainya adalah blob, array byte dengan panjang arbitrer.

Tag::ATTEstation_CHALLENGE

Versi: 3, 4

Dapat diulang? Tidak

Digunakan untuk memberikan verifikasi login dalam pengesahan.

Nilainya adalah blob, array byte dengan panjang arbitrer.

Tag::ATTESTATION_ID_BRAND

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nama merek perangkat, seperti yang ditampilkan oleh Build.BRAND di Android. Bidang ini hanya disetel saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTEstation_ID_DEVICE

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nama perangkat, seperti yang ditampilkan oleh Build.DEVICE di Android. Bidang ini hanya disetel saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTEstation_ID_IMEI

Versi: 3, 4

Dapat diulang? Ya

Menyediakan IMEI untuk semua radio pada perangkat. Kolom ini hanya ditetapkan saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTEstation_ID_MANUFACTURER

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nama produsen perangkat, seperti yang ditampilkan oleh Build.MANUFACTURER di Android. Bidang ini hanya diatur bila meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTESTATION_ID_MEID

Versi: 3, 4

Dapat diulang? Ya

Memberikan MEID untuk semua radio di perangkat. Kolom ini hanya ditetapkan saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTESTATION_ID_MODEL

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nama model perangkat, seperti yang ditampilkan oleh Build.MODEL di Android. Kolom ini hanya ditetapkan saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTESTATION_ID_PRODUCT

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nama produk perangkat, seperti yang ditampilkan oleh Build.PRODUCT di Android. Bidang ini hanya diatur bila meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::ATTESTATION_ID_SERIAL

Versi: 3, 4

Dapat diulang? Tidak

Memberikan nomor seri perangkat. Kolom ini hanya ditetapkan saat meminta pengesahan ID 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 blob, array byte dengan panjang arbitrer.

Tag::AUTH_TIMEOUT

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan waktu dalam detik saat kunci diberi otorisasi untuk digunakan, setelah autentikasi. Jika Tag::USER_SECURE_ID dan tag ini tidak ada, maka kunci tersebut 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 pengguna yang berhasil ditentukan oleh Tag::USER_SECURE_ID dengan metode autentikasi ditentukan oleh Tag::USER_AUTH_TYPE sehingga kunci tersebut dapat data

Tag::AUTH_TOKEN

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menyediakan autentikasi token untuk memulai, update atau selesai, untuk membuktikan otentikasi pengguna untuk operasi kunci yang memerlukan (kuncinya memiliki Tag::USER_SECURE_ID).

Nilainya adalah blob yang berisi struktur hw_auth_token_t.

Tag::BLOB_USAGE_USAGES

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan kondisi lingkungan sistem yang diperlukan agar kunci yang dihasilkan dapat digunakan.

Nilai yang memungkinkan ditentukan oleh enumerasi berikut:

Keymaster 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 dan yang lebih lama 
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 pada kondisi yang ditentukan. Kunci ini harus ditampilkan dengan karakteristik kunci dari generateKey dan getKeyCharacteristics. Jika pemanggil menentukan Tag::BLOB_USAGE_REQUIREMENTS dengan nilai KeyBlobUsageRequirements::STANDALONE, trustlet menampilkan blob kunci yang dapat digunakan tanpa dukungan sistem file. Hal ini penting untuk perangkat dengan disk terenkripsi, tempat 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 block cipher yang dapat digunakan dengan kunci. Tag ini hanya relevan dengan kunci AES.

Nilai yang memungkinkan ditentukan oleh enumerasi berikut:

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 dan yang lebih lama 
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 ada dalam mode yang terkait dengan kunci tersebut, gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::BOOT_PATCHLEVEL

Versi: 4

Tag::BOOT_PATCHLEVEL menentukan level patch keamanan image booting (kernel) yang dapat digunakan dengan kunci. Tag ini tidak pernah dikirim ke TA {i>keymaster<i}, tetapi ditambahkan ke daftar otorisasi yang diberlakukan perangkat keras oleh TA. Setiap upaya untuk gunakan kunci dengan nilai Tag::BOOT_PATCHLEVEL yang berbeda dari saat ini menjalankan sistem patchlevel menyebabkan begin(), getKeyCharacteristics() atau exportKey() untuk menampilkan ErrorCode::KEY_REQUIRES_UPGRADE. Lihat upgradeKey() untuk mengetahui detailnya.

Nilai tag adalah bilangan bulat dari format YYYYMMDD, dengan YYYY adalah tahun dengan empat digit dari pembaruan terakhir, MM adalah bulan dengan dua digit dan DD adalah dengan dua digit hari pembaruan terakhir. Misalnya, untuk kunci yang dibuat pada Perangkat Android terakhir diupdate pada 5 Juni 2018, nilainya adalah 20180605. Jika hari tidak diketahui, 00 dapat diganti.

Selama setiap booting, bootloader harus menyediakan level patch image booting ke lingkungan yang aman (mekanisme ditentukan berdasarkan implementasi).

Harus menggunakan hardware.

Tag::BOOTLOADER_ONLY

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan bahwa hanya bootloader yang dapat menggunakan kunci tersebut.

Tag ini berupa boolean, sehingga nilai yang memungkinkan adalah true (jika tag tersebut ada) dan false (jika tag tidak ada).

Setiap upaya untuk menggunakan kunci dengan Tag::BOOTLOADER_ONLY dari sistem Android akan gagal dengan ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan bahwa pemanggil dapat memberikan nonce untuk operasi yang memerlukan nonce.

Tag ini bersifat boolean, sehingga nilai yang mungkin adalah benar (jika tag ada) dan salah (jika tag tidak ada).

Tag ini hanya digunakan untuk kunci AES, dan hanya relevan untuk CBC, CTR, dan GCM mode pemblokiran. Jika tag tidak ada, penerapan harus menolak semua operasi yang menyediakan Tag::NONCE untuk mulai dengan ErrorCode::CALLER_NONCE_PROHIBITED.

Tag::CREATION_DATETIME

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan tanggal dan waktu kunci dibuat, dalam milidetik sejak 1 Januari 1970. Tag ini bersifat opsional dan hanya bersifat informasi.

Tag::DIGEST

Versi: 1, 2, 3, 4

Dapat diulang? Ya

Menentukan algoritma ringkasan yang dapat digunakan dengan kunci untuk melakukan penandatanganan dan verifikasi. Tag ini relevan dengan kunci RSA, ECDSA, dan HMAC.

Nilai yang memungkinkan 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 yang lebih lama 
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 ringkasan dalam argumen additionalParams dari begin. Jika intisari yang ditentukan tidak ada dalam ringkasan yang terkait dengan kunci tersebut, maka gagal dengan ErrorCode::INCOMPATIBLE_DIGEST.

Tag::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 dapat memiliki Tag::EC_CURVE, Tag::KEY_SIZE, atau keduanya.

Nilai yang memungkinkan 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 yang lebih lama 
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, dengan memilih kurva NIST yang sesuai.

Jika permintaan hanya berisi Tag::EC_CURVE, gunakan kurva yang ditentukan. Untuk Keymaster 3 dan yang lebih baru, kurva ditentukan dalam EcCurve. Untuk Keymaster 2 dan yang lebih lama, kurva ditentukan di keymaster_ec_curve_t.

Jika permintaan berisi keduanya, gunakan kurva yang ditentukan oleh Tag::EC_CURVE, dan validasikan bahwa ukuran kunci yang ditentukan sesuai untuk kurva tersebut. Jika tidak, tampilkan 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 yang dibatasi waktu dan cakupan aplikasi, seperti yang ditentukan oleh Tag::UNIQUE_ID.

Tag ini berupa boolean, sehingga nilai yang memungkinkan adalah true (jika tag tersebut ada) dan false (jika tag tidak ada).

Tag::KEY_SIZE

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan ukuran kunci, dalam bit, yang diukur dengan cara normal untuk algoritma kunci. Misalnya, untuk kunci RSA, Tag::KEY_SIZE menentukan ukuran modulus publik. Untuk kunci AES, panjang materi kunci rahasia ditentukan.

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. Yaitu kelipatan dari 8 dan minimal sebesar nilai Tag::MIN_MAC_LENGTH yang terkait dengan kunci tersebut.

Tag::MAX_USES_PER_BOOT

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan jumlah maksimum penggunaan kunci di antara sistem memulai ulang komputer. Ini adalah mekanisme lain untuk membatasi penggunaan kunci.

Nilainya adalah bilangan bulat 32-bit yang mewakili penggunaan per booting.

Ketika kunci dengan tag ini digunakan dalam suatu operasi, penghitung yang terkait dengan kunci harus bertambah selama begin. Setelah kunci telah melampaui nilai ini, semua upaya berikutnya untuk menggunakan kunci gagal dengan ErrorCode::MAX_OPS_EXCEEDED, hingga perangkat dimulai ulang. Ini menyiratkan bahwa trustlet menyimpan tabel penghitung penggunaan untuk kunci dengan . Karena memori Keymaster sering kali terbatas, tabel ini dapat memiliki dan Keymaster bisa menggagalkan operasi yang berupaya menggunakan kunci dengan tag ini saat tabel penuh. Tabel harus mengakomodasi minimal 16 kunci. Jika operasi gagal karena tabel penuh, Keymaster akan menampilkan 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 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 waktu yang diizinkan operasi menggunakan kunci. Kebijakan ini dapat digunakan untuk membatasi kapasitas penggunaan kunci dalam konteks di mana penggunaan tak terbatas mungkin memungkinkan serangan {i>brute force<i}.

Nilainya adalah bilangan bulat 32-bit yang mewakili detik antara waktu yang diizinkan operasional bisnis.

Saat kunci dengan tag ini digunakan dalam suatu operasi, mulai timer saat proses akhir atau batalkan panggilan. Setiap panggilan ke begin yang diterima sebelum timer menunjukkan bahwa interval yang ditentukan oleh Tag::MIN_SECONDS_BETWEEN_OPS telah berlalu akan gagal dengan ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Ini menyiratkan bahwa trustlet menyimpan tabel penghitung penggunaan untuk kunci dengan tag ini. Karena memori Keymaster sering kali terbatas, tabel ini dapat memiliki nilai maksimum tetap dan Keymaster dapat menggagalkan operasi yang berupaya menggunakan kunci dengan tag ini saat tabel penuh. Tabel harus mengakomodasi minimal 32 kunci yang sedang digunakan dan menggunakan kembali slot tabel secara agresif saat interval penggunaan minimum kunci berakhir. Jika operasi gagal karena tabel penuh, Keymaster akan ditampilkan ErrorCode::TOO_MANY_OPERATIONS.

Tag::NO_AUTH_REQUIRED

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan bahwa tidak diperlukan autentikasi untuk menggunakan kunci ini. Tag ini tidak dapat digunakan bersama dengan Tag::USER_SECURE_ID.

Tag ini bersifat boolean, sehingga nilai yang mungkin adalah benar (jika tag ada) dan salah (jika tag tidak ada).

Tag::NONCE

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menyediakan atau mengembalikan nonce atau initialization vector (IV) untuk AES GCM, CBC, enkripsi atau dekripsi CTR. Tag ini diberikan kepada mulai selama operasi enkripsi dan dekripsi. Ini hanya disediakan untuk memulai jika kunci memiliki Tag::CALLER_NONCE. Jika tidak disediakan, nonce atau IV yang sesuai akan dibuat secara acak oleh Keymaster dan ditampilkan dari awal.

Nilainya adalah blob, array byte dengan panjang arbitrer. Panjang yang diizinkan bergantung pada mode: nonce GCM memiliki panjang 12 byte; CBC dan CTR IV memiliki panjang 16 byte.

Tag::Origin

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan tempat kunci dibuat, jika diketahui. Tag ini tidak dapat ditentukan selama pembuatan atau impor kunci, dan harus ditambahkan ke karakteristik kunci oleh trustlet.

Keymaster 3

Nilai yang memungkinkan ditentukan dalam android::hardware::keymaster::v3_0::KeyOrigin:

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 dan yang lebih lama

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

Makna lengkap nilai tidak hanya bergantung pada nilai, tetapi juga pada apakah nilai tersebut ditemukan dalam daftar karakteristik yang diberlakukan hardware atau software.

GENERATED menunjukkan bahwa Keymaster membuat kunci. Jika berada dalam daftar perangkat keras, kunci dibuat dalam perangkat keras yang aman dan terikat secara permanen dengan perangkat keras. Jika dalam daftar yang dijalankan oleh perangkat lunak, kuncinya dibuat di {i>SoftKeymaster<i} dan tidak terikat dengan perangkat keras.

DERIVED menunjukkan bahwa kunci berasal dari dalam Keymaster. Kemungkinan ada di luar perangkat.

IMPORTED menunjukkan bahwa kunci dibuat di luar Keymaster dan diimpor ke Keymaster. Jika ada dalam daftar yang diterapkan hardware, kunci akan terikat hardware secara permanen, meskipun mungkin ada salinan di luar hardware yang aman. Jika di daftar {i>software-enforces<i}, kunci itu diimpor ke dalam {i>SoftKeymaster<i} dan tidak terikat perangkat keras.

UNKNOWN hanya boleh muncul dalam daftar yang diberlakukan hardware. Hal ini menunjukkan bahwa kunci terikat hardware, tetapi tidak diketahui apakah kunci awalnya dibuat di hardware yang aman atau diimpor. Hal ini hanya terjadi saat hardware keymaster0 digunakan untuk mengemulasi layanan keymaster1.

Tag::originATION_EXPIRE_DATETIME

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan tanggal dan waktu berakhirnya masa berlaku kunci untuk tujuan penandatanganan dan enkripsi. Setelah waktu ini, setiap upaya untuk menggunakan kunci dengan KeyPurpose::SIGN atau KeyPurpose::ENCRYPT yang disediakan untuk memulai akan gagal dengan ErrorCode::KEY_EXPIRED.

Nilainya adalah bilangan bulat 64-bit yang mewakili milidetik sejak 1 Januari 1970.

Tag::OS_PATCHLEVEL

Versi: 2, 3, 4

Dapat diulang? Tidak

Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang diberlakukan perangkat keras oleh TA.

Nilai tag adalah bilangan bulat dari format YYYYMM, dengan YYYY adalah tahun empat digit dari pembaruan terakhir dan MM adalah bulan dua digit dari memperbarui. Misalnya, untuk kunci yang dibuat pada perangkat Android yang terakhir diperbarui pada Desember 2015, nilainya akan menjadi 201512.

Kunci yang memiliki level patch yang berbeda dengan level patch saat ini tidak dapat digunakan. Upaya untuk menggunakan kunci tersebut akan menyebabkan begin, getKeyCharacteristics, atau exportKey menampilkan ErrorCode::KEY_REQUIRES_UPGRADE. Lihat Penautan Versi untuk detail selengkapnya.

Tag::OS_VERSION

Versi: 2, 3, 4

Dapat diulang? Tidak

Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang diberlakukan perangkat keras oleh TA.

Nilai tag adalah bilangan bulat dalam bentuk MMmmss, dengan MM adalah nomor versi utama, mm adalah nomor versi minor, dan ss adalah nomor versi sub-minor. Misalnya, untuk kunci yang dibuat di Android versi 4.0.3, nilainya akan menjadi 040003.

Tag::PADDING

Versi: 1, 2, 3, 4

Dapat diulang? Ya

Menentukan mode padding yang dapat digunakan dengan kunci. Tag ini yang relevan dengan kunci RSA dan AES.

Nilai yang memungkinkan 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 yang lebih lama 
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 RSA kunci penandatanganan/verifikasi dan tentukan RSA PKCS#1v2 PSS padding dan padding determenistik RSA PKCS#1 v1.5 masing-masing.

PaddingMode::NONE dapat digunakan dengan kunci RSA atau AES. Untuk kunci AES, jika PaddingMode::NONE digunakan dengan ECB atau CBC mode blok dan data yang akan dienkripsi atau didekripsi tidak lebih dari beberapa 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 {i>padding<i} harus ditentukan dalam panggilan ke memulai. Jika mode yang ditentukan tidak diotorisasi untuk kunci, operasi akan gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::PURPOSE

Versi: 1, 2, 3, 4

Dapat diulang? Ya

Menentukan kumpulan tujuan yang dapat digunakan kunci.

Nilai yang memungkinkan 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 yang lebih lama 
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 dibuat dengan beberapa nilai, meskipun suatu operasi memiliki satu tujuan. Jika Fungsi begin dipanggil untuk memulai operasi, tujuan operasi tersebut 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 direset ke setelan pabrik sejak rotasi ID unik terakhir. Digunakan untuk pengesahan kunci.

Tag ini bersifat boolean, sehingga nilai yang mungkin adalah benar (jika tag ada) dan salah (jika tag tidak ada).

Tag::ROLLBACK_RESISTANT

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menunjukkan bahwa kunci tahan rollback, yang berarti bahwa saat dihapus oleh deleteKey atau deleteAllKeys, kunci dijamin akan dihapus secara permanen dan tidak dapat digunakan. Sangat mungkin bahwa kunci tanpa tag ini dapat dihapus dan kemudian dipulihkan dari cadangan.

Tag ini bersifat boolean, sehingga nilai yang mungkin adalah benar (jika tag ada) dan salah (jika tag tidak ada).

Tag::ROOT_OF_TRUST

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan root kepercayaan, kunci yang digunakan oleh booting terverifikasi untuk memvalidasi sistem operasi yang di-booting (jika ada). Tag ini tidak pernah diberikan ke atau ditampilkan dari Keymaster dalam karakteristik kunci.

Tag::RSA_PUBLIC_EXPONENT

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan nilai eksponen publik untuk pasangan kunci RSA. Tag ini hanya relevan dengan kunci RSA, dan diperlukan untuk semua kunci RSA.

Nilainya adalah bilangan bulat tanpa tanda tangan 64-bit yang memenuhi persyaratan Eksponen publik RSA. Nilai ini harus berupa bilangan prima. Trustlet mendukung 2^16 + 1 dan dapat mendukung nilai-nilai wajar lainnya, khususnya nilai 3. Jika tidak ada eksponen yang ditentukan atau 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 blob, array byte dengan panjang arbitrer.

Tag::USAGE_EXPIRE_DATETIME

Versi: 1, 2, 3, 4

Dapat diulang? Tidak

Menentukan tanggal dan waktu berakhirnya kunci untuk tujuan verifikasi dan dekripsi. Setelah waktu ini, setiap upaya untuk menggunakan kunci dengan Tujuan Utama::VERIFIKASI atau Tujuan Utama::DECRYPT diberikan kepada mulai gagal 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 pengautentikasi pengguna yang dapat digunakan untuk memberikan otorisasi tombol. Saat diminta untuk melakukan operasi dengan kunci yang memiliki tag ini, Keymaster akan menerima token autentikasi, dan kolom authenticator_type token harus cocok dengan nilai dalam tag. Misalnya, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, dengan ntoh adalah fungsi yang mengonversi bilangan bulat yang diurutkan jaringan menjadi bilangan bulat yang diperintahkan oleh {i>host<i} dan auth_type_tag_value adalah nilai tag ini.

Nilainya adalah bitmask bilangan bulat 32-bit dari 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 yang lebih lama 
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? Ya

Menentukan bahwa kunci hanya dapat digunakan untuk pengguna aman tertentu status autentikasi. Tag ini sama eksklusifnya dengan Tag::NO_AUTH_REQUIRED.

Nilainya adalah bilangan bulat 64-bit yang menentukan status kebijakan autentikasi nilai yang harus ada dalam token otentikasi (diberikan kepada dimulai dengan Tag::AUTH_TOKEN) untuk mengizinkan penggunaan kunci tersebut. Apa saja panggil untuk memulai dengan kunci dengan tag ini yang tidak memberikan token otentikasi, atau memberikan token autentikasi tanpa nilai status kebijakan yang cocok, gagal.

Tag ini dapat diulang. Jika salah satu nilai yang diberikan cocok dengan nilai status kebijakan dalam token autentikasi, kunci akan diberi otorisasi untuk digunakan. Jika tidak, operasi akan gagal dengan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Tag::VENDOR_PATCHLEVEL

Versi: 4

Tag ini menentukan level patch keamanan image vendor yang digunakan yang dapat digunakan. Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang diberlakukan perangkat keras oleh TA. Setiap upaya untuk menggunakan kunci dengan nilai Tag::VENDOR_PATCHLEVEL yang berbeda dari patchlevel sistem yang sedang berjalan harus menyebabkan begin(), getKeyCharacteristics(), atau exportKey() menampilkan ErrorCode::KEY_REQUIRES_UPGRADE. Lihat upgradeKey() untuk mengetahui detailnya.

Nilai tag adalah bilangan bulat dalam bentuk YYYYMMDD, dengan YYYY adalah tahun empat digit dari update terakhir, MM adalah bulan dua digit, dan DD adalah hari dua digit dari update terakhir. Misalnya, untuk kunci yang dibuat pada Perangkat Android terakhir diupdate 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 aman saat HAL pertama kali dimuat (mekanisme ditentukan oleh implementasi). Lingkungan aman tidak boleh menerima patch level lain hingga setelah booting berikutnya.

Harus diterapkan oleh hardware.