Referensi Struct keymaster2_device

Membatalkan operasi kriptografi yang dimulai dengan begin() , membebaskan semua resource internal dan membatalkan operation_handle .

Definisi di baris 415 dari 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 arti bahwa jika RNG diberi seed (dari sumber mana pun) dengan data apa pun yang tidak dapat diprediksi (atau dikontrol) oleh penyerang, output RNG tidak dapat dibedakan dari acak. Jadi, jika entropi dari sumber mana pun bagus, output-nya akan bagus.

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	data	Data acak yang akan dicampur.
[in]	data_length	Panjang data .

Definisi pada baris 74 dari file keymaster2.h .

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

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	key_to_attest	Kunci keymaster yang akan digunakan untuk membuat sertifikat pengesahan.
[in]	attest_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 akan memilih kunci pengesahan yang disediakan yang akan digunakan untuk menandatangani sertifikat.
[out]	cert_chain	Array sertifikat X.509 yang dienkode DER. Yang pertama adalah sertifikat untuk key_to_attest . Entri yang tersisa akan dihubungkan kembali ke root. Pemanggil mengambil kepemilikan dan harus membatalkan alokasi dengan keymaster_free_cert_chain.

Definisi pada baris 239 dari file keymaster2.h .

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

Setiap panggilan ke begin() harus disambungkan dengan panggilan berikutnya ke finish() atau abort() , untuk memungkinkan implementasi keymaster membersihkan status operasi internal apa pun. Kegagalan untuk melakukannya dapat menyebabkan kebocoran ruang status internal atau resource internal lainnya dan pada akhirnya dapat menyebabkan begin() menampilkan KM_ERROR_TOO_MANY_OPERATIONS saat kehabisan ruang untuk operasi. Hasil apa pun selain KM_ERROR_OK dari begin() , update() atau finish() secara implisit akan membatalkan operasi, dalam hal ini abort() tidak perlu dipanggil (dan akan menampilkan KM_ERROR_INVALID_OPERATION_HANDLE jika dipanggil).

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	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 menyiratkan penandatanganan dan verifikasi, tetapi harus ditentukan sebagai KM_PURPOSE_ENCRYPT dan KM_PURPOSE_DECRYPT.
[in]	key	Kunci yang akan digunakan untuk operasi. key harus memiliki tujuan yang kompatibel dengan purpose dan semua persyaratan penggunaannya harus terpenuhi, atau begin() akan menampilkan kode error yang sesuai.
[in]	in_params	Parameter tambahan untuk operasi. Ini biasanya digunakan untuk memberikan data autentikasi, dengan KM_TAG_AUTH_TOKEN. Jika KM_TAG_APPLICATION_ID atau KM_TAG_APPLICATION_DATA diberikan selama pembuatan, keduanya harus diberikan di sini, atau operasi akan gagal dengan KM_ERROR_INVALID_KEY_BLOB. Untuk operasi yang memerlukan nonce atau IV, pada kunci yang dibuat dengan KM_TAG_CALLER_NONCE, in_params dapat berisi tag KM_TAG_NONCE.
[out]	out_params	Parameter output. Digunakan untuk menampilkan data tambahan dari inisialisasi operasi, terutama untuk menampilkan IV atau nonce dari operasi yang menghasilkan IV atau nonce. Pemanggil mengambil kepemilikan array parameter output dan harus membebaskannya dengan keymaster_free_param_set() . out_params dapat disetel ke NULL jika tidak ada parameter output yang diharapkan. Jika out_params adalah NULL, dan parameter output dihasilkan, begin() akan menampilkan KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	Handle operasi yang baru dibuat yang harus diteruskan ke update() , finish() atau abort() . Jika operation_handle adalah NULL, begin() akan menampilkan KM_ERROR_OUTPUT_PARAMETER_NULL.

Definisi di baris 332 dari file keymaster2.h .

Metode umum perangkat keymaster. Ini harus menjadi anggota pertama keymaster_device karena pengguna struktur ini akan mentransmisikan hw_device_t ke pointer keymaster_device dalam konteks yang diketahui bahwa hw_device_t mereferensikan keymaster_device.

Definisi di baris 35 dari file keymaster2.h .

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

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

Definisi di baris 58 dari file keymaster2.h .

Definisi pada baris 37 dari file keymaster2.h .

Menghapus semua kunci di keystore hardware. Digunakan saat keystore direset sepenuhnya. Setelah memanggil fungsi ini, Anda tidak akan dapat menggunakan blob kunci yang dibuat atau diimpor sebelumnya untuk operasi apa pun.

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

Parameter

[in]

dev

Struktur perangkat keymaster.

Definisi di baris 288 dari file keymaster2.h .

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

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

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	key	Kunci yang akan dihapus.

Definisi di baris 276 dari file keymaster2.h .

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

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

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	export_format	Format yang akan digunakan untuk mengekspor kunci.
[in]	key_to_export	Kunci yang akan diekspor.
[in]	client_id	Blob Client ID, yang harus cocok dengan blob yang diberikan di KM_TAG_APPLICATION_ID selama pembuatan kunci (jika ada).
[in]	app_data	Blob data aplikasi, yang harus cocok dengan blob yang disediakan di KM_TAG_APPLICATION_DATA selama pembuatan kunci (jika ada).
[out]	export_data	Materi kunci yang diekspor. Pemanggil akan mengambil alih kepemilikan.

Definisi di baris 213 dari file keymaster2.h .

Menyelesaikan operasi kriptografis yang dimulai dengan begin() dan membatalkan operation_handle .

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	operation_handle	Handle operasi yang ditampilkan oleh begin() . Nama sebutan channel ini akan dibatalkan validasinya.
[in]	in_params	Parameter tambahan untuk operasi. Untuk mode AEAD, ini digunakan untuk menentukan KM_TAG_ADDITIONAL_DATA, tetapi hanya jika tidak ada data input yang diberikan ke update() .
[in]	input	Data yang akan diproses, sesuai dengan parameter yang ditetapkan dalam panggilan ke begin() . finish() harus menggunakan semua data yang diberikan atau menampilkan KM_ERROR_INVALID_INPUT_LENGTH.
[in]	tanda tangan	Tanda tangan yang akan diverifikasi jika tujuan yang ditentukan dalam panggilan begin() adalah KM_PURPOSE_VERIFY.
[out]	output	Data output, jika ada. Pemanggil mengasumsikan kepemilikan buffer yang dialokasikan.

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

Definisi di baris 405 dari file keymaster2.h .

Lihat flag yang ditentukan untuk keymaster0_devices::flags di keymaster_common.h . Hanya digunakan untuk kompatibilitas mundur; perangkat hardware keymaster2 harus menetapkannya ke nol.

Definisi di baris 43 dari file keymaster2.h .

Menghasilkan kunci, atau pasangan kunci, yang menampilkan blob kunci dan/atau deskripsi kunci.

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

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; 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 jika 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 tidak boleh ditentukan; nilainya akan diberikan oleh implementasi.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	params	Array parameter pembuatan kunci
[out]	key_blob	menampilkan kunci yang dihasilkan. key_blob tidak boleh NULL. Pemanggil mengasumsikan kepemilikan key_blob->key_material dan harus membebaskannya.
[out]	karakteristik	menampilkan karakteristik kunci yang dihasilkan, jika bukan NULL. Jika bukan NULL, pemanggil akan menganggap kepemilikan dan harus mengalokasikan ulang dengan keymaster_free_characteristics() . Perhatikan bahwa KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID, dan KM_TAG_APPLICATION_DATA tidak pernah ditampilkan.

Definisi di baris 112 dari file keymaster2.h .

Menampilkan 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 tersebut tidak disertakan dalam karakteristik yang ditampilkan. Pemanggil mengasumsikan kepemilikan objek karakteristik yang dialokasikan, yang harus dide-alokasikan dengan keymaster_free_characteristics() .

Perhatikan bahwa KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah ditampilkan.

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	key_blob	Kunci untuk mengambil karakteristik.
[in]	client_id	Data client ID, atau NULL jika tidak ada yang terkait.
[in]	app_id	Data aplikasi, atau NULL jika tidak ada yang terkait.
[out]	karakteristik	Karakteristik utamanya. Tidak boleh NULL. Pemanggil mengasumsikan kepemilikan konten dan harus menghapus alokasi dengan keymaster_free_characteristics() .

