keymaster2_device مرجع هيكل
#include < keymaster2.h >
وصف مفصل
تعريف جهاز Keymaster2
التعريف في السطر 28 من ملف keymaster2.h .
التوثيق الميداني
keymaster_error_t (* abort) (const مبنى keymaster2_device * dev ، keymaster_operation_handle_t operation_handle) |
إحباط عملية التشفير التي بدأت بـ start () ، وتحرير جميع الموارد الداخلية وإبطال 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 الذي يستخدمه مدير المفاتيح. إن الانتروبيا المضافة من خلال هذه الطريقة مضمونة ألا تكون المصدر الوحيد للإنتروبيا المستخدمة ، ويجب أن تكون وظيفة الخلط آمنة ، بمعنى أنه إذا تم زرع RNG (من أي مصدر) بأي بيانات لا يستطيع المهاجم التنبؤ بها (أو التحكم) ، ثم لا يمكن تمييز خرج RNG عن عشوائي. وبالتالي ، إذا كانت الانتروبيا من أي مصدر جيدة ، فسيكون الناتج جيدًا.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] بيانات البيانات العشوائية المراد خلطها. [في] طول البيانات طول data
.
التعريف في السطر 74 للملف keymaster2.h .
keymaster_error_t (* attest_key) (const مبنى 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> الذي يحتوي على وصف المفتاح.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] key_to_attest مفتاح keymaster الذي سيتم إنشاء شهادة التصديق من أجله. [في] attest_params معلمات تحدد كيفية عمل التصديق. في الوقت الحالي ، المعلمة الوحيدة هي KM_TAG_ALGORITHM ، والتي يجب أن تكون إما KM_ALGORITHM_EC أو KM_ALGORITHM_RSA. يؤدي هذا إلى تحديد مفاتيح المصادقة المخصصة التي سيتم استخدامها لتوقيع الشهادة. [خارج] شهادة_سلسلة مصفوفة من شهادات X.509 بترميز DER. الأول سيكون شهادة key_to_attest
. سوف تتسلسل الإدخالات المتبقية مرة أخرى إلى الجذر. يأخذ المتصل الملكية ويجب عليه إلغاء التخصيص مع keymaster_free_cert_chain.
تعريف في السطر 239 لملف keymaster2.h .
keymaster_error_t (* start) (const مبنى 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 وستنشئ مؤشر العملية الذي يجب تمريره إلى الاستدعاءات اللاحقة للتحديث () أو الانتهاء () أو الإحباط () .
من الأهمية بمكان أن يتم إقران كل مكالمة لبدء () باستدعاء لاحق لإنهاء () أو إحباط () ، للسماح لتطبيق keymaster بتنظيف أي حالة تشغيل داخلية. قد يؤدي الفشل في القيام بذلك إلى تسرب مساحة الحالة الداخلية أو الموارد الداخلية الأخرى وقد يتسبب في النهاية في إرجاع start () KM_ERROR_TOO_MANY_OPERATIONS عند نفاد مساحة العمليات. أي نتيجة بخلاف KM_ERROR_OK من البدء () أو التحديث () أو النهاية () تؤدي ضمنيًا إلى إحباط العملية ، وفي هذه الحالة لا يلزم استدعاء الإحباط () (وسيعيد KM_ERROR_INVALID_OPERATION_HANDLE إذا تم استدعاؤه).
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] غاية الغرض من العملية ، أحد KM_PURPOSE_ENCRYPT أو KM_PURPOSE_DECRYPT أو KM_PURPOSE_SIGN أو KM_PURPOSE_VERIFY. لاحظ أنه بالنسبة لأوضاع AEAD ، فإن التشفير وفك التشفير يعنيان التوقيع والتحقق ، على التوالي ، ولكن يجب تحديدهما كـ KM_PURPOSE_ENCRYPT و KM_PURPOSE_DECRYPT. [في] مفتاح المفتاح الذي سيتم استخدامه للعملية. يجب أن يكون key
غرض متوافق معpurpose
ويجب تلبية جميع متطلبات استخدامه ، أو أن تبدأ () بإرجاع رمز خطأ مناسب.[في] 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. [خارج] عملية_مقبض مقبض العملية الذي تم إنشاؤه حديثًا والذي يجب تمريره للتحديث () أو الإنهاء () أو الإحباط () . إذا كانت process_handle هي NULL ، فستُرجع الدالة start () KM_ERROR_OUTPUT_PARAMETER_NULL.
التعريف في السطر 332 للملف keymaster2.h .
هيكل hw_device_t مشترك |
الطرق الشائعة لجهاز keymaster. يجب أن يكون هذا هو العضو الأول في keymaster_device حيث سيقوم مستخدمو هذه البنية بإرسال hw_device_t إلى مؤشر keymaster_device في السياقات حيث يُعرف hw_device_t مراجع keymaster_device.
التعريف في السطر 35 للملف keymaster2.h .
keymaster_error_t (* config) (const مبنى keymaster2_device * dev ، const keymaster_key_param_set_t * params) |
تكوين keymaster. يجب استدعاء هذه الطريقة مرة واحدة بعد فتح الجهاز وقبل استخدامه. يتم استخدامه لتقديم KM_TAG_OS_VERSION و KM_TAG_OS_PATCHLEVEL إلى مدير المفاتيح. حتى يتم استدعاء هذه الطريقة ، ستُرجع جميع الطرق الأخرى KM_ERROR_KEYMASTER_NOT_CONFIGURED. القيم التي توفرها هذه الطريقة لا يقبلها مدير المفاتيح إلا مرة واحدة لكل عملية تمهيد. ستُرجع المكالمات اللاحقة KM_ERROR_OK ، لكن لا تفعل شيئًا.
إذا كان تنفيذ keymaster في أجهزة آمنة وكان إصدار نظام التشغيل وقيم مستوى التصحيح المقدمة لا تتطابق مع القيم المقدمة للأجهزة الآمنة بواسطة أداة تحميل التشغيل (أو إذا لم يوفر برنامج bootloader قيمًا) ، فستقوم هذه الطريقة بإرجاع KM_ERROR_INVALID_ARGUMENT ، وجميع ستستمر الطرق الأخرى في إرجاع KM_ERROR_KEYMASTER_NOT_CONFIGURED.
التعريف في السطر 58 من ملف keymaster2.h .
* سياق باطل |
التعريف في السطر 37 للملف keymaster2.h .
keymaster_error_t (* delete_all_keys) (const مبنى keymaster2_device * dev) |
يحذف جميع المفاتيح الموجودة في مخزن مفاتيح الجهاز. تُستخدم عند إعادة تعيين ملف تخزين المفاتيح بالكامل. بعد استدعاء هذه الوظيفة ، سيكون من المستحيل استخدام أي نقاط رئيسية تم إنشاؤها أو استيرادها مسبقًا لأي عمليات.
هذه الوظيفة اختيارية ويجب تعيينها على NULL إذا لم يتم تنفيذها.
- المعلمات
[في] ديف هيكل جهاز keymaster.
التعريف في السطر 288 للملف keymaster2.h .
keymaster_error_t (* delete_key) (const مبنى keymaster2_device * dev ، const keymaster_key_blob_t * key) |
يحذف المفتاح أو زوج المفاتيح المرتبط بنقطة المفاتيح. بعد استدعاء هذه الوظيفة ، سيكون من المستحيل استخدام المفتاح لأية عمليات أخرى. يمكن تطبيقها على المفاتيح من جذور الثقة الأجنبية (المفاتيح غير قابلة للاستخدام في ظل جذر الثقة الحالي).
هذه الوظيفة اختيارية ويجب تعيينها على NULL إذا لم يتم تنفيذها.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] مفتاح المفتاح المراد حذفه.
التعريف في السطر 276 للملف keymaster2.h .
keymaster_error_t (* export_key) (const مبنى 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_blob_t * export_data ، keymaster_blob_t * export_data |
يصدر مفتاحًا عامًا أو متماثلًا ، ويعيد مصفوفة بايت بالتنسيق المحدد.
لاحظ أنه لا يُسمح بتصدير المفتاح المتماثل إلا إذا تم إنشاء المفتاح باستخدام KM_TAG_EXPORTABLE ، وفقط إذا تم استيفاء جميع متطلبات استخدام المفتاح (مثل المصادقة).
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] export_format الشكل الذي سيتم استخدامه لتصدير المفتاح. [في] key_to_export مفتاح التصدير. [في] معرف_العميل كائن معرف العميل ، والذي يجب أن يتطابق مع blob المقدم في KM_TAG_APPLICATION_ID أثناء إنشاء المفتاح (إن وجد). [في] معلومات التطبيق كائن بيانات التطبيق ، والذي يجب أن يتطابق مع البيانات الثنائية الكبيرة المتوفرة في KM_TAG_APPLICATION_DATA أثناء إنشاء المفتاح (إن وجد). [خارج] تصدير_بيانات المواد الرئيسية التي تم تصديرها. المتصل يفترض الملكية.
التعريف في السطر 213 للملف keymaster2.h .
keymaster_error_t (* finish) (const بنية 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_tm * out_params ) |
ينهي عملية التشفير التي تبدأ بـ start () ويلغي operation_handle
.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] عملية_مقبض تم إرجاع مؤشر العملية بواسطة start () . سيتم إبطال هذا المقبض. [في] in_params معلمات إضافية للعملية. بالنسبة لأوضاع AEAD ، يتم استخدام هذا لتحديد KM_TAG_ADDITIONAL_DATA ، ولكن فقط في حالة عدم تقديم بيانات إدخال للتحديث () . [في] الإدخال البيانات المراد معالجتها ، وفقًا للمعايير المحددة في استدعاء البدء () . يجب أن تستهلك النهاية () جميع البيانات المقدمة أو تُرجع KM_ERROR_INVALID_INPUT_LENGTH. [في] التوقيع التوقيع المراد التحقق منه إذا كان الغرض المحدد في استدعاء start () هو KM_PURPOSE_VERIFY. [خارج] انتاج بيانات الإخراج إن وجدت. يفترض المتصل ملكية المخزن المؤقت المخصص.
إذا كانت العملية التي يتم الانتهاء منها هي التحقق من صحة التوقيع أو فشل التحقق من وضع AEAD ثم إنهاء () سيعيد KM_ERROR_VERIFICATION_FAILED.
تعريف في السطر 405 لملف keymaster2.h .
uint32_t الأعلام |
راجع العلامات المحددة لـ keymaster0_devices :: flags في keymaster_common.h . تستخدم فقط للتوافق مع الإصدارات السابقة ؛ يجب أن تقوم أجهزة keymaster2 بتعيين هذا على صفر.
التعريف في السطر 43 للملف keymaster2.h .
keymaster_error_t (* create_key) (const construct keymaster2_device * dev ، const keymaster_key_param_set_t * params ، keymaster_key_blob_t * key_blob ، keymaster_key_characteristics_t * features) |
يولد مفتاحًا ، أو زوجًا من المفاتيح ، ويعيد blob مفتاحًا و / أو وصفًا للمفتاح.
يتم تعريف معلمات إنشاء المفاتيح على أنها أزواج من علامة / قيمة مدير المفاتيح ، يتم توفيرها في 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
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] بارامز صفيف من مفتاح إنشاء بارام [خارج] key_blob إرجاع المفتاح الذي تم إنشاؤه. يجب ألا يكون key_blob
. يفترض المتصل ملكية key_blob-> key_material ويجب تحريرها ().[خارج] مميزات إرجاع خصائص المفتاح الذي تم إنشاؤه ، إذا لم يكن NULL. إذا لم يكن NULL ، يفترض المتصل الملكية ويجب عليه إلغاء التخصيص مع keymaster_free_characteristics () . لاحظ أنه لن يتم إرجاع KM_TAG_ROOT_OF_TRUST و KM_TAG_APPLICATION_ID و KM_TAG_APPLICATION_DATA أبدًا.
التعريف في السطر 112 للملف keymaster2.h .
تُرجع خصائص المفتاح المحدد ، أو 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 أبدًا.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] key_blob مفتاح استعادة الخصائص من. [في] معرف_العميل بيانات معرّف العميل ، أو NULL في حالة عدم ارتباط أي منها. [في] معرف التطبيق بيانات التطبيق ، أو NULL إذا لم تقترن. [خارج] مميزات الخصائص الرئيسية. يجب ألا تكون فارغة. يفترض المتصل ملكية المحتويات ويجب عليه إلغاء التخصيص مع keymaster_free_characteristics () .
التعريف الموجود في السطر 139 للملف keymaster2.h .
keymaster_error_t (* import_key) (const بناء 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 ) |
يستورد مفتاحًا ، أو زوجًا من المفاتيح ، ويعيد blob مفتاحًا و / أو وصفًا للمفتاح.
تُعرَّف معظم معلمات الاستيراد الرئيسية على أنها أزواج قيمة / علامة مدير المفاتيح ، ويتم توفيرها في "المعلمات". انظر 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
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] بارامز المعلمات التي تحدد المفتاح المستورد. [في] بارامس_كونت عدد الإدخالات في params
.[في] key_format يحدد تنسيق البيانات الرئيسية في key_data. [خارج] key_blob تُستخدم لإرجاع النقطة الرئيسية غير الشفافة. يجب أن تكون غير فارغة. يفترض المتصل ملكية المادة الرئيسية المضمنة. [خارج] مميزات يُستخدم لإرجاع خصائص المفتاح المستورد. قد يكون 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_paramblset_t * out_params ، keymaster_key_param_set_t * out_params ، |
يوفر البيانات لعملية تشفير جارية ، وربما يستقبلها ، والتي تبدأ بـ start () .
إذا كانت process_handle غير صالحة ، فسيعرض التحديث () KM_ERROR_INVALID_OPERATION_HANDLE.
update () قد لا يستهلك كل البيانات المتوفرة في مخزن البيانات المؤقت. update () سيعيد الكمية المستهلكة في * data_consumed. يجب على المتصل تقديم البيانات غير المستهلكة في مكالمة لاحقة.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] عملية_مقبض تم إرجاع مؤشر العملية بواسطة start () . [في] in_params معلمات إضافية للعملية. بالنسبة لأوضاع AEAD ، يتم استخدام هذا لتحديد KM_TAG_ADDITIONAL_DATA. لاحظ أنه قد يتم توفير بيانات إضافية في مكالمات متعددة للتحديث () ، ولكن فقط حتى يتم توفير بيانات الإدخال. [في] الإدخال البيانات المراد معالجتها ، وفقًا للمعايير المحددة في استدعاء البدء () . لاحظ أن التحديث () قد يستهلك أو لا يستهلك جميع البيانات المقدمة. انظر input_consumed
.[خارج] إدخال_مستهلك كمية البيانات التي تم استهلاكها بواسطة update () . إذا كان هذا أقل من المبلغ المقدم ، فيجب على المتصل توفير الباقي في مكالمة لاحقة للتحديث () . [خارج] out_params معلمات الإخراج. تُستخدم لإرجاع بيانات إضافية من العملية. يأخذ المتصل ملكية مصفوفة معلمات الإخراج ويجب أن يحررها باستخدام keymaster_free_param_set () . يمكن تعيين out_params إلى NULL إذا لم يكن من المتوقع وجود معلمات إخراج. إذا كانت قيمة out_params هي NULL ، وتم إنشاء معلمات الإخراج ، فإن start () ستعيد KM_ERROR_OUTPUT_PARAMETER_NULL. [خارج] انتاج بيانات الإخراج إن وجدت. يفترض المتصل ملكية المخزن المؤقت المخصص. يجب ألا يكون الإخراج فارغًا.
لاحظ أن update () قد لا يوفر أي إخراج ، وفي هذه الحالة سيكون الناتج-> data_length صفرًا ، وقد تكون البيانات output-> فارغة أو ذات طول صفري (لذلك يجب على المتصل دائمًا تحريرها ()).
التعريف في السطر 376 للملف keymaster2.h .
keymaster_error_t (* Upgrade_key) (const مبنى keymaster2_device * dev ، const keymaster_key_blob_t * key_to_upgrade ، const keymaster_key_param_set_t * Upgrade_params ، keymaster_key_blob_t * Upged_key) |
ترقيات مفتاح قديم. يمكن أن تصبح المفاتيح "قديمة" بطريقتين: يمكن ترقية Keymaster إلى إصدار جديد ، أو يمكن تحديث النظام لإبطال إصدار نظام التشغيل و / أو مستوى التصحيح. في كلتا الحالتين ، ستؤدي محاولات استخدام مفتاح قديم إلى قيام مدير المفاتيح بإرجاع KM_ERROR_KEY_REQUIRES_UPGRADE. يجب استدعاء هذه الطريقة بعد ذلك لترقية المفتاح.
- المعلمات
[في] ديف هيكل جهاز keymaster. [في] key_to_upgrade مفتاح keymaster للترقية. [في] Upgrade_params المعلمات اللازمة لإكمال الترقية. على وجه الخصوص ، سيكون KM_TAG_APPLICATION_ID و KM_TAG_APPLICATION_DATA مطلوبين إذا تم تعريفهما للمفتاح. [خارج] Upged_key النقطة الرئيسية التي تمت ترقيتها.
التعريف في السطر 260 للملف keymaster2.h .
تم إنشاء وثائق هذه البنية من الملف التالي:
- الأجهزة / libhardware / تشمل / الأجهزة / keymaster2.h