ข้อมูลอ้างอิงเกี่ยวกับโครงสร้าง keymaster2_device

ช่องข้อมูล
ข้อมูลอ้างอิงเกี่ยวกับโครงสร้าง keymaster2_device

#include < keymaster2.h >

ฟิลด์ข้อมูล

struct hw_device_t   common
 
void *  context
 
uint32_t  flags
 
keymaster_error_t (*  configure )(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 *characteristics)
 
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 *characteristics)
 
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 *characteristics)
 
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 *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 *key)
 
keymaster_error_t (*  delete_all_keys )(const struct keymaster2_device *dev)
 
keymaster_error_t (*  begin )(const struct keymaster2_device *dev, keymaster_purpose_t purpose, 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 (*  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_params, keymaster_blob_t *output)
 
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 *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
 
keymaster_error_t (*  abort )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)
 

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

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

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

เอกสารประกอบในสนาม

keymaster_error_t (* abort)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

ยกเลิกการดำเนินการเข้ารหัสที่เริ่มต้นด้วย begin() โดยปล่อยทรัพยากรภายในทั้งหมดและทำให้ข้อมูลไม่ถูกต้อง operation_handle

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

keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] เพิ่มเติม ข้อมูลแบบสุ่มที่จะผสมเข้าด้วยกัน
[in] data_length ความยาวของ 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 ใน Keymaster (TODO(swillden): อธิบายเนื้อหาใบรับรองอย่างละเอียดยิ่งขึ้น) ใบรับรองจะมีส่วนขยายที่มี OID 1.3.6.1.4.1.11129.2.1.17 และค่าที่กําหนดไว้ใน <TODO:swillden – insert link here> ซึ่งมีคําอธิบายคีย์

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

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

keymaster_error_t (* begin)(const struct keymaster2_device *dev, keymaster_purpose_t purpose, 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)

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] วัตถุประสงค์ วัตถุประสงค์ของการดำเนินการ ซึ่งอาจเป็น KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN หรือ KM_PURPOSE_VERIFY โปรดทราบว่าสําหรับโหมด AEAD การเข้ารหัสและการถอดรหัสจะหมายถึงการรับรองและการยืนยันตามลําดับ แต่ควรระบุเป็น KM_PURPOSE_ENCRYPT และ KM_PURPOSE_DECRYPT
[in] คีย์ คีย์ที่จะใช้สำหรับการดำเนินการ key ต้องมีวัตถุประสงค์ที่เข้ากันได้กับ purpose และต้องเป็นไปตามข้อกำหนดการใช้งานทั้งหมด มิฉะนั้น begin() จะแสดงรหัสข้อผิดพลาดที่เหมาะสม
[in] 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 อาจมีแท็ก KM_TAG_NONCE ใน in_params
[out] out_params พารามิเตอร์เอาต์พุต ใช้เพื่อแสดงผลข้อมูลเพิ่มเติมจากการเริ่มต้นการดำเนินการ โดยเฉพาะอย่างยิ่งเพื่อแสดงผล IV หรือ Nonce จากการดำเนินการที่สร้าง IV หรือ Nonce ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์พารามิเตอร์เอาต์พุต และต้องปลดปล่อยด้วย keymaster_free_param_set() ระบบอาจตั้งค่า out_params เป็น NULL หากไม่ต้องการพารามิเตอร์เอาต์พุต หาก out_params เป็น NULL และสร้างพารามิเตอร์เอาต์พุตแล้ว begin() จะแสดงผลเป็น KM_ERROR_OUTPUT_PARAMETER_NULL
[out] operation_handle แฮนเดิลการดำเนินการที่สร้างขึ้นใหม่ซึ่งต้องส่งไปยัง update() , finish() หรือ abort() หาก operation_handle เป็น NULL begin() จะแสดงผล KM_ERROR_OUTPUT_PARAMETER_NULL

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

struct hw_device_t common

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

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

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

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

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

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

void* context

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

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

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster

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

keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] คีย์ กุญแจที่จะลบ

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

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] export_format รูปแบบที่จะใช้ส่งออกคีย์
[in] key_to_export คีย์ที่จะส่งออก
[in] client_id Blob รหัสไคลเอ็นต์ ซึ่งต้องตรงกับ Blob ที่ระบุใน KM_TAG_APPLICATION_ID ในระหว่างการสร้างคีย์ (หากมี)
[in] app_data Blob ข้อมูลแอปพลิเคชัน ซึ่งต้องตรงกับ Blob ที่ระบุใน KM_TAG_APPLICATION_DATA ในระหว่างการสร้างคีย์ (หากมี)
[out] export_data เนื้อหาคีย์ที่ส่งออก ผู้โทรจะเป็นผู้รับความเป็นเจ้าของ

คําจํากัดความที่บรรทัด 213 ของไฟล์ 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 *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

ดำเนินการเข้ารหัสให้เสร็จสมบูรณ์ซึ่งเริ่มต้นด้วย begin() และทำให้ค่าของ operation_handle เป็นโมฆะ

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

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

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

Flag ของ uint32_t

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

