keymaster2_device Referensi Struktur

Membatalkan operasi kriptografi yang dimulai dengan Begin() , membebaskan semua sumber daya internal dan membuat operation_handle tidak valid.

Definisi pada baris 415 file keymaster2.h .

Menambahkan entropi ke RNG yang digunakan oleh keymaster. Entropi yang ditambahkan melalui metode ini dijamin bukan satu-satunya sumber entropi yang digunakan, dan fungsi pencampuran harus aman, dalam artian jika RNG diunggulkan (dari sumber mana pun) dengan data apa pun, penyerang tidak dapat memprediksi (atau kontrol), maka keluaran RNG tidak dapat dibedakan dari acak. Jadi, jika entropi dari sumber mana pun bagus, maka outputnya juga bagus.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	data	Data acak untuk dicampur.
[di dalam]	data_panjang	Panjang data .

Definisi pada baris 74 file keymaster2.h .

Menghasilkan rantai sertifikat X.509 bertanda tangan yang membuktikan keberadaan key_to_attest di keymaster (TODO(swillden): Jelaskan konten sertifikat secara lebih rinci). Sertifikat akan berisi ekstensi dengan OID 1.3.6.1.4.1.11129.2.1.17 dan nilai yang ditentukan dalam <TODO:swillden – insert link here> yang berisi deskripsi kunci.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	kunci_untuk_membuktikan	Kunci keymaster yang sertifikat pengesahannya akan dibuat.
[di dalam]	membuktikan_params	Parameter yang menentukan cara melakukan pengesahan. Saat ini satu-satunya parameter adalah KM_TAG_ALGORITHM, yang harus berupa KM_ALGORITHM_EC atau KM_ALGORITHM_RSA. Tindakan ini memilih kunci pengesahan yang tersedia yang mana yang akan digunakan untuk menandatangani sertifikat.
[keluar]	rantai_sertifikat	Serangkaian sertifikat X.509 berkode DER. Yang pertama adalah sertifikat untuk key_to_attest . Entri yang tersisa akan dirangkai kembali ke root. Penelepon mengambil kepemilikan dan harus membatalkan alokasi dengan keymaster_free_cert_chain.

Definisi pada baris 239 file keymaster2.h .

Memulai operasi kriptografi menggunakan kunci yang ditentukan. Jika semuanya baik-baik saja, Begin() akan mengembalikan KM_ERROR_OK dan membuat pegangan operasi yang harus diteruskan ke panggilan berikutnya ke update() , finish() atau abort() .

Setiap panggilan ke Begin() harus dipasangkan dengan panggilan berikutnya ke finish() atau abort() , agar penerapan keymaster dapat membersihkan status operasi internal apa pun. Kegagalan untuk melakukan hal ini dapat membocorkan ruang status internal atau sumber daya internal lainnya dan pada akhirnya dapat menyebabkan start() mengembalikan KM_ERROR_TOO_MANY_OPERATIONS ketika kehabisan ruang untuk operasi. Hasil apa pun selain KM_ERROR_OK dari Begin() , update() atau finish() secara implisit membatalkan operasi, dalam hal ini abort() tidak perlu dipanggil (dan akan mengembalikan KM_ERROR_INVALID_OPERATION_HANDLE jika dipanggil).

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	tujuan	Tujuan operasi, salah satu dari KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN atau KM_PURPOSE_VERIFY. Perhatikan bahwa untuk mode AEAD, enkripsi dan dekripsi masing-masing berarti penandatanganan dan verifikasi, tetapi harus ditentukan sebagai KM_PURPOSE_ENCRYPT dan KM_PURPOSE_DECRYPT.
[di dalam]	kunci	Kunci yang akan digunakan untuk operasi. key harus memiliki tujuan yang sesuai dengan purpose dan semua persyaratan penggunaannya harus dipenuhi, atau mulai() akan mengembalikan kode kesalahan yang sesuai.
[di dalam]	di_params	Parameter tambahan untuk operasi. Ini biasanya digunakan untuk menyediakan data autentikasi, dengan KM_TAG_AUTH_TOKEN. Jika KM_TAG_APPLICATION_ID atau KM_TAG_APPLICATION_DATA diberikan selama pembuatan, maka harus diberikan di sini, atau operasi akan gagal dengan KM_ERROR_INVALID_KEY_BLOB. Untuk operasi yang memerlukan nonce atau IV, pada kunci yang dihasilkan dengan KM_TAG_CALLER_NONCE, in_params mungkin berisi tag KM_TAG_NONCE.
[keluar]	keluar_params	Parameter keluaran. Digunakan untuk mengembalikan data tambahan dari inisialisasi operasi, terutama untuk mengembalikan IV atau nonce dari operasi yang menghasilkan IV atau nonce. Penelepon mengambil kepemilikan array parameter keluaran dan harus membebaskannya dengan keymaster_free_param_set() . out_params dapat disetel ke NULL jika tidak ada parameter keluaran yang diharapkan. Jika out_params adalah NULL, dan parameter keluaran dihasilkan, start() akan mengembalikan KM_ERROR_OUTPUT_PARAMETER_NULL.
[keluar]	pegangan_operasi	Pegangan operasi yang baru dibuat yang harus diteruskan ke update() , finish() atau abort() . Jika Operation_handle adalah NULL, Begin() akan mengembalikan KM_ERROR_OUTPUT_PARAMETER_NULL.

