Fungsi Keymaster

Halaman ini memberikan detail untuk membantu pengimplementasi Keymaster Hardware Abstraction Layer (HAL). Panduan ini mencakup setiap fungsi dalam API dan versi Keymaster tempat fungsi tersebut tersedia serta menjelaskan implementasi default. Untuk tag, lihat halaman Tag Keymaster.

Catatan: Untuk mendukung transisi Keymaster 3 dari HAL struktur C gaya lama ke antarmuka HAL C++ yang dihasilkan dari definisi dalam Hardware Interface Definition Language (HIDL) baru, nama fungsi telah berubah di Android 8.0. Untuk mendukung hal ini, fungsi kini menggunakan camel case. Misalnya, get_key_characteristics sekarang menjadi getKeyCharacteristics.

Panduan penerapan umum

Panduan berikut berlaku untuk semua fungsi di API.

Parameter pointer input

Versi: 1, 2

Parameter pointer input yang tidak digunakan untuk panggilan tertentu mungkin NULL. Pemanggil tidak diwajibkan untuk memberikan placeholder. Misalnya, beberapa jenis dan mode kunci mungkin tidak menggunakan nilai apa pun dari argumen inParams untuk memulai, sehingga pemanggil dapat menetapkan inParams ke NULL atau memberikan kumpulan parameter kosong. Pemanggil juga dapat memberikan parameter yang tidak digunakan, dan metode Keymaster tidak boleh mengeluarkan error.

Jika parameter input yang diperlukan adalah NULL, metode Keymaster akan menampilkan ErrorCode::UNEXPECTED_NULL_POINTER.

Mulai Keymaster 3, tidak ada parameter pointer. Semua parameter diteruskan oleh nilai atau referensi konstanta.

Parameter pointer output

Versi: 1, 2

Serupa dengan parameter pointer input, parameter pointer output yang tidak digunakan mungkin NULL. Jika metode perlu menampilkan data dalam parameter output yang ditemukan sebagai NULL, metode tersebut harus menampilkan ErrorCode::OUTPUT_PARAMETER_NULL.

Mulai Keymaster 3, tidak ada parameter pointer. Semua parameter diteruskan oleh referensi nilai atau const.

Penyalahgunaan API

Versi: 1, 2, 3

Ada banyak cara bagi pemanggil untuk membuat permintaan yang tidak masuk akal atau bodoh, tetapi tidak salah secara teknis. Implementasi Keymaster tidak diperlukan untuk gagal dalam kasus tersebut atau mengeluarkan diagnostik. Penggunaan kunci yang terlalu kecil, spesifikasi parameter input yang tidak relevan, penggunaan kembali IV atau nonce, pembuatan kunci tanpa tujuan (sehingga tidak berguna) dan sejenisnya tidak boleh didiagnosis oleh implementasi. Tidak mencantumkan parameter yang diperlukan, spesifikasi parameter wajib yang tidak valid, dan error serupa harus didiagnosis.

Aplikasi, framework, dan keystore Android bertanggung jawab untuk memastikan bahwa panggilan ke modul Keymaster wajar dan berguna.

Perhatian: Implementasi Keymaster harus mencoba mendiagnosis error yang serius, seperti penghapusan parameter yang diperlukan, spesifikasi parameter yang diperlukan yang tidak valid, dan error serupa yang membahayakan integritas implementasi Keymaster.

Fungsi

getHardwareFeatures

Versi: 3

Metode getHardwareFeatures baru mengekspos kepada klien beberapa karakteristik penting dari hardware aman yang mendasarinya. Metode ini tidak mengambil argumen dan mengembalikan empat nilai, semuanya boolean:

• isSecure adalah true jika kunci disimpan di hardware aman (TEE, dll.) dan tidak pernah keluar dari hardware tersebut.
• supportsEllipticCurve adalah true jika hardware mendukung kriptografi Elliptic Curve dengan kurva NIST (P-224, P-256, P-384, dan P-521).
• supportsSymmetricCryptography adalah true jika hardware mendukung kriptografi simetris, termasuk AES dan HMAC.
• supportsAttestation adalah true jika hardware mendukung pembuatan sertifikat pengesahan kunci publik Keymaster, ditandatangani dengan kunci yang dimasukkan di lingkungan yang aman.

Satu-satunya kode error yang dapat ditampilkan metode ini adalah ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED, atau salah satu kode error yang menunjukkan kegagalan untuk berkomunikasi dengan hardware aman.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

atur

Versi: 2

Fungsi ini diperkenalkan di Keymaster 2 dan tidak digunakan lagi di Keymaster 3, karena informasi ini tersedia di file properti sistem, dan implementasi produsen membaca file tersebut selama startup.

Mengonfigurasi keymaster. Metode ini dipanggil sekali setelah perangkat dibuka dan sebelum digunakan. Tag ini digunakan untuk memberikan KM_TAG_OS_VERSION dan KM_TAG_OS_PATCHLEVEL ke keymaster. Hingga metode ini dipanggil, semua metode lain akan menampilkan KM_ERROR_KEYMASTER_NOT_CONFIGURED. Nilai yang diberikan oleh metode ini hanya diterima oleh keymaster satu kali per booting. Panggilan berikutnya akan menampilkan KM_ERROR_OK, tetapi tidak melakukan apa pun.

Jika implementasi keymaster berada di hardware aman dan versi OS serta nilai level patch yang diberikan tidak cocok dengan nilai yang diberikan ke hardware aman oleh bootloader (atau jika bootloader tidak memberikan nilai), metode ini akan menampilkan KM_ERROR_INVALID_ARGUMENT, dan semua metode lainnya akan terus menampilkan KM_ERROR_KEYMASTER_NOT_CONFIGURED.

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai add_rng_entropy dan diganti namanya di Keymaster 3.

Menambahkan entropi yang disediakan pemanggil ke kumpulan yang digunakan oleh implementasi Keymaster 1 untuk menghasilkan angka acak, untuk kunci, IV, dll.

