Halaman ini memberikan rincian untuk membantu pelaksana Lapisan Abstraksi Perangkat Keras Keymaster (HAL). Ini mencakup setiap fungsi di API dan versi Keymaster mana yang tersedia dan menjelaskan implementasi default. Untuk tag, lihat halaman Tag Keymaster .
Pedoman pelaksanaan umum
Panduan berikut berlaku untuk semua fungsi di API.
Parameter penunjuk masukan
Versi : 1, 2
Parameter penunjuk masukan yang tidak digunakan untuk panggilan tertentu mungkin NULL
. Penelepon tidak diharuskan memberikan placeholder. Misalnya, beberapa tipe dan mode kunci mungkin tidak menggunakan nilai apa pun dari argumen inParams
untuk memulai , sehingga pemanggil dapat menyetel inParams
ke NULL
atau memberikan kumpulan parameter kosong. Penelepon juga dapat memberikan parameter yang tidak digunakan, dan metode Keymaster tidak boleh mengeluarkan kesalahan.
Jika parameter masukan yang diperlukan adalah NULL, metode Keymaster harus mengembalikan ErrorCode::UNEXPECTED_NULL_POINTER
.
Mulai di Keymaster 3, tidak ada parameter penunjuk. Semua parameter diteruskan dengan referensi nilai atau konstanta.
Parameter penunjuk keluaran
Versi : 1, 2
Mirip dengan parameter penunjuk masukan, parameter penunjuk keluaran yang tidak digunakan mungkin NULL
. Jika suatu metode perlu mengembalikan data dalam parameter keluaran yang ditemukan NULL
, metode tersebut harus mengembalikan ErrorCode::OUTPUT_PARAMETER_NULL
.
Mulai di Keymaster 3, tidak ada parameter penunjuk. Semua parameter diteruskan dengan referensi nilai atau konstanta.
penyalahgunaan API
Versi : 1, 2, 3
Ada banyak cara penelepon dapat mengajukan permintaan yang tidak masuk akal atau bodoh namun secara teknis tidak salah. Implementasi Keymaster tidak harus gagal dalam kasus seperti itu atau mengeluarkan diagnostik. Penggunaan kunci yang terlalu kecil, spesifikasi parameter masukan yang tidak relevan, penggunaan kembali IV atau nonce, pembuatan kunci tanpa tujuan (karenanya tidak berguna) dan sejenisnya tidak boleh didiagnosis oleh implementasi. Kelalaian parameter yang diperlukan, spesifikasi parameter yang diperlukan tidak valid, dan kesalahan serupa harus didiagnosis.
Aplikasi, framework, dan keystore Android bertanggung jawab untuk memastikan bahwa panggilan ke modul Keymaster masuk akal dan berguna.
Fungsi
dapatkan Fitur Perangkat Keras
Versi : 3
Metode getHardwareFeatures
yang baru memperlihatkan kepada klien beberapa karakteristik penting dari perangkat keras aman yang mendasarinya. Metode ini tidak memerlukan argumen dan mengembalikan empat nilai, semuanya boolean:
-
isSecure
true
jika kunci disimpan di perangkat keras yang aman (TEE, dll.) dan tidak pernah meninggalkannya. -
supportsEllipticCurve
true
jika perangkat keras mendukung kriptografi Elliptic Curve dengan kurva NIST (P-224, P-256, P-384, dan P-521). -
supportsSymmetricCryptography
true
jika perangkat keras mendukung kriptografi simetris, termasuk AES dan HMAC. -
supportsAttestation
true
jika perangkat keras mendukung pembuatan sertifikat pengesahan kunci publik Keymaster, yang ditandatangani dengan kunci yang disuntikkan di lingkungan yang aman.
Satu-satunya kode kesalahan yang dapat dikembalikan oleh metode ini adalah ErrorCode:OK
, ErrorCode::KEYMASTER_NOT_CONFIGURED
atau salah satu kode kesalahan yang menunjukkan kegagalan berkomunikasi dengan perangkat keras aman.
getHardwareFeatures() generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography, bool supportsAttestation, bool supportsAllDigests, string keymasterName, string keymasterAuthorName);
konfigurasikan
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 pabrikan membaca file tersebut selama startup.
Mengonfigurasi keymaster. Metode ini dipanggil satu kali setelah perangkat dibuka dan sebelum digunakan. Ini digunakan untuk memberikan KM_TAG_OS_VERSION dan KM_TAG_OS_PATCHLEVEL ke keymaster. Hingga metode ini dipanggil, semua metode lainnya akan mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED
. Nilai yang diberikan oleh metode ini hanya diterima oleh keymaster satu kali setiap boot. Panggilan berikutnya mengembalikan KM_ERROR_OK
, tetapi tidak melakukan apa pun.
Jika implementasi keymaster berada di perangkat keras aman dan versi OS serta nilai tingkat patch yang diberikan tidak cocok dengan nilai yang diberikan ke perangkat keras aman oleh bootloader (atau jika bootloader tidak memberikan nilai), maka metode ini akan mengembalikan KM_ERROR_INVALID_ARGUMENT
, dan semua lainnya metode terus mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED
.
keymaster_error_t (*configure)(const struct keymaster2_device* dev, const keymaster_key_param_set_t* params);
tambahkanRngEntropy
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 nomor acak, untuk kunci, IV, dll.
Implementasi Keymaster perlu menggabungkan entropi yang disediakan dengan aman ke dalam kumpulannya, yang juga harus berisi entropi yang dihasilkan secara internal dari generator nomor acak perangkat keras. Pencampuran harus ditangani sedemikian rupa sehingga penyerang yang memiliki kendali penuh atas bit yang disediakan addRngEntropy
atau bit yang dihasilkan perangkat keras, namun tidak keduanya, tidak memiliki keuntungan yang tidak dapat diabaikan dalam memprediksi bit yang dihasilkan dari kumpulan entropi.
Implementasi Keymaster yang mencoba memperkirakan entropi di kumpulan internalnya berasumsi bahwa data yang disediakan oleh addRngEntropy
tidak mengandung entropi. Implementasi Keymaster dapat mengembalikan ErrorCode::INVALID_INPUT_LENGTH
jika diberikan lebih dari 2 KiB data dalam satu panggilan.
menghasilkanKey
Versi : 1, 2, 3
Fungsi ini diperkenalkan di Keymaster 1 sebagai generate_key
dan diganti namanya di Keymaster 3.
Menghasilkan kunci kriptografi baru, menentukan otorisasi terkait, yang terikat secara permanen ke kunci tersebut. Implementasi Keymaster membuat kunci tidak dapat digunakan dengan cara apa pun yang tidak sesuai dengan otorisasi yang ditentukan pada waktu pembuatan. Sehubungan dengan otorisasi yang tidak dapat diterapkan oleh perangkat keras aman, kewajiban perangkat keras aman terbatas pada memastikan bahwa otorisasi yang tidak dapat diterapkan terkait dengan kunci tidak dapat diubah, sehingga setiap panggilan ke getKeyCharacteristics mengembalikan nilai asli. Selain itu, karakteristik yang dikembalikan oleh generateKey
mengalokasikan otorisasi dengan benar antara daftar yang didukung perangkat keras dan yang didukung perangkat lunak. Lihat getKeyCharacteristics untuk lebih jelasnya.
Parameter yang disediakan untuk generateKey
bergantung pada jenis kunci yang dihasilkan. Bagian ini merangkum tag yang diperlukan dan opsional untuk setiap jenis kunci. Tag::ALGORITMA selalu diperlukan, untuk menentukan jenisnya.
Kunci RSA
Parameter berikut diperlukan untuk menghasilkan kunci RSA.
- Tag::KEY_SIZE menentukan ukuran modulus publik, dalam bit. Jika dihilangkan, metode akan mengembalikan
ErrorCode::UNSUPPORTED_KEY_SIZE
. Nilai yang didukung adalah 1024, 2048, 3072, dan 4096. Nilai yang disarankan adalah semua ukuran kunci yang merupakan kelipatan 8. - Tag::RSA_PUBLIC_EXPONENT menentukan nilai eksponen publik RSA. Jika dihilangkan, metode akan mengembalikan
ErrorCode::INVALID_ARGUMENT
. Nilai yang didukung adalah 3 dan 65537. Nilai yang disarankan semuanya adalah nilai prima hingga 2^64.
Parameter berikut tidak diperlukan untuk menghasilkan kunci RSA, tetapi membuat kunci RSA tanpa parameter tersebut akan menghasilkan kunci yang tidak dapat digunakan. Namun, fungsi generateKey
tidak mengembalikan kesalahan jika parameter ini dihilangkan.
- Tag::PURPOSE menentukan tujuan yang diperbolehkan. Semua tujuan harus didukung untuk kunci RSA, dalam kombinasi apa pun.
- Tag::DIGEST menentukan algoritme intisari yang dapat digunakan dengan kunci baru. Implementasi yang tidak mendukung semua algoritma intisari harus menerima permintaan pembuatan kunci yang mencakup intisari yang tidak didukung. Intisari yang tidak didukung harus ditempatkan dalam daftar "yang didukung perangkat lunak" dalam karakteristik kunci yang dikembalikan. Hal ini karena kuncinya dapat digunakan dengan intisari lainnya, namun pencernaan dilakukan dalam perangkat lunak. Kemudian perangkat keras dipanggil untuk melakukan operasi dengan
Digest::NONE
. - Tag::PADDING menentukan mode padding yang dapat digunakan dengan kunci baru. Implementasi yang tidak mendukung semua algoritma intisari perlu menempatkan
PaddingMode::RSA_PSS
danPaddingMode::RSA_OAEP
dalam daftar karakteristik utama yang didukung perangkat lunak jika ada algoritma intisari yang tidak didukung yang ditentukan.
kunci ECDSA
Hanya Tag::KEY_SIZE yang diperlukan untuk menghasilkan kunci ECDSA. Ini digunakan untuk memilih grup EC. Nilai yang didukung adalah 224, 256, 384 dan 521, yang masing-masing 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 menghasilkan kunci AES. Jika dihilangkan, metode akan mengembalikan ErrorCode::UNSUPPORTED_KEY_SIZE
. Nilai yang didukung adalah 128 dan 256, dengan dukungan opsional untuk kunci AES 192-bit.
Parameter berikut ini sangat relevan untuk kunci AES, namun tidak diperlukan untuk membuatnya:
-
Tag::BLOCK_MODE
menentukan mode blok yang dapat digunakan kunci baru. -
Tag::PADDING
menentukan mode padding yang dapat digunakan. Ini hanya relevan untuk mode ECB dan CBC.
Jika mode blok GCM ditentukan, berikan Tag::MIN_MAC_LENGTH . Jika dihilangkan, metode akan mengembalikan 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 merupakan kelipatan 8 dan minimal 64.
- Tag::DIGEST menentukan algoritma intisari untuk kunci tersebut. Tepat satu intisari ditentukan, jika tidak, kembalikan
ErrorCode::UNSUPPORTED_DIGEST
. Jika intisari tidak didukung oleh trustlet, kembalikanErrorCode::UNSUPPORTED_DIGEST
.
Karakteristik utama
Jika argumen karakteristiknya bukan NULL, generateKey
mengembalikan karakteristik kunci yang baru dibuat, dibagi secara tepat ke dalam daftar yang didukung perangkat keras dan daftar yang didukung perangkat lunak. Lihat getKeyCharacteristics untuk deskripsi karakteristik mana yang masuk dalam daftar mana. Karakteristik yang dikembalikan mencakup 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 dikembalikan sehingga nilainya tidak dapat ditemukan dengan memeriksa blob kunci yang dikembalikan. Namun, mereka 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, namun mungkin tidak ditentukan selama pembuatan atau impor kunci dan tidak pernah dikembalikan.
Selain tag yang disediakan, trustlet juga menambahkan Tag::ORIGIN , dengan nilai KeyOrigin::GENERATED
, dan jika kuncinya tahan rollback,
Resistensi kemunduran
Resistensi rollback berarti bahwa setelah sebuah kunci dihapus dengan deleteKey atau deleteAllKeys , kunci tersebut dijamin oleh perangkat keras yang aman agar tidak dapat digunakan lagi. Implementasi tanpa resistensi rollback biasanya mengembalikan materi kunci yang dihasilkan atau diimpor ke pemanggil sebagai blob kunci, formulir terenkripsi dan diautentikasi. Saat keystore menghapus blob kunci, kunci tersebut akan hilang, namun penyerang yang sebelumnya berhasil mengambil materi kunci berpotensi memulihkannya ke perangkat.
Kunci bersifat tahan rollback jika perangkat keras yang aman menjamin bahwa kunci yang dihapus tidak dapat dikembalikan lagi nanti. Hal ini umumnya dilakukan dengan menyimpan metadata kunci tambahan di lokasi tepercaya yang tidak dapat dimanipulasi oleh penyerang. Pada perangkat seluler, mekanisme yang digunakan biasanya adalah 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 ukurannya, metode ini harus berhasil meskipun ketahanan rollback tidak dapat disediakan 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.
Mengembalikan parameter dan otorisasi yang terkait dengan kunci yang diberikan, dibagi menjadi dua set: yang didukung perangkat keras dan yang didukung perangkat lunak. Deskripsi di sini berlaku sama untuk daftar karakteristik utama yang dikembalikan oleh generateKey dan importKey .
Jika Tag::APPLICATION_ID
diberikan selama pembuatan atau impor kunci, nilai yang sama diberikan ke metode ini dalam argumen clientId
. Jika tidak, metode akan mengembalikan ErrorCode::INVALID_KEY_BLOB
. Demikian pula, jika Tag::APPLICATION_DATA
diberikan selama pembuatan atau impor, nilai yang sama diberikan ke metode ini dalam argumen appData
.
Karakteristik yang dikembalikan oleh metode ini menjelaskan secara lengkap jenis dan penggunaan kunci yang ditentukan.
Aturan umum untuk memutuskan apakah tag tertentu termasuk dalam daftar yang didukung perangkat keras atau yang didukung perangkat lunak adalah jika arti dari tag tersebut dijamin sepenuhnya oleh perangkat keras yang aman, maka tag tersebut akan diterapkan secara perangkat keras. Jika tidak, perangkat lunaknya akan diterapkan. Di bawah ini adalah daftar tag tertentu yang alokasinya mungkin tidak jelas:
- Tag::ALGORITHM , Tag::KEY_SIZE , dan Tag::RSA_PUBLIC_EXPONENT adalah properti intrinsik dari kunci tersebut. Untuk kunci apa pun yang diamankan oleh perangkat keras, tag ini akan ada dalam daftar yang didukung perangkat keras.
- Tag::Nilai DIGEST yang didukung oleh perangkat keras aman ditempatkan dalam daftar yang didukung perangkat keras. Intisari yang tidak didukung masuk dalam daftar yang didukung perangkat lunak.
- Tag::Nilai PADDING umumnya masuk dalam daftar yang didukung perangkat keras, kecuali ada kemungkinan bahwa mode padding tertentu harus dilakukan oleh perangkat lunak. Dalam hal ini, mereka masuk dalam daftar yang didukung perangkat lunak. Kemungkinan seperti itu muncul untuk kunci RSA yang mengizinkan padding PSS atau OAEP dengan algoritma intisari yang tidak didukung oleh perangkat keras yang aman.
- Tag::USER_SECURE_ID dan Tag::USER_AUTH_TYPE diterapkan pada perangkat keras hanya jika autentikasi pengguna diterapkan pada perangkat keras. Untuk mencapai hal ini, kepercayaan Keymaster dan kepercayaan otentikasi yang relevan harus aman dan berbagi kunci HMAC rahasia yang digunakan untuk menandatangani dan memvalidasi token otentikasi. Lihat halaman Otentikasi untuk detailnya.
- Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME , dan Tag ::USAGE_EXPIRE_DATETIME memerlukan akses ke jam dinding yang benar dan dapat diverifikasi. Sebagian besar perangkat keras yang aman hanya memiliki akses ke informasi waktu yang disediakan oleh OS yang tidak aman, yang berarti tag tersebut diterapkan oleh perangkat lunak.
- Tag::ORIGIN selalu ada dalam daftar perangkat keras untuk kunci yang terikat perangkat keras. Kehadirannya dalam daftar tersebut adalah cara lapisan yang lebih tinggi menentukan bahwa suatu kunci didukung oleh perangkat keras.
kunci impor
Versi : 1, 2, 3
Fungsi ini diperkenalkan di Keymaster 1 sebagai import_key
dan diganti namanya di Keymaster 3.
Mengimpor material utama ke perangkat keras Keymaster. Parameter definisi kunci dan karakteristik keluaran ditangani sama seperti untuk generateKey
, dengan pengecualian berikut:
- Tag::KEY_SIZE dan Tag::RSA_PUBLIC_EXPONENT (hanya untuk kunci RSA) tidak diperlukan dalam parameter input. Jika tidak disediakan, trustlet menyimpulkan nilai dari materi kunci yang disediakan dan menambahkan tag dan nilai yang sesuai ke karakteristik kunci. Jika parameter disediakan, trustlet memvalidasinya terhadap material utama. Jika terjadi ketidakcocokan, metode akan mengembalikan
ErrorCode::IMPORT_PARAMETER_MISMATCH
. - Tag::ORIGIN yang dikembalikan memiliki nilai yang sama dengan
KeyOrigin::IMPORTED
.
eksporKey
Versi : 1, 2, 3
Fungsi ini diperkenalkan di Keymaster 1 export_key
dan diganti namanya di Keymaster 3.
Mengekspor kunci publik dari pasangan kunci Keymaster RSA atau EC.
Jika Tag::APPLICATION_ID
diberikan selama pembuatan atau impor kunci, nilai yang sama diberikan ke metode ini dalam argumen clientId
. Jika tidak, metode akan mengembalikan ErrorCode::INVALID_KEY_BLOB
. Demikian pula, jika Tag::APPLICATION_DATA
diberikan selama pembuatan atau impor, nilai yang sama 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 diterapkan oleh modul Keymaster yang memberikan resistensi rollback.
hapusSemuaKeys
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 resistensi rollback.
menghancurkanAttestationIds
Versi : 3
Metode destroyAttestationIds()
digunakan untuk menonaktifkan fitur pengesahan ID baru (opsional, namun sangat disarankan) secara permanen. Jika TEE tidak memiliki cara untuk memastikan bahwa pengesahan ID dinonaktifkan secara permanen setelah metode ini dipanggil, maka pengesahan ID tidak boleh diterapkan sama sekali, dalam hal ini metode ini tidak melakukan apa pun dan mengembalikan ErrorCode::UNIMPLEMENTED
. Jika pengesahan ID didukung, metode ini perlu diterapkan dan harus menonaktifkan secara permanen semua upaya pengesahan ID di masa mendatang. Metode ini dapat dipanggil beberapa kali. Jika pengesahan ID sudah dinonaktifkan secara permanen, metode ini tidak melakukan apa pun dan mengembalikan ErrorCode::OK
.
Satu-satunya kode kesalahan yang dapat dikembalikan oleh metode ini adalah ErrorCode::UNIMPLEMENTED
(jika pengesahan ID tidak didukung), ErrorCode:OK
, ErrorCode::KEYMASTER_NOT_CONFIGURED
atau salah satu kode kesalahan yang menunjukkan kegagalan berkomunikasi dengan perangkat keras aman.
mulai
Versi : 1, 2, 3
Memulai operasi kriptografi, menggunakan kunci yang ditentukan, untuk tujuan tertentu, dengan parameter yang ditentukan (sesuai kebutuhan), dan mengembalikan pegangan operasi yang digunakan dengan pembaruan dan penyelesaian untuk menyelesaikan operasi. Pegangan operasi juga digunakan sebagai token "tantangan" dalam operasi yang diautentikasi, dan untuk operasi tersebut disertakan dalam bidang challenge
token otentikasi.
Implementasi Keymaster mendukung setidaknya 16 operasi bersamaan. Keystore menggunakan hingga 15, menyisakan satu untuk vold yang digunakan untuk enkripsi kata sandi. Ketika Keystore memiliki 15 operasi yang sedang berlangsung ( begin
telah dipanggil, tetapi finish
atau abort
belum dipanggil) dan menerima permintaan untuk memulai operasi ke-16, ia akan memanggil abort
operasi yang paling jarang digunakan untuk mengurangi jumlah operasi aktif ke 14 sebelum panggilan begin
untuk memulai operasi yang baru diminta.
Jika Tag::APPLICATION_ID atau Tag::APPLICATION_DATA ditentukan selama pembuatan atau impor kunci, panggilan untuk begin
menyertakan tag tersebut dengan nilai awal yang ditentukan dalam argumen inParams
ke metode ini.
Penegakan otorisasi
Selama metode ini, otorisasi kunci berikut diberlakukan oleh trustlet jika penerapannya menempatkannya dalam karakteristik "ditegakkan oleh perangkat keras" dan jika operasi tersebut bukan operasi kunci publik. Operasi kunci publik, yang berarti KeyPurpose::ENCRYPT
dan KeyPurpose::VERIFY
, dengan kunci RSA atau EC, diperbolehkan untuk berhasil meskipun persyaratan otorisasi tidak terpenuhi.
- Tag::PURPOSE : Tujuan yang ditentukan dalam panggilan
begin()
harus sesuai dengan salah satu tujuan dalam otorisasi kunci, kecuali operasi yang diminta adalah operasi kunci publik. Jika tujuan yang ditentukan tidak cocok dan operasi tersebut bukan operasi kunci publik,begin
akan mengembalikanErrorCode::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 mengembalikan
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
atauKeyPurpose::SIGN
, metode akan mengembalikanErrorCode::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
atauKeyPurpose::VERIFY
, metode akan mengembalikanErrorCode::KEY_EXPIRED
. - Tag::MIN_SECONDS_BETWEEN_OPS dibandingkan dengan pengatur waktu relatif tepercaya yang menunjukkan penggunaan kunci terakhir. Jika waktu penggunaan terakhir ditambah nilai tag kurang dari waktu saat ini, metode akan mengembalikan
ErrorCode::KEY_RATE_LIMIT_EXCEEDED
. Lihat deskripsi tag untuk detail penerapan yang penting. - Tag::MAX_USES_PER_BOOT dibandingkan dengan penghitung aman yang melacak penggunaan kunci sejak waktu boot. Jika jumlah penggunaan sebelumnya melebihi nilai tag, metode akan mengembalikan
ErrorCode::KEY_MAX_OPS_EXCEEDED
. - Tag::USER_SECURE_ID diterapkan dengan metode ini hanya jika kunci juga memiliki Tag::AUTH_TIMEOUT . Jika kuncinya memiliki keduanya, maka metode ini harus menerima Tag::AUTH_TOKEN yang valid di
inParams
. Agar token autentikasi valid, semua hal berikut harus benar:- Bidang HMAC memvalidasi dengan benar.
- Setidaknya salah satu nilai Tag::USER_SECURE_ID dari kunci cocok dengan setidaknya salah satu nilai ID aman dalam token.
- Kuncinya memiliki Tag::USER_AUTH_TYPE yang cocok dengan jenis autentikasi di token.
Jika salah satu kondisi ini tidak terpenuhi, metode akan mengembalikan
ErrorCode::KEY_USER_NOT_AUTHENTICATED
. - Tag::CALLER_NONCE memungkinkan pemanggil untuk menentukan vektor nonce atau inisialisasi (IV). Jika kunci tidak memiliki tag ini, namun pemanggil memberikan Tag::NONCE ke metode ini,
ErrorCode::CALLER_NONCE_PROHIBITED
dikembalikan. - Tag::BOOTLOADER_ONLY menetapkan bahwa hanya bootloader yang dapat menggunakan kunci tersebut. Jika metode ini dipanggil dengan kunci khusus bootloader setelah bootloader selesai dijalankan, metode ini akan mengembalikan
ErrorCode::INVALID_KEY_BLOB
.
Kunci RSA
Semua operasi kunci RSA menentukan satu mode padding di inParams
. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan mengembalikan ErrorCode::UNSUPPORTED_PADDING_MODE
.
Operasi penandatanganan dan verifikasi RSA memerlukan intisari, seperti halnya operasi enkripsi dan dekripsi RSA dengan mode padding OAEP. Untuk kasus tersebut, pemanggil menentukan tepat satu intisari di inParams
. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan mengembalikan ErrorCode::UNSUPPORTED_DIGEST
.
Operasi kunci pribadi ( KeyPurpose::DECYPT
dan KeyPurpose::SIGN
) memerlukan otorisasi intisari dan padding, yang berarti bahwa otorisasi kunci harus berisi nilai yang ditentukan. Jika tidak, metode akan mengembalikan ErrorCode::INCOMPATIBLE_DIGEST
atau ErrorCode::INCOMPATIBLE_PADDING
, sebagaimana mestinya. Operasi kunci publik ( KeyPurpose::ENCRYPT
dan KeyPurpose::VERIFY
) diizinkan dengan intisari 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 mengembalikan ErrorCode::UNSUPPORTED_PADDING_MODE
jika mode yang ditentukan tidak mendukung tujuan yang ditentukan.
Ada beberapa interaksi penting antara mode padding dan intisari:
-
PaddingMode::NONE
menunjukkan bahwa operasi RSA "mentah" dilakukan. Jika menandatangani atau memverifikasi,Digest::NONE
ditentukan untuk intisari. Tidak diperlukan intisari untuk enkripsi atau dekripsi tanpa bantalan. -
PaddingMode::RSA_PKCS1_1_5_SIGN
padding memerlukan intisari. Intisarinya mungkinDigest::NONE
, dalam hal ini implementasi Keymaster tidak dapat membangun struktur tanda tangan PKCS#1 v1.5 yang tepat, karena tidak dapat menambahkan struktur DigestInfo. Sebaliknya, implementasinya membangun0x00 || 0x01 || PS || 0x00 || M
, dimana M adalah pesan yang diberikan dan PS adalah string padding. Ukuran kunci RSA harus setidaknya 11 byte lebih besar dari pesan, jika tidak, metode akan mengembalikanErrorCode::INVALID_INPUT_LENGTH
. -
PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT
padding tidak memerlukan intisari. -
PaddingMode::RSA_PSS
padding memerlukan intisari, yang mungkin bukanDigest::NONE
. JikaDigest::NONE
ditentukan, metode akan mengembalikanErrorCode::INCOMPATIBLE_DIGEST
. Selain itu, ukuran kunci RSA harus setidaknya 2 + D byte lebih besar dari ukuran keluaran intisari, dengan D adalah ukuran intisari, dalam byte. Jika tidak, metode akan mengembalikanErrorCode::INCOMPATIBLE_DIGEST
. Ukuran garamnya adalah D. -
PaddingMode::RSA_OAEP
padding memerlukan intisari, yang mungkin bukanDigest::NONE
. JikaDigest::NONE
ditentukan, metode akan mengembalikanErrorCode::INCOMPATIBLE_DIGEST
.
kunci EC
Operasi kunci EC menentukan satu mode padding di inParams
. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan mengembalikan ErrorCode::UNSUPPORTED_PADDING_MODE
.
Operasi kunci privat ( KeyPurpose::SIGN
) memerlukan otorisasi intisari dan padding, yang berarti otorisasi kunci harus berisi nilai yang ditentukan. Jika tidak, kembalikan ErrorCode::INCOMPATIBLE_DIGEST
. Operasi kunci publik ( KeyPurpose::VERIFY
) diizinkan dengan intisari 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, kembalikan ErrorCode::UNSUPPORTED_BLOCK_MODE
atau ErrorCode::UNSUPPORTED_PADDING_MODE
. Mode yang ditentukan harus diotorisasi oleh kunci, jika tidak, metode akan mengembalikan 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, kembalikan ErrorCode::UNSUPPORTED_MAC_LENGTH
. Untuk nilai yang kurang dari panjang minimum kunci, kembalikan 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
, modenya mungkin PaddingMode::NONE
atau PaddingMode::PKCS7
. Jika mode padding tidak memenuhi ketentuan ini, kembalikan ErrorCode::INCOMPATIBLE_PADDING_MODE
.
Jika mode bloknya adalah BlockMode::CBC
, BlockMode::CTR
, atau BlockMode::GCM
, diperlukan vektor inisialisasi atau nonce. Dalam kebanyakan kasus, penelepon tidak boleh memberikan infus atau nonce. Dalam hal ini, implementasi Keymaster menghasilkan IV atau nonce acak dan mengembalikannya melalui Tag::NONCE di outParams
. CBC dan CTR IV berukuran 16 byte. Nonce GCM berukuran 12 byte. Jika otorisasi kunci berisi Tag::CALLER_NONCE , maka pemanggil dapat memberikan IV/nonce dengan Tag::NONCE di inParams
. Jika nonce diberikan ketika Tag::CALLER_NONCE tidak diotorisasi, kembalikan 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 intisari atau kurang dari nilai Tag::MIN_MAC_LENGTH
dalam otorisasi kunci. Untuk panjang MAC yang lebih besar dari panjang intisari atau bukan kelipatan 8, kembalikan ErrorCode::UNSUPPORTED_MAC_LENGTH
. Untuk nilai yang kurang dari panjang minimum kunci, kembalikan ErrorCode::INVALID_MAC_LENGTH
.
memperbarui
Versi : 1, 2, 3
Menyediakan data untuk diproses dalam operasi berkelanjutan yang dimulai dengan start . Operasi ditentukan oleh parameter operationHandle
.
Untuk memberikan lebih banyak fleksibilitas dalam penanganan buffer, penerapan metode ini memiliki opsi untuk mengonsumsi lebih sedikit data daripada yang disediakan. Penelepon bertanggung jawab melakukan perulangan untuk memasukkan sisa data pada panggilan berikutnya. Jumlah input yang dikonsumsi dikembalikan dalam parameter inputConsumed
. Implementasi selalu menggunakan setidaknya satu byte, kecuali operasi tidak dapat menerima byte lagi; jika lebih dari nol byte disediakan dan nol byte dikonsumsi, penelepon menganggap ini sebagai kesalahan dan membatalkan operasi.
Implementasi juga dapat memilih berapa banyak data yang akan dikembalikan, sebagai hasil dari pembaruan. Ini hanya relevan untuk operasi enkripsi dan dekripsi, karena penandatanganan dan verifikasi tidak mengembalikan data hingga selesai . Kembalikan data sedini mungkin, daripada melakukan buffering.
Penanganan kesalahan
Jika metode ini mengembalikan kode kesalahan selain ErrorCode::OK
, operasi dibatalkan dan pegangan operasi menjadi tidak valid. Setiap penggunaan pegangan di masa depan, dengan metode ini, finish , atau abort , akan mengembalikan ErrorCode::INVALID_OPERATION_HANDLE
.
Penegakan otorisasi
Penegakan otorisasi kunci dilakukan terutama di start . Satu-satunya pengecualian adalah ketika kuncinya memiliki:
- Satu atau lebih Tag::USER_SECURE_IDs , dan
- Tidak memiliki Tag::AUTH_TIMEOUT
Dalam hal ini, kunci memerlukan otorisasi per operasi, dan metode pembaruan menerima Tag::AUTH_TOKEN dalam argumen inParams
. HMAC memverifikasi bahwa token tersebut valid dan berisi ID pengguna aman yang cocok, cocok dengan Tag::USER_AUTH_TYPE kunci, dan berisi pegangan operasi dari operasi saat ini di bidang tantangan. Jika ketentuan ini tidak terpenuhi, kembalikan ErrorCode::KEY_USER_NOT_AUTHENTICATED
.
Penelepon memberikan token otentikasi untuk setiap panggilan untuk memperbarui dan menyelesaikan . Implementasinya 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 pembaruan. Ini mungkin tidak hanya menghabiskan sebagian dari blok. Namun, jika pemanggil memilih untuk memberikan data dalam beberapa pembaruan, metode ini menerimanya. Jika pemanggil memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan (panjang data melebihi ukuran kunci RSA), kembalikan 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 pembaruan. Metode ini mungkin tidak hanya menghabiskan sebagian blok saja.
Namun, jika pemanggil memilih untuk memberikan data dalam beberapa pembaruan, metode ini menerimanya. Jika penelepon memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan, data tersebut akan terpotong secara diam-diam. (Ini berbeda dengan penanganan kelebihan data yang disediakan 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) namun selalu mendahului data untuk dienkripsi atau didekripsi. Panggilan pembaruan mungkin menerima data terkait dan data untuk dienkripsi/dekripsi, namun pembaruan berikutnya mungkin tidak menyertakan data terkait. Jika penelepon memberikan data terkait ke panggilan pembaruan setelah panggilan yang menyertakan data untuk dienkripsi/didekripsi, kembalikan ErrorCode::INVALID_TAG
.
Untuk enkripsi GCM, tag ditambahkan ke ciphertext dengan finish . Selama dekripsi, Tag::MAC_LENGTH
byte terakhir dari data yang disediakan untuk panggilan pembaruan terakhir adalah tag. Karena pemanggilan update tertentu tidak dapat mengetahui apakah itu pemanggilan terakhir, maka pemanggilan tersebut memproses semuanya kecuali panjang tag dan menyangga data tag yang mungkin selama finish .
menyelesaikan
Versi : 1, 2, 3
Menyelesaikan operasi yang sedang berlangsung yang dimulai dengan Begin , memproses semua data yang belum diproses yang disediakan oleh pembaruan .
Metode ini adalah yang terakhir dipanggil dalam suatu operasi, sehingga semua data yang diproses dikembalikan.
Baik berhasil menyelesaikan atau mengembalikan kesalahan, metode ini menyelesaikan operasi dan karenanya membatalkan pegangan operasi yang disediakan. Penggunaan pegangan di masa depan, dengan metode ini atau pembaruan atau dibatalkan , mengembalikan ErrorCode::INVALID_OPERATION_HANDLE
.
Operasi penandatanganan mengembalikan tanda tangan sebagai output. Operasi verifikasi menerima tanda tangan dalam parameter signature
, dan tidak mengembalikan output.
Penegakan otorisasi
Penegakan otorisasi utama dilakukan terutama pada awal . Satu -satunya pengecualian adalah kasus di mana kunci memiliki:
- Satu atau lebih tag :: user_secure_ids , dan
- Tidak memiliki tag :: auth_timeout
Dalam hal ini, kunci membutuhkan otorisasi per operasi, dan metode pembaruan menerima tag :: auth_token dalam argumen inParams
. HMAC memverifikasi bahwa token itu valid dan berisi ID pengguna yang aman yang cocok, cocok dengan tag kunci :: user_auth_type , dan berisi pegangan operasi operasi saat ini di bidang tantangan. Jika kondisi ini tidak terpenuhi, kembalikan ErrorCode::KEY_USER_NOT_AUTHENTICATED
.
Penelepon memberikan token otentikasi untuk setiap panggilan untuk memperbarui dan menyelesaikan . Implementasi hanya perlu memvalidasi token sekali jika lebih suka.
Kunci RSA
Beberapa persyaratan tambahan, tergantung pada mode padding:
-
PaddingMode::NONE
. Untuk operasi penandatanganan dan enkripsi yang tidak diadkripsi, jika data yang disediakan lebih pendek dari kunci, data menjadi nol-empuk di sebelah kiri sebelum penandatanganan/enkripsi. Jika data memiliki panjang yang sama dengan kunci, tetapi secara numerik lebih besar, kembalikanErrorCode::INVALID_ARGUMENT
. Untuk operasi verifikasi dan dekripsi, data harus persis selama kunci. Jika tidak, returnErrorCode::INVALID_INPUT_LENGTH.
-
PaddingMode::RSA_PSS
. Untuk operasi tanda tangan yang padat PSS, garam PSS adalah ukuran dari pesan pencernaan dan dihasilkan secara acak. Pencernaan yang ditentukan dengan TAG :: Digest ininputParams
on Begin digunakan sebagai algoritma PSS Digest, dan sebagai algoritma MGF1 Digest. -
PaddingMode::RSA_OAEP
. Pencernaan yang ditentukan dengan TAG :: Digest ininputParams
On Begin digunakan sebagai algoritma OAEP Digest, dan SHA1 digunakan sebagai algoritma MGF1 Digest.
Kunci ecdsa
Jika data yang disediakan untuk penandatanganan atau verifikasi yang tidak diwadai terlalu panjang, terpotong.
kunci AES
Beberapa kondisi tambahan, tergantung pada mode blok:
-
BlockMode::ECB
atauBlockMode::CBC
. Jika padding adalahPaddingMode::NONE
dan panjang data bukan kelipatan dari ukuran blok AES, returnErrorCode::INVALID_INPUT_LENGTH
. Jika padding adalahPaddingMode::PKCS7
, pad data per spesifikasi PKCS#7. Perhatikan bahwa PKCS#7 merekomendasikan untuk menambahkan blok padding tambahan jika data adalah kelipatan panjang blok. -
BlockMode::GCM
. Selama enkripsi, setelah memproses semua plaintext, hitung tag ( tag :: mac_length byte) dan menambahkannya ke ciphertext yang dikembalikan. Selama dekripsi, proses tag terakhir :: mac_length byte sebagai tag. Jika verifikasi tag gagal, kembalikanErrorCode::VERIFICATION_FAILED
.
menggugurkan
Versi : 1, 2, 3
Membatalkan operasi yang sedang berlangsung. Setelah panggilan untuk dibatalkan, return ErrorCode::INVALID_OPERATION_HANDLE
untuk setiap penggunaan selanjutnya dari pegangan operasi yang disediakan dengan pembaruan , finish , atau abort .
get_supported_algorithms
Versi 1
Mengembalikan daftar algoritma yang didukung oleh implementasi perangkat keras Keymaster. Implementasi perangkat lunak mengembalikan daftar kosong; Implementasi hibrida mengembalikan daftar yang hanya berisi algoritma yang didukung oleh perangkat keras.
Implementasi KeyMaster 1 mendukung RSA, EC, AES dan HMAC.
get_supported_block_modes
Versi 1
Mengembalikan daftar mode blok AES yang didukung oleh implementasi perangkat keras KeyMaster untuk algoritma dan tujuan tertentu.
Untuk RSA, EC dan HMAC, yang tidak memblokir sandi, metode ini mengembalikan daftar kosong untuk semua tujuan yang valid. Tujuan tidak valid harus menyebabkan metode mengembalikan ErrorCode::INVALID_PURPOSE
.
Implementasi KeyMaster 1 mendukung ECB, CBC, CTR dan GCM untuk enkripsi dan dekripsi AES.
get_supported_padding_modes
Versi 1
Mengembalikan daftar mode padding yang didukung oleh implementasi perangkat keras KeyMaster untuk algoritma dan tujuan tertentu.
HMAC dan EC tidak memiliki gagasan tentang padding sehingga metode ini mengembalikan daftar kosong untuk semua tujuan yang valid. Tujuan tidak valid harus menyebabkan metode mengembalikan ErrorCode::INVALID_PURPOSE
.
Untuk RSA, Dukungan Implementasi Keyymaster 1:
- Enkripsi, dekripsi, penandatanganan, dan verifikasi yang tidak disetujui. Untuk enkripsi dan penandatanganan yang tidak disusun, jika pesannya lebih pendek dari modulus publik, implementasi harus menumpuknya dengan nol. Untuk dekripsi dan verifikasi yang tidak disusun, panjang input harus sesuai dengan ukuran modulus publik.
- PKCS#1 V1.5 Mode Enkripsi dan Penandatanganan Padding
- PSS dengan panjang garam minimum 20
- OAEP
Untuk AES dalam mode ECB dan CBC, implementasi KeyMaster 1 tidak mendukung padding dan PKCS#7-Padding. Mode CTR dan GCM hanya mendukung tidak ada padding.
get_supported_digests
Versi 1
Mengembalikan daftar mode Digest yang didukung oleh implementasi perangkat keras KeyMaster untuk algoritma dan tujuan tertentu.
Tidak ada mode AES mendukung atau memerlukan pencernaan, sehingga metode ini mengembalikan daftar kosong untuk tujuan yang valid.
Implementasi KeyMaster 1 dapat mengimplementasikan subset dari pencernaan yang ditentukan. Implementasi menyediakan SHA-256 dan dapat menyediakan MD5, SHA1, SHA-224, SHA-256, SHA384 dan SHA512 (set lengkap pencernaan yang ditentukan).
get_supported_import_formats
Versi 1
Mengembalikan daftar format impor yang didukung oleh implementasi perangkat keras Keymaster dari algoritma yang ditentukan.
Implementasi KeyMaster 1 mendukung format PKCS#8 (tanpa perlindungan kata sandi) untuk mengimpor pasangan kunci RSA dan EC, dan mendukung impor mentah AES dan materi kunci HMAC.
get_supported_export_formats
Versi 1
Mengembalikan daftar format ekspor yang didukung oleh implementasi perangkat keras 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 Sejarah
Keymaster 0
Fungsi -fungsi berikut termasuk dalam definisi KeyMaster 0 asli. Mereka hadir di Keymaster 1 struct keymaster1_device_t. Namun, di Keymaster 1.0 mereka tidak diimplementasikan, dan pointer fungsi mereka diatur ke nol.
-
generate_keypair
-
import_keypair
-
get_keypair_public
-
delete_keypair
-
delete_all
-
sign_data
-
Verify_data
Keymaster 1
Fungsi -fungsi berikut termasuk dalam definisi Keymaster 1, tetapi dihilangkan dalam Keymaster 2, bersama dengan fungsi Keyymaster 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 -fungsi berikut termasuk dalam definisi Keymaster 2, tetapi dihilangkan dalam Keymaster 3, bersama dengan fungsi Keyymaster 1 yang tercantum di atas.
-
configure