Definisi pada baris 332 file keymaster2.h .

Metode umum perangkat keymaster. Ini harus menjadi anggota pertama keymaster_device karena pengguna struktur ini akan melemparkan hw_device_t ke penunjuk keymaster_device dalam konteks yang diketahui bahwa hw_device_t merujuk pada keymaster_device.

Definisi pada baris 35 file keymaster2.h .

Mengonfigurasi keymaster. Metode ini harus 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 akan mengembalikan KM_ERROR_OK, tetapi tidak melakukan apa pun.

Jika implementasi keymaster berada di perangkat keras yang 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 semuanya metode lain akan terus mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Definisi pada baris 58 file keymaster2.h .

Definisi pada baris 37 file keymaster2.h .

Menghapus semua kunci di keystore perangkat keras. Digunakan saat keystore direset sepenuhnya. Setelah memanggil fungsi ini, tidak mungkin menggunakan blob kunci yang dibuat atau diimpor sebelumnya untuk operasi apa pun.

Fungsi ini bersifat opsional dan harus disetel ke NULL jika tidak diterapkan.

Parameter

[di dalam]

dev

Struktur perangkat keymaster.

Definisi pada baris 288 file keymaster2.h .

Menghapus kunci, atau pasangan kunci, yang terkait dengan blob kunci. Setelah memanggil fungsi ini, kunci tersebut tidak dapat digunakan untuk operasi lainnya. Dapat diterapkan pada kunci dari akar kepercayaan asing (kunci tidak dapat digunakan berdasarkan akar kepercayaan saat ini).

Fungsi ini bersifat opsional dan harus disetel ke NULL jika tidak diterapkan.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	kunci	Kunci yang akan dihapus.

Definisi pada baris 276 file keymaster2.h .

Mengekspor kunci publik atau kunci simetris, mengembalikan array byte dalam format yang ditentukan.

Perhatikan bahwa ekspor kunci simetris hanya diperbolehkan jika kunci dibuat dengan KM_TAG_EXPORTABLE, dan hanya jika semua persyaratan untuk penggunaan kunci (misalnya autentikasi) terpenuhi.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	ekspor_format	Format yang akan digunakan untuk mengekspor kunci.
[di dalam]	kunci_untuk_ekspor	Kuncinya adalah mengekspor.
[di dalam]	id_klien	Blob ID klien, yang harus cocok dengan blob yang disediakan di KM_TAG_APPLICATION_ID selama pembuatan kunci (jika ada).
[di dalam]	data aplikasi	Blob data aplikasi, yang harus cocok dengan blob yang disediakan di KM_TAG_APPLICATION_DATA selama pembuatan kunci (jika ada).
[keluar]	ekspor_data	Bahan utama yang diekspor. Penelepon mengambil alih kepemilikan.

Definisi pada baris 213 file keymaster2.h .

Menyelesaikan operasi kriptografi yang dimulai dengan Begin() dan membatalkan validasi operation_handle .

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	pegangan_operasi	Pegangan operasi dikembalikan oleh Begin() . Pegangan ini akan menjadi tidak valid.
[di dalam]	di_params	Parameter tambahan untuk operasi. Untuk mode AEAD, ini digunakan untuk menentukan KM_TAG_ADDITIONAL_DATA, namun hanya jika tidak ada data masukan yang diberikan ke update() .
[di dalam]	memasukkan	Data yang akan diproses, sesuai parameter yang ditetapkan dalam panggilan ke Begin() . finish() harus menggunakan semua data yang disediakan atau mengembalikan KM_ERROR_INVALID_INPUT_LENGTH.
[di dalam]	tanda tangan	Tanda tangan yang akan diverifikasi jika tujuan yang ditentukan dalam panggilan start() adalah KM_PURPOSE_VERIFY.
[keluar]	keluaran	Data keluaran, jika ada. Penelepon mengambil alih kepemilikan buffer yang dialokasikan.

