Tag Otorisasi Keymaster

Halaman ini memberikan detail untuk membantu pelaksana HAL Keymaster. Ini mencakup setiap tag di HAL, di versi Keymaster mana tag itu tersedia, dan apakah tag tersebut 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 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 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. Sebelum waktu ini, setiap upaya untuk menggunakan kunci gagal dengan ErrorCode::KEY_NOT_YET_VALID .

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

Tag::ALGORITMA

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menentukan algoritma kriptografi dengan kunci yang digunakan.

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::ALL_APPLICATIONS

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Dicadangkan 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 pada tubuh. Pada titik ini, TEE tidak diharapkan dapat memberikan akses aman ke sensor pada tubuh, atau sensor pada tubuh sangat aman, jadi ini diharapkan menjadi fitur yang sepenuhnya didukung oleh 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

Ketika disediakan untuk generateKey atau importKey , tag ini menentukan data yang diperlukan selama semua penggunaan kunci. Secara khusus, panggilan ke exportKey dan getKeyCharacteristics perlu memberikan nilai yang sama ke parameter clientId , dan panggilan untuk memulai 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 ke 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 secara brutal. 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

Ketika disediakan untuk generateKey atau importKey , tag ini menentukan data yang diperlukan selama semua penggunaan kunci. Secara khusus, panggilan ke exportKey dan getKeyCharacteristics perlu memberikan nilai yang sama dalam parameter clientId , dan panggilan untuk memulai 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 ke 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 konten tag secara kasar ).

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::ASOSIATED_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 menghitung tag GCM.

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::ATTESTATION_APPLICATION_ID

Versi : 3, 4

Dapat diulang ? Tidak

Digunakan untuk mengidentifikasi kumpulan kemungkinan aplikasi yang telah memulai pengesahan kunci.

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.

Tag::ATTESTATION_ID_BRAND

Versi : 3, 4

Dapat diulang ? Tidak

Memberikan nama merek perangkat, seperti yang dikembalikan oleh Build.BRAND di Android. Bidang ini disetel hanya saat meminta pengesahan pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini 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 pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini 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 pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini 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 produsen perangkat, seperti yang dikembalikan oleh Build.MANUFACTURER di Android. Bidang ini disetel hanya saat meminta pengesahan pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini gagal dengan ErrorCode::CANNOT_ATTEST_IDS .

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::ATTESTATION_ID_MEID

Versi : 3, 4

Dapat diulang ? Ya

Menyediakan MEID untuk semua radio di perangkat. Bidang ini hanya akan disetel saat meminta pengesahan pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini gagal dengan ErrorCode::CANNOT_ATTEST_IDS .

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::ATTESTATION_ID_MODEL

Versi : 3, 4

Dapat diulang ? Tidak

Memberikan nama model perangkat, seperti yang dikembalikan oleh Build.MODEL di Android. Bidang ini disetel hanya saat meminta pengesahan pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini gagal dengan ErrorCode::CANNOT_ATTEST_IDS .

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::ATTESTATION_ID_PRODUCT

Versi : 3, 4

Dapat diulang ? Tidak

Memberikan nama produk perangkat, seperti yang dikembalikan oleh Build.PRODUCT di Android. Bidang ini disetel hanya saat meminta pengesahan pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini 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 pengenal perangkat.

Jika perangkat tidak mendukung pengesahan ID (atau destroyAttestationIds() dipanggil sebelumnya dan perangkat tidak dapat lagi membuktikan ID-nya), permintaan pengesahan kunci apa pun yang menyertakan tag ini gagal dengan ErrorCode::CANNOT_ATTEST_IDS .

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah.

Tag::AUTH_TIMEOUT

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menentukan waktu dalam detik saat kunci diotorisasi untuk digunakan, setelah autentikasi. Jika Tag::USER_SECURE_ID ada 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 berhasil dari pengguna yang ditentukan oleh Tag::USER_SECURE_ID dengan metode autentikasi yang ditentukan oleh Tag::USER_AUTH_TYPE bahwa kunci dapat digunakan.

Tag::AUTH_TOKEN

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menyediakan 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 untuk kunci yang dihasilkan untuk 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 kunci 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. Ini penting untuk perangkat dengan disk terenkripsi, di mana sistem file mungkin tidak tersedia sampai setelah kunci Keymaster digunakan untuk mendekripsi disk.

