مرجع بنية keymaster1_device

حقول البيانات
مرجع بنية keymaster1_device

#include < keymaster1.h >

حقول البيانات

struct hw_device_t   شائعة
 
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 .

مستندات الحقل

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

تؤدي هذه الوظيفة إلى إيقاف عملية تشفير بدأت باستخدام الوسيطة 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)

تضيف هذه القيمة عنصرًا عشوائيًا إلى مولد الأرقام العشوائية الذي يستخدمه Keymaster. لا يُضمن أن تكون المَعلمة العشوائية المُضافة من خلال هذه الطريقة هي المصدر الوحيد للمَعلمة العشوائية المستخدَمة، ويجب أن تكون دالة الاختلاط آمنة، بمعنى أنّه إذا تمّت تعبئة مولد الأرقام العشوائية (من أي مصدر) بأي بيانات لا يمكن للمهاجم توقّعها (أو التحكّم فيها)، لا يمكن تمييز الناتج من مولد الأرقام العشوائية عن الأرقام العشوائية. وبالتالي، إذا كانت قيمة القصور من أي مصدر جيدة، سيكون الناتج جيدًا.

المعلمات
[in] dev بنية جهاز Keymaster
[in] البيانات بيانات عشوائية يتم دمجها
[in] data_length مدة data .

التعريف في السطر 242 من الملف keymaster1.h .

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)

يبدأ عملية تشفير باستخدام المفتاح المحدّد. إذا كان كل شيء على ما يرام، ستعرِض الدالة begin() القيمة KM_ERROR_OK وستُنشئ معرّف عملية يجب تمريره إلى عمليات الاستدعاء اللاحقة للدالة update() أو finish() أو abort() .

من المهم أن يتم إقران كلّ طلب للوظيفة begin() بطلب لاحق للوظيفة finish() أو abort() ، للسماح لعملية تنفيذ Keymaster بتنظيف أيّ حالة عملية داخلية. وقد يؤدي عدم إجراء ذلك إلى تسرب مساحة الحالة الداخلية أو موارد داخلية أخرى، وقد يؤدي في النهاية إلى عرض القيمة KM_ERROR_TOO_MANY_OPERATIONS في القيمة المعروضة من الدالة begin() عند نفاد المساحة للعمليات. تؤدي أي نتيجة غير 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. بالنسبة إلى العمليات التي تتطلّب مفتاح تشفير عشوائي أو مفتاح تشفير السلسلة، في المفاتيح التي تم إنشاؤها باستخدام علامة KM_TAG_CALLER_NONCE، قد تحتوي مَعلمات in_params على علامة KM_TAG_NONCE. بالنسبة إلى عمليات AEAD، يتم تحديد KM_TAG_CHUNK_SIZE هنا.
[out] out_params مَعلمات الإخراج تُستخدَم لإرجاع بيانات إضافية من عملية الإعداد، لا سيما لإرجاع مفتاح الالتفاف أو المفتاح العشوائي من العمليات التي تُنشئ مفتاح الالتفاف أو المفتاح العشوائي. يحصل المُرسِل على ملكية مصفوفة مَعلمات الإخراج ويجب تحريرها باستخدام keymaster_free_param_set() . يمكن ضبط out_params على NULL إذا لم يكن من المتوقّع وجود مَعلمات ناتجة. إذا كانت out_params فارغة، وتم إنشاء مَعلمات الإخراج، begin() سيعرض الخطأ KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] operation_handle معرّف العملية الذي تم إنشاؤه حديثًا والذي يجب تمريره إلى update() أو finish() أو abort() . إذا كان معرّف_العملية يساوي 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)

لحذف جميع المفاتيح في متجر مفاتيح الأجهزة تُستخدَم عند إعادة ضبط ملف تخزين المفاتيح بالكامل. بعد استدعاء هذه الدالة، سيكون من المستحيل استخدام أيّ مجموعات بيانات مفاتيح تم إنشاؤها أو استيرادها في السابق لأيّ عمليات.

هذه الدالة اختيارية ويجب ضبطها على NULL في حال عدم تنفيذها.

المعلمات
[in] dev بنية جهاز Keymaster

التعريف في السطر 407 من الملف keymaster1.h .

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