Implementasi Keymaster perlu mencampurkan entropi yang disediakan dengan aman ke dalam kumpulannya, yang juga harus berisi entropi yang dihasilkan secara internal dari generator angka acak hardware. Pencampuran harus ditangani sehingga penyerang yang memiliki kontrol penuh atas bit yang disediakan addRngEntropy atau bit yang dihasilkan hardware, tetapi tidak keduanya, tidak memiliki keuntungan yang tidak dapat diabaikan dalam memprediksi bit yang dihasilkan dari kumpulan entropi.

Implementasi Keymaster yang mencoba memperkirakan entropi dalam kumpulan internalnya mengasumsikan bahwa data yang disediakan oleh addRngEntropy tidak berisi entropi. Implementasi Keymaster dapat menampilkan ErrorCode::INVALID_INPUT_LENGTH jika diberi lebih dari 2 KiB data dalam satu panggilan.

generateKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai generate_key dan diganti namanya di Keymaster 3.

Membuat kunci kriptografis baru, menentukan otorisasi terkait, yang terikat secara permanen ke kunci tersebut. Penerapan Keymaster membuat kunci tidak dapat digunakan dengan cara apa pun yang tidak konsisten dengan otorisasi yang ditentukan pada waktu pembuatan. Sehubungan dengan otorisasi yang tidak dapat diterapkan oleh hardware aman, kewajiban hardware aman terbatas pada memastikan bahwa otorisasi yang tidak dapat diterapkan yang terkait dengan kunci tidak dapat diubah, sehingga setiap panggilan ke getKeyCharacteristics menampilkan nilai asli. Selain itu, karakteristik yang ditampilkan oleh generateKey mengalokasikan otorisasi dengan benar antara daftar yang menerapkan hardware dan software yang diterapkan. Lihat getKeyCharacteristics untuk mengetahui detail selengkapnya.

Parameter yang diberikan ke generateKey bergantung pada jenis kunci yang dihasilkan. Bagian ini merangkum tag yang diperlukan dan opsional untuk setiap jenis kunci. Tag::ALGORITHM selalu diperlukan, untuk menentukan jenisnya.

Kunci RSA

Parameter berikut diperlukan untuk membuat kunci RSA.

• Tag::KEY_SIZE menentukan ukuran modulus publik, dalam bit. Jika dihilangkan, metode akan menampilkan ErrorCode::UNSUPPORTED_KEY_SIZE. Nilai yang didukung adalah 1024, 2048, 3072, dan 4096. Nilai yang direkomendasikan adalah semua ukuran kunci yang merupakan kelipatan 8.
• Tag::RSA_PUBLIC_EXPONENT menentukan nilai eksponen publik RSA. Jika dihilangkan, metode akan menampilkan ErrorCode::INVALID_ARGUMENT. Nilai yang didukung adalah 3 dan 65537. Nilai yang direkomendasikan adalah semua nilai prima hingga 2^64.

Parameter berikut tidak diperlukan untuk membuat kunci RSA, tetapi membuat kunci RSA tanpa parameter tersebut akan menghasilkan kunci yang tidak dapat digunakan. Namun, fungsi generateKey tidak menampilkan error jika parameter ini dihilangkan.

• Tag::PURPOSE menentukan tujuan yang diizinkan. Semua tujuan harus didukung untuk kunci RSA, dalam kombinasi apa pun.
• Tag::DIGEST menentukan algoritma ringkasan yang dapat digunakan dengan kunci baru. Implementasi yang tidak mendukung semua algoritma ringkasan harus menerima permintaan pembuatan kunci yang menyertakan ringkasan yang tidak didukung. Ringkasan yang tidak didukung harus ditempatkan dalam daftar "software-enforced" dalam karakteristik kunci yang ditampilkan. Hal ini karena kunci dapat digunakan dengan ringkasan lain tersebut, tetapi ringkasan dilakukan dalam software. Kemudian, hardware akan dipanggil untuk menjalankan operasi dengan Digest::NONE.
• Tag::PADDING menentukan mode padding yang dapat digunakan dengan kunci baru. Implementasi yang tidak mendukung semua algoritma ringkasan harus menempatkan PaddingMode::RSA_PSS dan PaddingMode::RSA_OAEP dalam daftar karakteristik utama yang diterapkan software jika ada algoritma ringkasan yang tidak didukung yang ditentukan.

Kunci ECDSA

Hanya Tag::KEY_SIZE yang diperlukan untuk membuat kunci ECDSA. Ini digunakan untuk memilih grup EC. Nilai yang didukung adalah 224, 256, 384, dan 521, yang menunjukkan kurva NIST p-224, p-256, p-384, dan p521.

Tag::DIGEST juga diperlukan untuk kunci ECDSA yang berguna, tetapi tidak diperlukan untuk pembuatan.

Kunci AES

Hanya Tag::KEY_SIZE yang diperlukan untuk membuat kunci AES. Jika dihilangkan, metode akan menampilkan ErrorCode::UNSUPPORTED_KEY_SIZE. Nilai yang didukung adalah 128 dan 256, dengan dukungan opsional untuk kunci AES 192-bit.

Parameter berikut sangat relevan untuk kunci AES, tetapi tidak perlu membuatnya:

• Tag::BLOCK_MODE menentukan mode blok yang dapat digunakan dengan kunci baru.
• Tag::PADDING menentukan mode padding yang dapat digunakan. Ini hanya relevan untuk mode ECB dan CBC.

Jika mode pemblokiran GCM ditentukan, berikan Tag::MIN_MAC_LENGTH. Jika dihilangkan, metode akan menampilkan ErrorCode::MISSING_MIN_MAC_LENGTH. Nilai tag adalah kelipatan 8 dan antara 96 dan 128.

Kunci HMAC

Parameter berikut diperlukan untuk pembuatan kunci HMAC:

• Tag::KEY_SIZE menentukan ukuran kunci dalam bit. Nilai yang lebih kecil dari 64 dan nilai yang bukan kelipatan 8 tidak didukung. Semua kelipatan 8, dari 64 hingga 512, didukung. Nilai yang lebih besar mungkin didukung.
• Tag::MIN_MAC_LENGTH menentukan panjang minimum MAC yang dapat dibuat atau diverifikasi dengan kunci ini. Nilainya adalah kelipatan 8 dan minimal 64.
• Tag::DIGEST menentukan algoritma ringkasan untuk kunci. Hanya satu ringkasan yang ditentukan, jika tidak, tampilkan ErrorCode::UNSUPPORTED_DIGEST. Jika ringkasan tidak didukung oleh trustlet, tampilkan ErrorCode::UNSUPPORTED_DIGEST.

Karakteristik utama

Jika argumen karakteristik bukan NULL, generateKey akan menampilkan karakteristik kunci yang baru dibuat yang dibagi secara tepat ke dalam daftar yang diterapkan hardware dan software. Lihat getKeyCharacteristics untuk mengetahui deskripsi mengenai karakteristik yang ada di daftar. Karakteristik yang ditampilkan menyertakan semua parameter yang ditentukan untuk pembuatan kunci, kecuali Tag::APPLICATION_ID dan Tag::APPLICATION_DATA. Jika tag ini disertakan dalam parameter kunci, tag tersebut akan dihapus dari karakteristik yang ditampilkan sehingga tidak mungkin menemukan nilainya dengan memeriksa blob kunci yang ditampilkan. Namun, nilai tersebut terikat secara kriptografis ke blob kunci, sehingga jika nilai yang benar tidak diberikan saat kunci digunakan, penggunaan akan gagal. Demikian pula, Tag::ROOT_OF_TRUST terikat secara kriptografis ke kunci, tetapi tidak dapat ditentukan selama pembuatan atau impor kunci dan tidak pernah ditampilkan.

Selain tag yang disediakan, trustlet juga menambahkan Tag::ORIGIN, dengan nilai KeyOrigin::GENERATED, dan jika kunci tahan rollback,

Tag::ROLLBACK_RESISTANT.

Ketahanan rollback

Ketahanan rollback berarti bahwa setelah kunci dihapus dengan deleteKey atau deleteAllKeys, kunci tersebut dijamin oleh hardware yang aman agar tidak dapat digunakan lagi. Implementasi tanpa resistensi rollback biasanya menampilkan materi kunci yang dihasilkan atau diimpor ke pemanggil sebagai blob kunci, formulir terenkripsi dan diautentikasi. Saat keystore menghapus blob kunci, kunci tersebut akan hilang, tetapi penyerang yang sebelumnya berhasil mengambil materi kunci berpotensi memulihkannya ke perangkat.

Kunci bersifat tahan rollback jika hardware aman menjamin bahwa kunci yang dihapus tidak dapat dipulihkan nanti. Hal ini umumnya dilakukan dengan menyimpan metadata kunci tambahan di lokasi tepercaya yang tidak dapat dimanipulasi oleh penyerang. Di perangkat seluler, mekanisme yang digunakan untuk ini biasanya Replay Protected Memory Blocks (RPMB). Karena jumlah kunci yang dapat dibuat pada dasarnya tidak terbatas dan penyimpanan tepercaya yang digunakan untuk ketahanan rollback mungkin terbatas ukuran, metode ini harus berhasil meskipun ketahanan rollback tidak dapat diberikan untuk kunci baru. Dalam hal ini, Tag::ROLLBACK_RESISTANT tidak boleh ditambahkan ke karakteristik utama.

getKeyCharacteristics

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai get_key_characteristics dan diganti namanya di Keymaster 3.

Menampilkan parameter dan otorisasi yang terkait dengan kunci yang diberikan, yang dibagi menjadi dua kumpulan: yang diterapkan hardware dan yang diterapkan software. Deskripsi di sini berlaku sama untuk daftar karakteristik kunci yang ditampilkan oleh generateKey dan importKey.

Jika Tag::APPLICATION_ID diberikan selama pembuatan atau impor kunci, nilai yang sama akan diberikan ke metode ini dalam argumen clientId. Jika tidak, metode ini akan menampilkan ErrorCode::INVALID_KEY_BLOB. Demikian pula, jika Tag::APPLICATION_DATA diberikan selama pembuatan atau impor, nilai yang sama akan diberikan ke metode ini dalam argumen appData.

Karakteristik yang ditampilkan oleh metode ini sepenuhnya menjelaskan jenis dan penggunaan kunci yang ditentukan.

Aturan umum untuk menentukan apakah tag tertentu termasuk dalam daftar yang menerapkan hardware atau software adalah bahwa jika arti tag sepenuhnya terjamin oleh hardware yang aman, artinya hardware diterapkan. Jika tidak, software akan diterapkan. Berikut adalah daftar tag tertentu yang alokasinya yang benar mungkin tidak jelas:

• Tag::ALGORITHM, Tag::KEY_SIZE, dan Tag::RSA_PUBLIC_EXPONENT adalah properti intrinsik kunci. Untuk kunci apa pun yang diamankan oleh hardware, tag ini ada dalam daftar yang diberlakukan hardware.
• Nilai Tag::DIGEST yang didukung oleh hardware aman ditempatkan dalam daftar yang didukung hardware. Ringkasan yang tidak didukung akan masuk dalam daftar yang didukung software.
• Nilai Tag::PADDING umumnya masuk dalam daftar yang didukung hardware, kecuali jika ada kemungkinan bahwa mode padding tertentu mungkin harus dilakukan oleh software. Dalam hal ini, mereka masuk dalam daftar yang didukung perangkat lunak. Kemungkinan ini muncul untuk kunci RSA yang mengizinkan padding PSS atau OAEP dengan algoritma ringkasan yang tidak didukung oleh hardware aman.
• Tag::USER_SECURE_ID dan Tag::USER_AUTH_TYPE hanya diberlakukan oleh hardware jika autentikasi pengguna diberlakukan oleh hardware. Untuk mencapainya, kepercayaan Keymaster dan trustlet autentikasi yang relevan harus aman dan memiliki kunci HMAC rahasia yang digunakan untuk menandatangani dan memvalidasi token autentikasi. Lihat halaman Autentikasi untuk mengetahui detailnya.
• Tag Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME, dan Tag::USAGE_EXPIRE_DATETIME memerlukan akses ke jam dinding yang dapat diverifikasi kebenarannya. Sebagian besar hardware yang aman hanya memiliki akses ke informasi waktu yang disediakan oleh OS yang tidak aman, yang berarti tag diterapkan oleh software.
• Tag::Origin selalu ada dalam daftar hardware untuk kunci yang terikat dengan hardware. Kehadirannya dalam daftar tersebut menunjukkan cara lapisan yang lebih tinggi menentukan bahwa kunci didukung hardware.

importKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai import_key dan diganti namanya di Keymaster 3.

Mengimpor materi kunci ke hardware Keymaster. Parameter definisi kunci dan karakteristik output ditangani sama seperti untuk generateKey, dengan pengecualian berikut:

• Tag::KEY_SIZE dan Tag::RSA_PUBLIC_EXPONENT (khusus kunci RSA) tidak diperlukan dalam parameter input. Jika tidak disediakan, trustlet akan menyimpulkan nilai dari materi kunci yang disediakan dan menambahkan tag dan nilai yang sesuai ke karakteristik kunci. Jika parameter disediakan, trustlet akan memvalidasi parameter tersebut terhadap materi kunci. Jika terjadi ketidakcocokan, metode akan menampilkan ErrorCode::IMPORT_PARAMETER_MISMATCH.
• Tag::ORIGIN yang ditampilkan memiliki nilai yang sama dengan KeyOrigin::IMPORTED.

exportKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai export_key dan diganti namanya di Keymaster 3.

Mengekspor kunci publik dari pasangan kunci RSA atau EC Keymaster.

Jika Tag::APPLICATION_ID diberikan selama pembuatan kunci atau impor, nilai yang sama akan diberikan ke metode ini dalam argumen clientId. Jika tidak, metode akan menampilkan ErrorCode::INVALID_KEY_BLOB. Demikian pula, jika Tag::APPLICATION_DATA disediakan selama pembuatan atau impor, nilai yang sama akan diberikan ke metode ini dalam argumen appData.

deleteKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai delete_key dan diganti namanya di Keymaster 3.

Menghapus kunci yang disediakan. Metode ini bersifat opsional, dan hanya diimplementasikan oleh modul Keymaster yang memberikan ketahanan rollback.

deleteAllKeys

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai delete_all_keys dan diganti namanya di Keymaster 3.

Menghapus semua kunci. Metode ini bersifat opsional, dan hanya diterapkan oleh modul Keymaster yang memberikan ketahanan rollback.

destroyAttestationIds

Versi: 3

Metode destroyAttestationIds() digunakan untuk menonaktifkan fitur pengesahan ID baru (opsional, tetapi sangat direkomendasikan) secara permanen. Jika TEE tidak memiliki cara untuk memastikan bahwa pengesahan ID dinonaktifkan secara permanen setelah metode ini dipanggil, pengesahan ID tidak boleh diterapkan sama sekali. Dalam hal ini, metode ini tidak melakukan apa pun dan menampilkan ErrorCode::UNIMPLEMENTED. Jika pengesahan ID didukung, metode ini perlu diimplementasikan dan harus menonaktifkan semua upaya pengesahan ID mendatang secara permanen. Metode ini dapat dipanggil berapa kali pun. Jika pengesahan ID sudah dinonaktifkan secara permanen, metode ini tidak akan melakukan apa pun dan menampilkan ErrorCode::OK.

Satu-satunya kode error yang dapat ditampilkan metode ini adalah ErrorCode::UNIMPLEMENTED (jika pengesahan ID tidak didukung), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED, atau salah satu kode error yang menunjukkan kegagalan untuk berkomunikasi dengan hardware aman.

begin

Versi: 1, 2, 3

Memulai operasi kriptografi, menggunakan kunci yang ditentukan, untuk tujuan yang ditentukan, dengan parameter yang ditentukan (sebagaimana diperlukan), dan menampilkan handle operasi yang digunakan dengan update dan finish untuk menyelesaikan operasi. Nama sebutan operasi juga digunakan sebagai token "tantangan" dalam operasi yang diautentikasi, dan untuk operasi tersebut disertakan dalam kolom challenge dari token autentikasi.

Implementasi Keymaster mendukung setidaknya 16 operasi serentak. Keystore menggunakan hingga 15, menyisakan satu untuk digunakan oleh vold untuk enkripsi sandi. Jika Keystore memiliki 15 operasi yang sedang berlangsung (begin telah dipanggil, tetapi finish atau abort belum dipanggil) dan menerima permintaan untuk memulai operasi ke-16, Keystore akan memanggil abort pada operasi yang paling jarang digunakan untuk mengurangi jumlah operasi aktif menjadi 14 sebelum memanggil begin untuk memulai operasi yang baru diminta.

Jika Tag::APPLICATION_ID atau Tag::APPLICATION_DATA ditentukan selama pembuatan atau impor kunci, panggilan ke begin akan menyertakan tag tersebut dengan nilai yang awalnya ditentukan dalam argumen inParams ke metode ini.

Penerapan otorisasi

Selama metode ini, otorisasi kunci berikut diterapkan oleh trustlet jika implementasi menempatkannya dalam karakteristik "yang diberlakukan hardware" dan jika operasinya bukan operasi kunci publik. Operasi kunci publik, yang berarti KeyPurpose::ENCRYPT dan KeyPurpose::VERIFY, dengan kunci RSA atau EC, diizinkan untuk berhasil meskipun persyaratan otorisasi tidak terpenuhi.