Jika operasi yang diselesaikan adalah verifikasi tanda tangan atau dekripsi dan verifikasi mode AEAD gagal, maka finish() akan mengembalikan KM_ERROR_VERIFICATION_FAILED.

Definisi pada baris 405 file keymaster2.h .

Lihat tanda yang ditentukan untuk keymaster0_devices::flags di keymaster_common.h . Hanya digunakan untuk kompatibilitas ke belakang; perangkat keras keymaster2 harus menyetel ini ke nol.

Definisi pada baris 43 file keymaster2.h .

Menghasilkan kunci, atau pasangan kunci, mengembalikan blob kunci dan/atau deskripsi kunci.

Parameter pembuatan kunci didefinisikan sebagai pasangan tag/nilai keymaster, yang disediakan di params . Lihat keymaster_tag_t untuk daftar lengkapnya. Beberapa nilai yang selalu diperlukan untuk menghasilkan kunci yang berguna adalah:

• KM_TAG_ALGORITMA;
• KM_TAG_TUJUAN; Dan
• (KM_TAG_USER_SECURE_ID dan KM_TAG_USER_AUTH_TYPE) atau KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT umumnya harus ditentukan kecuali KM_TAG_NO_AUTH_REQUIRED ada, atau pengguna harus mengautentikasi untuk setiap penggunaan.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH dan KM_TAG_DIGEST harus ditentukan untuk algoritma yang memerlukannya.

Tag berikut mungkin tidak ditentukan; nilai-nilai mereka akan diberikan oleh implementasi.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	param	Array param pembangkitan kunci
[keluar]	kunci_blob	mengembalikan kunci yang dihasilkan. key_blob tidak boleh NULL. Penelepon mengambil kepemilikan key_blob->key_material dan harus membebaskan() itu.
[keluar]	karakteristik	mengembalikan karakteristik kunci yang dihasilkan, jika bukan NULL. Jika non-NULL, pemanggil mengambil alih kepemilikan dan harus membatalkan alokasi dengan keymaster_free_characteristics() . Perhatikan bahwa KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah dikembalikan.

Definisi pada baris 112 file keymaster2.h .

Mengembalikan karakteristik kunci yang ditentukan, atau KM_ERROR_INVALID_KEY_BLOB jika key_blob tidak valid (implementasi harus memvalidasi integritas kunci sepenuhnya). client_id dan app_data harus berupa ID dan data yang diberikan saat kunci dibuat atau diimpor, atau kosong jika KM_TAG_APPLICATION_ID dan/atau KM_TAG_APPLICATION_DATA tidak diberikan selama pembuatan. Nilai-nilai tersebut tidak termasuk dalam karakteristik yang dikembalikan. Penelepon mengambil alih kepemilikan objek karakteristik yang dialokasikan, yang harus dibatalkan alokasinya dengan keymaster_free_characteristics() .

Perhatikan bahwa KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah dikembalikan.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	kunci_blob	Kunci untuk mengambil karakteristik dari.
[di dalam]	id_klien	Data ID klien, atau NULL jika tidak ada yang terkait.
[di dalam]	app_id	Data aplikasi, atau NULL jika tidak ada yang terkait.
[keluar]	karakteristik	Karakteristik utama. Tidak boleh NULL. Penelepon mengambil alih kepemilikan konten dan harus membatalkan alokasi dengan keymaster_free_characteristics() .

Definisi pada baris 139 file keymaster2.h .

Mengimpor kunci, atau pasangan kunci, yang mengembalikan blob kunci dan/atau deskripsi kunci.

Sebagian besar parameter impor kunci didefinisikan sebagai pasangan tag/nilai keymaster, yang disediakan dalam "params". Lihat keymaster_tag_t untuk daftar lengkapnya. Nilai yang selalu diperlukan untuk mengimpor kunci yang berguna adalah:

• KM_TAG_ALGORITMA;
• KM_TAG_TUJUAN; Dan
• (KM_TAG_USER_SECURE_ID dan KM_TAG_USER_AUTH_TYPE) atau KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT umumnya harus ditentukan. Jika tidak ditentukan, pengguna harus mengautentikasi untuk setiap penggunaan.

Tag berikut akan mengambil nilai default jika tidak ditentukan:

