Fungsi Keymaster

Halaman ini memberikan detail untuk membantu pengimplementasi Keymaster {i>Hardware Abstraksi Layers<i} (HAL). Ini mencakup setiap fungsi dalam API dan versi Keymaster yang tersedia, dan menjelaskan implementasi default. Untuk tag, lihat Tag Keymaster.

Panduan penerapan umum

Panduan berikut berlaku untuk semua fungsi di API.

Parameter pointer input

Versi: 1, 2

Parameter pointer input yang tidak digunakan untuk panggilan tertentu mungkin NULL. Pemanggil tidak diwajibkan untuk menyediakan placeholder. Misalnya, beberapa jenis dan mode kunci mungkin tidak menggunakan nilai apa pun dari Argumen inParams untuk begin, sehingga pemanggil mungkin tetapkan inParams ke NULL atau berikan parameter kosong atur. Pemanggil juga bisa menyediakan parameter yang tidak digunakan, dan metode Keymaster harus tidak mengeluarkan error.

Jika parameter input yang diperlukan adalah NULL, metode Keymaster akan ditampilkan ErrorCode::UNEXPECTED_NULL_POINTER.

Mulai Keymaster 3, tidak ada parameter pointer. Semua parameter diteruskan oleh nilai atau referensi konstanta.

Parameter pointer output

Versi: 1, 2

Serupa dengan parameter pointer input, parameter pointer output yang tidak digunakan mungkin NULL. Jika suatu metode perlu menampilkan data dalam output yang didapati adalah NULL, parameter tersebut akan ditampilkan ErrorCode::OUTPUT_PARAMETER_NULL.

Mulai Keymaster 3, tidak ada parameter pointer. Semua parameter diteruskan oleh nilai atau referensi konstanta.

Penyalahgunaan API

Versi: 1, 2, 3

Ada banyak cara yang dapat digunakan pemanggil untuk membuat permintaan yang tidak masuk akal atau bodoh tetapi secara teknis tidak salah. Implementasi Keymaster tidak gagal dalam kasus tersebut atau mengeluarkan diagnostik. Penggunaan tombol yang terlalu kecil, spesifikasi parameter {i>input <i}yang tidak relevan, penggunaan kembali IV atau {i>nonce<i}, pembuatan kunci tanpa tujuan (karenanya tidak berguna) dan sejenisnya tidak boleh yang didiagnosis oleh implementasi. Tidak mencantumkan parameter yang diperlukan, spesifikasi parameter wajib tidak valid, dan error serupa harus didiagnosis.

Aplikasi, framework, dan keystore Android bertanggung jawab untuk memastikan bahwa panggilan ke modul Keymaster masuk akal dan berguna.

Fungsi

getHardwareFeatures

Versi: 3

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

• isSecure adalah true jika kunci disimpan di perangkat keras yang aman (TEE, dll.) dan tidak pernah meninggalkannya.
• supportsEllipticCurve adalah true jika perangkat keras mendukung kriptografi Kurva Elliptik dengan kurva NIST (P-224, P-256, P-384, dan P-521).
• supportsSymmetricCryptography adalah true apakah perangkat keras tersebut mendukung kriptografi simetris, termasuk AES dan HMAC.
• supportsAttestation adalah true jika yang mendukung pembuatan sertifikat pengesahan kunci publik Keymaster, ditandatangani dengan kunci yang dimasukkan dalam lingkungan aman.

Satu-satunya kode error yang mungkin ditampilkan oleh metode ini adalah ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED atau salah satu kode error menunjukkan kegagalan untuk berkomunikasi dengan perangkat keras yang aman.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

atur

Versi: 2

Fungsi ini diperkenalkan di Keymaster 2 dan tidak digunakan lagi di Keymaster 3, karena informasi ini tersedia di file properti sistem, dan produsen implementasi membaca file tersebut selama {i>startup<i}.

Mengonfigurasi keymaster. Metode ini dipanggil sekali setelah perangkat dibuka dan sebelum digunakan. Ini digunakan untuk memberikan KM_TAG_OS_VERSION dan KM_TAG_OS_PATCHLEVEL ke {i>keymaster<i}. Sampai metode ini dipanggil, semua metode lainnya akan ditampilkan KM_ERROR_KEYMASTER_NOT_CONFIGURED. Nilai yang diberikan oleh hanya diterima oleh keymaster satu kali per booting. Setelah panggilan akan menampilkan KM_ERROR_OK, tetapi tidak melakukan apa pun.

Jika implementasi {i>keymaster<i} dilakukan pada perangkat keras dan versi OS yang aman, serta nilai level patch yang diberikan tidak cocok dengan nilai yang diberikan ke hardware oleh bootloader (atau jika bootloader tidak memberikan nilai), metode ini akan menampilkan KM_ERROR_INVALID_ARGUMENT, dan semua akan terus menampilkan KM_ERROR_KEYMASTER_NOT_CONFIGURED.

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai add_rng_entropy dan diganti namanya di Keymaster 3.

Menambahkan entropi yang disediakan pemanggil ke kumpulan yang digunakan oleh implementasi Keymaster 1 untuk menghasilkan angka acak, untuk kunci, IV, dll.

Implementasi Keymaster harus secara aman mencampur elemen nilai entropi ke dalam kumpulannya, yang juga harus berisi entropi yang dihasilkan secara internal dari generator angka acak perangkat keras. Pencampuran harus ditangani sehingga penyerang yang memiliki kendali penuh baik dari bit yang disediakan oleh addRngEntropy atau buatan hardware bit, tetapi tidak keduanya, tidak memiliki keuntungan yang tidak dapat diabaikan dalam memprediksi bit yang dihasilkan dari kumpulan entropi.