Definisi di baris 139 dari file keymaster2.h .

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

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

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; 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 melakukan autentikasi untuk setiap penggunaan.

Tag berikut akan menggunakan nilai default jika tidak ditentukan:

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

Tag berikut tidak boleh ditentukan; nilainya akan diberikan oleh implementasi.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	params	Parameter yang menentukan kunci yang diimpor.
[in]	params_count	Jumlah entri dalam params .
[in]	key_format	menentukan format data kunci di key_data.
[out]	key_blob	Digunakan untuk menampilkan blob kunci buram. Harus non-NULL. Pemanggil mengasumsikan kepemilikan key_material yang ada.
[out]	karakteristik	Digunakan untuk menampilkan karakteristik kunci yang diimpor. Dapat berupa NULL, dalam hal ini tidak ada karakteristik yang akan ditampilkan. Jika bukan NULL, pemanggil akan menganggap kepemilikan konten dan harus mengalokasikan ulang dengan keymaster_free_characteristics() . Perhatikan bahwa KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah ditampilkan.

Definisi di baris 186 dari file keymaster2.h .

Memberikan data ke, dan mungkin menerima output dari, operasi kriptografis yang sedang berlangsung yang dimulai dengan begin() .

Jika operation_handle tidak valid, update() akan menampilkan KM_ERROR_INVALID_OPERATION_HANDLE.

update() mungkin tidak menggunakan semua data yang disediakan dalam buffer data. update() akan menampilkan jumlah yang digunakan di *data_consumed. Pemanggil harus memberikan data yang tidak digunakan dalam panggilan berikutnya.

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	operation_handle	Handle operasi yang ditampilkan oleh begin() .
[in]	in_params	Parameter tambahan untuk operasi. Untuk mode AEAD, ini digunakan untuk menentukan KM_TAG_ADDITIONAL_DATA. Perhatikan bahwa data tambahan dapat diberikan dalam beberapa panggilan ke update() , tetapi hanya sampai data input telah diberikan.
[in]	input	Data yang akan diproses, sesuai dengan parameter yang ditetapkan dalam panggilan ke begin() . Perhatikan bahwa update() mungkin menggunakan atau tidak menggunakan semua data yang disediakan. Lihat input_consumed .
[out]	input_consumed	Jumlah data yang digunakan oleh update() . Jika kurang dari jumlah yang diberikan, pemanggil harus memberikan sisanya dalam panggilan berikutnya ke update() .
[out]	out_params	Parameter output. Digunakan untuk menampilkan data tambahan dari operasi Pemanggil mengambil kepemilikan array parameter output dan harus membebaskannya dengan keymaster_free_param_set() . out_params dapat disetel ke NULL jika tidak ada parameter output yang diharapkan. Jika out_params adalah NULL, dan parameter output dihasilkan, begin() akan menampilkan KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Data output, jika ada. Pemanggil mengasumsikan kepemilikan buffer yang dialokasikan. output tidak boleh NULL.

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

Definisi di baris 376 dari file keymaster2.h .

Mengupgrade kunci lama. Kunci dapat menjadi "lama" dengan dua cara: Keymaster dapat diupgrade ke versi baru, atau sistem dapat diupdate untuk membatalkan validasi versi OS dan/atau level patch. Dalam kedua kasus tersebut, upaya untuk menggunakan kunci lama akan menyebabkan keymaster menampilkan KM_ERROR_KEY_REQUIRES_UPGRADE. Kemudian, metode ini harus dipanggil untuk mengupgrade kunci.

Parameter

[in]	dev	Struktur perangkat keymaster.
[in]	key_to_upgrade	Kunci keymaster yang akan diupgrade.
[in]	upgrade_params	Parameter yang diperlukan untuk menyelesaikan upgrade. Secara khusus, KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA akan diperlukan jika ditentukan untuk kunci.
[out]	upgraded_key	Blob kunci yang diupgrade.

Definisi di baris 260 dari file keymaster2.h .