คําจํากัดความที่บรรทัด 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 *characteristics)

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

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

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE และ
  • (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
พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] params อาร์เรย์ของพารามิเตอร์การสร้างคีย์
[out] key_blob แสดงผลคีย์ที่สร้างขึ้น key_blob ต้องไม่ใช่ NULL ผู้เรียกใช้จะถือว่าเป็นเจ้าของ key_blob->key_material และต้อง free()
[out] ลักษณะเฉพาะ แสดงลักษณะของคีย์ที่สร้างขึ้น หากไม่ใช่ค่า 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 *characteristics)

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

โปรดทราบว่าระบบจะไม่แสดงผล KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] key_blob คีย์สําหรับดึงข้อมูลลักษณะ
[in] client_id ข้อมูลรหัสไคลเอ็นต์ หรือ NULL หากไม่มีการเชื่อมโยง
[in] app_id ข้อมูลแอป หรือ NULL หากไม่มีการเชื่อมโยง
[out] ลักษณะเฉพาะ ลักษณะสำคัญ ต้องไม่เท่ากับ 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 *characteristics)

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

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

  • KM_TAG_ALGORITHM;
  • KM_TAG_PURPOSE และ
  • (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
พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] params พารามิเตอร์ที่กําหนดคีย์ที่นําเข้า
[in] params_count จํานวนรายการใน params
[in] key_format ระบุรูปแบบของข้อมูลคีย์ใน key_data
[out] key_blob ใช้เพื่อแสดงผล Blob ของคีย์แบบทึบ ต้องไม่ใช่ NULL ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของ key_material ที่มีอยู่ในนั้น
[out] ลักษณะเฉพาะ ใช้เพื่อแสดงลักษณะของคีย์ที่นำเข้า อาจเป็นค่า NULL ซึ่งในกรณีนี้ ระบบจะไม่แสดงลักษณะ หากไม่ใช่ค่า NULL ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของเนื้อหา และต้องดำเนินการยกเลิกการจัดสรรด้วย keymaster_free_characteristics() โปรดทราบว่าระบบจะไม่แสดงผล KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA

คําจํากัดความที่บรรทัด 186 ของไฟล์ 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_params, keymaster_blob_t *output)

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

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] operation_handle แฮนเดิลการดำเนินการที่แสดงผลโดย begin()
[in] in_params พารามิเตอร์เพิ่มเติมสําหรับการดำเนินการ สําหรับโหมด AEAD จะใช้เพื่อระบุ KM_TAG_ADDITIONAL_DATA โปรดทราบว่าคุณอาจระบุข้อมูลเพิ่มเติมในการเรียกใช้ update() หลายครั้ง แต่ต้องระบุข้อมูลอินพุตก่อน
[in] อินพุต ข้อมูลที่ประมวลผลตามพารามิเตอร์ที่ตั้งค่าไว้ในการเรียกใช้ begin() โปรดทราบว่า update() อาจใช้ข้อมูลทั้งหมดที่ระบุหรือไม่ก็ได้ ดู input_consumed
[out] input_consumed จํานวนข้อมูลที่ update() ใช้ไป หากจำนวนเงินที่ชำระน้อยกว่าจำนวนเงินที่ระบุ ผู้โทรควรชำระส่วนที่เหลือในการเรียกใช้ครั้งถัดไปของ update()
[out] out_params พารามิเตอร์เอาต์พุต ใช้เพื่อแสดงผลข้อมูลเพิ่มเติมจากการดำเนินการ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์พารามิเตอร์เอาต์พุตและต้องปลดปล่อยด้วย keymaster_free_param_set() ระบบอาจตั้งค่า out_params เป็น NULL หากไม่ต้องการพารามิเตอร์เอาต์พุต หาก out_params เป็น NULL และสร้างพารามิเตอร์เอาต์พุตแล้ว begin() จะแสดงผลเป็น KM_ERROR_OUTPUT_PARAMETER_NULL
[out] เอาต์พุต ข้อมูลเอาต์พุต (หากมี) ผู้เรียกใช้จะถือว่าเป็นเจ้าของบัฟเฟอร์ที่จัดสรร output ต้องไม่เป็น NULL

โปรดทราบว่า update() อาจไม่แสดงผลลัพธ์ใดๆ ในกรณีนี้ output->data_length จะเท่ากับ 0 และ output->data อาจมีค่า NULL หรือมีความยาวเป็น 0 (ดังนั้นผู้เรียกใช้จึงควร 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)

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] key_to_upgrade คีย์ Keymaster ที่จะอัปเกรด
[in] upgrade_params พารามิเตอร์ที่จําเป็นสําหรับการอัปเกรดให้เสร็จสมบูรณ์ โดยเฉพาะอย่างยิ่ง คุณจะต้องระบุ KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA หากมีการกําหนดไว้สําหรับคีย์
[out] upgraded_key Blob คีย์ที่อัปเกรดแล้ว

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

เอกสารประกอบสำหรับโครงสร้างนี้สร้างขึ้นจากไฟล์ต่อไปนี้