implementasi Keymaster yang mencoba memperkirakan entropi kumpulan internal mengasumsikan bahwa data yang disediakan oleh addRngEntropy tidak memiliki entropi. Implementasi Keymaster mungkin tampilkan ErrorCode::INVALID_INPUT_LENGTH jika diberi lebih dari 2 KiB data dalam satu panggilan.

generateKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai generate_key dan diganti namanya di Keymaster 3.

Menghasilkan kunci kriptografis baru, menentukan otorisasi terkait, yang terikat secara permanen dengan kunci. Implementasi Keymaster tidak mungkin menggunakan kunci dengan cara apa pun yang tidak sesuai dengan otorisasi yang ditentukan pada waktu pembuatan. Sehubungan dengan otorisasi yang tidak dapat diterapkan, maka kewajiban perangkat keras yang aman terbatas pada memastikan bahwa otorisasi tak berkekuatan yang terkait dengan kunci tidak dapat dimodifikasi, sehingga setiap panggilan ke getKeyCharacteristics menampilkan nilai aslinya. Selain itu, karakteristik yang dikembalikan oleh generateKey mengalokasikan otorisasi dengan benar di antara daftar yang didukung perangkat keras dan perangkat lunak. Lihat getKeyCharacteristics untuk detail selengkapnya.

Parameter yang diberikan ke generateKey bergantung pada jenis kunci data yang dihasilkan. Bagian ini merangkum tag yang diperlukan dan opsional untuk setiap jenis kunci. Tag::ALGORITHM selalu diperlukan, untuk menentukan jenis.

Kunci RSA

Parameter berikut diperlukan untuk membuat kunci RSA.

• Tag::KEY_SIZE menentukan ukuran modulus publik, dalam bit. Jika dihilangkan, metode ini akan menampilkan ErrorCode::UNSUPPORTED_KEY_SIZE. Nilai yang didukung adalah 1024, 2048, 3072, dan 4096. Nilai yang direkomendasikan semua ukuran kunci yang merupakan kelipatan 8.
• Tag::RSA_PUBLIC_EXPONENT menentukan nilai eksponen publik RSA. Jika dihilangkan, metode akan menampilkan ErrorCode::INVALID_ARGUMENT. Nilai yang didukung adalah 3 dan 65537. Nilai yang direkomendasikan adalah semua nilai prima sampai 2^64.

Parameter berikut tidak diperlukan untuk membuat kunci RSA, tetapi membuat kunci RSA tanpa mereka akan menghasilkan kunci yang tidak dapat digunakan. Namun, Fungsi generateKey tidak akan menampilkan error jika parameter ini dihilangkan.

• Tag::PURPOSE menentukan tujuan yang diizinkan. Semua tujuan harus didukung untuk kunci RSA, di kombinasi apa pun.
• Tag::DIGEST menentukan {i>digest<i} yang dapat digunakan dengan kunci baru tersebut. Implementasi yang tidak mendukung semua algoritma digest harus menerima pembuatan kunci permintaan yang menyertakan ringkasan yang tidak didukung. Ringkasan yang tidak didukung harus ditempatkan dalam model "didorong oleh software" daftar karakteristik utama yang ditampilkan. Hal ini karena kunci dapat digunakan dengan ringkasan lain, tetapi mencerna adalah berjalan dalam software. 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 {i>digest <i}perlu menempatkan PaddingMode::RSA_PSS dan PaddingMode::RSA_OAEP inci daftar karakteristik utama yang diberlakukan oleh software jika ditentukan oleh algoritma digest.

Kunci ECDSA

Hanya Tag::KEY_SIZE yang yang diperlukan untuk membuat kunci ECDSA. Ini digunakan untuk memilih grup EC. Nilai yang didukung adalah 224, 256, 384 dan 521, yang menunjukkan Kurva NIST p-224, p-256, p-384, dan p521.

Tag::DIGEST juga diperlukan agar kunci ECDSA berguna, tetapi tidak diwajibkan untuk pembuatan.

Kunci AES

Hanya Tag::KEY_SIZE diperlukan untuk membuat 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, tetapi tidak yang diperlukan untuk membuatnya:

• Tag::BLOCK_MODE menentukan mode blok yang digunakan kunci baru dapat digunakan.
• Tag::PADDING menentukan mode padding yang mungkin data Ini hanya relevan untuk mode ECB dan CBC.

Jika mode blok GCM ditetapkan, maka sediakan Tag::MIN_MAC_LENGTH. Jika dihilangkan, metode akan menampilkan ErrorCode::MISSING_MIN_MAC_LENGTH. Nilai tag adalah kelipatan 8 dan antara 96 hingga 128.

Kunci HMAC

Parameter berikut diperlukan untuk pembuatan kunci HMAC:

• Tag::KEY_SIZE menentukan ukuran kunci dalam bit. Nilai yang lebih kecil dari 64 dan nilai yang bukan kelipatan 8 tidak didukung. Semua kelipatan 8, dari 64 hingga 512, didukung. Nilai yang lebih besar mungkin didukung.
• Tag::MIN_MAC_LENGTH menentukan panjang minimum MAC yang dapat dibuat atau diverifikasi dengan kunci ini. Nilainya adalah kelipatan 8 dan minimal 64.
• Tag::DIGEST menentukan algoritma digest untuk kunci tersebut. Persis satu digest ditentukan, jika tidak, tampilkan ErrorCode::UNSUPPORTED_DIGEST. Jika ringkasan tidak didukung oleh trustlet, kembali ErrorCode::UNSUPPORTED_DIGEST.