Tag::BLOCK_MODE

Versi : 1, 2, 3, 4

Dapat diulang ? Ya

Menentukan mode cipher blok yang dengannya kunci dapat digunakan. Tag ini hanya relevan dengan 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 begin . Jika mode yang ditentukan tidak dalam mode yang terkait dengan kunci, operasi gagal dengan ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Tag::BOOT_PATCHLEVEL

Versi : 4

Tag::BOOT_PATCHLEVEL menentukan tingkat patch keamanan gambar boot (kernel) yang dengannya kunci dapat digunakan. Tag ini tidak pernah dikirim ke TA keymaster, tetapi ditambahkan ke daftar otorisasi yang didukung perangkat keras oleh TA. Setiap upaya untuk menggunakan kunci dengan nilai Tag::BOOT_PATCHLEVEL yang berbeda dari level patch sistem yang sedang berjalan menyebabkan begin() , getKeyCharacteristics() atau exportKey() untuk mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat upgradeKey() untuk detailnya.

Nilai tag adalah bilangan bulat dari bentuk YYYYMMDD, di mana 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 boot, bootloader harus menyediakan level patch image boot ke lingkungan aman (mekanisme ditentukan oleh implementasi).

Harus didukung oleh perangkat keras.

Tag::BOOTLOADER_ONLY

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menentukan hanya bootloader yang dapat menggunakan kunci tersebut.

Tag ini adalah boolean, jadi kemungkinan nilainya 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 pemanggil dapat memberikan nonce untuk operasi yang tidak memerlukan.

Tag ini adalah boolean, jadi kemungkinan nilainya 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, implementasi 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 kunci dibuat, dalam milidetik sejak 1 Januari 1970. Tag ini bersifat opsional dan informasi saja.

Tag::DIGEST

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 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 begin . Jika intisari yang ditentukan tidak ada dalam intisari yang terkait dengan kunci, operasi 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 bergerak maju, 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 didefinisikan dalam EcCurve . Untuk Keymaster 2 dan sebelumnya, kurva didefinisikan dalam 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, kembalikan ErrorCode::INVALID_ARGUMENT .

Tag::INCLUDE_UNIQUE_ID

Versi : 2, 3, 4

Dapat diulang ? Tidak

Tag ini ditetapkan selama pembuatan kunci untuk menunjukkan bahwa sertifikat pengesahan untuk kunci yang dihasilkan harus berisi ID unik perangkat yang memiliki cakupan aplikasi dan dibatasi waktu, seperti yang ditentukan oleh Tag::UNIQUE_ID .

Tag ini adalah boolean, jadi kemungkinan nilainya adalah true (jika tag ada) dan false (jika tag tidak ada).

Tag::KEY_SIZE

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, ini menentukan panjang materi kunci rahasia.

Tag::MAC_LENGTH

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Memberikan panjang yang diminta dari tag otentikasi MAC atau GCM, dalam bit.

Nilainya adalah panjang MAC dalam bit. Ini adalah kelipatan 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.

Ketika kunci dengan tag ini digunakan dalam operasi, penghitung terkait kunci harus ditambahkan selama panggilan awal . Setelah penghitung kunci melebihi nilai ini, semua upaya berikutnya untuk menggunakan kunci gagal dengan ErrorCode::MAX_OPS_EXCEEDED , hingga perangkat dihidupkan 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 yang tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini ketika tabel penuh. Tabel perlu mengakomodasi 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 8. Untuk kunci HMAC, nilainya setidaknya 64. Untuk kunci GCM, nilainya setidaknya 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 di antara operasi yang diizinkan.

Ketika kunci dengan tag ini digunakan dalam operasi, mulai timer selama panggilan selesai atau batal . 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 yang tetap dan Keymaster dapat menggagalkan operasi yang mencoba menggunakan kunci dengan tag ini ketika tabel penuh. Tabel perlu 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 adalah boolean, jadi kemungkinan nilainya adalah true (jika tag ada) dan false (jika tag tidak ada).

