การอ้างอิงโครงสร้าง keymaster2_device

เขตข้อมูล
การอ้างอิงโครงสร้าง keymaster2_device

#include < keymaster2.h >

เขตข้อมูล

โครงสร้าง hw_device_t ทั่วไป
เป็นโมฆะ * บริบท
uint32_t ธง
keymaster_error_t (* กำหนดค่า )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy ) (const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
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 *ลักษณะเฉพาะ)
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 *ลักษณะเฉพาะ)
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 *ลักษณะเฉพาะ)
keymaster_error_t (* Export_key )(const struct keymaster2_device *dev, keymaster_key_format_t ส่งออก_รูปแบบ, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)
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)
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 *upgraded_key)
keymaster_error_t (* Delete_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *คีย์)
keymaster_error_t (* Delete_all_keys )(const struct keymaster2_device *dev)
keymaster_error_t (* เริ่มต้น )(const struct keymaster2_device *dev, วัตถุประสงค์ของ 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)
keymaster_error_t (* อัปเดต )(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_params, keymaster_blob_t *output)
keymaster_error_t (* เสร็จสิ้น )(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 *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* ยกเลิก )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

คำอธิบายโดยละเอียด

คำจำกัดความของอุปกรณ์ Keymaster2

คำจำกัดความที่บรรทัดที่ 28 ของไฟล์ keymaster2.h

เอกสารภาคสนาม

keymaster_error_t (* ยกเลิก) (const struct keymaster2_device * dev, keymaster_operation_handle_t operation_handle)

ยกเลิกการดำเนินการเข้ารหัสลับที่เริ่มต้นด้วย beginning() ทำให้ทรัพยากรภายในว่างทั้งหมดและทำให้ operation_handle เป็นโมฆะ

คำจำกัดความที่บรรทัด 415 ของไฟล์ keymaster2.h

keymaster_error_t (* add_rng_entropy) (const struct keymaster2_device *dev, const uint8_t *ข้อมูล, size_t data_length)

เพิ่มเอนโทรปีให้กับ RNG ที่ใช้โดยคีย์มาสเตอร์ เอนโทรปีที่เพิ่มผ่านวิธีนี้รับประกันว่าจะไม่ใช่แหล่งเดียวของเอนโทรปีที่ใช้ และฟังก์ชันการผสมจำเป็นต้องปลอดภัย ในแง่ที่ว่าหาก RNG ได้รับการเพาะ (จากแหล่งใดๆ ก็ตาม) ด้วยข้อมูลใดๆ ที่ผู้โจมตีไม่สามารถคาดเดาได้ (หรือ ควบคุม) ดังนั้นเอาท์พุต RNG จะแยกไม่ออกจากการสุ่ม ดังนั้นหากเอนโทรปีจากแหล่งใดๆ ดี ผลลัพธ์ก็จะออกมาดี

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] ข้อมูล ข้อมูลสุ่มที่จะนำมาผสม
[ใน] ข้อมูล_ความยาว ความยาวของ data

คำจำกัดความที่บรรทัดที่ 74 ของไฟล์ 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)

สร้างกลุ่มใบรับรอง X.509 ที่ลงนามแล้วเพื่อยืนยันการมีอยู่ของ key_to_attest ในคีย์มาสเตอร์ (TODO(swillden): อธิบายเนื้อหาใบรับรองโดยละเอียดเพิ่มเติม) ใบรับรองจะมีส่วนขยายที่มี OID 1.3.6.1.4.1.11129.2.1.17 และค่าที่กำหนดใน <TODO:swillden – insert link here> ซึ่งมีคำอธิบายคีย์

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] key_to_attest คีย์คีย์มาสเตอร์ที่จะใช้สร้างใบรับรองการรับรอง
[ใน] attest_params พารามิเตอร์ที่กำหนดวิธีการรับรอง ในปัจจุบัน พารามิเตอร์เดียวคือ KM_TAG_ALGORITHM ซึ่งต้องเป็น KM_ALGORITHM_EC หรือ KM_ALGORITHM_RSA การดำเนินการนี้จะเลือกว่าจะใช้คีย์การรับรองใดในการลงนามใบรับรอง
[ออก] cert_chain อาร์เรย์ของใบรับรอง X.509 ที่เข้ารหัส DER รายการแรกจะเป็นใบรับรองสำหรับ key_to_attest รายการที่เหลือจะโยงกลับไปที่รูท ผู้โทรเข้าเป็นเจ้าของและต้องจัดสรรคืนด้วย keymaster_free_cert_chain