Karakteristik utama

Jika argumen karakteristik adalah non-NULL, generateKey akan menampilkan karakteristik kunci yang baru dibuat terbagi dengan tepat menjadi daftar yang didukung perangkat keras dan perangkat lunak. Lihat getKeyCharacteristics untuk deskripsi karakteristik apa yang masuk daftarnya. Karakteristik yang dikembalikan menyertakan semua parameter yang ditentukan untuk pembuatan kunci, kecuali Tag::APPLICATION_ID dan Tag::APPLICATION_DATA. Jika tag ini disertakan dalam parameter kunci, tag tersebut akan dihapus dari karakteristik yang dikembalikan, sehingga tidak mungkin untuk menemukan nilainya dengan memeriksa blob kunci yang ditampilkan. Namun, mereka terikat secara kriptografis, ke blob kunci, sehingga jika nilai yang benar tidak diberikan saat kunci digunakan, maka penggunaan gagal. Demikian pula, Tag::ROOT_OF_TRUST adalah terikat secara kriptografis ke kunci, tetapi mungkin tidak ditentukan selama pembuatan atau impor kunci dan tidak pernah ditampilkan.

Selain tag yang disediakan, trustlet juga menambahkan Tag::Origin, dengan nilai KeyOrigin::GENERATED, dan jika kunci itu tahan terhadap rollback,

Ketahanan rollback

Perlawanan {i>rollback<i} berarti bahwa setelah kunci dihapus dengan deleteKey atau deleteAllKeys, hal ini dijamin oleh hardware yang aman tidak akan pernah dapat digunakan lagi. Implementasi tanpa ketahanan rollback biasanya menampilkan materi kunci yang dibuat atau diimpor ke pemanggil sebagai blob kunci, yang terenkripsi dan diotentikasi. Saat keystore menghapus blob kunci, kuncinya akan hilang, tetapi penyerang yang sebelumnya berhasil mengambil materi kunci yang berpotensi memulihkannya ke perangkat.

Kunci bersifat tahan terhadap rollback jika hardware aman menjamin bahwa kunci dihapus kunci tidak dapat dipulihkan nanti. Hal ini umumnya dilakukan dengan menyimpan kunci tambahan {i>metadata<i} di lokasi tepercaya yang tidak dapat dimanipulasi oleh penyerang. Aktif perangkat seluler, mekanisme yang digunakan untuk ini biasanya adalah {i>Replay Protected Memory<i} Pemblokiran (RPMB). Karena jumlah kunci yang mungkin dibuat pada dasarnya adalah tidak terbatas dan penyimpanan tepercaya yang digunakan untuk ketahanan rollback mungkin terbatas yang besar, metode ini harus berhasil bahkan jika ketahanan rollback tidak dapat diberikan untuk kunci baru. Dalam kasus tersebut, Tag::ROLLBACK_RESISTANT tidak boleh ditambahkan ke dalam karakteristik utama.

getKeyCharacteristics

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai get_key_characteristics dan diganti namanya di Keymaster 3.

Menampilkan parameter dan otorisasi yang terkait dengan kunci yang diberikan, dibagi menjadi dua set: perangkat keras dan ditegakkan menggunakan perangkat lunak. Deskripsi di sini berlaku juga untuk daftar karakteristik utama yang ditampilkan oleh generateKey dan importKey.

Jika Tag::APPLICATION_ID diberikan selama pembuatan kunci atau impor, nilai yang sama diberikan untuk metode ini dalam argumen clientId. Jika tidak, akan menampilkan ErrorCode::INVALID_KEY_BLOB. Demikian pula, jika Tag::APPLICATION_DATA diberikan selama pembuatan atau impor, nilai yang sama diberikan untuk metode ini dalam argumen appData.

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

Aturan umum untuk memutuskan apakah tag tertentu termasuk dalam daftar yang didukung perangkat keras atau perangkat lunak adalah jika arti tag sepenuhnya dijamin oleh perangkat keras yang aman, perangkat keras itu ditegakkan. Jika tidak, akan software diberlakukan. Di bawah ini adalah daftar tag spesifik yang alokasinya sudah benar mungkin tidak jelas:

• Tag::ALGORITHM, Tag::KEY_SIZE, dan Tag::RSA_PUBLIC_EXPONENT adalah properti intrinsik kunci. Untuk kunci apa pun yang diamankan oleh perangkat keras, tag tersebut akan berada di daftar yang didukung hardware.
• Nilai Tag::DIGEST yang didukung oleh perangkat keras aman ditempatkan di daftar perangkat keras yang didukung. Ringkasan yang tidak didukung dimasukkan dalam daftar yang didukung software.
• Nilai Tag::PADDING umumnya masuk ke daftar yang didukung perangkat keras, kecuali ada kemungkinan bahwa mode padding tertentu mungkin 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 digest yang tidak didukung oleh perangkat keras yang aman.
• Tag::USER_SECURE_ID dan Tag::USER_AUTH_TYPE ditegakkan dengan perangkat keras hanya jika otentikasi pengguna diterapkan pada perangkat keras. Kepada mencapai ini, kepercayaan Keymaster dan otentikasi yang relevan keduanya harus aman dan berbagi kunci HMAC rahasia yang digunakan untuk menandatangani dan memvalidasi token otentikasi. Lihat Authentication untuk mengetahui detailnya.
• Tag::ACTIVE_DATETIME, Tag::OriginATION_EXPIRE_DATETIME, dan tag Tag::USAGE_EXPIRE_DATETIME membutuhkan akses ke jam dinding yang benar dan dapat diverifikasi. Hardware paling aman hanya memiliki akses ke informasi waktu yang disediakan oleh OS tidak aman, yang berarti {i>tag<i} diterapkan di perangkat lunak.
• Tag::Origin adalah selalu dalam daftar perangkat keras untuk kunci yang terikat dengan perangkat keras. Kehadirannya di adalah cara lapisan yang lebih tinggi menentukan bahwa suatu kunci didukung oleh perangkat keras.

ImportKey

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai import_key dan diganti namanya di Keymaster 3.

Mengimpor materi kunci ke hardware Keymaster. Parameter definisi kunci dan karakteristik output ditangani sama seperti generateKey, dengan pengecualian berikut:

• Tag::KEY_SIZE dan Tag::RSA_PUBLIC_EXPONENT (hanya untuk kunci RSA) tidak diperlukan dalam parameter input. Jika tidak diberikan, {i>trustlet<i} menyimpulkan nilai-nilai dari materi kunci yang disediakan dan menambahkan tag dan nilai yang sesuai dengan karakteristik utama. Jika parameternya yang diberikan, trustlet memvalidasinya terhadap materi kunci. Di kolom jika ketidakcocokan ini terjadi, metode akan menampilkan ErrorCode::IMPORT_PARAMETER_MISMATCH.
• Tag::Origin yang ditampilkan memiliki nilai yang sama dengan KeyOrigin::IMPORTED.

kunciekspor

Versi: 1, 2, 3

Fungsi ini diperkenalkan di Keymaster 1 sebagai export_key dan diganti namanya di Keymaster 3.

Mengekspor kunci publik dari pasangan kunci RSA atau EC Keymaster.

Jika Tag::APPLICATION_ID diberikan selama pembuatan kunci atau nilai impor, nilai yang sama diberikan untuk metode ini dalam Argumen clientId. Jika tidak, metode akan menampilkan ErrorCode::INVALID_KEY_BLOB. Demikian pula, jika Tag::APPLICATION_DATA diberikan selama pembuatan atau impor, nilai yang sama diberikan pada metode ini dalam argumen appData.

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 yang diimplementasikan oleh modul Keymaster yang memberikan ketahanan terhadap rollback.

deleteAllKeys

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 ketahanan terhadap rollback.

menghancurkanAttestationId

Versi: 3

Metode destroyAttestationIds() digunakan untuk nonaktifkan yang baru (opsional, tetapi sangat direkomendasikan) Pengesahan tanda pengenal aplikasi baru. Jika TEE tidak memiliki cara untuk memastikan bahwa pengesahan ID secara permanen dinonaktifkan setelah metode ini dipanggil, maka pengesahan ID tidak boleh diimplementasikan sama sekali, dalam hal ini metode ini tidak melakukan apa-apa dan akan menampilkan ErrorCode::UNIMPLEMENTED. Jika pengesahan ID didukung, metode ini perlu diterapkan dan harus menonaktifkan semua upaya pengesahan ID di masa mendatang. Metode dapat disebut berapa pun jumlah kali. Jika pengesahan ID sudah dinonaktifkan secara permanen, metode ini melakukan tidak ada apa pun dan menampilkan ErrorCode::OK.

Satu-satunya kode error yang mungkin ditampilkan oleh metode ini adalah ErrorCode::UNIMPLEMENTED (jika pengesahan ID tidak didukung), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED, atau salah satu kode error yang menunjukkan kegagalan komunikasi dengan jaringan perangkat keras.

begin

Versi: 1, 2, 3

Memulai operasi kriptografi, menggunakan kunci yang ditetapkan, untuk nilai yang tujuan, dengan parameter yang ditentukan (sebagaimana diperlukan), dan menampilkan yang digunakan dengan update dan finish untuk menyelesaikan operasi. Tuas operasi adalah juga digunakan sebagai "tantangan" token tertentu dalam operasi yang diotentikasi, dan untuk operasi disertakan di kolom challenge dari kolom token otentikasi.

Implementasi Keymaster mendukung setidaknya 16 konfigurasi secara serentak operasional bisnis. Keystore menggunakan hingga 15, tersisa satu untuk vold digunakan untuk sandi enkripsi. Jika Keystore memiliki 15 operasi yang sedang berlangsung (begin telah telah dipanggil, tetapi finish atau abort belum dihubungi dipanggil) dan menerima permintaan untuk memulai tanggal 16, abort pada operasi yang terakhir digunakan untuk mengurangi jumlah operasi aktif ke 14 sebelum memanggil begin untuk memulai operasi yang baru diminta.

Jika Tag::APPLICATION_ID atau Tag::APPLICATION_DATA telah ditentukan selama pembuatan atau impor kunci, panggilan ke begin mencakup tag dengan nilai asli yang telah ditentukan dalam argumen inParams ke metode ini.

Penerapan otorisasi

Selama metode ini, otorisasi kunci berikut diberlakukan oleh tepercaya jika implementasi tersebut menempatkannya dalam karakteristik dan jika operasinya bukan merupakan operasi kunci publik. Kunci publik operasi, yang berarti KeyPurpose::ENCRYPT dan KeyPurpose::VERIFY, dengan kunci RSA atau EC, diizinkan untuk berhasil meskipun otorisasi persyaratan tidak terpenuhi.

• Tag::TUJUAN: Tujuan yang ditentukan dalam panggilan begin() harus sesuai dengan salah satu tujuan otorisasi kunci, kecuali jika operasi yang diminta adalah kunci publik operasi. Jika tujuan yang ditentukan tidak cocok dan operasi tidak operasi kunci publik, begin akan menampilkan ErrorCode::UNSUPPORTED_PURPOSE. Operasi kunci publik adalah enkripsi asimetris atau operasi verifikasi.
• Tag::ACTIVE_DATETIME hanya dapat diterapkan jika sumber waktu UTC tepercaya tersedia. Jika tanggal dan waktu saat ini sebelum nilai tag, metode ini akan menampilkan 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 menampilkan 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 menampilkan ErrorCode::KEY_EXPIRED.
• Tag::MIN_SECONDS_BETWEEN_OPS dibandingkan dengan penunjuk waktu relatif tepercaya yang menunjukkan penggunaan terakhir tombolnya. Jika waktu penggunaan terakhir ditambah nilai tag kurang dari waktu saat ini, metode ini akan menampilkan ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Lihat deskripsi tag untuk mengetahui detail implementasi penting.
• Tag::MAX_USES_PER_BOOT dibandingkan dengan penghitung aman yang melacak penggunaan kunci sejak waktu {i>booting<i}. Jika jumlah penggunaan sebelumnya melebihi nilai tag, akan menampilkan ErrorCode::KEY_MAX_OPS_EXCEEDED.
• Tag::USER_SECURE_ID diberlakukan oleh metode ini hanya jika kuncinya juga memiliki Tag::AUTH_TIMEOUT. Jika kunci memiliki keduanya, metode ini harus menerima respons Tag::AUTH_TOKEN masuk inParams. Agar token autentikasi valid, semua hal berikut harus benar:
  • Kolom HMAC memvalidasi dengan benar.
  • Setidaknya salah satu Tag::USER_SECURE_ID nilai dari kunci cocok dengan setidaknya salah satu nilai ID aman pada sebelumnya yang benar.
  • Kunci tersebut memiliki Tag::USER_AUTH_TYPE yang cocok dengan jenis auth dalam token.

  Jika salah satu kondisi ini tidak terpenuhi, metode akan menampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

• Tag::CALLER_NONCE memungkinkan pemanggil untuk menentukan nonce atau initialization vector (IV). Jika kunci tidak memiliki tag ini, tetapi pemanggil telah memberikan Tag::NONCE ke metode ini, ErrorCode::CALLER_NONCE_PROHIBITED ditampilkan.
• Tag::KHUSUS BOOTLOADER menentukan bahwa hanya {i>bootloader<i} yang dapat menggunakan kunci tersebut. Jika metode ini dipanggil dengan kunci khusus {i>bootloader<i} setelah {i> bootloader<i} selesai dieksekusi, kueri akan menghasilkan ErrorCode::INVALID_KEY_BLOB.

Kunci RSA

Semua operasi kunci RSA menentukan tepat satu mode padding di inParams. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode akan menampilkan ErrorCode::UNSUPPORTED_PADDING_MODE.

Operasi penandatanganan dan verifikasi RSA memerlukan ringkasan, begitu juga dengan enkripsi RSA dan dekripsi dengan mode padding OAEP. Untuk kasus tersebut, pemanggil menentukan tepat satu ringkasan di inParams. Jika tidak ditentukan atau ditentukan lebih dari sekali, metode ini akan menampilkan ErrorCode::UNSUPPORTED_DIGEST.

Operasi kunci pribadi (KeyPurpose::DECYPT dan KeyPurpose::SIGN) membutuhkan otorisasi digest dan padding, yang berarti bahwa otorisasi kunci harus berisi nilai-nilai yang ditentukan. Jika tidak, metode akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST atau ErrorCode::INCOMPATIBLE_PADDING, sebagaimana diperlukan. Operasi kunci publik (KeyPurpose::ENCRYPT dan KeyPurpose::VERIFY) diizinkan dengan digest atau padding yang tidak sah.

Dengan pengecualian PaddingMode::NONE, semua mode padding RSA hanya berlaku untuk tujuan tertentu. Secara khusus, Anda bisa 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 akan menampilkan ErrorCode::UNSUPPORTED_PADDING_MODE jika mode yang ditentukan tidak mendukung tujuan yang ditentukan.

Ada beberapa interaksi penting antara mode padding dan ringkasan:

• PaddingMode::NONE menunjukkan bahwa "raw" Operasi RSA adalah dilaksanakan. Jika menandatangani atau memverifikasi, Digest::NONE adalah yang ditentukan untuk ringkasan. Tidak diperlukan ringkasan untuk enkripsi tanpa padding atau dekripsi.
• Padding PaddingMode::RSA_PKCS1_1_5_SIGN memerlukan ringkasan. Tujuan digest mungkin Digest::NONE, dalam hal ini Keymaster tidak dapat membangun struktur tanda tangan PKCS#1 v1.5 yang tepat, karena struktur DigestInfo tidak dapat ditambahkan. Sebaliknya, implementasi menghasilkan 0x00 || 0x01 || PS || 0x00 || M, dengan M adalah yang diberikan dan PS adalah string padding. Ukuran kunci RSA harus berukuran minimal 11 byte lebih besar dari pesan. Jika tidak, metode ini akan menampilkan ErrorCode::INVALID_INPUT_LENGTH.
• Padding PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT tidak memerlukan ringkasan.
• Padding PaddingMode::RSA_PSS memerlukan ringkasan, yang mungkin tidak Digest::NONE. Jika Digest::NONE ditentukan, elemen akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST. Selain itu, ukuran kunci RSA setidaknya harus lebih besar 2 + D byte lebih besar dari output ukuran {i>digest<i}, dengan D adalah ukuran {i>digest<i}, dalam byte. Sebaliknya metode ini akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST. Ukuran garam adalah D.
• Padding PaddingMode::RSA_OAEP memerlukan ringkasan, yang mungkin tidak Digest::NONE. Jika Digest::NONE ditentukan, elemen akan menampilkan ErrorCode::INCOMPATIBLE_DIGEST.

Kunci EC

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

Operasi kunci pribadi (KeyPurpose::SIGN) memerlukan otorisasi digest dan padding, yang berarti bahwa otorisasi kunci harus berisi nilai-nilai yang ditentukan. Jika tidak, kembalikan ErrorCode::INCOMPATIBLE_DIGEST. Operasi kunci publik (KeyPurpose::VERIFY) diizinkan dengan ringkasan atau padding yang tidak sah.

Kunci AES

Operasi kunci AES menetapkan dengan tepat satu mode blok dan satu mode padding di inParams. Jika salah satu nilai tidak ditentukan atau ditentukan lebih dari sekali, tampilkan ErrorCode::UNSUPPORTED_BLOCK_MODE atau ErrorCode::UNSUPPORTED_PADDING_MODE. Moda yang ditentukan harus diizinkan oleh kunci. Jika tidak, metode ini akan menampilkan ErrorCode::INCOMPATIBLE_BLOCK_MODE atau ErrorCode::INCOMPATIBLE_PADDING_MODE.

Jika mode blokir 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 non-kelipatan dari 8, tampilkan ErrorCode::UNSUPPORTED_MAC_LENGTH. Untuk nilai {i>less<i}, dari panjang minimum kunci, tampilkan ErrorCode::INVALID_MAC_LENGTH.

Jika mode blokir 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 kondisi ini, tampilkan ErrorCode::INCOMPATIBLE_PADDING_MODE.

Jika mode blokir adalah BlockMode::CBC, BlockMode::CTR, atau BlockMode::GCM, vektor inisialisasi atau nonce diperlukan. Dalam sebagian besar kasus, pemanggil tidak boleh memberikan IV atau nonce. Dalam kasus tersebut, Implementasi Keymaster menghasilkan IV atau nonce acak dan mengembalikannya melalui Tag::NONCE di outParams. CBC dan CTR IV adalah 16 byte. Nonce GCM adalah 12 byte. Jika kunci otorisasi berisi Tag::CALLER_NONCE, maka pemanggil dapat memberikan IV/nonce dengan Tag::NONCE di inParams. Jika nonce diberikan saat Tag::CALLER_NONCE tidak diotorisasi, tampilkan ErrorCode::CALLER_NONCE_PROHIBITED. Jika nonce tidak disediakan saat Tag::CALLER_NONCE diotorisasi, buat IV/nonce acak.

Kunci HMAC

Operasi kunci HMAC menentukan Tag::MAC_LENGTH di inParams. Nilai yang ditentukan harus kelipatan dari 8 yang tidak lebih besar dari atau kurang dari nilai Tag::MIN_MAC_LENGTH pada otorisasi kunci. Untuk panjang MAC yang lebih besar dari panjang {i>digest<i} atau non-kelipatan 8, tampilkan ErrorCode::UNSUPPORTED_MAC_LENGTH. Untuk nilai yang kurang dari panjang minimum kunci, tampilkan ErrorCode::INVALID_MAC_LENGTH.

update

Versi: 1, 2, 3

Menyediakan data untuk diproses dalam operasi yang sedang berlangsung yang dimulai dengan dimulai. Operasi ditentukan oleh parameter operationHandle.

Untuk memberikan fleksibilitas yang lebih besar dalam penanganan buffer, implementasi metode ini memiliki opsi untuk menggunakan lebih sedikit data daripada yang diberikan. Penelepon adalah bertanggung jawab untuk melakukan {i>looping <i}untuk memberi data pada panggilan berikutnya. Tujuan jumlah input yang dikonsumsi ditampilkan dalam parameter inputConsumed. Implementasi selalu menggunakan setidaknya satu byte, kecuali jika operasi tidak dapat menerima lagi; jika disediakan lebih dari nol byte dan nol jika byte dikonsumsi, pemanggil menganggap ini sebagai error dan membatalkan operasi.

Implementasi juga dapat memilih berapa banyak data yang akan ditampilkan, sebagai hasil dari memperbarui. Kunci ini hanya relevan untuk operasi enkripsi dan dekripsi, karena penandatanganan dan verifikasi tidak menampilkan data hingga selesai. Tampilkan data sedini mungkin, bukan di-buffer.

Penanganan error

Jika metode ini menampilkan kode error selain ErrorCode::OK, operasi dibatalkan dan handle operasi menjadi tidak valid. Apa saja penggunaan {i>handle<i} di masa mendatang, dengan metode ini, menyelesaikan, atau membatalkan, akan menampilkan ErrorCode::INVALID_OPERATION_HANDLE.

Penerapan otorisasi