تؤدي هذه العملية إلى حذف المفتاح أو مفتاحَي التشفير المرتبطَين بمجموعة مفاتيح التشفير. بعد استدعاء هذه الدالة، سيكون من المستحيل استخدام المفتاح لأي عمليات أخرى. يمكن تطبيقها على مفاتيح من جُذور ثقة أجنبية (مفاتيح لا يمكن استخدامها بموجب جذر الثقة الحالي).

هذه الدالة اختيارية ويجب ضبطها على 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 .

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)

تُنهي عملية تشفير بدأت باستخدام begin() وتبطل operation_handle .

المعلمات
[in] dev بنية جهاز Keymaster
[in] operation_handle معرّف العملية الذي تم إرجاعه من الدوالّ التالية: begin() . سيتم إلغاء هذا الاسم المعرِّف.
[in] params مَعلمات إضافية للعملية في أوضاع AEAD، يتم استخدام هذا الإجراء لتحديد KM_TAG_ADDITIONAL_DATA، ولكن فقط في حال عدم تقديم بيانات إدخال إلى update() .
[in] التوقيع التوقيع الذي سيتم التحقّق منه إذا كان الغرض المحدّد في begin() هو KM_PURPOSE_VERIFY.
[out] output بيانات الإخراج، إن وُجدت يتولّى المُتصل ملكية المخزن المؤقت المخصّص.

إذا كانت العملية التي يتمّ إنهاؤها هي عملية إثبات صحة توقيع أو عملية فك تشفير في وضع AEAD وتعذّر إثبات صحتها، ستُعرِض الدالة finish() الخطأ KM_ERROR_VERIFICATION_FAILED.

التعريف في السطر 521 من الملف keymaster1.h .

علامات uint32_t

اطّلِع على العلامات المحدّدة لمفتاح keymaster0_devices::flags فيملف keymaster_common.h

التعريف في السطر 46 من الملف keymaster1.h .

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)

تُنشئ مفتاحًا أو زوجًا من مفاتيح التشفير، مع عرض كتلة مفتاح و/أو وصف للمفتاح.

يتمّ تحديد مَعلمات إنشاء المفاتيح على أنّها أزواج علامة/قيمة لمفتاح التحكم الرئيسي، ويتمّ تقديمها في 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 فارغة. يُفترض أنّ المُتصل يملك key_blob->key_material ويجب أن يُطلق سراحه باستخدام free()‎.
[out] الخصائص تعرِض خصائص المفتاح الذي تم إنشاؤه، إذا لم تكن القيمة فارغة. إذا لم تكن القيمة فارغة، يتولّى المُرسِل الملكية ويجب إلغاء تخصيصها باستخدام الإجراء 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)
تم إيقافه نهائيًا:
لإنشاء مفتاحَي تشفير عام والخاص إنّ ملف تخزين المفاتيح الذي يتم إرجاعه غير شفاف ويجب تقديمه لاحقًا للتوقيع والتحقّق.

يتم عرض القيمة 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 .

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_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 تُستخدَم لإرجاع كتلة مفتاح غير شفافة. يجب أن يكون غير NULL. يفترض المُتصل ملكية key_material المضمّنة.
[out] الخصائص تُستخدَم لعرض خصائص المفتاح الذي تم استيراده. قد تكون قيمة 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). إنّ ملفّ البيانات المُجمَّعة للمفتاح الذي يتم إرجاعه غير شفاف، وسيتم توفيره لاحقًا للتوقيع والتحقّق.

يتم عرض القيمة 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 فارغة، وتم إنشاء مَعلمات الإخراج، begin() سيعرض الخطأ KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] output بيانات الإخراج، إن وُجدت يتولّى المُتصل ملكية المخزن المؤقت المخصّص. يجب ألا يكون الإخراج فارغًا.

يُرجى العلم أنّ دالة update() قد لا تقدّم أيّ إخراج، وفي هذه الحالة سيكون طول السلسلة output->data_length يساوي صفرًا، وقد تكون السلسلة output->data إما NULL أو ذات طول يساوي صفرًا (لذلك على المُرسِل دائمًا استخدام دالة 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 .

تم إنشاء مستندات هذه البنية من الملف التالي: