Fungsi Keymaster

Halaman ini memberikan detail untuk membantu pelaksana Keymaster Hardware Abstraction Layers (HALs). Ini mencakup setiap fungsi di API dan versi Keymaster mana fungsi itu tersedia dan menjelaskan implementasi default. Untuk tag, lihat halaman Tag Keymaster .

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

Pedoman implementasi 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 menyediakan placeholder. Misalnya, beberapa jenis dan mode kunci mungkin tidak menggunakan nilai apa pun dari argumen inParams untuk memulai , sehingga pemanggil dapat menyetel inParams ke NULL atau memberikan set parameter kosong. Penelepon juga dapat memberikan parameter yang tidak digunakan, dan metode Keymaster tidak boleh mengeluarkan kesalahan.

Jika parameter input yang diperlukan adalah NULL, metode Keymaster harus mengembalikan ErrorCode::UNEXPECTED_NULL_POINTER .

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

Parameter penunjuk keluaran

Versi : 1, 2

Mirip dengan parameter pointer input, parameter pointer output yang tidak digunakan mungkin NULL . Jika suatu metode perlu mengembalikan data dalam parameter keluaran yang ditemukan NULL , itu harus mengembalikan ErrorCode::OUTPUT_PARAMETER_NULL .

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

Penyalahgunaan API

Versi : 1, 2, 3

Ada banyak cara penelepon dapat membuat permintaan yang tidak masuk akal atau bodoh tetapi tidak salah secara teknis. Implementasi keymaster tidak diharuskan untuk gagal dalam kasus seperti itu atau mengeluarkan diagnostik. Penggunaan kunci yang terlalu kecil, spesifikasi parameter input yang tidak relevan, penggunaan kembali infus atau nonces, 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.

Ini adalah tanggung jawab aplikasi, kerangka kerja, dan keystore Android untuk memastikan bahwa panggilan ke modul Keymaster masuk akal dan berguna.

Perhatian: Implementasi Keymaster harus berusaha untuk mendiagnosis kesalahan serius, seperti penghilangan parameter yang diperlukan, spesifikasi parameter yang diperlukan tidak valid, dan kesalahan serupa yang membahayakan integritas implementasi Keymaster.

Fungsi

getHardwareFeatures

Versi : 3

Metode getHardwareFeatures yang baru memaparkan kepada klien beberapa karakteristik penting dari perangkat keras aman yang mendasarinya. Metode ini tidak mengambil argumen dan mengembalikan empat nilai, semua boolean:

• isSecure true jika kunci disimpan dalam perangkat keras yang aman (TEE, dll.) dan tidak pernah meninggalkannya.
• supportsEllipticCurve true jika perangkat keras mendukung kriptografi Kurva Elliptik 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 untuk berkomunikasi dengan perangkat keras yang 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 master kunci. Metode ini dipanggil sekali setelah perangkat dibuka dan sebelum digunakan. Ini digunakan untuk memberikan KM_TAG_OS_VERSION dan KM_TAG_OS_PATCHLEVEL ke keymaster. Sampai metode ini dipanggil, semua metode lain mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED . Nilai yang diberikan oleh metode ini hanya diterima oleh keymaster satu kali per boot. Panggilan berikutnya mengembalikan KM_ERROR_OK , tetapi tidak melakukan apa pun.

Jika implementasi keymaster dalam 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 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);

tambahkanRngEntropi

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, infus, dll.

Implementasi keymaster perlu secara aman mencampur entropi yang disediakan ke dalam kumpulannya, yang juga harus berisi entropi yang dihasilkan secara internal dari generator nomor acak perangkat keras. Pencampuran harus ditangani sehingga penyerang yang memiliki kendali penuh atas bit yang addRngEntropy atau bit yang dihasilkan perangkat keras, tetapi 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 mengasumsikan bahwa data yang disediakan oleh addRngEntropy tidak berisi entropi. Implementasi keymaster dapat mengembalikan ErrorCode::INVALID_INPUT_LENGTH jika diberikan lebih dari 2 KiB data dalam satu panggilan.

menghasilkanKunci

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. Implementasi keymaster tidak memungkinkan untuk menggunakan kunci dengan cara apa pun yang tidak konsisten dengan otorisasi yang ditentukan pada waktu pembuatan. Sehubungan dengan otorisasi yang tidak dapat diterapkan oleh perangkat keras yang aman, kewajiban perangkat keras yang aman terbatas untuk memastikan bahwa otorisasi yang tidak dapat diterapkan yang terkait dengan kunci tersebut tidak dapat dimodifikasi, sehingga setiap panggilan ke getKeyCharacteristics mengembalikan nilai aslinya. Selain itu, karakteristik yang dikembalikan oleh generateKey mengalokasikan otorisasi dengan benar antara daftar yang didukung perangkat keras dan 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::ALGORITHM 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 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 mengembalikan ErrorCode::INVALID_ARGUMENT . Nilai yang didukung adalah 3 dan 65537. Nilai yang disarankan adalah semua nilai prima hingga 2^64.

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

• Tag::PURPOSE menentukan tujuan yang diizinkan. Semua tujuan perlu didukung untuk kunci RSA, dalam kombinasi apa pun.
• Tag::DIGEST menentukan algoritme intisari yang dapat digunakan dengan kunci baru. Implementasi yang tidak mendukung semua algoritme intisari harus menerima permintaan pembuatan kunci yang menyertakan intisari yang tidak didukung. Intisari yang tidak didukung harus ditempatkan dalam daftar "didukung perangkat lunak" dalam karakteristik kunci yang dikembalikan. Ini karena kuncinya dapat digunakan dengan intisari lainnya, tetapi mencerna 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 algoritme intisari perlu menempatkan PaddingMode::RSA_PSS dan PaddingMode::RSA_OAEP dalam daftar karakteristik kunci yang didukung perangkat lunak jika ada algoritme intisari yang tidak didukung ditentukan.

Kunci ECDSA

Hanya Tag::KEY_SIZE yang diperlukan untuk membuat kunci ECDSA. 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 membuat kunci AES. Jika dihilangkan, metode mengembalikan 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 untuk membuatnya:

• Tag::BLOCK_MODE menentukan mode blok yang dengannya kunci baru dapat digunakan.
• 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 adalah kelipatan 8 dan minimal 64.
• Tag::DIGEST menentukan algoritme intisari untuk kunci. Tepat satu intisari ditentukan, jika tidak, kembalikan ErrorCode::UNSUPPORTED_DIGEST . Jika intisari tidak didukung oleh trustlet, kembalikan ErrorCode::UNSUPPORTED_DIGEST .

Karakteristik utama

Jika argumen karakteristik adalah non-NULL, generateKey mengembalikan karakteristik kunci yang baru dibuat yang dibagi dengan tepat ke dalam daftar yang didukung perangkat keras dan 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 tidak mungkin menemukan nilainya dengan memeriksa gumpalan kunci yang dikembalikan. Namun, mereka terikat secara kriptografis ke gumpalan 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 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,

Tag::ROLLBACK_RESISTANT .

Resistensi rollback

Resistensi rollback berarti bahwa setelah kunci dihapus dengan deleteKey atau deleteAllKeys , dijamin oleh perangkat keras yang aman tidak akan dapat digunakan lagi. Implementasi tanpa resistensi rollback biasanya mengembalikan materi kunci yang dihasilkan atau diimpor ke pemanggil sebagai gumpalan kunci, bentuk terenkripsi dan diautentikasi. Saat keystore menghapus gumpalan kunci, kuncinya hilang, tetapi penyerang yang sebelumnya berhasil mengambil materi kunci berpotensi mengembalikannya ke perangkat.

Kunci tahan rollback jika perangkat keras yang aman menjamin bahwa kunci yang dihapus tidak dapat dipulihkan nanti. Ini umumnya dilakukan dengan menyimpan metadata kunci tambahan di lokasi tepercaya yang tidak dapat dimanipulasi oleh penyerang. Pada perangkat seluler, mekanisme yang digunakan untuk ini biasanya adalah Replay Protected Memory Blocks (RPMB). Karena jumlah kunci yang dapat dibuat pada dasarnya tidak terbatas dan penyimpanan tepercaya yang digunakan untuk resistensi rollback mungkin terbatas ukurannya, metode ini perlu berhasil bahkan jika resistensi rollback tidak dapat disediakan untuk kunci baru. Dalam hal ini, Tag::ROLLBACK_RESISTANT tidak boleh ditambahkan ke karakteristik kunci.

getKeyKarakteristik

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 disediakan, dibagi menjadi dua set: perangkat keras dan 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 untuk 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 untuk metode ini dalam argumen appData .

Karakteristik yang dikembalikan oleh metode ini sepenuhnya menggambarkan jenis dan penggunaan kunci yang ditentukan.

Aturan umum untuk memutuskan apakah tag yang diberikan termasuk dalam daftar yang didukung perangkat keras atau perangkat lunak adalah bahwa jika arti dari tag tersebut sepenuhnya dijamin oleh perangkat keras yang aman, itu adalah perangkat keras yang ditegakkan. Jika tidak, itu adalah perangkat lunak yang diberlakukan. 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. Untuk kunci apa pun yang diamankan oleh perangkat keras, tag ini akan ada dalam daftar yang didukung perangkat keras.
• Nilai Tag::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.
• Nilai Tag::PADDING umumnya masuk dalam daftar yang didukung perangkat keras, kecuali jika ada kemungkinan 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 algoritme intisari yang tidak didukung oleh perangkat keras yang aman.
• Tag::USER_SECURE_ID dan Tag::USER_AUTH_TYPE didukung oleh perangkat keras hanya jika autentikasi pengguna diterapkan oleh perangkat keras. Untuk mencapai hal ini, trustlet Keymaster dan trustlet otentikasi yang relevan keduanya 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 Tag memerlukan akses ke jam dinding yang benar-benar benar. Sebagian besar perangkat keras yang aman hanya memiliki akses ke informasi waktu yang disediakan oleh OS yang tidak aman, yang berarti bahwa tag tersebut diberlakukan oleh perangkat lunak.
• Tag::ORIGIN selalu ada dalam daftar perangkat keras untuk kunci yang terikat perangkat keras. Kehadirannya dalam daftar itu 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 materi kunci 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 materi utama. Jika terjadi ketidakcocokan, metode mengembalikan ErrorCode::IMPORT_PARAMETER_MISMATCH .
• Tag::ORIGIN yang dikembalikan memiliki nilai yang sama dengan KeyOrigin::IMPORTED .

eksporKunci

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 atau impor kunci, nilai yang sama diberikan untuk 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 untuk metode ini dalam argumen appData .

hapusKey

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 opsional, dan hanya diimplementasikan 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 opsional, dan hanya diimplementasikan oleh modul Keymaster yang memberikan resistensi rollback.

hancurkan AttestationIds

Versi : 3

Metode destroyAttestationIds() digunakan untuk menonaktifkan fitur pengesahan ID baru (opsional, tetapi sangat disarankan) 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 mengembalikan ErrorCode::UNIMPLEMENTED . Jika pengesahan ID didukung, metode ini perlu diterapkan dan harus secara permanen menonaktifkan semua upaya pengesahan ID di masa mendatang. Metode dapat dipanggil beberapa kali. Jika pengesahan ID sudah dinonaktifkan secara permanen, metode 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 untuk berkomunikasi dengan perangkat keras yang aman.

mulai

Versi : 1, 2, 3

Memulai operasi kriptografi, menggunakan kunci yang ditentukan, untuk tujuan yang ditentukan, dengan parameter yang ditentukan (yang sesuai), 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 termasuk dalam bidang challenge dari token otentikasi.

Implementasi Keymaster mendukung setidaknya 16 operasi bersamaan. Keystore menggunakan hingga 15, menyisakan satu untuk vold digunakan untuk enkripsi kata sandi. Ketika Keystore memiliki 15 operasi yang sedang begin (start telah dipanggil, tetapi finish atau abort belum dipanggil) dan menerima permintaan untuk memulai tanggal 16, ia memanggil abort pada operasi yang paling jarang digunakan untuk mengurangi jumlah operasi aktif ke 14 sebelum menelepon begin 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 yang ditentukan semula dalam argumen inParams ke metode ini.

penegakan otorisasi

Selama metode ini, otorisasi kunci berikut ini diberlakukan oleh trustlet jika implementasi menempatkannya dalam karakteristik "berlaku perangkat keras" dan jika operasi tersebut bukan operasi kunci publik. Operasi kunci publik, artinya 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 mengembalikan 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 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 atau KeyPurpose::SIGN , metode mengembalikan 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 mengembalikan ErrorCode::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 implementasi 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 oleh metode ini hanya jika kuncinya juga memiliki Tag::AUTH_TIMEOUT . Jika kunci memiliki keduanya, maka metode ini harus menerima Tag::AUTH_TOKEN yang valid di inParams . Agar token auth valid, semua hal berikut harus benar:
  • Bidang HMAC memvalidasi dengan benar.
  • Setidaknya satu dari 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 dalam token.

  Jika salah satu dari 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, tetapi 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 tepat satu mode padding di inParams . Jika tidak ditentukan atau ditentukan lebih dari sekali, metode ini 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 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 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 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 ada intisari yang diperlukan untuk enkripsi atau dekripsi yang tidak diisi.