คำจำกัดความที่บรรทัด 239 ของไฟล์ keymaster2.h

keymaster_error_t (* เริ่มต้น)(const struct keymaster2_device *dev, วัตถุประสงค์ ของ 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)

เริ่มต้นการดำเนินการเข้ารหัสลับโดยใช้คีย์ที่ระบุ หากทุกอย่างเรียบร้อยดี start() จะส่งคืน KM_ERROR_OK และสร้างตัวจัดการการดำเนินการซึ่งจะต้องส่งผ่านไปยังการเรียกครั้งต่อไปเพื่อ update() , finish() หรือ abort()

จำเป็นอย่างยิ่งที่จะต้องจับคู่การเรียก start() แต่ละครั้งกับการเรียกที่ตามมาเพื่อ เสร็จสิ้น() หรือ ยกเลิก() เพื่อให้การใช้งานคีย์มาสเตอร์สามารถล้างสถานะการดำเนินการภายในใดๆ ได้ การไม่ทำเช่นนี้อาจทำให้พื้นที่สถานะภายในหรือทรัพยากรภายในอื่นๆ รั่วไหล และในที่สุดอาจทำให้ start() ส่งคืน KM_ERROR_TOO_MANY_OPERATIONS เมื่อพื้นที่ไม่เพียงพอสำหรับการดำเนินการ ผลลัพธ์ใดๆ นอกเหนือจาก KM_ERROR_OK จาก beginning() , update() หรือ finish() จะยกเลิกการดำเนินการโดยปริยาย ซึ่งในกรณีนี้ ไม่จำเป็นต้องเรียกใช้ abort() (และจะส่งคืน KM_ERROR_INVALID_OPERATION_HANDLE หากเรียกใช้)

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] วัตถุประสงค์ วัตถุประสงค์ของการดำเนินการ หนึ่งใน KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN หรือ KM_PURPOSE_VERIFY โปรดทราบว่าสำหรับโหมด AEAD การเข้ารหัสและการถอดรหัสหมายถึงการลงนามและการตรวจสอบ ตามลำดับ แต่ควรระบุเป็น KM_PURPOSE_ENCRYPT และ KM_PURPOSE_DECRYPT
[ใน] สำคัญ กุญแจที่จะใช้ในการดำเนินการ key จะต้องมีวัตถุประสงค์ที่สอดคล้องกับ purpose และต้องปฏิบัติตามข้อกำหนดการใช้งานทั้งหมด มิฉะนั้น start() จะส่งรหัสข้อผิดพลาดที่เหมาะสมกลับมา
[ใน] in_params พารามิเตอร์เพิ่มเติมสำหรับการดำเนินการ โดยทั่วไปจะใช้เพื่อให้ข้อมูลการตรวจสอบสิทธิ์ด้วย KM_TAG_AUTH_TOKEN หากมีการระบุ KM_TAG_APPLICATION_ID หรือ KM_TAG_APPLICATION_DATA ในระหว่างการสร้าง จะต้องระบุไว้ที่นี่ ไม่เช่นนั้นการดำเนินการจะล้มเหลวด้วย KM_ERROR_INVALID_KEY_BLOB สำหรับการดำเนินการที่ต้องใช้ nonce หรือ IV บนคีย์ที่สร้างด้วย KM_TAG_CALLER_NONCE นั้น in_params อาจมีแท็ก KM_TAG_NONCE
[ออก] out_params พารามิเตอร์เอาท์พุต ใช้เพื่อส่งคืนข้อมูลเพิ่มเติมจากการเตรียมใช้งานการดำเนินการ โดยเฉพาะอย่างยิ่งเพื่อส่งคืน IV หรือ nonce จากการดำเนินการที่สร้าง IV หรือ nonce ผู้เรียกเข้าเป็นเจ้าของอาร์เรย์พารามิเตอร์เอาต์พุต และต้องปล่อยอาร์เรย์พารามิเตอร์เอาต์พุตด้วย keymaster_free_param_set() out_params อาจถูกตั้งค่าเป็น NULL หากไม่ต้องการพารามิเตอร์เอาต์พุต หาก out_params เป็น NULL และสร้างพารามิเตอร์เอาต์พุต start() จะส่งกลับ KM_ERROR_OUTPUT_PARAMETER_NULL
[ออก] การดำเนินงาน_การจัดการ ตัวจัดการการดำเนินการที่สร้างขึ้นใหม่ซึ่งจะต้องส่งผ่านไปยัง update() , finish() หรือ abort() หาก operation_handle เป็น NULL, start() จะส่งกลับ KM_ERROR_OUTPUT_PARAMETER_NULL

