keymaster2_device مرجع الهيكل
#include < keymaster2.h >
وصف تفصيلي
تعريف جهاز 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 لا يمكن تمييزه عن العشوائي. وبالتالي، إذا كانت الإنتروبيا من أي مصدر جيدة، فسيكون الناتج جيدًا.
- حدود
[في] ديف هيكل جهاز keymaster. [في] بيانات بيانات عشوائية ليتم خلطها. [في] طول البيانات طول 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): قم بوصف محتويات الشهادة بمزيد من التفاصيل). ستحتوي الشهادة على ملحق بمعرف الكائن 1.3.6.1.4.1.11129.2.1.17 وقيمة محددة في <TODO:swillden – أدخل الرابط هنا> الذي يحتوي على وصف المفتاح.
- حدود
[في] ديف هيكل جهاز keymaster. [في] key_to_attest المفتاح الرئيسي الذي سيتم إنشاء شهادة التصديق عليه. [في] attest_params المعلمات التي تحدد كيفية القيام بالتصديق. في الوقت الحالي، المعلمة الوحيدة هي KM_TAG_ALGORITHM، والتي يجب أن تكون إما KM_ALGORITHM_EC أو KM_ALGORITHM_RSA. يؤدي هذا إلى تحديد مفاتيح التصديق المتوفرة التي سيتم استخدامها لتوقيع الشهادة. [خارج] 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 غرض, 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 وينشئ مقبض العملية الذي يجب تمريره إلى الاستدعاءات اللاحقة للتحديث() أو Finish() أو abort() .
من المهم جدًا أن يتم إقران كل استدعاء للبدء() مع استدعاء لاحق للإنهاء() أو إحباط() ، للسماح لتطبيق مدير المفاتيح بتنظيف أي حالة تشغيل داخلية. قد يؤدي الفشل في القيام بذلك إلى تسرب مساحة الحالة الداخلية أو الموارد الداخلية الأخرى وقد يؤدي في النهاية إلى إرجاع KM_ERROR_TOO_MANY_OPERATIONS عند نفاد المساحة للعمليات. أي نتيجة بخلاف KM_ERROR_OK من begin() أو update() أو Finish() تؤدي إلى إحباط العملية ضمنيًا، وفي هذه الحالة لا يلزم استدعاء abort() (وسيرجع 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ويجب استيفاء جميع متطلبات الاستخدام الخاصة به، أو ستعيد begin() رمز الخطأ المناسب.[في] 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، وتم إنشاء معلمات الإخراج، فستُرجع begin() KM_ERROR_OUTPUT_PARAMETER_NULL. [خارج] Operation_handle مقبض العملية الذي تم إنشاؤه حديثًا والذي يجب تمريره إلى update() أو Finish() أو abort() . إذا كانت قيمة Operation_handle NULL، فستُرجع الدالة begin() 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 (* تكوين)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
تكوين مدير المفاتيح. ويجب استدعاء هذه الطريقة مرة واحدة بعد فتح الجهاز وقبل استخدامه. يتم استخدامه لتوفير KM_TAG_OS_VERSION وKM_TAG_OS_PATCHLEVEL إلى مدير المفاتيح. حتى يتم استدعاء هذا الأسلوب، ستُرجع كافة الطرق الأخرى KM_ERROR_KEYMASTER_NOT_CONFIGURED. يتم قبول القيم التي توفرها هذه الطريقة بواسطة keymaster مرة واحدة فقط لكل تمهيد. ستعيد المكالمات اللاحقة KM_ERROR_OK، لكن لا تفعل شيئًا.
إذا كان تطبيق keymaster في جهاز آمن وكان إصدار نظام التشغيل وقيم مستوى التصحيح المقدمة لا تتطابق مع القيم المقدمة إلى الجهاز الآمن بواسطة أداة تحميل التشغيل (أو إذا لم يقدم أداة تحميل التشغيل قيمًا)، فسترجع هذه الطريقة KM_ERROR_INVALID_ARGUMENT، وكل شيء ستستمر الطرق الأخرى في إرجاع KM_ERROR_KEYMASTER_NOT_CONFIGURED.
التعريف في السطر 58 من الملف keymaster2.h .
| سياق باطل* |
التعريف في السطر 37 من الملف keymaster2.h .
| keymaster_error_t (*delete_all_keys)(بنية أساسية keymaster2_device *dev) |
يحذف جميع المفاتيح الموجودة في مخزن مفاتيح الأجهزة. يُستخدم عند إعادة ضبط ملف تخزين المفاتيح بالكامل. بعد استدعاء هذه الوظيفة، سيكون من المستحيل استخدام أي نقاط مفاتيح تم إنشاؤها أو استيرادها مسبقًا لأية عمليات.
هذه الوظيفة اختيارية ويجب ضبطها على NULL إذا لم يتم تنفيذها.
- حدود
[في] ديف هيكل جهاز keymaster.
التعريف في السطر 288 من الملف keymaster2.h .
| keymaster_error_t (*delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
يحذف المفتاح، أو زوج المفاتيح، المرتبط بنقطة المفتاح. بعد استدعاء هذه الوظيفة، سيكون من المستحيل استخدام المفتاح لأي عمليات أخرى. يمكن تطبيقه على المفاتيح من جذور الثقة الأجنبية (المفاتيح غير قابلة للاستخدام ضمن جذر الثقة الحالي).
هذه الوظيفة اختيارية ويجب ضبطها على NULL إذا لم يتم تنفيذها.
- حدود
[في] ديف هيكل جهاز keymaster. [في] مفتاح المفتاح المراد حذفه.
التعريف في السطر 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، وفقط إذا تم استيفاء كافة متطلبات استخدام المفتاح (مثل المصادقة).
- حدود
[في] ديف هيكل جهاز keymaster. [في] Export_format التنسيق الذي سيتم استخدامه لتصدير المفتاح. [في] key_to_export مفتاح التصدير. [في] معرف العميل كائن ثنائي كبير الحجم لمعرف العميل، والذي يجب أن يتطابق مع الكائن الثنائي الكبير المقدم في KM_TAG_APPLICATION_ID أثناء إنشاء المفتاح (إن وجد). [في] معلومات التطبيق كائن ثنائي كبير الحجم لبيانات التطبيق، والذي يجب أن يتطابق مع الكائن الثنائي الكبير المتوفر في KM_TAG_APPLICATION_DATA أثناء إنشاء المفتاح (إن وجد). [خارج] 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 .
- حدود
[في] ديف هيكل جهاز keymaster. [في] Operation_handle تم إرجاع مقبض العملية بواسطة begin() . سيتم إبطال هذا المقبض. [في] in_params معلمات إضافية للعملية. بالنسبة لأوضاع AEAD، يُستخدم هذا لتحديد KM_TAG_ADDITIONAL_DATA، ولكن فقط في حالة عدم توفير بيانات إدخال للتحديث() . [في] مدخل البيانات المراد معالجتها، وفقًا للمعلمات المحددة في استدعاء البدء () . يجب أن تستهلك الدالة Finish() كافة البيانات المقدمة أو تُرجع KM_ERROR_INVALID_INPUT_LENGTH. [في] إمضاء التوقيع المطلوب التحقق منه إذا كان الغرض المحدد في استدعاء begin() هو KM_PURPOSE_VERIFY. [خارج] انتاج بيانات الإخراج إن وجدت. يفترض المتصل ملكية المخزن المؤقت المخصص.
إذا كانت العملية التي يتم الانتهاء منها هي التحقق من التوقيع أو فشل فك التشفير والتحقق في وضع AEAD، فسوف تقوم Finish() بإرجاع KM_ERROR_VERIFICATION_FAILED.
التعريف في السطر 405 من الملف keymaster2.h .
| علامات uint32_t |
راجع العلامات المحددة لـ keymaster0_devices::flags في keymaster_common.h . يُستخدم فقط للتوافق مع الإصدارات السابقة؛ يجب على أجهزة keymaster2 ضبط هذا على الصفر.
التعريف في السطر 43 من الملف keymaster2.h .
| keymaster_error_t (* generator_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *الخصائص) |
يُنشئ مفتاحًا، أو زوجًا من المفاتيح، ويعيد فقاعة مفتاح و/أو وصفًا للمفتاح.
يتم تعريف معلمات إنشاء المفاتيح على أنها أزواج علامات/قيمة مفتاح المفاتيح، المتوفرة في 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 .
| 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 *الخصائص) |
إرجاع خصائص المفتاح المحدد، أو 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 إذا لم يكن أي منها مرتبطًا. [في] app_id بيانات التطبيق، أو 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 *الخصائص) |
يستورد مفتاحًا أو زوجًا من المفاتيح، مما يؤدي إلى إرجاع كائن كبير كبير و/أو وصف للمفتاح.
يتم تعريف معظم معلمات الاستيراد الرئيسية على أنها أزواج علامات/قيمة 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
- حدود
[في] ديف هيكل جهاز keymaster. [في] المعلمات المعلمات التي تحدد المفتاح المستورد. [في] params_count عدد الإدخالات في 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 (* تحديث)(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 غير صالحة، فسوف يُرجع التحديث () KM_ERROR_INVALID_OPERATION_HANDLE.
قد لا يستهلك التحديث () كافة البيانات المتوفرة في المخزن المؤقت للبيانات. سوف يقوم التحديث () بإرجاع الكمية المستهلكة في *data_consumed. يجب على المتصل تقديم البيانات غير المستهلكة في مكالمة لاحقة.
- حدود
[في] ديف هيكل جهاز keymaster. [في] Operation_handle تم إرجاع مقبض العملية بواسطة begin() . [في] in_params معلمات إضافية للعملية. بالنسبة لأوضاع AEAD، يُستخدم هذا لتحديد KM_TAG_ADDITIONAL_DATA. لاحظ أنه قد يتم توفير بيانات إضافية في عدة استدعاءات للتحديث() ، ولكن فقط حتى يتم توفير بيانات الإدخال. [في] مدخل البيانات المراد معالجتها، وفقًا للمعلمات المحددة في استدعاء البدء () . لاحظ أن التحديث () قد يستهلك أو لا يستهلك كافة البيانات المقدمة. راجع input_consumed.[خارج] input_consumed مقدار البيانات التي تم استهلاكها بواسطة التحديث () . إذا كان هذا أقل من المبلغ المقدم، فيجب على المتصل توفير الباقي في استدعاء لاحق لـ update() . [خارج] out_params معلمات الإخراج. يُستخدم لإرجاع بيانات إضافية من العملية. يحصل المتصل على ملكية مصفوفة معلمات الإخراج ويجب عليه تحريرها باستخدام keymaster_free_param_set() . قد يتم تعيين out_params على NULL إذا لم تكن هناك معلمات إخراج متوقعة. إذا كانت قيمة out_params NULL، وتم إنشاء معلمات الإخراج، فستُرجع begin() KM_ERROR_OUTPUT_PARAMETER_NULL. [خارج] انتاج بيانات الإخراج إن وجدت. يفترض المتصل ملكية المخزن المؤقت المخصص. يجب ألا يكون الإخراج فارغًا.
لاحظ أن التحديث () قد لا يوفر أي مخرجات، وفي هذه الحالة سيكون الناتج->طول البيانات صفرًا، وقد يكون طول الإخراج->البيانات إما NULL أو صفرًا (لذلك يجب على المتصل دائمًا تحريرها).
التعريف في السطر 376 من الملف keymaster2.h .
| keymaster_error_t (* ترقية_مفتاح) (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 إلى إصدار جديد، أو يمكن تحديث النظام لإبطال إصدار نظام التشغيل و/أو مستوى التصحيح. في كلتا الحالتين، ستؤدي محاولات استخدام مفتاح قديم إلى قيام مدير المفاتيح بإرجاع KM_ERROR_KEY_REQUIRES_UPGRADE. يجب بعد ذلك استدعاء هذه الطريقة لترقية المفتاح.
- حدود
[في] ديف هيكل جهاز keymaster. [في] key_to_upgrade مفتاح keymaster للترقية. [في] update_params المعلمات اللازمة لإكمال الترقية. على وجه الخصوص، ستكون KM_TAG_APPLICATION_ID وKM_TAG_APPLICATION_DATA مطلوبة إذا تم تعريفهما للمفتاح. [خارج] Upgraded_key النقطة الرئيسية التي تمت ترقيتها.
التعريف في السطر 260 من الملف keymaster2.h .
تم إنشاء وثائق هذه البنية من الملف التالي:
- الأجهزة/libhardware/تشمل/الأجهزة/ keymaster2.h