• Tag::PURPOSE: Tujuan yang ditentukan dalam panggilan begin() harus cocok dengan salah satu tujuan dalam otorisasi kunci, kecuali jika operasi yang diminta adalah operasi kunci publik. Jika tujuan yang ditentukan tidak cocok dan operasi bukan operasi kunci publik, begin akan menampilkan ErrorCode::UNSUPPORTED_PURPOSE. Operasi kunci publik adalah operasi enkripsi atau verifikasi asimetris.
• Tag::ACTIVE_DATETIME hanya dapat diterapkan jika sumber waktu UTC tepercaya tersedia. Jika tanggal dan waktu saat ini sebelum nilai tag, metode akan menampilkan ErrorCode::KEY_NOT_YET_VALID.
• Tag::originATION_EXPIRE_DATETIME hanya dapat diterapkan jika sumber waktu UTC tepercaya tersedia. Jika tanggal dan waktu saat ini lebih lambat dari nilai tag dan tujuannya adalah KeyPurpose::ENCRYPT atau KeyPurpose::SIGN, metode akan menampilkan ErrorCode::KEY_EXPIRED.
• Tag::USAGE_EXPIRE_DATETIME hanya dapat diterapkan jika sumber waktu UTC tepercaya tersedia. Jika tanggal dan waktu saat ini lebih lambat dari nilai tag dan tujuannya adalah KeyPurpose::DECRYPT atau KeyPurpose::VERIFY, metode ini akan menampilkan ErrorCode::KEY_EXPIRED.
• Tag::MIN_SECONDS_BETWEEN_OPS dibandingkan dengan timer relatif tepercaya yang menunjukkan penggunaan terakhir kunci. Jika waktu penggunaan terakhir ditambah nilai tag kurang dari waktu saat ini, metode akan menampilkan ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Lihat deskripsi tag untuk mengetahui detail penerapan yang penting.
• Tag::MAX_USES_PER_BOOT dibandingkan dengan penghitung aman yang melacak penggunaan kunci sejak waktu booting. Jika jumlah penggunaan sebelumnya melebihi nilai tag, metode akan menampilkan ErrorCode::KEY_MAX_OPS_EXCEEDED.
• Tag::USER_SECURE_ID diterapkan oleh metode ini hanya jika kunci tersebut juga memiliki Tag::AUTH_TIMEOUT. Jika kunci memiliki keduanya, metode ini harus menerima Tag::AUTH_TOKEN yang valid di inParams. Agar token autentikasi valid, semua hal berikut harus benar:
  • Kolom HMAC divalidasi dengan benar.
  • Setidaknya salah satu nilai Tag::USER_SECURE_ID dari kunci cocok dengan setidaknya salah satu nilai ID aman dalam token.
  • Kunci memiliki Tag::USER_AUTH_TYPE yang cocok dengan jenis autentikasi dalam token.

  Jika salah satu kondisi ini tidak terpenuhi, metode akan menampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

• Tag::CALLER_NONCE memungkinkan pemanggil menentukan nonce atau vektor inisialisasi (IV). Jika kunci tidak memiliki tag ini, tetapi pemanggil memberikan Tag::NONCE ke metode ini, ErrorCode::CALLER_NONCE_PROHIBITED akan ditampilkan.
• Tag::BOOTLOADER_ONLY menentukan bahwa hanya bootloader yang dapat menggunakan kunci. Jika metode ini dipanggil dengan kunci khusus bootloader setelah bootloader selesai dieksekusi, metode ini akan menampilkan ErrorCode::INVALID_KEY_BLOB.

Kunci RSA

Semua operasi kunci RSA menentukan tepat satu mode padding di inParams. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan menampilkan ErrorCode::UNSUPPORTED_PADDING_MODE.

Operasi penandatanganan dan verifikasi RSA memerlukan ringkasan, begitu juga dengan operasi enkripsi dan dekripsi RSA dengan mode padding OAEP. Untuk kasus tersebut, pemanggil menentukan persis satu ringkasan di inParams. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan menampilkan ErrorCode::UNSUPPORTED_DIGEST.

Operasi kunci pribadi (KeyPurpose::DECYPT dan KeyPurpose::SIGN) memerlukan otorisasi ringkasan dan padding, yang berarti otorisasi kunci harus berisi nilai yang ditentukan. Jika tidak, metode akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST atau ErrorCode::INCOMPATIBLE_PADDING, sebagaimana mestinya. Operasi kunci publik (KeyPurpose::ENCRYPT dan KeyPurpose::VERIFY) diizinkan dengan ringkasan atau padding yang tidak sah.

Dengan pengecualian PaddingMode::NONE, semua mode padding RSA hanya berlaku untuk tujuan tertentu. Secara khusus, PaddingMode::RSA_PKCS1_1_5_SIGN dan PaddingMode::RSA_PSS hanya mendukung penandatanganan dan verifikasi, sedangkan PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT dan PaddingMode::RSA_OAEP hanya mendukung enkripsi dan dekripsi. Metode ini menampilkan ErrorCode::UNSUPPORTED_PADDING_MODE jika mode yang ditentukan tidak mendukung tujuan yang ditentukan.

Ada beberapa interaksi penting antara mode padding dan ringkasan:

• PaddingMode::NONE menunjukkan bahwa operasi RSA "mentah" dilakukan. Jika menandatangani atau memverifikasi, Digest::NONE akan ditentukan untuk ringkasan. Tidak diperlukan ringkasan untuk enkripsi atau dekripsi tanpa padding.
• Padding PaddingMode::RSA_PKCS1_1_5_SIGN memerlukan ringkasan. Ringkasan dapat berupa Digest::NONE, dalam hal ini implementasi Keymaster tidak dapat membuat struktur tanda tangan PKCS#1 v1.5 yang tepat, karena tidak dapat menambahkan struktur DigestInfo. Sebagai gantinya, implementasi membuat 0x00 || 0x01 || PS || 0x00 || M, dengan M adalah pesan yang disediakan dan PS adalah string padding. Ukuran kunci RSA setidaknya harus 11 byte lebih besar dari pesan. Jika tidak, metode akan menampilkan ErrorCode::INVALID_INPUT_LENGTH.
• Padding PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT tidak memerlukan ringkasan.
• Padding PaddingMode::RSA_PSS memerlukan ringkasan, yang tidak boleh Digest::NONE. Jika Digest::NONE ditentukan, metode akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST. Selain itu, ukuran kunci RSA harus minimal 2 + D byte lebih besar dari ukuran output ringkasan, dengan D adalah ukuran ringkasan, dalam byte. Jika tidak, metode akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST. Ukuran garam adalah D.
• Padding PaddingMode::RSA_OAEP memerlukan ringkasan, yang tidak boleh Digest::NONE. Jika Digest::NONE ditentukan, metode akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST.

Kunci EC

Operasi kunci EC menentukan tepat satu mode padding di inParams. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan menampilkan ErrorCode::UNSUPPORTED_PADDING_MODE.

Operasi kunci pribadi (KeyPurpose::SIGN) memerlukan otorisasi ringkasan dan padding, yang berarti bahwa otorisasi kunci harus berisi nilai yang ditentukan. Jika tidak, tampilkan ErrorCode::INCOMPATIBLE_DIGEST. Operasi kunci publik (KeyPurpose::VERIFY) diizinkan dengan ringkasan atau padding yang tidak sah.

Kunci AES

Operasi kunci AES menentukan dengan tepat satu mode blok dan satu mode padding di inParams. Jika salah satu nilai tidak ditentukan atau ditentukan lebih dari sekali, tampilkan ErrorCode::UNSUPPORTED_BLOCK_MODE atau ErrorCode::UNSUPPORTED_PADDING_MODE. Mode yang ditentukan harus diotorisasi oleh kunci, jika tidak, metode akan menampilkan ErrorCode::INCOMPATIBLE_BLOCK_MODE atau ErrorCode::INCOMPATIBLE_PADDING_MODE.

Jika mode blok adalah BlockMode::GCM, inParams menentukan Tag::MAC_LENGTH, dan nilai yang ditentukan adalah kelipatan 8 yang tidak lebih besar dari 128 atau kurang dari nilai Tag::MIN_MAC_LENGTH dalam otorisasi kunci. Untuk panjang MAC yang lebih besar dari 128 atau bukan kelipatan 8, tampilkan ErrorCode::UNSUPPORTED_MAC_LENGTH. Untuk nilai yang kurang dari panjang minimum kunci, tampilkan ErrorCode::INVALID_MAC_LENGTH.

Jika mode blok adalah BlockMode::GCM atau BlockMode::CTR, mode padding yang ditentukan harus PaddingMode::NONE. Untuk BlockMode::ECB atau BlockMode::CBC, mode-nya dapat berupa PaddingMode::NONE atau PaddingMode::PKCS7. Jika mode padding tidak memenuhi kondisi ini, tampilkan ErrorCode::INCOMPATIBLE_PADDING_MODE.

Jika mode blok adalah BlockMode::CBC, BlockMode::CTR, atau BlockMode::GCM, vektor inisialisasi atau nonce diperlukan. Pada umumnya, pemanggil tidak boleh memberikan IV atau nonce. Dalam hal ini, implementasi Keymaster akan menghasilkan IV atau nonce acak dan menampilkannya dengan Tag::NONCE di outParams. IV CBC dan CTR berukuran 16 byte. Nonce GCM berukuran 12 byte. Jika otorisasi kunci berisi Tag::CALLER_NONCE, pemanggil dapat memberikan IV atau nonce dengan Tag::NONCE di inParams. Jika nonce diberikan saat Tag::CALLER_NONCE tidak diotorisasi, tampilkan ErrorCode::CALLER_NONCE_PROHIBITED. Jika nonce tidak diberikan saat Tag::CALLER_NONCE diotorisasi, buat IV/nonce acak.

Kunci HMAC

Operasi kunci HMAC menentukan Tag::MAC_LENGTH di inParams. Nilai yang ditentukan harus merupakan kelipatan 8 yang tidak lebih besar dari panjang ringkasan atau kurang dari nilai Tag::MIN_MAC_LENGTH dalam otorisasi kunci. Untuk panjang MAC yang lebih besar dari panjang ringkasan atau bukan kelipatan 8, tampilkan ErrorCode::UNSUPPORTED_MAC_LENGTH. Untuk nilai yang kurang dari panjang minimum kunci, tampilkan ErrorCode::INVALID_MAC_LENGTH.

update

Versi: 1, 2, 3

Memberikan data untuk diproses dalam operasi yang sedang berlangsung yang dimulai dengan begin. Operasi ditentukan oleh parameter operationHandle.

Agar penanganan buffer menjadi lebih fleksibel, implementasi metode ini memiliki opsi untuk menggunakan lebih sedikit data daripada yang disediakan. Pemanggil bertanggung jawab atas loop untuk memberikan data lainnya dalam panggilan berikutnya. Jumlah input yang digunakan ditampilkan dalam parameter inputConsumed. Implementasi selalu menggunakan setidaknya satu byte, kecuali jika operasi tidak dapat menerima byte lebih banyak. Jika disediakan lebih dari nol byte dan byte yang digunakan adalah nol, pemanggil akan menganggap ini sebagai error dan membatalkan operasi.

Implementasi juga dapat memilih jumlah data yang akan ditampilkan, sebagai hasil dari update. Hal ini hanya relevan untuk operasi enkripsi dan dekripsi, karena penandatanganan dan verifikasi tidak menampilkan data hingga selesai. Tampilkan data sedini mungkin, bukan buffering.

Penanganan error

Jika metode ini menampilkan kode error selain ErrorCode::OK, operasi akan dibatalkan dan handle operasi akan dibatalkan validasinya. Setiap penggunaan handle di masa mendatang, dengan metode ini, finish, atau abort, akan menampilkan ErrorCode::INVALID_OPERATION_HANDLE.

Penerapan otorisasi

Penerapan otorisasi kunci dilakukan terutama di begin. Satu-satunya pengecualian adalah kasus jika kunci memiliki:

• Satu atau beberapa Tag::USER_SECURE_IDs, dan
• Tidak memiliki Tag::AUTH_TIMEOUT

Dalam hal ini, kunci memerlukan otorisasi per operasi, dan metode update menerima Tag::AUTH_TOKEN dalam argumen inParams. HMAC memverifikasi bahwa token valid dan berisi ID pengguna aman yang cocok, cocok dengan Tag::USER_AUTH_TYPE kunci, dan berisi handle operasi dari operasi saat ini di kolom tantangan. Jika kondisi ini tidak terpenuhi, tampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Pemanggil memberikan token autentikasi ke setiap panggilan untuk mengupdate dan menyelesaikan. Implementasi hanya perlu memvalidasi token satu kali jika diinginkan.

Kunci RSA

Untuk operasi penandatanganan dan verifikasi dengan Digest::NONE, metode ini menerima seluruh blok untuk ditandatangani atau diverifikasi dalam satu update. Fungsi ini tidak dapat menggunakan hanya sebagian blok. Namun, jika pemanggil memilih untuk memberikan data dalam beberapa pembaruan, metode ini akan menerimanya. Jika pemanggil memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan (panjang data melebihi ukuran kunci RSA), tampilkan ErrorCode::INVALID_INPUT_LENGTH.

Kunci ECDSA

Untuk operasi penandatanganan dan verifikasi dengan Digest::NONE, metode ini menerima seluruh blok untuk ditandatangani atau diverifikasi dalam satu update. Metode ini tidak dapat menggunakan sebagian blok saja.

Namun, jika pemanggil memilih untuk memberikan data dalam beberapa update, metode ini akan menerimanya. Jika pemanggil memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan, data akan otomatis terpotong. (Hal ini berbeda dengan penanganan data berlebih yang diberikan dalam operasi RSA serupa. Alasannya adalah kompatibilitas dengan klien lama.)

Kunci AES

Mode AES GCM mendukung "data autentikasi terkait", yang disediakan melalui tag Tag::ASSOCIATED_DATA dalam argumen inParams. Data terkait dapat diberikan dalam panggilan berulang (penting jika data terlalu besar untuk dikirim dalam satu blok) tetapi selalu mendahului data untuk dienkripsi atau didekripsi. Panggilan update dapat menerima data terkait dan data untuk dienkripsi/didekripsi, tetapi update berikutnya tidak dapat menyertakan data terkait. Jika pemanggil memberikan data terkait ke panggilan update setelah panggilan yang menyertakan data untuk dienkripsi/didekode, tampilkan ErrorCode::INVALID_TAG.

Untuk enkripsi GCM, tag ditambahkan ke ciphertext dengan finish. Selama dekripsi, Tag::MAC_LENGTH byte data terakhir yang diberikan ke panggilan update terakhir adalah tag. Karena pemanggilan update tertentu tidak dapat mengetahui apakah itu adalah pemanggilan terakhir, pemanggilan tersebut akan memproses semua kecuali panjang tag dan buffering data tag yang mungkin selama finish.

selesai

Versi: 1, 2, 3

Menyelesaikan operasi yang sedang berlangsung yang dimulai dengan begin, yang memproses semua data yang belum diproses yang disediakan oleh update.

Metode ini adalah metode terakhir yang dipanggil dalam operasi, sehingga semua data yang diproses akan ditampilkan.

Baik berhasil diselesaikan maupun menampilkan error, metode ini akan menyelesaikan operasi, sehingga membatalkan handle operasi yang disediakan. Semua penggunaan nama sebutan channel di masa mendatang, dengan metode ini atau metode update atau batalkan, akan menampilkan ErrorCode::INVALID_OPERATION_HANDLE.

Operasi penandatanganan menampilkan tanda tangan sebagai output. Operasi verifikasi menerima tanda tangan dalam parameter signature, dan tidak menampilkan output.

Penerapan otorisasi

Penerapan otorisasi kunci terutama dilakukan di awal. Satu-satunya pengecualian adalah kasus jika kunci memiliki:

• Satu atau beberapa Tag::USER_SECURE_IDs, dan
• Tidak memiliki Tag::AUTH_TIMEOUT

Dalam hal ini, kunci memerlukan otorisasi per operasi, dan metode update akan menerima Tag::AUTH_TOKEN dalam argumen inParams. HMAC memverifikasi bahwa token valid dan berisi ID pengguna aman yang cocok, cocok dengan Tag::USER_AUTH_TYPE kunci, dan berisi tuas operasi operasi saat ini di kolom tantangan. Jika kondisi ini tidak terpenuhi, tampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Pemanggil memberikan token autentikasi ke setiap panggilan untuk memperbarui dan menyelesaikan. Implementasi hanya perlu memvalidasi token satu kali jika diinginkan.

Kunci RSA

Beberapa persyaratan tambahan, bergantung pada mode padding:

• PaddingMode::NONE. Untuk operasi penandatanganan dan enkripsi tanpa padding, jika data yang diberikan lebih pendek daripada kunci, data tersebut akan diberi padding nol di sebelah kiri sebelum penandatanganan/enkripsi. Jika data memiliki panjang yang sama dengan kunci, tetapi lebih besar secara numerik, tampilkan ErrorCode::INVALID_ARGUMENT. Untuk operasi verifikasi dan dekripsi, data harus sama persis dengan panjang kuncinya. Jika tidak, tampilkan ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. Untuk operasi tanda tangan dengan padding PSS, salt PSS adalah ukuran ringkasan pesan dan dibuat secara acak. Ringkasan yang ditentukan dengan Tag::DIGEST di inputParams pada begin digunakan sebagai algoritma ringkasan PSS, dan sebagai algoritma ringkasan MGF1.
• PaddingMode::RSA_OAEP. Ringkasan yang ditentukan dengan Tag::DIGEST di inputParams pada awal digunakan sebagai algoritma ringkasan OAEP, dan SHA1 digunakan sebagai algoritma ringkasan MGF1.