• KM_TAG_KEY_SIZE akan default ke ukuran kunci yang disediakan.
• KM_TAG_RSA_PUBLIC_EXPONENT akan default ke nilai dalam kunci yang disediakan (untuk kunci RSA)

Tag berikut mungkin tidak ditentukan; nilai-nilai mereka akan diberikan oleh implementasi.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	param	Parameter yang menentukan kunci yang diimpor.
[di dalam]	params_count	Jumlah entri dalam params .
[di dalam]	format_kunci	menentukan format data kunci di key_data.
[keluar]	kunci_blob	Digunakan untuk mengembalikan gumpalan kunci buram. Harus bukan NULL. Penelepon mengambil alih kepemilikan key_material yang terkandung.
[keluar]	karakteristik	Digunakan untuk mengembalikan karakteristik kunci yang diimpor. Mungkin NULL, dalam hal ini tidak ada karakteristik yang akan dikembalikan. Jika non-NULL, pemanggil mengambil alih kepemilikan konten dan harus membatalkan alokasi dengan keymaster_free_characteristics() . Perhatikan bahwa KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah dikembalikan.

Definisi pada baris 186 file keymaster2.h .

Menyediakan data ke, dan mungkin menerima keluaran dari, operasi kriptografi berkelanjutan yang dimulai dengan Begin() .

Jika operasi_handle tidak valid, update() akan mengembalikan KM_ERROR_INVALID_OPERATION_HANDLE.

update() mungkin tidak menggunakan semua data yang disediakan di buffer data. update() akan mengembalikan jumlah yang dikonsumsi dalam *data_consumed. Penelepon harus memberikan data yang tidak terpakai pada panggilan berikutnya.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	pegangan_operasi	Pegangan operasi dikembalikan oleh Begin() .
[di dalam]	di_params	Parameter tambahan untuk operasi. Untuk mode AEAD, ini digunakan untuk menentukan KM_TAG_ADDITIONAL_DATA. Perhatikan bahwa data tambahan mungkin diberikan dalam beberapa panggilan ke update() , namun hanya sampai data masukan telah diberikan.
[di dalam]	memasukkan	Data yang akan diproses, sesuai parameter yang ditetapkan dalam panggilan ke Begin() . Perhatikan bahwa update() mungkin menggunakan atau tidak menggunakan semua data yang disediakan. Lihat input_consumed .
[keluar]	masukan_dikonsumsi	Jumlah data yang dikonsumsi oleh update() . Jika jumlahnya kurang dari jumlah yang diberikan, pemanggil harus memberikan sisanya pada panggilan berikutnya ke update() .
[keluar]	keluar_params	Parameter keluaran. Digunakan untuk mengembalikan data tambahan dari operasi Penelepon mengambil kepemilikan array parameter output dan harus membebaskannya dengan keymaster_free_param_set() . out_params dapat disetel ke NULL jika tidak ada parameter keluaran yang diharapkan. Jika out_params adalah NULL, dan parameter keluaran dihasilkan, start() akan mengembalikan KM_ERROR_OUTPUT_PARAMETER_NULL.
[keluar]	keluaran	Data keluaran, jika ada. Penelepon mengambil alih kepemilikan buffer yang dialokasikan. keluaran tidak boleh NULL.

Perhatikan bahwa update() mungkin tidak memberikan output apa pun, dalam hal ini output->data_length akan menjadi nol, dan output->data dapat berupa NULL atau nol-panjang (jadi pemanggil harus selalu free() itu).

Definisi pada baris 376 file keymaster2.h .

Meningkatkan kunci lama. Kunci bisa menjadi "lama" dengan dua cara: Keymaster dapat ditingkatkan ke versi baru, atau sistem dapat diperbarui untuk membatalkan versi OS dan/atau tingkat patch. Dalam kedua kasus tersebut, upaya untuk menggunakan kunci lama akan mengakibatkan keymaster mengembalikan KM_ERROR_KEY_REQUIRES_UPGRADE. Metode ini kemudian harus dipanggil untuk mengupgrade kunci.

Parameter

[di dalam]	dev	Struktur perangkat keymaster.
[di dalam]	kunci_untuk_meningkatkan	Kunci keymaster untuk meningkatkan.
[di dalam]	tingkatkan_params	Parameter yang diperlukan untuk menyelesaikan peningkatan. Secara khusus, KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA akan diperlukan jika ditentukan untuk kunci.
[keluar]	kunci_yang ditingkatkan	Blob kunci yang ditingkatkan.

Definisi pada baris 260 file keymaster2.h .