توفر هذه الصفحة تفاصيل لمساعدة المستخدمين في تنفيذ HALs في Keymaster. يتناول كل علامة في HAL، أي إصدار Keymaster الذي تتوفر فيه هذه العلامة وما إذا كانت العلامة قابلة للتكرار. باستثناء ما هو مذكور في أوصاف العلامات، يتم استخدام جميع العلامات أدناه أثناء إنشاء المفتاح لتحديد المفتاح وسماتها الشخصية.
بالنسبة إلى Keymaster 4، يتم تحديد العلامات في
platform/hardware/interfaces/keymaster/keymaster-version/types.hal
,
مثل
3.0/types.hal لـ Keymaster 3
4.0/types.hal لـ Keymaster 4. بالنسبة إلى Keymaster 2 والإصدارات الأقدم، يتم تحديد العلامات في
platform/hardware/libhardware/include/hardware/keymaster_defs.h
بالنسبة إلى الدوال، راجِع الدوال الرئيسية.
علامة::ACTIVE_DATETIME
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة التاريخ والوقت اللذين يصبح فيهما المفتاح نشطًا. قبل ذلك
ووقتًا، وفشلت أي محاولة لاستخدام المفتاح مع
ErrorCode::KEY_NOT_YET_VALID
تكون القيمة عبارة عن عدد صحيح 64 بت يمثل المللي ثانية منذ 1 كانون الثاني (يناير)، 1970.
علامة::ALGORITHM
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة خوارزمية التشفير التي يتم استخدام المفتاح معها.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class Algorithm : uint32_t { RSA = 1, EC = 3, AES = 32, HMAC = 128, };
typedef enum { KM_ALGORITHM_RSA = 1, KM_ALGORITHM_EC = 3, KM_ALGORITHM_AES = 32, KM_ALGORITHM_HMAC = 128, } keymaster_algorithm_t;
العلامة::ALL_APPLICATIONS
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
محجوزة للاستخدام في المستقبل.
العلامة::ALLOW_WHILE_ON_BODY
الإصدار: 2 و3 و4
هل يمكن تكراره؟ لا
لا تنطبق هذه العلامة إلا على أجهزة Android Wear المزوّدة بأجهزة استشعار أثناء حملها. علامة @ لهذه النقطة، ليس من المتوقع أن تتمكن أي بيئة تنفيذ موثوقة من توفير وصول آمن إلى أداة استشعار حملها أو كانت أجهزة الاستشعار في الجسم آمنة للغاية، من المتوقع أن تكون ميزة تفرضها البرامج بحتًا.
العلامة::ALL_المستخدمون
الإصدار: 3 و4
هل يمكن تكراره؟ لا
محجوزة للاستخدام في المستقبل.
العلامة::APPLICATION_DATA
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
عند توفيرها
إنشاء مفتاح
أو ImportKey،
تحدد هذه العلامة البيانات اللازمة أثناء جميع استخدامات المفتاح. ضِمن
وخاصةً المكالمات
exportKey و
getKeyCharacteristics
تحتاج إلى توفير نفس القيمة للمعلمة clientId
، كما يتم استدعاء
إلى البدء في تقديم
هذه العلامة والبيانات المرتبطة نفسها كجزء من inParams
تعيين. إذا لم تتوفر البيانات الصحيحة، فستُرجع الدالة
ErrorCode::INVALID_KEY_BLOB
يرتبط محتوى هذه العلامة بالمفتاح تشفيرًا، مما يعني أنه ينبغي ألا يكون ذلك ممكناً للخصم الذي لديه إمكانية الوصول إلى جميع أسرارًا عالمية آمنة ولكن لا يمكنها الوصول إلى محتوى العلامة لفك تشفير بدون فرض إضعاف لمحتوى العلامة، وهو ما يمكن للتطبيقات منعه من خلال لتحديد محتوى مرتفع بدرجة كافية
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::APPLICATION_ID
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
عند توفيرها
إنشاء مفتاح
أو ImportKey،
تحدد هذه العلامة البيانات اللازمة أثناء جميع استخدامات المفتاح. ضِمن
وخاصةً المكالمات
exportKey و
getKeyCharacteristics
يجب توفير القيمة نفسها في المعلمة clientId
المكالمات إلى البدء بحاجة إلى
توفير هذه العلامة والبيانات المرتبطة نفسها كجزء من
تم ضبط inParams
. إذا لم تتوفر البيانات الصحيحة، لا يمكن استخدام
تعرض ErrorCode::INVALID_KEY_BLOB
.
يرتبط محتوى هذه العلامة بالمفتاح تشفيرًا، مما يعني أنه خصم يمكنه الوصول إلى جميع أسرار العالم الآمنة - ولكن لا يملك الإذن بالوصول إلى محتوى العلامة، ولا يمكن فك تشفير (بدون القوة الغاشمة على محتوى العلامة).
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ASSOCIATED_DATA
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تقدم "بيانات مرتبطة" لتشفير أو فك التشفير AES-GCM هذه العلامة المقدمة للتحديث يحدد البيانات غير المشفرة/غير المشفرة، ولكن يتم استخدامها في الحوسبة بعلامة GCM.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_APPLICATION_ID
الإصدار: 3 و4
هل يمكن تكراره؟ لا
يُستخدَم لتحديد مجموعة التطبيقات المحتملة التي بدأ مصادقة المفتاح.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_CHALLENGE
الإصدار: 3 و4
هل يمكن تكراره؟ لا
يُستخدَم لتقديم تحدي في المصادقة.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_BRAND
الإصدار: 3 و4
هل يمكن تكراره؟ لا
تقدِّم اسم العلامة التجارية للجهاز وفقًا لما يعرضه "Build.BRAND
"
في Android. يتم ضبط هذا الحقل فقط عند طلب مصادقة
معرّفات الأجهزة.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_DEVICE
الإصدار: 3 و4
هل يمكن تكراره؟ لا
تقدّم هذه السمة اسم الجهاز كما هو وارد في "Build.DEVICE
".
في Android. يتم ضبط هذا الحقل فقط عند طلب مصادقة
معرّفات الأجهزة.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_IMEI
الإصدار: 3 و4
هل يمكن تكراره؟ نعم
يوفّر هذا الإعداد أرقام IMEI لجميع الأجهزة اللاسلكية على الجهاز. تم ضبط هذا الحقل فقط عند طلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_MANUFACTURER
الإصدار: 3 و4
هل يمكن تكراره؟ لا
توفّر اسم الشركة المصنّعة للجهاز وفقًا لما تعرضه
Build.MANUFACTURER
في Android يتم ضبط هذا الحقل فقط عندما
تطلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_MEID
الإصدار: 3 و4
هل يمكن تكراره؟ نعم
توفّر هذه السياسة معرّفات MEID لجميع الأجهزة اللاسلكية على الجهاز. سيتم ضبط هذا الحقل فقط. عند طلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_MODEL
الإصدار: 3 و4
هل يمكن تكراره؟ لا
توفّر هذه البيانات اسم طراز الجهاز وفقًا لما يعرضه
Build.MODEL
في Android يتم ضبط هذا الحقل فقط عندما
تطلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_PRODUCT
الإصدار: 3 و4
هل يمكن تكراره؟ لا
توفّر اسم المنتج كما هو وارد في الجهاز
Build.PRODUCT
في Android يتم ضبط هذا الحقل فقط عندما
تطلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::ATTESTATION_ID_SERIAL
الإصدار: 3 و4
هل يمكن تكراره؟ لا
يتم تقديم الرقم التسلسلي للجهاز. يتم ضبط هذا الحقل فقط عندما تطلب مصادقة معرّفات الجهاز.
إذا كان الجهاز لا يتيح مصادقة الهوية (أو
تم الاتصال بـ "destroyAttestationIds()
" في السابق ويمكن للجهاز
لم تعد تشهد معرفاتها)، وأي طلب مصادقة رئيسي يتضمن
فشلت هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS
.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::AUTH_ربح
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدّد الوقت بالثواني الذي يتم فيه السماح باستخدام المفتاح بعد المصادقة. إذا كانت العلامة::USER_SECURE_ID وكانت هذه العلامة غير موجودة، فهذا يعني أن المفتاح يحتاج إلى مصادقة لكل الاستخدام (راجِع بدء تفاصيل تدفق المصادقة لكل عملية).
والقيمة هي عدد صحيح 32 بت يحدد الوقت بالثواني بعد مصادقة ناجحة للمستخدم المحدّد من خلال Tag::USER_SECURE_ID باستخدام طريقة المصادقة المحددة بواسطة العلامة::USER_AUTH_TYPE التي يمكن تحديد استخدام البيانات المختلفة.
العلامة::AUTH_TOKEN
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
لتوفير مصادقة الرمز المميّز للبدء، تحديث أو النهاية، لإثبات مصادقة المستخدم لإجراء عملية أساسية تتطلب (يحتوي المفتاح على Tag::USER_SECURE_ID).
القيمة هي كائن ثنائي كبير يحتوي على بنية hw_auth_token_t
.
العلامة::BLOB_USAGE_REQUIREMENTS
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة شروط بيئة النظام اللازمة للملف الذي تم إنشاؤه. الذي سيتم استخدامه.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };
typedef enum { KM_BLOB_STANDALONE = 0, KM_BLOB_REQUIRES_FILE_SYSTEM = 1, } keymaster_key_blob_usage_requirements_t;
يمكن تحديد هذه العلامة أثناء إنشاء مفتاح لاشتراط أن يكون المفتاح
قابلة للاستخدام في الحالة المحددة. يجب إرجاعه مع المفتاح
الخصائص من
generateKey و
getKeyCharacteristics
إذا حدّد المتصل Tag::BLOB_USAGE_REQUIREMENTS
باستخدام
القيمة KeyBlobUsageRequirements::STANDALONE
التي تُرجعها الثقة الثنائية الكبيرة (blob) الرئيسية
يمكن استخدامها بدون دعم نظام الملفات. هذا الإجراء ضروري للأجهزة.
بالأقراص المشفّرة، حيث قد لا يكون نظام الملفات متاحًا حتى
بعد استخدام مفتاح Keymaster لفك تشفير القرص.
العلامة::BLOCK_mode
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ نعم
تحدّد هذه السياسة وضع أو أوضاع تشفير الكتل التي يمكن استخدام المفتاح معها. ترتبط هذه العلامة بمفاتيح AES فقط.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };
typedef enum { KM_MODE_ECB = 1, KM_MODE_CBC = 2, KM_MODE_CTR = 3, KM_MODE_GCM = 32, } keymaster_block_mode_t;
هذه العلامة قابلة للتكرار، وبالنسبة إلى عمليات مفاتيح تشفير AES، يتم تحديد وضع في
وسيطة additionalParams
البدء.
إذا لم يكن الوضع المحدّد في الأوضاع المرتبطة بالمفتاح، سيتم
تعذّر إتمام العملية مع ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
علامة::BOOT_PATCHLEVEL
الإصدار: 4
تحدد العلامة::BOOT_PATCHLEVEL مستوى تصحيح أمان صورة التمهيد (kernel)
التي يمكن استخدام المفتاح معها ولا يتم مطلقًا إرسال هذه العلامة إلى مساعد المفتاح الأساسي، ولكن
يضيفه TA إلى قائمة التفويض التي تفرضها الأجهزة. أي محاولة
استخدِم مفتاحًا بقيمة Tag::BOOT_PATCHLEVEL
مختلفة عن
ويسبب تشغيل مستوى تصحيح النظام حاليًا begin()
،
getKeyCharacteristics()
أو exportKey()
للإرجاع
ErrorCode::KEY_REQUIRES_UPGRADE
يمكنك الاطّلاع على upgradeKey()
.
لمزيد من التفاصيل.
قيمة العلامة هي عدد صحيح بالصيغة YYYYMMDD، حيث يشير YYYY إلى والسنة المكونة من أربعة أرقام لآخر تحديث، والحرف MM هو الشهر المكوّن من رقمين والرمز DD هو آخر تحديث ليوم مكون من رقمين. على سبيل المثال، بالنسبة إلى المفتاح الذي تم إنشاؤه على وكان آخر تحديث لجهاز Android في 5 حزيران (يونيو) 2018، ستكون القيمة 20180605. وإذا لم يكن اليوم معروفًا، يمكن استبدال 00.
خلال كل عملية تشغيل، يجب أن يوفر برنامج الإقلاع مستوى التصحيح الخاص بصورة التشغيل إلى البيئة الآمنة (يتم تحديد الآلية من أجل التنفيذ).
ويجب أن يتم فرض هذا الإجراء باستخدام أجهزة.
العلامة::BOOTLOADER_ONLY
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة أنّ برنامج الإقلاع فقط هو الذي يمكنه استخدام المفتاح.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
إنّ أي محاولة لاستخدام مفتاح مع Tag::BOOTLOADER_ONLY
من
تعذّر نظام Android مع ErrorCode::INVALID_KEY_BLOB
.
العلامة::CALLER_NONCE
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
للإشارة إلى أنه يمكن للمتصل توفير رقم خاص للعمليات التي لا تتطلب.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
تُستخدم هذه العلامة فقط لمفاتيح AES، وهي ذات صلة فقط بـ CBC ونسبة النقر إلى الظهور وGCM
أوضاع الحظر. في حال عدم توفّر العلامة، من المفترض أن ترفض عمليات التنفيذ أي علامة
العملية التي توفر Tag::NONCE إلى
البدء
مع ErrorCode::CALLER_NONCE_PROHIBITED
.
العلامة::CREATION_DATETIME
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدّد تاريخ ووقت إنشاء المفتاح بالمللي ثانية منذ 1 يناير 1970 وهذه العلامة اختيارية وإعلامية فقط.
العلامة::DIGEST
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ نعم
تحدّد خوارزميات الملخص التي يمكن استخدامها مع المفتاح لتنفيذها وعمليات التوقيع والتحقق. هذه العلامة ذات صلة بـ RSA وECDSA مفاتيح HMAC.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class Digest : uint32_t { NONE = 0, MD5 = 1, SHA1 = 2, SHA_2_224 = 3, SHA_2_256 = 4, SHA_2_384 = 5, SHA_2_512 = 6, };
typedef enum { KM_DIGEST_NONE = 0, KM_DIGEST_MD5 = 1, KM_DIGEST_SHA1 = 2, KM_DIGEST_SHA_2_224 = 3, KM_DIGEST_SHA_2_256 = 4, KM_DIGEST_SHA_2_384 = 5, KM_DIGEST_SHA_2_512 = 6, } keymaster_digest_t;
هذه العلامة قابلة للتكرار. بالنسبة إلى عمليات التوقيع والتحقق، حدد
ملخص في الوسيطة additionalParams
الخاصة
البدء.
إذا لم يكن الملخص المحدد موجودًا في الملخصات المرتبطة بالمفتاح، فإن
تعذّر إتمام العملية مع ErrorCode::INCOMPATIBLE_DIGEST
.
العلامة::EC_CURVE
الإصدار: 2 و3 و4
هل يمكن تكراره؟ لا
في Keymaster 1، تم تخمين المنحنى المستخدَم لمفاتيح EC من المفتاح المحدَّد.
الحجم. لتحسين المرونة من الآن فصاعدًا، قدّم Keymaster 2 بيانًا
لتحديد المنحنيات. قد تتضمن طلبات إنشاء مفتاح الإحالات الناجحة المحسّنة
Tag::EC_CURVE
أو Tag::KEY_SIZE
أو كلاهما
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };
enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };
إذا كان طلب الإنشاء يحتوي على Tag::KEY_SIZE
فقط،
إلى منطق Keymaster 1، واختيار منحنى NIST المناسب.
إذا كان الطلب يحتوي على Tag::EC_CURVE
فقط، استخدِم السمة
المنحنى المحدد. بالنسبة إلى Keymaster 3 والإصدارات الأحدث، يتم تحديد المنحنيات في
EcCurve
بالنسبة إلى Keymaster 2 والإصدارات الأقدم، يتم تحديد المنحنيات
في keymaster_ec_curve_t
.
إذا كان الطلب يحتوي على كليهما، استخدم المنحنى المحدد
Tag::EC_CURVE
، وتأكَّد من أنّ حجم المفتاح المحدَّد هو
مناسبًا لهذا المنحنى. وإذا لم يكن كذلك، فارجع
ErrorCode::INVALID_ARGUMENT
العلامة::INCLUDE_UNIQUE_ID
الإصدار: 2 و3 و4
هل يمكن تكراره؟ لا
يتم تحديد هذه العلامة أثناء إنشاء مفتاح للإشارة إلى أنّ المصادقة للمفتاح الذي تم إنشاؤه، يجب أن تحتوي على نطاق معرّف فريد للجهاز محدد زمنيًا كما هو محدد في العلامة::UNIQUE_ID.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
العلامة::KEY_size
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
لتحديد حجم المفتاح، بالبت، والقياس بالطريقة العادية
وخوارزمية المفتاح. على سبيل المثال، بالنسبة إلى مفاتيح RSA، تحدّد الدالة Tag::KEY_SIZE
.
حجم المعامل العام. بالنسبة إلى مفاتيح AES، يحدد هذا النموذج الطول
مادة المفتاح السري.
العلامة::MAC_LENGTH
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
يوفر الطول المطلوب لعلامة مصادقة MAC أو GCM بالبت.
القيمة هي طول MAC بوحدات البت. وهو من مضاعفات 8 وفي على الأقل مثل قيمة Tag::MIN_MAC_LENGTH المرتبطة بالمفتاح.
العلامة::MAX_USES_PER_BOOT
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تُحدِّد الحد الأقصى لعدد مرات استخدام المفتاح بين النظام. عمليات إعادة التشغيل. هذه آلية أخرى لتحديد معدّل استخدام المفاتيح.
القيمة هي عدد صحيح 32 بت يمثل الاستخدامات لكل تمهيد.
عند استخدام مفتاح بهذه العلامة في إحدى العمليات، يظهر العدّاد المرتبط بالمفتاح
أثناء
بدء الاتصال. بعد المفتاح
تجاوز العدّاد هذه القيمة، وفشلت كل المحاولات اللاحقة لاستخدام المفتاح
مع ErrorCode::MAX_OPS_EXCEEDED
، إلى أن تتم إعادة تشغيل الجهاز.
هذا يعني أن Trustlet يحتفظ بجدول استخدام عدادات للمفاتيح باستخدام هذا
. بما أنّ ذاكرة Keymaster غالبًا ما تكون محدودة، يمكن أن يحتوي هذا الجدول على
ويمكن أن يفشل Keymaster في العمليات التي تحاول استخدام المفاتيح مع
هذه العلامة عندما يكون الجدول ممتلئًا. يجب أن يتّسع الجدول لعدد مفاتيح لا يقل عن 16 مفتاحًا.
في حال تعذّر تنفيذ عملية بسبب امتلاء الجدول، يعرض Keymaster
ErrorCode::TOO_MANY_OPERATIONS
علامة::MIN_MAC_LENGTH
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدد هذه العلامة الحد الأدنى لطول عنوان MAC الذي يمكن طلبه أو باستخدام هذا المفتاح لمفاتيح HMAC ومفاتيح AES التي تتوافق مع وضع GCM.
هذه القيمة هي الحد الأدنى لطول MAC، بالبت. وهي من مضاعفات 8. بالنسبة HMAC، فإن القيمة لا تقل عن 64. بالنسبة إلى مفاتيح GCM، لا تقل القيمة عن 96 ولا يزيد عن 128.
العلامة::MIN_SECONDS_BETWEEN_OPS
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة الحدّ الأدنى لمقدار الوقت المنقضي بين القيم المسموح بها. العمليات باستخدام مفتاح. يمكن استخدام ذلك للحدّ من استخدامات المفاتيح في السياقات. حيث قد يؤدي الاستخدام غير المحدود إلى تفعيل هجمات القوة الغاشمة.
القيمة هي عدد صحيح 32 بت يمثّل الثواني بين القيم المسموح بها العمليات التجارية.
عند استخدام مفتاح يحمل هذه العلامة في عملية، يمكنك بدء موقّت.
أثناء النهاية أو
إلغاء المكالمة. أي تقييم
عبارة عن طلب البدء والذي
المستلم قبل الموقت إلى أن الفاصل الزمني المحدد
انقضى Tag::MIN_SECONDS_BETWEEN_OPS
وتعذّر
ErrorCode::KEY_RATE_LIMIT_EXCEEDED
هذا النمط
أن موثوق به يحتفظ بجدول استخدام عدادات للمفاتيح بهذه العلامة.
نظرًا لأن ذاكرة Keymaster غالبًا ما تكون محدودة، يمكن أن يحتوي هذا الجدول على حد أقصى ثابت
قد يخفق الحجم وKeymaster في العمليات التي تحاول استخدام المفاتيح مع هذه العلامة
عندما يكون الجدول ممتلئًا. يجب أن يستوعب الجدول 32 مستخدمًا على الأقل.
وإعادة استخدام خانات الجدول بشدة عند انتهاء فواصل الحد الأدنى من الاستخدام الرئيسية.
في حال تعذّر تنفيذ عملية بسبب امتلاء الجدول، يعرض Keymaster
ErrorCode::TOO_MANY_OPERATIONS
العلامة::NO_AUTH_REQUIRED
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة أنّه ما مِن مصادقة مطلوبة لاستخدام هذا المفتاح. هذه العلامة حصرية باستخدام Tag::USER_SECURE_ID.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
العلامة::NONCE
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
توفير أو إرجاع ملف nonce أو متجه إعداد (IV) لمعيار AES GCM أو CBC أو فك التشفير أو نسبة النقر إلى الظهور. يتم تقديم هذه العلامة إلى البدء أثناء عمليات التشفير وفك التشفير. لا يتم تقديمه إلا البدء إذا كان المفتاح يحتوي على Tag::CALLER_NONCE. إذا لم يتم تقديمه، رقم غير مناسب أو قيمة IV مناسبة بشكل عشوائي عن طريق مدير المفاتيح وتم إرجاعه من البداية.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي. الأطوال المسموح بها يعتمد على الوضع: يبلغ طول nonces في GCM 12 بايت؛ 16 عامًا على CBC ونسبة النقر إلى الظهور IV بايت.
العلامة::Origin
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تُحدِّد مكان إنشاء المفتاح، إذا كان معروفًا. قد لا يتم تحديد هذه العلامة أثناء إنشاء المفتاح أو الاستيراد، ويجب إضافته إلى الخصائص الرئيسية من خلال الثقة.
Keymaster 3يتم تحديد القيم المحتملة في
android::hardware::keymaster::v3_0::KeyOrigin
:
enum class KeyOrigin : uint32_t { GENERATED = 0, DERIVED = 1, IMPORTED = 2, UNKNOWN = 3, };
يتم تحديد القيم المحتمَلة في keymaster_origin_t
:
typedef enum { KM_ORIGIN_GENERATED = 0, KM_ORIGIN_IMPORTED = 2, KM_ORIGIN_UNKNOWN = 3, } keymaster_key_origin_t
لا يعتمد المعنى الكامل للقيمة على القيمة فقط ولكن على ما إذا توجد في قائمة الخصائص التي تفرضها الأجهزة أو التي تفرضها البرامج.
تشير القيمة GENERATED
إلى أنّ تطبيق Keymaster هو من أنشأ المفتاح.
إذا كنت في قائمة الأجهزة المفروضة،
أن المفتاح تم إنشاؤه في أجهزة آمنة ومرتبط بالأجهزة بشكل دائم. في حال حذف
في القائمة التي تفرضها البرامج، فإن المفتاح تم إنشاؤه في SoftKeymaster
غير مرتبط بالأجهزة.
تشير القيمة DERIVED
إلى أنّ المفتاح تم اشتقاقه داخل تطبيق Keymaster.
من المحتمل أن تكون متاحة خارج الجهاز.
يشير IMPORTED
إلى أنّه تم إنشاء المفتاح خارج
من Keymaster
واستيرادها إلى
مدير المفاتيح. وإذا كانت في قائمة الأجهزة المفروضة، فإنها تكون مرتبطة بشكل دائم بالأجهزة،
على الرغم من احتمال وجود نسخ خارج الأجهزة الآمنة. إذا كانت تجربة
قائمة تنفيذات البرامج، فقد تم استيراد المفتاح إلى SoftKeymaster
بالأجهزة المرتبطة به.
يجب ألا يظهر UNKNOWN
إلا في القائمة المفروضة من خلال الأجهزة.
إنه يشير إلى أن المفتاح
الأجهزة، ولكن لا يُعرف ما إذا كان قد تم إنشاء المفتاح في الأصل
أجهزة آمنة أو تم استيرادها. ولا يحدث ذلك إلا عندما يتم تشغيل جهاز keymaster0
لمحاكاة خدمات keymaster1.
العلامة::تؤدي هاري واختري من تاريخ انتهاء العمل إلى Google
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدّد تاريخ ووقت انتهاء صلاحية المفتاح للتوقيع
التشفير. بعد هذا الوقت، ستتخذ أي محاولة لاستخدام مفتاح مع
الغرض الرئيسي::SIGN أو
Keyالغرض::ENCRYPT متوفّر
فشل البدء
مع ErrorCode::KEY_EXPIRED
.
والقيمة هي عدد صحيح 64 بت يمثل المللي ثانية منذ 1 يناير 1970
العلامة::OS_PATCHLEVEL
الإصدار: 2 و3 و4
هل يمكن تكراره؟ لا
ولا يتم مطلقًا إرسال هذه العلامة إلى Keymaster TA، ولكن تتم إضافتها إلى قائمة بالتفويضات التي تفرضها الأجهزة من قبل TA.
قيمة العلامة هي عدد صحيح بالصيغة YYYYMM، حيث يشير YYYY إلى السنة المكوّنة من أربعة أرقام لآخر تحديث، وMM هو الشهر المكوّن من رقمين لآخر تحديث. على سبيل المثال، بالنسبة إلى المفتاح الذي تم إنشاؤه على جهاز Android تم تحديثه آخر مرة في كانون الأول (ديسمبر) 2015، ستكون القيمة 201512.
المفاتيح التي لها مستوى تصحيح مختلف عن مستوى رمز التصحيح الحالي ليست
للاستخدام. تُعد محاولة استخدام مثل هذه الأسباب الرئيسية
begin،
getKeyCharacteristics
أو exportKey
لعرض ErrorCode::KEY_REQUIRES_UPGRADE
. عرض
ربط الإصدار للتعرّف على المزيد
التفاصيل.
العلامة::OS_VERSION
الإصدار: 2 و3 و4
هل يمكن تكراره؟ لا
ولا يتم مطلقًا إرسال هذه العلامة إلى Keymaster TA، ولكن تتم إضافتها إلى قائمة بالتفويضات التي تفرضها الأجهزة من قبل TA.
قيمة العلامة هي عدد صحيح للنموذج MMmmss، حيث يكون MM هو العامل الرئيسي رقم الإصدار، ويكون mm هو رقم الإصدار الثانوي، وss هو رقم الإصدار الثانوي الصف. على سبيل المثال، بالنسبة إلى المفتاح الذي تم إنشاؤه في الإصدار 4.0.3 من Android، تكون قيمة سيكون 040003.
علامة::PADDING
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ نعم
تحدّد هذه السياسة أوضاع المساحة المتروكة التي يمكن استخدامها مع المفتاح. هذه العلامة ذات صلة بمفاتيح RSA وAES.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class PaddingMode : uint32_t { NONE = 1, RSA_OAEP = 2, RSA_PSS = 3, RSA_PKCS1_1_5_ENCRYPT = 4, RSA_PKCS1_1_5_SIGN = 5, PKCS7 = 64, };
typedef enum { KM_PAD_NONE = 1, KM_PAD_RSA_OAEP = 2, KM_PAD_RSA_PSS = 3, KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4, KM_PAD_RSA_PKCS1_1_5_SIGN = 5, KM_PAD_PKCS7 = 64, } keymaster_padding_t;
PaddingMode::RSA_OAEP
و
يتم استخدام PaddingMode::RSA_PKCS1_1_5_ENCRYPT
فقط لمفاتيح تشفير/فك التشفير RSA وتحديد RSA PKCS#1v2 OAEP
المساحة المتروكة والمساحة المتروكة العشوائية للإصدار 1.5 من RSA PKCS#1 على التوالي.
PaddingMode::RSA_PSS
و
يقتصر استخدام PaddingMode::RSA_PKCS1_1_5_SIGN
على الإعلانات المتجاوبة على شبكة البحث.
مفاتيح التوقيع/إثبات الملكية وتحديد RSA PKCS#1v2 PSS
المساحة المتروكة والمساحة المتروكة الحتمية للإصدار 1.5 من RSA PKCS#1، على التوالي.
يمكن استخدام PaddingMode::NONE
مع RSA أو
مفاتيح AES. بالنسبة إلى مفاتيح AES، في حال استخدام PaddingMode::NONE
باستخدام وضع الحظر ECB أو CBC مع إمكانية تشفير البيانات أو فك تشفيرها
ليس مضاعفًا لحجم كتلة AES في الطول، فإن الاتصال لإنهاء
إخفاق مع ErrorCode::INVALID_INPUT_LENGTH
.
لا يمكن استخدام PaddingMode::PKCS7
إلا مع مفاتيح AES فقط،
باستخدام وضعَي ECB وCBC فقط.
هذه العلامة قابلة للتكرار. يجب تحديد وضع المساحة المتروكة في استدعاء الدالة
البدء.
لن تنجح العملية إذا لم يكن الوضع المحدَّد هو الاعتماد على المفتاح.
مع ErrorCode::INCOMPATIBLE_BLOCK_MODE
.
علامة::PURPOSE
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ نعم
تحدِّد هذه السياسة مجموعة الأغراض التي يمكن استخدام المفتاح من أجلها.
يتم تحديد القيم المحتملة من خلال التعداد التالي:
Keymaster 3enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };
typedef enum { KM_PURPOSE_ENCRYPT = 0, KM_PURPOSE_DECRYPT = 1, KM_PURPOSE_SIGN = 2, KM_PURPOSE_VERIFY = 3, } keymaster_purpose_t;
هذه العلامة قابلة للتكرار؛ بقيم متعددة،
على الرغم من أن العملية لها غرض واحد. عندما
begin باسم
لبدء عملية، يتم تحديد الغرض منها.
إذا كان الغرض المحدّد للعملية غير مصرح به من قِبل
، فإن العملية تفشل مع ErrorCode::INCOMPATIBLE_PURPOSE
.
العلامة::RESET_CLAIM_ID_ROTATION
الإصدار: 3 و4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة ما إذا تمت إعادة ضبط الجهاز على الإعدادات الأصلية. منذ آخر تغيير فريد للمعرف. يُستخدَم لمصادقة المفتاح.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
العلامة::ROLLBACK_RESISTANT
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
يشير إلى أنّ المفتاح لا يمكن التراجع عنه، ما يعني أنّه عند حذفه باستخدام deleteKey أو deleteAllKeys، يكون المفتاح مضمونًا لحذفه نهائيًا وغير قابل للاستخدام. من الممكن يمكن حذف المفاتيح التي لا تحتوي على هذه العلامة ثم استعادتها من النسخة الاحتياطية.
هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم وجود العلامة).
العلامة::ROOT_OF_TRUST
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
يحدد جذر الثقة، وهو المفتاح الذي تستخدمه عملية التشغيل المتحقَّق منه التحقق من بدء تشغيل نظام التشغيل (إن وجد). لم يتم توفير هذه العلامة مطلقًا إلى Keymaster أو يعود إليه في الخصائص الرئيسية.
العلامة::RSA_public_EXPONENT
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تُحدِّد قيمة الأس العام لزوج مفاتيح RSA. هذه العلامة وذات صلة بمفاتيح RSA فقط، وضرورية لجميع مفاتيح RSA.
القيمة هي عدد صحيح غير موقَّع بحجم 64 بت يلبي متطلبات
الأس العام RSA. يجب أن تكون هذه القيمة رقمًا أوليًا. تدعم المؤسسات الائتمانية
القيمة 2^16+1 وقد تدعم قيمًا معقولة أخرى، ولا سيما القيمة 3.
إذا لم يتم تحديد الأس أو إذا كان الأس المحدد غير معتمد،
تعذّر إنشاء مفتاح مع ErrorCode::INVALID_ARGUMENT
.
العلامة::UNIQUE_ID
الإصدار: 3 و4
هل يمكن تكراره؟ لا
يُستخدَم لتقديم معرّف فريد في المصادقة.
القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.
العلامة::USAGE_EXPIRE_DATETIME
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
يحدد تاريخ ووقت انتهاء صلاحية المفتاح للتحقق
فك التشفير. بعد هذا الوقت، ستتخذ أي محاولة لاستخدام مفتاح مع
Keyالغرض:التحقّق أو
الغرض الرئيسي::DeRYPT مقدّم إلى
تعذُّر عملية البدء
مع ErrorCode::KEY_EXPIRED
.
والقيمة هي عدد صحيح 64 بت يمثل المللي ثانية منذ 1 يناير 1970
العلامة::USER_AUTH_TYPE
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدّد هذه السياسة أنواع مصادقات المستخدمين التي يمكن استخدامها لمنح الإذن بهذا الإجراء.
المفتاح. عندما يُطلب من Keymaster تنفيذ عملية باستخدام مفتاح باستخدام هذا
فإنها تتلقى رمز مصادقة، ويتم إرسال
يحتاج حقل authenticator_type
إلى مطابقة القيمة في العلامة.
على سبيل المثال، (ntoh(token.authenticator_type) &
auth_type_tag_value) != 0
، حيث تكون ntoh
دالة
تُحوِّل الأعداد الصحيحة المرتبة على الشبكة إلى أعداد صحيحة مرتَّبة بواسطة المضيف
تمثّل auth_type_tag_value
قيمة هذه العلامة.
تكون القيمة هي قناع بت لعدد صحيح 32 بت للقيم من التعداد:
Keymaster 3enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };
typedef enum { HW_AUTH_NONE = 0, HW_AUTH_PASSWORD = 1 << 0, HW_AUTH_FINGERPRINT = 1 << 1, // Additional entries should be powers of 2. HW_AUTH_ANY = UINT32_MAX, } hw_authenticator_type_t;
العلامة::USER_SECURE_ID
الإصدار: 1، 2، 3، 4
هل يمكن تكراره؟ لا
تحدِّد هذه السياسة إمكانية استخدام مفتاح معيّن فقط تحت مستخدم آمن معيّن. حالة المصادقة. لا يمكن استخدام هذه العلامة مع الآخرين مع العلامة::NO_AUTH_REQUIRED.
القيمة هي عدد صحيح 64 بت يحدد حالة سياسة المصادقة التي يجب أن تكون موجودة في رمز المصادقة المميز (الذي يتم تقديمه إلى تبدأ بـ العلامة::AUTH_TOKEN) للسماح باستخدام المفتاح. أي تقييم عبارة إلى البدء بمفتاح بهذه العلامة لا يوفر أو رمز المصادقة، أو يوفر فشل رمز المصادقة المميز بدون قيمة حالة سياسة مطابقة.
هذه العلامة قابلة للتكرار. في حال تطابق أي من القيم المقدَّمة مع أي سياسة
الحالة في الرمز المميز للمصادقة، فإن المفتاح مخول للاستخدام.
وبخلاف ذلك، تخفق العملية مع
ErrorCode::KEY_USER_NOT_AUTHENTICATED
العلامة::VENDOR_PATCHLEVEL
الإصدار: 4
تحدد هذه العلامة مستوى تصحيح الأمان لصورة المورد الذي يمكن من خلاله استخدام المفتاح
تنبؤي. ولا يتم مطلقًا إرسال هذه العلامة إلى Keymaster TA، ولكن تتم إضافتها إلى
قائمة بالتفويضات التي تفرضها الأجهزة من قبل TA. يمكن أن تكون أي محاولة لاستخدام مفتاح مع
قيمة Tag::VENDOR_PATCHLEVEL
مختلفة عن القيمة قيد التشغيل حاليًا
يجب أن يتسبب مستوى تصحيح النظام في begin()
،
getKeyCharacteristics()
أو exportKey()
للإرجاع
ErrorCode::KEY_REQUIRES_UPGRADE
يمكنك الاطّلاع على upgradeKey()
.
لمزيد من التفاصيل.
قيمة العلامة هي عدد صحيح بالصيغة YYYYMMDD، حيث يشير YYYY إلى والسنة المكونة من أربعة أرقام لآخر تحديث، والحرف MM هو الشهر المكوّن من رقمين والرمز DD هو آخر تحديث ليوم مكون من رقمين. على سبيل المثال، بالنسبة إلى المفتاح الذي تم إنشاؤه على وكان آخر تحديث لجهاز Android في 5 حزيران (يونيو) 2018، ستكون القيمة 20180605.
يجب أن يقرأ مقياس HAL الخاص بـ IKeymasterDevice مستوى تصحيح البائع الحالي من النظام.
الموقع ro.vendor.build.security_patch
وتسليمه إلى
عندما يتم تحميل HAL لأول مرة (الآلية
محددة التنفيذ). يجب ألا تقبل البيئة الآمنة سياسة أخرى
حتى ما بعد التمهيد التالي.
ويجب أن يتم فرض هذا الإجراء باستخدام أجهزة.