คำจำกัดความที่บรรทัด 332 ของไฟล์ keymaster2.h

struct hw_device_t ทั่วไป

วิธีการทั่วไปของอุปกรณ์คีย์มาสเตอร์ นี่ จะต้อง เป็นสมาชิกคนแรกของ keymaster_device เนื่องจากผู้ใช้ของโครงสร้างนี้จะส่ง hw_device_t ไปยังตัวชี้ keymaster_device ในบริบทที่ทราบว่า hw_device_t อ้างอิงถึง keymaster_device

คำจำกัดความที่บรรทัดที่ 35 ของไฟล์ keymaster2.h

keymaster_error_t (* กำหนดค่า) (const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)

กำหนดค่าคีย์มาสเตอร์ ต้องเรียกวิธีนี้หนึ่งครั้งหลังจากเปิดอุปกรณ์และก่อนใช้งาน ใช้เพื่อจัดเตรียม KM_TAG_OS_VERSION และ KM_TAG_OS_PATCHLEVEL ให้กับคีย์มาสเตอร์ จนกว่าจะมีการเรียกเมธอดนี้ เมธอดอื่นๆ ทั้งหมดจะส่งคืน KM_ERROR_KEYMASTER_NOT_CONFIGURED ค่าที่ระบุโดยวิธีนี้ได้รับการยอมรับโดยคีย์มาสเตอร์เพียงครั้งเดียวต่อการบูตเท่านั้น การโทรครั้งต่อไปจะส่งคืน KM_ERROR_OK แต่ไม่ทำอะไรเลย

หากการใช้งานคีย์มาสเตอร์อยู่ในฮาร์ดแวร์ที่ปลอดภัย และเวอร์ชันระบบปฏิบัติการและค่าระดับแพตช์ที่ระบุไม่ตรงกับค่าที่บูตโหลดเดอร์มอบให้กับฮาร์ดแวร์ที่ปลอดภัย (หรือหากบูตโหลดเดอร์ไม่ได้ระบุค่า) ดังนั้นเมธอดนี้จะส่งคืน KM_ERROR_INVALID_ARGUMENT และทั้งหมด วิธีอื่นจะส่งคืน KM_ERROR_KEYMASTER_NOT_CONFIGURED ต่อไป

คำจำกัดความที่บรรทัดที่ 58 ของไฟล์ keymaster2.h

บริบทเป็นโมฆะ*

คำจำกัดความที่บรรทัดที่ 37 ของไฟล์ keymaster2.h

keymaster_error_t (* Delete_all_keys) (const struct keymaster2_device *dev)

ลบคีย์ทั้งหมดในที่เก็บคีย์ฮาร์ดแวร์ ใช้เมื่อรีเซ็ตที่เก็บคีย์โดยสมบูรณ์ หลังจากเรียกใช้ฟังก์ชันนี้แล้ว คุณจะไม่สามารถใช้คีย์ blobs ที่สร้างหรือนำเข้าไว้ก่อนหน้านี้สำหรับการดำเนินการใดๆ ได้

ฟังก์ชันนี้เป็นทางเลือกและควรตั้งค่าเป็น NULL หากไม่ได้ใช้งาน

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์

คำจำกัดความที่บรรทัด 288 ของไฟล์ keymaster2.h

keymaster_error_t (* Delete_key) (const struct keymaster2_device * dev, const keymaster_key_blob_t * คีย์)

