ข้อมูลอ้างอิง Struct keymaster1_device

ข้อมูลอ้างอิง Struct keymaster1_device

#include < keymaster1.h >

ฟิลด์ข้อมูล

struct hw_device_t   common
 
uint32_t  client_version
 
uint32_t  flags
 
void *  context
 
int(*  generate_keypair )(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  import_keypair )(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  get_keypair_public )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
 
int(*  delete_keypair )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
 
int(*  delete_all )(const struct keymaster1_device *dev)
 
int(*  sign_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
 
int(*  verify_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
 
keymaster_error_t (*  get_supported_algorithms )(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)
 
keymaster_error_t (*  get_supported_block_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_padding_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_digests )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)
 
keymaster_error_t (*  get_supported_import_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  get_supported_export_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  add_rng_entropy )(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length)
 
keymaster_error_t (*  generate_key )(const struct keymaster1_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 keymaster1_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 keymaster1_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 keymaster1_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 (*  delete_key )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)
 
keymaster_error_t (*  delete_all_keys )(const struct keymaster1_device *dev)
 
keymaster_error_t (*  begin )(const struct keymaster1_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 keymaster1_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 keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
 
keymaster_error_t (*  abort )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle)
 

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

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

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

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

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

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

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

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] เพิ่มเติม ข้อมูลแบบสุ่มที่จะผสมเข้าด้วยกัน
[in] data_length ความยาวของ data .

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

เริ่มการดำเนินการเข้ารหัสโดยใช้คีย์ที่ระบุ หากทุกอย่างเรียบร้อยดี 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 สําหรับการดำเนินการ AEAD ให้ระบุ KM_TAG_CHUNK_SIZE ที่นี่
[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

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

uint32_t client_version

การดำเนินการนี้เลิกใช้งานแล้ว ใช้ช่อง "module_api_version" และ "hal_api_version" ใหม่ในการเริ่มต้น keymaster_module แทน

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

struct hw_device_t common

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

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

void* context

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

int(* delete_all)(const struct keymaster1_device *dev)
เลิกใช้งานแล้ว:
ลบคีย์ทั้งหมดในคีย์สโตร์ฮาร์ดแวร์ ใช้เมื่อรีเซ็ตคีย์สโตร์โดยสมบูรณ์

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

แสดงผล 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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

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

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

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

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

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

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

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

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

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

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

int(* delete_keypair)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
เลิกใช้งานแล้ว:
ลบคู่คีย์ที่เชื่อมโยงกับบล็อกคีย์

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

แสดงผล 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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

keymaster_error_t (* export_key)(const struct keymaster1_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)

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

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] export_format รูปแบบที่จะใช้ส่งออกคีย์
[in] key_to_export คีย์ที่จะส่งออก
[out] export_data เนื้อหาคีย์ที่ส่งออก ผู้โทรจะเป็นผู้รับความเป็นเจ้าของ
[out] export_data_length ความยาวของ export_data

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

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

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

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

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

Flag ของ uint32_t

ดู Flag ที่กําหนดไว้สําหรับ keymaster0_devices::flags ใน keymaster_common.h

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

สร้างคีย์หรือคู่คีย์ โดยส่งคืน 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 อาร์เรย์ของพารามิเตอร์การสร้างคีย์
[in] params_count ความยาวของ 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

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

int(* generate_keypair)(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
เลิกใช้งานแล้ว:
สร้างคีย์สาธารณะและส่วนตัว Blob คีย์ที่แสดงผลจะทึบแสงและต้องระบุสำหรับการลงชื่อและยืนยันในภายหลัง

แสดงผล: 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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

keymaster_error_t (* get_key_characteristics)(const struct keymaster1_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_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA

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

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

int(* get_keypair_public)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
เลิกใช้งานแล้ว:
รับส่วนของคีย์สาธารณะในคู่คีย์ คีย์สาธารณะต้องอยู่ในรูปแบบอาร์เรย์ไบต์ที่เข้ารหัส X.509 (มาตรฐาน Java)

แสดงผล: 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0 ในกรณีที่เกิดข้อผิดพลาด ระบบไม่ควรจัดสรร x509_data

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

keymaster_error_t (* get_supported_algorithms)(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)

รับอัลกอริทึมที่รองรับ

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[out] อัลกอริทึม อาร์เรย์ของอัลกอริทึมที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] algorithms_length ความยาวของ algorithms .

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

keymaster_error_t (* get_supported_block_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)

รับโหมดการบล็อกที่รองรับสำหรับอัลกอริทึมที่ระบุ

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] อัลกอริทึม อัลกอริทึมที่ระบบจะแสดงผลโหมดที่รองรับ
[out] โหมด อาร์เรย์ของโหมดที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] modes_length ความยาวของ modes .

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

