Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Fungsi Keymaster

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 .

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

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 dan PaddingMode::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, kembalikan ErrorCode::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,

Menandai::ROLLBACK_RESISTANT .

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.

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 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 akan 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 akan 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 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 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. Sebaliknya, implementasinya membangun 0x00 || 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 mengembalikan ErrorCode::INVALID_INPUT_LENGTH .
PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding tidak memerlukan intisari.
PaddingMode::RSA_PSS padding memerlukan intisari, yang mungkin bukan Digest::NONE . Jika Digest::NONE ditentukan, metode akan mengembalikan ErrorCode::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 mengembalikan ErrorCode::INCOMPATIBLE_DIGEST . Ukuran garamnya adalah D.
PaddingMode::RSA_OAEP padding memerlukan intisari, yang mungkin bukan Digest::NONE . Jika Digest::NONE ditentukan, metode akan mengembalikan ErrorCode::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, kembalikan ErrorCode::INVALID_ARGUMENT . Untuk operasi verifikasi dan dekripsi, data harus persis selama kunci. Jika tidak, return ErrorCode::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 in inputParams on Begin digunakan sebagai algoritma PSS Digest, dan sebagai algoritma MGF1 Digest.
PaddingMode::RSA_OAEP . Pencernaan yang ditentukan dengan TAG :: Digest in inputParams 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 atau BlockMode::CBC . Jika padding adalah PaddingMode::NONE dan panjang data bukan kelipatan dari ukuran blok AES, return ErrorCode::INVALID_INPUT_LENGTH . Jika padding adalah PaddingMode::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, kembalikan ErrorCode::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