ลบคีย์หรือคู่คีย์ที่เชื่อมโยงกับคีย์บล็อบ หลังจากเรียกใช้ฟังก์ชันนี้แล้ว คุณจะไม่สามารถใช้คีย์สำหรับการดำเนินการอื่นใดได้ อาจนำไปใช้กับคีย์จากรากของความไว้วางใจต่างประเทศ (คีย์ไม่สามารถใช้งานได้ภายใต้รากของความไว้วางใจในปัจจุบัน)

ฟังก์ชันนี้เป็นทางเลือกและควรตั้งค่าเป็น NULL หากไม่ได้ใช้งาน

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] สำคัญ คีย์ที่จะถูกลบ

คำจำกัดความที่บรรทัด 276 ของไฟล์ keymaster2.h

keymaster_error_t (* Export_key)(const struct keymaster2_device *dev, keymaster_key_format_t ส่งออกรูปแบบ, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)

ส่งออกคีย์สาธารณะหรือคีย์สมมาตร โดยส่งคืนอาร์เรย์ไบต์ในรูปแบบที่ระบุ

โปรดทราบว่าอนุญาตให้ส่งออกคีย์สมมาตรได้ก็ต่อเมื่อมีการสร้างคีย์ด้วย KM_TAG_EXPORTABLE และเฉพาะเมื่อตรงตามข้อกำหนดทั้งหมดสำหรับการใช้งานคีย์ (เช่น การตรวจสอบสิทธิ์)

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] ส่งออก_รูปแบบ รูปแบบที่จะใช้สำหรับการส่งออกคีย์
[ใน] คีย์_to_ส่งออก กุญแจสำคัญในการส่งออก
[ใน] ลูกค้า_id Client ID blob ซึ่งจะต้องตรงกับ blob ที่ระบุใน KM_TAG_APPLICATION_ID ระหว่างการสร้างคีย์ (ถ้ามี)
[ใน] ข้อมูลแอพ Appliation data blob ซึ่งจะต้องตรงกับ blob ที่ให้ไว้ใน KM_TAG_APPLICATION_DATA ระหว่างการสร้างคีย์ (ถ้ามี)
[ออก] ส่งออก_ข้อมูล วัสดุหลักที่ส่งออก ผู้โทรเข้าถือสิทธิ์ความเป็นเจ้าของ

คำจำกัดความที่บรรทัด 213 ของไฟล์ keymaster2.h

keymaster_error_t (* เสร็จสิ้น) (const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *อินพุต, const keymaster_blob_t *ลายเซ็น, keymaster_key_param_set_t *out_params, keymaster_blob_t *เอาต์พุต)

สิ้นสุดการดำเนินการเข้ารหัสลับที่เริ่มต้นด้วย start() และทำให้ operation_handle เป็นโมฆะ

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] การดำเนินงาน_การจัดการ หมายเลขอ้างอิงการดำเนินการที่ส่งคืนโดย start() หมายเลขอ้างอิงนี้จะใช้งานไม่ได้
[ใน] in_params พารามิเตอร์เพิ่มเติมสำหรับการดำเนินการ สำหรับโหมด AEAD สิ่งนี้ใช้เพื่อระบุ KM_TAG_ADDITIONAL_DATA แต่เฉพาะในกรณีที่ไม่มีการป้อนข้อมูลอินพุตให้ update()
[ใน] ป้อนข้อมูล ข้อมูลที่จะประมวลผลตามพารามิเตอร์ที่สร้างขึ้นในการเรียก to beginning() finish() ต้องใช้ข้อมูลที่ให้มาทั้งหมดหรือส่งคืน KM_ERROR_INVALID_INPUT_LENGTH
[ใน] ลายเซ็น ลายเซ็นที่จะตรวจสอบหากวัตถุประสงค์ที่ระบุไว้ในการเรียก beginning() คือ KM_PURPOSE_VERIFY
[ออก] เอาท์พุท ข้อมูลเอาท์พุต ถ้ามี ผู้เรียกถือว่าความเป็นเจ้าของบัฟเฟอร์ที่จัดสรร

