علامات تفويض Keymaster

توفر هذه الصفحة تفاصيل لمساعدة المستخدمين في تنفيذ 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 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum 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,
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 والإصدارات الأقدم 
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 2 والإصدارات الأقدم

يتم تحديد القيم المحتمَلة في 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 3 
enum 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,
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 والإصدارات الأقدم 
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 3 
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 والإصدارات الأقدم 
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 لأول مرة (الآلية محددة التنفيذ). يجب ألا تقبل البيئة الآمنة سياسة أخرى حتى ما بعد التمهيد التالي.

ويجب أن يتم فرض هذا الإجراء باستخدام أجهزة.