Tag::tidak pernah

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menyediakan atau mengembalikan nonce atau Vektor Inisialisasi (IV) untuk enkripsi atau dekripsi AES GCM, CBC, atau CTR. Tag ini disediakan untuk memulai selama operasi enkripsi dan dekripsi. Itu hanya disediakan untuk memulai jika kuncinya memiliki Tag::CALLER_NONCE . Jika tidak disediakan, nonce atau IV yang sesuai akan dihasilkan secara acak oleh Keymaster dan dikembalikan dari awal.

Nilainya adalah gumpalan, array byte yang panjangnya berubah-ubah. Panjang yang diizinkan tergantung pada mode: nonce GCM panjangnya 12 byte; CBC dan CTR IV memiliki panjang 16 byte.

Tag::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.

Ketua 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 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 nilainya tetapi juga pada apakah nilai tersebut 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 dalam daftar yang didukung perangkat keras, itu terikat perangkat keras secara permanen, meskipun salinan di luar perangkat keras yang aman mungkin ada. Jika dalam daftar penerapan perangkat lunak, kunci diimpor ke SoftKeymaster dan tidak terikat perangkat keras.

UNKNOWN seharusnya hanya muncul dalam daftar yang didukung perangkat keras. Ini menunjukkan bahwa kunci tersebut terikat dengan 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 mengemulasi 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 waktu ini, setiap 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.

Tag::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 dari bentuk YYYYMM, di mana 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 bulan Desember 2015, nilainya adalah 201512.

Kunci yang memiliki level patch berbeda dari level patch saat ini tidak dapat digunakan. Upaya untuk menggunakan penyebab utama seperti itu dimulai , getKeyCharacteristics , atau exportKey untuk mengembalikan ErrorCode::KEY_REQUIRES_UPGRADE . Lihat Pengikatan 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 didukung perangkat keras oleh TA.

Nilai tag adalah bilangan bulat dari bentuk MMmmss, di mana 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 masing-masing menentukan padding OAEP RSA PKCS#1v2 dan RSA PKCS#1 v1.5 padding acak. PaddingMode::RSA_PSS dan PaddingMode::RSA_PKCS1_1_5_SIGN hanya digunakan untuk kunci penandatanganan/verifikasi RSA dan masing-masing 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 panjang 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 set tujuan yang kunci dapat digunakan.

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 operasi memiliki satu tujuan. Ketika fungsi begin dipanggil untuk memulai operasi, tujuan operasi ditentukan. Jika tujuan yang ditentukan untuk operasi tidak diotorisasi oleh kunci, operasi 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 adalah boolean, jadi kemungkinan nilainya adalah true (jika tag ada) dan false (jika tag tidak ada).

Tag::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 adalah boolean, jadi kemungkinan nilainya 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 kepada atau dikembalikan 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 untuk kunci RSA, dan diperlukan untuk semua kunci RSA.

Nilainya adalah bilangan bulat tidak 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 wajar 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.

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 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.

Tag::USER_AUTH_TYPE

Versi : 1, 2, 3, 4

Dapat diulang ? Tidak

Menentukan jenis autentikator pengguna yang dapat digunakan untuk mengotorisasi kunci ini. Ketika Keymaster diminta untuk melakukan operasi dengan kunci dengan tag ini, ia menerima token otentikasi, 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 diurutkan jaringan menjadi bilangan bulat yang dipesan oleh host dan auth_type_tag_value adalah nilai dari tag ini.

Nilainya adalah bitmask integer 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 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 otentikasi 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 perlu ada dalam token autentikasi (disediakan untuk dimulai dengan Tag::AUTH_TOKEN ) untuk mengizinkan penggunaan kunci. Panggilan apa pun untuk memulai dengan kunci dengan tag ini yang tidak menyediakan 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 diizinkan untuk digunakan. Jika tidak, operasi gagal dengan ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Tag::VENDOR_PATCHLEVEL

Versi : 4

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

Nilai tag adalah bilangan bulat dari bentuk YYYYMMDD, di mana 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 tanggal 5 Juni 2018, nilainya adalah 20180605.

IKeymasterDevice HAL 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 (mekanismenya ditentukan oleh implementasi). Lingkungan aman tidak boleh menerima patchlevel lain sampai setelah boot berikutnya.

Harus didukung oleh perangkat keras.