หากการดำเนินการที่เสร็จสิ้นเป็นการตรวจสอบลายเซ็นหรือการถอดรหัสในโหมด AEAD และการตรวจสอบล้มเหลว finish() จะส่งกลับ KM_ERROR_VERIFICATION_FAILED

คำจำกัดความที่บรรทัด 405 ของไฟล์ keymaster2.h

ธง uint32_t

ดูแฟล็กที่กำหนดไว้สำหรับ keymaster0_devices::flags ใน keymaster_common.h ใช้สำหรับความเข้ากันได้แบบย้อนหลังเท่านั้น อุปกรณ์ฮาร์ดแวร์ keymaster2 ต้องตั้งค่านี้เป็นศูนย์

คำจำกัดความที่บรรทัดที่ 43 ของไฟล์ 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 *ลักษณะเฉพาะ)

สร้างคีย์หรือคู่คีย์ โดยส่งคืนคีย์หยดและ/หรือคำอธิบายของคีย์

พารามิเตอร์การสร้างคีย์ถูกกำหนดให้เป็นคู่แท็ก/ค่าของคีย์มาสเตอร์ ซึ่งระบุไว้ใน params ดู keymaster_tag_t สำหรับรายการทั้งหมด ค่าบางค่าที่จำเป็นสำหรับการสร้างคีย์ที่มีประโยชน์เสมอคือ:

  • KM_TAG_ALGORITHM;
  • KM_TAG_วัตถุประสงค์; และ
  • (KM_TAG_USER_SECURE_ID และ KM_TAG_USER_AUTH_TYPE) หรือ KM_TAG_NO_AUTH_REQUIRED

โดยทั่วไปควรระบุ KM_TAG_AUTH_TIMEOUT เว้นแต่ KM_TAG_NO_AUTH_REQUIRED มีอยู่ ไม่เช่นนั้นผู้ใช้จะต้องตรวจสอบสิทธิ์สำหรับการใช้งานทุกครั้ง

ต้องระบุ KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH และ KM_TAG_DIGEST สำหรับอัลกอริทึมที่ต้องการ

แท็กต่อไปนี้ไม่สามารถระบุได้ คุณค่าของพวกเขาจะได้รับจากการดำเนินการ

  • KM_TAG_ORIGIN
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] พารามิเตอร์ อาร์เรย์ของพารามิเตอร์การสร้างคีย์
[ออก] key_blob ส่งคืนคีย์ที่สร้างขึ้น key_blob ต้องไม่เป็น NULL ผู้เรียกถือว่าความเป็นเจ้าของ key_blob->key_material และต้อง free() มัน
[ออก] ลักษณะเฉพาะ ส่งคืนคุณสมบัติของคีย์ที่สร้างขึ้นหากไม่ใช่ NULL หากไม่ใช่ NULL ผู้เรียกจะถือว่าเป็นเจ้าของและต้องจัดสรรคืนด้วย keymaster_free_Characteristics() โปรดทราบว่า KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA จะไม่ถูกส่งคืน

คำจำกัดความที่บรรทัด 112 ของไฟล์ 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 *ลักษณะเฉพาะ)

ส่งกลับลักษณะของคีย์ที่ระบุ หรือ KM_ERROR_INVALID_KEY_BLOB หาก key_blob ไม่ถูกต้อง (การใช้งานจะต้องตรวจสอบความสมบูรณ์ของคีย์โดยสมบูรณ์) client_id และ app_data ต้องเป็น ID และข้อมูลที่ให้ไว้เมื่อมีการสร้างหรือนำเข้าคีย์ หรือว่างเปล่าหากไม่มีการระบุ KM_TAG_APPLICATION_ID และ/หรือ KM_TAG_APPLICATION_DATA ในระหว่างการสร้าง ค่าเหล่านั้นจะไม่รวมอยู่ในลักษณะที่ส่งคืน ผู้เรียกจะถือว่าเป็นเจ้าของวัตถุลักษณะที่จัดสรร ซึ่งจะต้องจัดสรรคืนด้วย keymaster_free_Characteristics()

โปรดทราบว่า KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA จะไม่ถูกส่งคืน

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] key_blob กุญแจสำคัญในการดึงคุณลักษณะมาจาก
[ใน] ลูกค้า_id ข้อมูลรหัสลูกค้า หรือ NULL หากไม่มีการเชื่อมโยง
[ใน] app_id ข้อมูลแอป หรือ NULL หากไม่มีการเชื่อมโยงกัน
[ออก] ลักษณะเฉพาะ ลักษณะสำคัญ ต้องไม่เป็นโมฆะ ผู้เรียกจะถือว่าเป็นเจ้าของเนื้อหาและต้องจัดสรรคืนด้วย keymaster_free_Characteristics()

คำจำกัดความที่บรรทัด 139 ของไฟล์ 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 *ลักษณะเฉพาะ)

นำเข้าคีย์หรือคู่คีย์ ส่งคืนคีย์หยดและ/หรือคำอธิบายของคีย์

พารามิเตอร์การนำเข้าคีย์ส่วนใหญ่ถูกกำหนดให้เป็นคู่แท็ก/ค่าของคีย์มาสเตอร์ ซึ่งระบุไว้ใน "params" ดู keymaster_tag_t สำหรับรายการทั้งหมด ค่าที่จำเป็นสำหรับการนำเข้าคีย์ที่มีประโยชน์เสมอคือ:

  • KM_TAG_ALGORITHM;
  • KM_TAG_วัตถุประสงค์; และ
  • (KM_TAG_USER_SECURE_ID และ KM_TAG_USER_AUTH_TYPE) หรือ KM_TAG_NO_AUTH_REQUIRED

โดยทั่วไปควรระบุ KM_TAG_AUTH_TIMEOUT หากไม่ระบุ ผู้ใช้จะต้องตรวจสอบสิทธิ์การใช้งานทุกครั้ง

แท็กต่อไปนี้จะใช้ค่าเริ่มต้นหากไม่ได้ระบุ:

  • KM_TAG_KEY_SIZE จะมีค่าเริ่มต้นเป็นขนาดของคีย์ที่ให้ไว้
  • KM_TAG_RSA_PUBLIC_EXPONENT จะมีค่าเริ่มต้นเป็นค่าในคีย์ที่ให้ไว้ (สำหรับคีย์ RSA)

แท็กต่อไปนี้ไม่สามารถระบุได้ คุณค่าของพวกเขาจะได้รับจากการดำเนินการ

  • KM_TAG_ORIGIN
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] พารามิเตอร์ พารามิเตอร์ที่กำหนดคีย์ที่นำเข้า
[ใน] พารามิเตอร์_count จำนวนรายการใน params
[ใน] คีย์_ฟอร์แมต ระบุรูปแบบของข้อมูลคีย์ใน key_data
[ออก] key_blob ใช้เพื่อส่งคืนหยดคีย์ทึบแสง จะต้องไม่เป็นโมฆะ ผู้เรียกถือว่าความเป็นเจ้าของ key_material ที่มีอยู่
[ออก] ลักษณะเฉพาะ ใช้เพื่อคืนคุณสมบัติของคีย์ที่นำเข้า อาจเป็น NULL ซึ่งในกรณีนี้จะไม่มีการส่งคืนคุณสมบัติใดๆ หากไม่ใช่ NULL ผู้เรียกจะถือว่าเป็นเจ้าของเนื้อหาและต้องจัดสรรคืนด้วย keymaster_free_Characteristics() โปรดทราบว่า KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA จะไม่ถูกส่งคืน

คำจำกัดความที่บรรทัด 186 ของไฟล์ keymaster2.h

keymaster_error_t (* อัพเดต) (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_params, keymaster_blob_t *output)

ให้ข้อมูลและอาจได้รับเอาต์พุตจากการดำเนินการเข้ารหัสลับที่กำลังดำเนินอยู่ซึ่งเริ่มต้นด้วย beginning()

หาก operation_handle ไม่ถูกต้อง update() จะส่งกลับ KM_ERROR_INVALID_OPERATION_HANDLE

update() อาจไม่ใช้ข้อมูลทั้งหมดที่ให้ไว้ในบัฟเฟอร์ข้อมูล update() จะส่งคืนจำนวนเงินที่ใช้ใน *data_consumed ผู้โทรควรให้ข้อมูลที่ไม่ได้ใช้ในการโทรครั้งต่อไป

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] การดำเนินงาน_การจัดการ หมายเลขอ้างอิงการดำเนินการที่ส่งคืนโดย start()
[ใน] in_params พารามิเตอร์เพิ่มเติมสำหรับการดำเนินการ สำหรับโหมด AEAD จะใช้เพื่อระบุ KM_TAG_ADDITIONAL_DATA โปรดทราบว่าอาจมีการให้ข้อมูลเพิ่มเติมในการเรียกหลายครั้งเพื่อ update() แต่จนกว่าจะมีการให้ข้อมูลอินพุตเท่านั้น
[ใน] ป้อนข้อมูล ข้อมูลที่จะประมวลผลตามพารามิเตอร์ที่สร้างขึ้นในการเรียก to beginning() โปรดทราบว่า update() อาจใช้หรือไม่ใช้ข้อมูลทั้งหมดที่ให้ไว้ ดูที่ input_consumed
[ออก] input_consumed จำนวนข้อมูลที่ใช้โดย update() หากน้อยกว่าจำนวนเงินที่ให้ไว้ ผู้โทรควรจัดเตรียมส่วนที่เหลือในการเรียก update() ครั้งต่อไป
[ออก] out_params พารามิเตอร์เอาท์พุต ใช้เพื่อส่งคืนข้อมูลเพิ่มเติมจากการดำเนินการ ผู้เรียกจะเป็นเจ้าของอาร์เรย์พารามิเตอร์เอาต์พุต และต้องปล่อยว่างด้วย keymaster_free_param_set() out_params อาจถูกตั้งค่าเป็น NULL หากไม่ต้องการพารามิเตอร์เอาต์พุต หาก out_params เป็น NULL และสร้างพารามิเตอร์เอาต์พุต start() จะส่งกลับ KM_ERROR_OUTPUT_PARAMETER_NULL
[ออก] เอาท์พุท ข้อมูลเอาท์พุต ถ้ามี ผู้เรียกถือว่าความเป็นเจ้าของบัฟเฟอร์ที่จัดสรร เอาต์พุตจะต้องไม่เป็น NULL

โปรดทราบว่า update() อาจไม่มีเอาต์พุตใดๆ ในกรณีนี้ output->data_length จะเป็นศูนย์ และ output->data อาจเป็น NULL หรือความยาวเป็นศูนย์ (ดังนั้นผู้เรียกควร free() เสมอ)

คำจำกัดความที่บรรทัด 376 ของไฟล์ 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 *upgraded_key)

อัปเกรดคีย์เก่า คีย์สามารถกลายเป็น "เก่า" ได้สองวิธี: Keymaster สามารถอัปเกรดเป็นเวอร์ชันใหม่ได้ หรือสามารถอัปเดตระบบเพื่อทำให้เวอร์ชันระบบปฏิบัติการและ/หรือระดับแพตช์เป็นโมฆะได้ ไม่ว่าในกรณีใด การพยายามใช้คีย์เก่าจะส่งผลให้คีย์มาสเตอร์ส่งคืน KM_ERROR_KEY_REQUIRES_UPGRADE ควรเรียกวิธีนี้เพื่ออัพเกรดคีย์

พารามิเตอร์
[ใน] ผู้พัฒนา โครงสร้างอุปกรณ์คีย์มาสเตอร์
[ใน] คีย์_to_อัปเกรด คีย์คีย์มาสเตอร์ที่จะอัปเกรด
[ใน] อัพเกรด_พารามิเตอร์ พารามิเตอร์ที่จำเป็นในการอัพเกรดให้เสร็จสมบูรณ์ โดยเฉพาะอย่างยิ่ง จะต้องมี KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA หากถูกกำหนดไว้สำหรับคีย์
[ออก] อัพเกรด_คีย์ Blob คีย์ที่อัปเกรดแล้ว

คำจำกัดความที่บรรทัด 260 ของไฟล์ keymaster2.h

เอกสารประกอบสำหรับโครงสร้างนี้สร้างขึ้นจากไฟล์ต่อไปนี้:
  • ฮาร์ดแวร์ / libhardware / รวม / ฮาร์ดแวร์ / keymaster2.h