Penerapan otorisasi kunci terutama dilakukan saat dimulai. Satu-satunya pengecualian adalah kasus jika kunci memiliki:

• Satu atau beberapa Tag::USER_SECURE_ID, dan
• Tidak memiliki Tag::AUTH_TIMEOUT

Dalam hal ini, kunci memerlukan otorisasi per operasi, dan update menerima Tag::AUTH_TOKEN dalam argumen inParams. HMAC memverifikasi bahwa token tersebut valid dan berisi ID pengguna aman yang cocok, akan cocok dengan kunci Tag::USER_AUTH_TYPE, dan berisi handle operasi operasi saat ini di isian tantangan. Jika ketentuan ini tidak terpenuhi, tampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Pemanggil memberikan token autentikasi ke setiap panggilan untuk memperbarui dan selesai. Penerapan tersebut 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 memperbarui. Aplikasi mungkin tidak hanya menggunakan sebagian blok. Namun, jika pemanggil memilih menyediakan data dalam beberapa pembaruan, metode ini menerimanya. Jika pemanggil memberikan lebih banyak data untuk ditandatangani daripada yang dapat digunakan (panjang melebihi ukuran kunci RSA), tampilkan 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 memperbarui. Metode ini mungkin tidak hanya menggunakan sebagian 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, data tersebut otomatis terpotong. (Ini berbeda dengan dan penanganan kelebihan data yang disediakan dalam operasi RSA serupa. Alasannya adalah kompatibilitas dengan klien lama.)

Kunci AES

Mode AES GCM mendukung "data otentikasi terkait," yang disediakan melalui Tag::ASSOCIATED_DATA tag dalam argumen inParams. Data terkait dapat diberikan dalam panggilan berulang (penting jika data terlalu besar untuk dikirim dalam satu blok) tetapi selalu mendahului data untuk dienkripsi atau didekripsi. Panggilan update dapat menerima kedua data terkait dan data untuk dienkripsi/didekripsi, tetapi pembaruan selanjutnya mungkin tidak menyertakan layanan otomatis dan data skalabel. Apakah pemanggil memberikan data terkait ke panggilan update setelah panggilan yang menyertakan data untuk dienkripsi/didekripsi, tampilkan ErrorCode::INVALID_TAG.

Untuk enkripsi GCM, tag ditambahkan ke teks tersandi dengan selesai. Selama dekripsi, yang terakhir Tag::MAC_LENGTH byte dari data yang disediakan hingga panggilan update adalah tag-nya. Sejak pemanggilan update tidak dapat mengetahui apakah itu adalah panggilan terakhir, fungsi ini memproses semua kecuali panjang tag dan menyangga kemungkinan data tag saat selesai.

selesai

Versi: 1, 2, 3

Menyelesaikan operasi yang sedang berlangsung yang dimulai dengan begin, memproses semua data yang belum diproses yang disediakan oleh update.

Metode ini adalah yang terakhir dipanggil dalam suatu operasi, jadi semua data yang telah diproses.

Apakah metode ini berhasil diselesaikan atau menghasilkan {i>error<i}, metode ini akan menyelesaikan operasi sehingga menjadi tidak valid untuk {i>handle<i} operasi yang disediakan. Apa saja penggunaan nama sebutan channel di masa mendatang, dengan metode ini atau update atau abort, menampilkan ErrorCode::INVALID_OPERATION_HANDLE.

Operasi penandatanganan menampilkan tanda tangan sebagai output. Operasi verifikasi menerima tanda tangan dalam parameter signature, dan tidak menampilkan output.

Penerapan otorisasi

Penerapan otorisasi kunci dilakukan terutama di memulai. Satu-satunya pengecualian adalah kasus jika kunci memiliki:

• Satu atau lebih Tag::USER_SECURE_ID, dan
• Tidak memiliki Tag::AUTH_TIMEOUT

Dalam hal ini, kunci memerlukan otorisasi per operasi, dan update menerima Tag::AUTH_TOKEN dalam argumen inParams. HMAC memverifikasi bahwa token valid dan berisi ID pengguna aman yang cocok, yang cocok dengan Tag::USER_AUTH_TYPE, dan berisi handle operasi dari operasi saat ini di isian tantangan. Jika ketentuan ini tidak terpenuhi, tampilkan ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Pemanggil memberikan token otentikasi ke setiap panggilan ke update dan finish. Penerapan tersebut hanya perlu memvalidasi token satu kali jika diinginkan.

Kunci RSA

Beberapa persyaratan tambahan, bergantung pada mode padding:

• PaddingMode::NONE. Untuk operasi penandatanganan dan enkripsi tanpa padding, jika data yang disediakan lebih pendek dari kunci, data akan diberi padding nol di sebelah kiri sebelum menandatangani/enkripsi. Jika data itu panjangnya sama dengan kunci, tetapi secara numerik lebih besar, tampilkan ErrorCode::INVALID_ARGUMENT. Sebagai verifikasi dan dekripsi, panjang data harus sama persis sebagai kuncinya. Jika tidak, tampilkan ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. Untuk operasi tanda tangan dengan padding PSS, {i>salt<i} PSS adalah ukuran {i>message digest<i} dan dihasilkan secara acak. Ringkasan yang ditentukan dengan Tag::DIGEST di inputParams pada awal digunakan sebagai ringkasan PSS dan sebagai algoritma digest MGF1.
• PaddingMode::RSA_OAEP. {i>Digest<i} yang ditentukan dengan Tag::DIGEST di inputParams pada awal digunakan sebagai OAEP {i>digest<i}, dan SHA1 digunakan sebagai algoritma digest MGF1.

