#include < keymaster2.h >

حقول البيانات
struct hw_device_t	شائعة

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)

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

المعلمات

[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 بتنظيف أيّ حالة عملية داخلية. وقد يؤدي عدم إجراء ذلك إلى تسرب مساحة الحالة الداخلية أو موارد داخلية أخرى، وقد يؤدي في النهاية إلى عرض القيمة 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.
[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.

التعريف في السطر 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. يجب استدعاء هذه الطريقة مرة واحدة بعد فتح الجهاز وقبل استخدامه. ويُستخدَم هذا الرمز لتوفير KM_TAG_OS_VERSION وKM_TAG_OS_PATCHLEVEL لخدمة Keymaster. إلى أن يتم استدعاء هذه الطريقة، ستُعرِض جميع الطرق الأخرى الخطأ KM_ERROR_KEYMASTER_NOT_CONFIGURED. لا يقبل برنامج Keymaster القيم المقدَّمة من خلال هذه الطريقة إلا مرة واحدة لكل عملية تشغيل. ستؤدي المكالمات اللاحقة إلى عرض القيمة 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)

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

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

المعلمات

[in] dev بنية جهاز Keymaster

التعريف في السطر 288 من الملف keymaster2.h .

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

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

هذه الدالة اختيارية ويجب ضبطها على 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	ملف نصي لمعرّف العميل، والذي يجب أن يتطابق مع الملف النصي المقدَّم في KM_TAG_APPLICATION_ID أثناء إنشاء المفتاح (إن توفّر)
[in]	app_data	مجموعة بيانات التطبيق التي يجب أن تتطابق مع مجموعة البيانات المقدَّمة في 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]	output	بيانات الإخراج، إن وُجدت يتولّى المُتصل ملكية المخزن المؤقت المخصّص.

إذا كانت العملية التي يتمّ إنهاؤها هي عملية إثبات صحة توقيع أو عملية فك تشفير في وضع 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 *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	صفيف مَعلمات إنشاء المفتاح
[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.

التعريف في السطر 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]	الخصائص	السمات الرئيسية يجب ألا تكون فارغة. يتولّى المُرسِل ملكية المحتوى ويجب أن يُلغي تخصيصه باستخدام دالة 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)

تستورد مفتاحًا أو مفتاحَي تشفير، وتُعيد رمزًا مميّزًا للمفتاح و/أو وصفًا للمفتاح.

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

يُرجى العلم أنّ دالة 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 إلى إصدار جديد، أو يمكن تحديث النظام لإبطال إصدار نظام التشغيل و/أو مستوى تصحيح الخطأ. وفي كلتا الحالتَين، ستؤدي محاولات استخدام مفتاح قديم إلى عرض 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	ملف نصي للمفتاح تمت ترقيته

التعريف في السطر 260 من الملف keymaster2.h .

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

hardware/libhardware/include/hardware/ keymaster2.h

مرجع بنية keymaster2_device

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

وصف مفصّل

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