Kunci ECDSA

Jika data yang diberikan untuk penandatanganan atau verifikasi tanpa padding terlalu panjang, pangkas data tersebut.

Kunci AES

Beberapa kondisi tambahan, bergantung pada mode blokir:

• BlockMode::ECB atau BlockMode::CBC. Jika padding adalah PaddingMode::NONE dan panjang data bukan kelipatan ukuran blok AES, tampilkan ErrorCode::INVALID_INPUT_LENGTH. Jika padding adalah PaddingMode::PKCS7, isi data sesuai spesifikasi PKCS#7. Perlu diketahui bahwa PKCS#7 merekomendasikan penambahan blok padding tambahan jika data merupakan kelipatan panjang blok.
• BlockMode::GCM. Selama enkripsi, setelah memproses semua teks biasa, hitung tag (byte Tag::MAC_LENGTH) dan tambahkan ke ciphertext yang ditampilkan. Selama dekripsi, proses byte Tag::MAC_LENGTH terakhir sebagai tag. Jika verifikasi tag gagal, tampilkan ErrorCode::VERIFICATION_FAILED.

batal

Versi: 1, 2, 3

Membatalkan operasi yang sedang berlangsung. Setelah panggilan untuk membatalkan, tampilkan ErrorCode::INVALID_OPERATION_HANDLE untuk penggunaan berikutnya dari handle operasi yang disediakan dengan update, finish, atau batalkan.

get_supported_algorithms

Versi: 1

Menampilkan daftar algoritma yang didukung oleh implementasi hardware Keymaster. Implementasi software menampilkan daftar kosong; implementasi hibrida menampilkan daftar yang hanya berisi algoritma yang didukung oleh hardware.

Implementasi Keymaster 1 mendukung RSA, EC, AES, dan HMAC.

get_supported_block_modes

Versi: 1

Menampilkan daftar mode blok AES yang didukung oleh implementasi hardware Keymaster untuk algoritma dan tujuan yang ditentukan.

Untuk RSA, EC, dan HMAC, yang bukan cipher blok, metode ini menampilkan daftar kosong untuk semua tujuan yang valid. Tujuan yang tidak valid akan menyebabkan metode menampilkan ErrorCode::INVALID_PURPOSE.

Implementasi Keymaster 1 mendukung ECB, CBC, CTR, dan GCM untuk enkripsi dan dekripsi AES.

get_supported_padding_modes

Versi: 1

Menampilkan daftar mode padding yang didukung oleh implementasi hardware Keymaster untuk algoritma dan tujuan yang ditentukan.

HMAC dan EC tidak memiliki konsep padding sehingga metode ini menampilkan daftar kosong untuk semua tujuan yang valid. Tujuan yang tidak valid akan menyebabkan metode menampilkan ErrorCode::INVALID_PURPOSE.

Untuk RSA, implementasi Keymaster 1 mendukung:

• Enkripsi, dekripsi, penandatanganan, dan verifikasi tanpa padding. Untuk enkripsi dan penandatanganan tanpa padding, jika pesan lebih pendek dari modulus publik, implementasi harus mengisi bagian kirinya dengan nol. Untuk dekripsi dan verifikasi tanpa padding, panjang input harus cocok dengan ukuran modulus publik.
• Enkripsi PKCS#1 v1.5 dan mode padding penandatanganan
• PSS dengan panjang salt minimum 20
• OAEP

Untuk AES dalam mode ECB dan CBC, implementasi Keymaster 1 tidak mendukung padding dan padding PKCS#7. Mode CTR dan GCM hanya mendukung tanpa padding.

get_supported_digests

Versi: 1

Menampilkan daftar mode ringkasan yang didukung oleh implementasi hardware Keymaster untuk algoritma dan tujuan tertentu.

Tidak ada mode AES yang mendukung atau memerlukan ringkasan, sehingga metode ini menampilkan daftar kosong untuk tujuan yang valid.

Implementasi Keymaster 1 dapat menerapkan subset ringkasan yang ditentukan. Implementasinya menyediakan SHA-256 dan dapat menyediakan MD5, SHA1, SHA-224, SHA-256, SHA384, dan SHA512 (kumpulan lengkap ringkasan yang ditentukan).

get_supported_import_formats

Versi: 1

Menampilkan daftar format impor yang didukung oleh implementasi hardware Keymaster dari algoritma yang ditentukan.

Implementasi Keymaster 1 mendukung format PKCS#8 (tanpa perlindungan sandi) untuk mengimpor pasangan kunci RSA dan EC, serta mendukung impor RAW materi kunci AES dan HMAC.

get_supported_export_formats

Versi: 1

Menampilkan daftar format ekspor yang didukung oleh implementasi hardware Keymaster dari algoritma yang ditentukan.

Implementasi Keymaster1 mendukung format X.509 untuk mengekspor kunci publik RSA dan EC. Ekspor kunci pribadi atau kunci asimetris tidak didukung.

Fungsi historis

Keymaster 0

Fungsi berikut termasuk dalam definisi Keymaster 0 yang asli. Keduanya ada di Keymaster 1 struct keymaster1_device_t. Namun, di Keymaster 1.0, keduanya tidak diimplementasikan, dan pointer fungsinya ditetapkan ke NULL.

• generate_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• Verify_data

Keymaster 1

Fungsi berikut termasuk dalam definisi Keymaster 1, tetapi dihapus di Keymaster 2, bersama dengan fungsi Keymaster 0 yang tercantum di atas.

• get_supported_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_supported_export_formats

Keymaster 2

Fungsi berikut termasuk dalam definisi Keymaster 2, tetapi dihapus di Keymaster 3, bersama dengan fungsi Keymaster 1 yang tercantum di atas.

• configure