keymaster_error_t (* get_supported_digests)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)

รับข้อมูลสรุปที่รองรับสำหรับอัลกอริทึมที่ระบุ ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของอาร์เรย์ที่จัดสรร

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] อัลกอริทึม อัลกอริทึมที่ระบบจะแสดงข้อมูลสรุปที่รองรับ
[out] สรุป อาร์เรย์ของข้อมูลสรุปที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] digests_length ความยาวของ digests .

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

keymaster_error_t (* get_supported_export_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

รับรูปแบบการส่งออกคีย์ที่รองรับสำหรับคีย์ของอัลกอริทึมที่ระบุ ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของอาร์เรย์ที่จัดสรร

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] อัลกอริทึม อัลกอริทึมที่ระบบจะแสดงผลรูปแบบที่รองรับ
[out] รูปแบบ รูปแบบที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] formats_length ความยาวของ formats .

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

keymaster_error_t (* get_supported_import_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

รับรูปแบบการนําเข้าคีย์ที่รองรับสําหรับคีย์ของอัลกอริทึมที่ระบุ ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของอาร์เรย์ที่จัดสรร

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] อัลกอริทึม อัลกอริทึมที่ระบบจะแสดงผลรูปแบบที่รองรับ
[out] รูปแบบ รูปแบบที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] formats_length ความยาวของ formats .

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

keymaster_error_t (* get_supported_padding_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)

รับโหมดการเติมที่รองรับสําหรับอัลกอริทึมที่ระบุ ผู้เรียกใช้จะถือว่าตนเป็นเจ้าของอาร์เรย์ที่จัดสรร

พารามิเตอร์
[in] dev โครงสร้างอุปกรณ์ Keymaster
[in] อัลกอริทึม อัลกอริทึมที่ระบบจะแสดงผลโหมดการเติมที่รองรับ
[out] โหมด อาร์เรย์ของโหมดการเติมที่รองรับ ผู้เรียกใช้จะเป็นเจ้าของอาร์เรย์และต้อง free()
[out] modes_length ความยาวของ modes .

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

นําเข้าคีย์หรือคู่คีย์ โดยแสดงผล 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_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID และ KM_TAG_APPLICATION_DATA

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

int(* import_keypair)(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
เลิกใช้งานแล้ว:
นําเข้าคู่คีย์สาธารณะและส่วนตัว คีย์ที่นำเข้าจะอยู่ในรูปแบบ PKCS#8 ที่มีการเข้ารหัส DER (มาตรฐาน Java) Blob คีย์ที่แสดงผลจะทึบแสงและจะใช้สำหรับการลงนามและการยืนยันในภายหลัง

แสดงผล: 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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

int(* sign_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
เลิกใช้งานแล้ว:
เซ็นข้อมูลโดยใช้บล็อกคีย์ที่สร้างไว้ก่อนหน้านี้ ซึ่งจะใช้คีย์แบบไม่สมมาตรหรือคีย์ลับก็ได้

แสดงผล: 0 เมื่อสําเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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

keymaster_error_t (* update)(const struct keymaster1_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() เสมอ)

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

int(* verify_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
เลิกใช้งานแล้ว:
ยืนยันข้อมูลที่ลงนามด้วยบล็อกคีย์ ซึ่งจะใช้คีย์แบบไม่สมมาตรหรือคีย์ลับก็ได้

แสดงผล: 0 เมื่อยืนยันสำเร็จ หรือรหัสข้อผิดพลาดที่น้อยกว่า 0

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


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