• PaddingMode::RSA_PKCS1_1_5_SIGN padding membutuhkan intisari. Intisari mungkin Digest::NONE , dalam hal ini implementasi Keymaster tidak dapat membangun struktur tanda tangan PKCS#1 v1.5 yang tepat, karena tidak dapat menambahkan struktur DigestInfo. Sebagai gantinya, implementasi membangun 0x00 || 0x01 || PS || 0x00 || M , di mana M adalah pesan yang disediakan dan PS adalah string padding. Ukuran kunci RSA harus setidaknya 11 byte lebih besar dari pesan, jika tidak, metode akan mengembalikan ErrorCode::INVALID_INPUT_LENGTH .
• PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding tidak memerlukan intisari.
• PaddingMode::RSA_PSS padding membutuhkan intisari, yang mungkin bukan Digest::NONE . Jika Digest::NONE ditentukan, metode mengembalikan ErrorCode::INCOMPATIBLE_DIGEST . Selain itu, ukuran kunci RSA harus setidaknya 2 + D byte lebih besar dari ukuran keluaran intisari, di mana D adalah ukuran intisari, dalam byte. Jika tidak, metode mengembalikan ErrorCode::INCOMPATIBLE_DIGEST . Ukuran garam D
• PaddingMode::RSA_OAEP padding membutuhkan intisari, yang mungkin bukan Digest::NONE . Jika Digest::NONE ditentukan, metode mengembalikan ErrorCode::INCOMPATIBLE_DIGEST .

kunci EC

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

Operasi kunci pribadi ( KeyPurpose::SIGN ) memerlukan otorisasi intisari dan padding, yang berarti bahwa 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 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 blok 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 adalah 16 byte. Nonce GCM adalah 12 byte. Jika otorisasi kunci berisi Tag::CALLER_NONCE , maka pemanggil dapat memberikan IV/nonce dengan Tag::NONCE di inParams . Jika nonce diberikan saat 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 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 yang sedang berlangsung dimulai dengan mulai . Operasi ditentukan oleh parameter operationHandle .

Untuk memberikan lebih banyak fleksibilitas untuk penanganan buffer, implementasi metode ini memiliki opsi untuk mengkonsumsi lebih sedikit data daripada yang disediakan. Penelepon bertanggung jawab untuk mengulang untuk memberi makan sisa data dalam panggilan berikutnya. Jumlah input yang dikonsumsi dikembalikan dalam parameter inputConsumed . Implementasi selalu menggunakan setidaknya satu byte, kecuali jika operasi tidak dapat menerima lagi; jika lebih dari nol byte disediakan dan nol byte dikonsumsi, pemanggil 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 buffer.

Penanganan kesalahan

Jika metode ini mengembalikan kode kesalahan selain ErrorCode::OK , operasi dibatalkan dan pegangan operasi tidak valid. Setiap penggunaan pegangan di masa mendatang, dengan metode ini, finish , atau abort , mengembalikan ErrorCode::INVALID_OPERATION_HANDLE .

penegakan otorisasi

Penegakan otorisasi kunci dilakukan terutama di awal . Satu-satunya pengecualian adalah kasus di mana kuncinya memiliki:

• Satu atau beberapa 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 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 kondisi ini tidak terpenuhi, kembalikan ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Penelepon menyediakan token otentikasi untuk setiap panggilan untuk memperbarui dan menyelesaikan . Implementasi hanya perlu memvalidasi token sekali 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 mengkonsumsi hanya sebagian dari blok. Namun, jika penelepon memilih untuk memberikan data dalam beberapa pembaruan, metode ini menerimanya. Jika penelepon 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 dari blok.

Namun, jika penelepon memilih untuk memberikan data dalam beberapa pembaruan, metode ini menerimanya. Jika penelepon memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan, data akan terpotong secara diam-diam. (Ini berbeda dari 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) tetapi selalu mendahului data yang akan dienkripsi atau didekripsi. Panggilan pembaruan dapat menerima data dan data terkait untuk mengenkripsi/mendekripsi, tetapi 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, byte Tag::MAC_LENGTH terakhir dari data yang diberikan ke panggilan pembaruan terakhir adalah tag. Karena pemanggilan pembaruan yang diberikan tidak dapat mengetahui apakah itu pemanggilan terakhir, ia memproses semua kecuali panjang tag dan menyangga data tag yang mungkin selama finish .

menyelesaikan

Versi : 1, 2, 3

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

• One or more Tag::USER_SECURE_IDs , and
• Does not have a Tag::AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

• PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is at least 20 bytes in length and randomly generated. The salt may be longer; the reference implementation uses maximally sized salt. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest algorithm.
• PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

• BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
• BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

• Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
• PKCS#1 v1.5 encryption and signing padding modes
• PSS with a minimum salt length of 20
• OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

• configure