Kunci ECDSA

Jika data yang diberikan untuk verifikasi atau penandatanganan tanpa padding terlalu panjang, potong anotasi.

Kunci AES

Beberapa kondisi tambahan, bergantung pada mode blokir:

• BlockMode::ECB atau BlockMode::CBC. Jika padding adalah PaddingMode::NONE dan panjang data bukan kelipatan dari ukuran blok AES, tampilkan ErrorCode::INVALID_INPUT_LENGTH. Jika padding adalah PaddingMode::PKCS7, berikan data sesuai dengan spesifikasi PKCS#7. Perlu diketahui bahwa PKCS#7 merekomendasikan penambahan blok padding tambahan jika data merupakan kelipatan dari panjang blok.
• BlockMode::GCM. Selama enkripsi, setelah pemrosesan semua teks biasa, hitung tag (Tag::MAC_LENGTH byte) dan menambahkannya ke ciphertext yang ditampilkan. Selama dekripsi, proses Tag::MAC_LENGTH terakhir {i>byte<i} sebagai tag. Jika verifikasi tag gagal, tampilkan ErrorCode::VERIFICATION_FAILED.

batal

Versi: 1, 2, 3

Membatalkan operasi yang sedang berlangsung. Setelah panggilan untuk membatalkan, kembali ErrorCode::INVALID_OPERATION_HANDLE untuk setiap penggunaan selanjutnya dari handle operasi yang disediakan dengan update, selesaikan, atau batalkan.

get_supported_algorithms

Versi: 1

Menampilkan daftar algoritma yang didukung oleh hardware Keymaster terlepas dari implementasi layanan. Implementasi software menampilkan daftar kosong; 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

Menampilkan daftar mode blok AES yang didukung oleh hardware Keymaster implementasi untuk algoritma dan tujuan tertentu.

Untuk RSA, EC dan HMAC, yang bukan penyandian blok, metode ini mengembalikan daftar kosong untuk semua tujuan yang valid. Tujuan yang tidak valid akan menyebabkan metode tampilkan ErrorCode::INVALID_PURPOSE.

Implementasi Keymaster 1 mendukung ECB, CBC, CTR, dan GCM untuk AES enkripsi dan dekripsi.

get_supported_padding_modes

Versi: 1

Menampilkan daftar mode padding yang didukung oleh hardware Keymaster implementasi untuk algoritma dan tujuan tertentu.

HMAC dan EC tidak memiliki gambaran padding sehingga metode menampilkan daftar kosong untuk semua tujuan yang valid. Tujuan yang tidak valid akan menyebabkan metode ditampilkan ErrorCode::INVALID_PURPOSE.

Untuk RSA, dukungan implementasi Keymaster 1:

• Enkripsi, dekripsi, penandatanganan, dan verifikasi tanpa padding. Untuk tanpa padding enkripsi dan penandatanganan, jika pesan lebih pendek dari modulus publik, harus di-kiri{i> <i}dengan nol. Untuk dekripsi tanpa padding dan verifikasi, panjang input harus sesuai dengan ukuran modulus publik.
• Enkripsi PKCS#1 v1.5 dan mode padding penandatanganan
• PSS dengan panjang salt minimum 20
• OAEP

Untuk AES dalam mode ECB dan CBC, implementasi Keymaster 1 tidak mendukung dan padding PKCS#7. Mode CTR dan GCM hanya mendukung tanpa padding.

get_supported_digests

Versi: 1

Menampilkan daftar mode ringkasan yang didukung oleh hardware Keymaster implementasi untuk algoritma dan tujuan tertentu.

Tidak ada mode AES yang mendukung atau memerlukan digesting, sehingga metode akan menampilkan untuk tujuan yang valid.

Implementasi Keymaster 1 dapat mengimplementasikan subset dari digest. Implementasi menyediakan SHA-256 dan dapat memberikan MD5, SHA1, SHA-224, SHA-256, SHA384, dan SHA512 (kumpulan lengkap ringkasan yang ditentukan).

get_supported_import_formats

Versi: 1

Menampilkan daftar format impor yang didukung oleh hardware Keymaster implementasi algoritma tertentu.

Implementasi Keymaster 1 mendukung format PKCS#8 (tanpa kata sandi ) untuk mengimpor pasangan kunci RSA dan EC, dan mendukung impor RAW Materi kunci AES dan HMAC.

get_supported_export_formats

Versi: 1

Menampilkan daftar format ekspor yang didukung oleh hardware Keymaster implementasi algoritma tertentu.

Implementasi Keymaster1 mendukung format X.509 untuk mengekspor RSA dan Kunci publik EC. Ekspor kunci pribadi atau kunci asimetris tidak didukung.

Fungsi historis

Keymaster 0

Fungsi berikut termasuk dalam definisi Keymaster 0 yang asli. Mereka hadir di Keymaster 1 struct keymaster1_device_t. Namun, di Keymaster 1.0.1.0 mereka tidak diimplementasikan, dan pointer fungsi mereka ditetapkan ke NULL.

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

Keymaster 1

Fungsi berikut termasuk dalam definisi Keymaster 1, namun dihapus di Keymaster 2, bersama dengan fungsi Keymaster 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 berikut termasuk dalam definisi Keymaster 2, namun dihapus di Keymaster 3, bersama dengan fungsi Keymaster 1 yang tercantum di atas.

• configure