Referensi Struktur keymaster2_device
#include < keymaster2.h >
Detil Deskripsi
Definisi perangkat Keymaster2
Definisi pada baris 28 dari file keymaster2.h .
Dokumentasi Lapangan
| keymaster_error_t (* batalkan)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle) |
Membatalkan operasi kriptografi yang dimulai dengan begin() , membebaskan semua sumber daya internal dan membatalkan operation_handle .
Definisi pada baris 415 dari file keymaster2.h .
| keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length) |
Menambahkan entropi ke RNG yang digunakan oleh keymaster. Entropi yang ditambahkan melalui metode ini dijamin tidak menjadi satu-satunya sumber entropi yang digunakan, dan fungsi pencampuran diperlukan untuk mengamankan, dalam arti jika RNG diunggulkan (dari sumber mana pun) dengan data apa pun yang tidak dapat diprediksi oleh penyerang (atau kontrol), maka keluaran RNG tidak dapat dibedakan dari acak. Jadi, jika entropi dari sumber mana pun baik, outputnya akan baik.
- Parameter
[di] dev Struktur perangkat keymaster. [di] data Data acak untuk dicampur. [di] data_panjang Panjang data.
Definisi pada baris 74 dari file keymaster2.h .
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
Menghasilkan rantai sertifikat X.509 yang ditandatangani 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] dev Struktur perangkat keymaster. [di] key_to_attest Kunci keymaster yang sertifikat pengesahannya akan dibuat. [di] 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. Ini memilih kunci pengesahan yang disediakan yang akan digunakan untuk menandatangani sertifikat. [keluar] cert_chain Serangkaian sertifikat X.509 yang disandikan DER. Yang pertama adalah sertifikat untuk key_to_attest. Entri yang tersisa akan berantai kembali ke root. Penelepon mengambil kepemilikan dan harus membatalkan alokasi dengan keymaster_free_cert_chain.
Definisi pada baris 239 dari file keymaster2.h .
| keymaster_error_t (* begin)(const struct keymaster2_device *dev, tujuan keymaster_purpose_t , const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle |
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() .
Sangat penting bahwa setiap panggilan ke begin() dipasangkan dengan panggilan berikutnya ke finish() atau abort() , untuk memungkinkan implementasi keymaster membersihkan semua status operasi internal. Kegagalan untuk melakukan ini dapat membocorkan ruang keadaan internal atau sumber daya internal lainnya dan pada akhirnya dapat menyebabkan begin() 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] dev Struktur perangkat keymaster. [di] tujuan Tujuan operasi, salah satu KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN atau KM_PURPOSE_VERIFY. Perhatikan bahwa untuk mode AEAD, enkripsi dan dekripsi menyiratkan penandatanganan dan verifikasi, masing-masing, tetapi harus ditetapkan sebagai KM_PURPOSE_ENCRYPT dan KM_PURPOSE_DECRYPT. [di] kunci Kunci yang akan digunakan untuk operasi. keyharus memiliki tujuan yang sesuai denganpurposedan semua persyaratan penggunaannya harus dipenuhi, atau begin() akan mengembalikan kode kesalahan yang sesuai.[di] in_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, mereka harus disediakan 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. [keluar] out_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 larik 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, begin() akan mengembalikan KM_ERROR_OUTPUT_PARAMETER_NULL. [keluar] operasi_handle 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 dari file keymaster2.h .
| struct hw_device_t umum |
Metode umum perangkat keymaster. Ini harus menjadi anggota pertama dari keymaster_device karena pengguna struktur ini akan melemparkan hw_device_t ke penunjuk keymaster_device dalam konteks yang diketahui bahwa hw_device_t mereferensikan keymaster_device.
Definisi pada baris 35 dari file keymaster2.h .
| keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
Mengonfigurasi master kunci. Metode ini harus 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 akan mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED. Nilai yang diberikan oleh metode ini hanya diterima oleh keymaster satu kali per boot. Panggilan berikutnya akan mengembalikan KM_ERROR_OK, tetapi tidak melakukan apa pun.
Jika implementasi keymaster 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 metode lain akan terus mengembalikan KM_ERROR_KEYMASTER_NOT_CONFIGURED.
Definisi pada baris 58 dari file keymaster2.h .
| konteks batal* |
Definisi pada baris 37 dari file keymaster2.h .
| keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev) |
Menghapus semua kunci di keystore perangkat keras. Digunakan saat keystore direset sepenuhnya. Setelah memanggil fungsi ini, tidak mungkin menggunakan gumpalan kunci yang dibuat atau diimpor sebelumnya untuk operasi apa pun.
Fungsi ini opsional dan harus disetel ke NULL jika tidak diterapkan.
- Parameter
[di] dev Struktur perangkat keymaster.
Definisi pada baris 288 dari file keymaster2.h .
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
Menghapus kunci, atau pasangan kunci, yang terkait dengan gumpalan kunci. Setelah memanggil fungsi ini, tidak mungkin menggunakan kunci untuk operasi lain. Dapat diterapkan ke kunci dari akar kepercayaan asing (kunci tidak dapat digunakan di bawah akar kepercayaan saat ini).
Fungsi ini opsional dan harus disetel ke NULL jika tidak diterapkan.
- Parameter
[di] dev Struktur perangkat keymaster. [di] kunci Kunci yang akan dihapus.
Definisi pada baris 276 dari file keymaster2.h .
| keymaster_error_t (* export_key)(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *ekspor) |
Mengekspor kunci publik atau 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] dev Struktur perangkat keymaster. [di] ekspor_format Format yang akan digunakan untuk mengekspor kunci. [di] key_to_ekspor Kunci untuk mengekspor. [di] client_id Blob ID klien, yang harus cocok dengan blob yang disediakan di KM_TAG_APPLICATION_ID selama pembuatan kunci (jika ada). [di] 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 kunci yang diekspor. Penelepon mengambil alih kepemilikan.
Definisi pada baris 213 dari file keymaster2.h .
| keymaster_error_t (* finish)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *tanda tangan, keymaster_key_param_blob_t * output_blob_t |
Menyelesaikan operasi kriptografi yang dimulai dengan begin() dan membatalkan operation_handle .
- Parameter
[di] dev Struktur perangkat keymaster. [di] operasi_handle Pegangan operasi dikembalikan oleh begin() . Pegangan ini akan dibatalkan. [di] 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() . [di] memasukkan Data yang akan diproses, sesuai dengan parameter yang ditetapkan dalam panggilan ke begin() . finish() harus menggunakan semua data yang disediakan atau mengembalikan KM_ERROR_INVALID_INPUT_LENGTH. [di] tanda tangan Tanda tangan yang akan diverifikasi jika tujuan yang ditentukan dalam panggilan begin() adalah KM_PURPOSE_VERIFY. [keluar] keluaran Data keluaran, jika ada. Penelepon mengasumsikan kepemilikan buffer yang dialokasikan.
Jika operasi yang sedang diselesaikan adalah verifikasi tanda tangan atau dekripsi mode AEAD dan verifikasi gagal, maka finish() akan mengembalikan KM_ERROR_VERIFICATION_FAILED.
Definisi pada baris 405 dari file keymaster2.h .
| bendera uint32_t |
Lihat flag yang ditentukan untuk keymaster0_devices::flags di keymaster_common.h . Digunakan hanya untuk kompatibilitas mundur; perangkat keras keymaster2 harus menyetel ini ke nol.
Definisi pada baris 43 dari file keymaster2.h .
| keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *karakteristik) |
Menghasilkan kunci, atau pasangan kunci, mengembalikan gumpalan kunci dan/atau deskripsi kunci.
Parameter pembuatan kunci didefinisikan sebagai pasangan tag/nilai keymaster, yang disediakan dalam params . Lihat keymaster_tag_t untuk daftar lengkapnya. Beberapa nilai yang selalu diperlukan untuk menghasilkan kunci yang berguna adalah:
- KM_TAG_ALGORITHM;
- 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 algoritme yang memerlukannya.
Tag berikut mungkin tidak ditentukan; nilai-nilai mereka akan diberikan oleh implementasi.
- KM_TAG_ASAL,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parameter
[di] dev Struktur perangkat keymaster. [di] params Array param generasi kunci [keluar] key_blob mengembalikan kunci yang dihasilkan. key_blobtidak boleh NULL. Penelepon mengasumsikan kepemilikan key_blob->key_material dan harus membebaskan() itu.[keluar] karakteristik mengembalikan karakteristik kunci yang dihasilkan, jika bukan NULL. Jika non-NULL, pemanggil mengasumsikan 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 dari file keymaster2.h .
| keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t ) *karakteristik |
Mengembalikan karakteristik kunci yang ditentukan, atau KM_ERROR_INVALID_KEY_BLOB jika key_blob tidak valid (implementasi harus sepenuhnya memvalidasi integritas kunci). 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 termasuk dalam karakteristik yang dikembalikan. Pemanggil mengasumsikan kepemilikan objek karakteristik yang dialokasikan, yang harus dialokasikan dengan keymaster_free_characteristics() .
Perhatikan bahwa KM_TAG_APPLICATION_ID dan KM_TAG_APPLICATION_DATA tidak pernah dikembalikan.
- Parameter
[di] dev Struktur perangkat keymaster. [di] key_blob Kunci untuk mengambil karakteristik dari. [di] client_id Data ID klien, atau NULL jika tidak ada yang terkait. [di] app_id Data aplikasi, atau NULL jika tidak ada yang terkait. [keluar] karakteristik Karakteristik kunci. Tidak boleh NULL. Penelepon mengasumsikan kepemilikan konten dan harus membatalkan alokasi dengan keymaster_free_characteristics() .
Definisi pada baris 139 dari file keymaster2.h .
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t |
Mengimpor kunci, atau pasangan kunci, mengembalikan gumpalan 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_ALGORITHM;
- 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_ASAL,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- Parameter
[di] dev Struktur perangkat keymaster. [di] params Parameter yang menentukan kunci yang diimpor. [di] params_count Jumlah entri dalam params.[di] format_kunci menentukan format data kunci di key_data. [keluar] key_blob Digunakan untuk mengembalikan gumpalan kunci buram. Harus bukan NULL. Penelepon mengasumsikan 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 mengasumsikan 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 dari file keymaster2.h .
| keymaster_error_t (* update)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_parabt * out_param |
Menyediakan data ke, dan mungkin menerima keluaran dari, operasi kriptografi yang sedang berlangsung dimulai dengan begin() .
Jika operation_handle tidak valid, update() akan mengembalikan KM_ERROR_INVALID_OPERATION_HANDLE.
update() mungkin tidak menggunakan semua data yang disediakan dalam buffer data. update() akan mengembalikan jumlah yang dikonsumsi dalam *data_consumed. Penelepon harus memberikan data yang tidak terpakai dalam panggilan berikutnya.
- Parameter
[di] dev Struktur perangkat keymaster. [di] operasi_handle Pegangan operasi dikembalikan oleh begin() . [di] 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 masukan telah disediakan. [di] memasukkan Data yang akan diproses, sesuai dengan parameter yang ditetapkan dalam panggilan ke begin() . Perhatikan bahwa update() mungkin atau mungkin tidak menggunakan semua data yang disediakan. Lihat input_consumed.[keluar] masukan_dikonsumsi Jumlah data yang dikonsumsi oleh update() . Jika ini kurang dari jumlah yang diberikan, pemanggil harus memberikan sisanya dalam panggilan berikutnya ke update() . [keluar] out_params Parameter keluaran. Digunakan untuk mengembalikan data tambahan dari operasi Pemanggil mengambil kepemilikan larik 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, begin() akan mengembalikan KM_ERROR_OUTPUT_PARAMETER_NULL. [keluar] keluaran Data keluaran, jika ada. Penelepon mengasumsikan 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 membebaskan() itu).
Definisi pada baris 376 dari file keymaster2.h .
| keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgrade_key) |
Upgrade kunci lama. Kunci dapat menjadi "lama" dalam 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 memutakhirkan kunci.
- Parameter
[di] dev Struktur perangkat keymaster. [di] key_to_upgrade Kunci keymaster untuk meningkatkan. [di] upgrade_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] upgrade_key Gumpalan kunci yang ditingkatkan.
Definisi pada baris 260 dari file keymaster2.h .
Dokumentasi untuk struct ini dibuat dari file berikut:
- hardware/libhardware/include/hardware/ keymaster2.h