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

توفر هذه الصفحة تفاصيل لمساعدة منفذي Keymaster HALs. وهو يغطي كل علامة في طبقة توصيف الأجهزة (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 .

للحصول على الوظائف، راجع صفحة وظائف Keymaster .

العلامة::ACTIVE_DATETIME

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد التاريخ والوقت الذي يصبح فيه المفتاح نشطًا. قبل هذا الوقت، تفشل أي محاولة لاستخدام المفتاح مع ErrorCode::KEY_NOT_YET_VALID .

القيمة عبارة عن عدد صحيح 64 بت يمثل المللي ثانية منذ 1 يناير 1970.

العلامة::الخوارزمية

الإصدار : 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 المزودة بأجهزة استشعار مثبتة على الجسم. في هذه المرحلة، ليس من المتوقع أن يكون أي TEE قادرًا على توفير الوصول الآمن إلى المستشعر الموجود على الجسم، أو أن تكون المستشعرات الموجودة على الجسم آمنة جدًا، لذلك من المتوقع أن تكون هذه ميزة يتم فرضها برمجيًا بحتًا.

العلامة::ALL_USERS

الإصدار : 3، 4

قابل للتكرار ؟ لا

محجوزة للاستخدام في المستقبل.

العلامة::APPLICATION_DATA

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

عند توفيرها لـ generatorKey أو importKey ، تحدد هذه العلامة البيانات الضرورية أثناء جميع استخدامات المفتاح. على وجه الخصوص، تحتاج الاستدعاءات إلى exportKey و getKeyCharacteristics إلى توفير نفس القيمة لمعلمة clientId ، كما تحتاج الاستدعاءات للبدء إلى توفير هذه العلامة ونفس البيانات المرتبطة بها كجزء من مجموعة inParams . إذا لم يتم توفير البيانات الصحيحة، تقوم الدالة بإرجاع ErrorCode::INVALID_KEY_BLOB .

يرتبط محتوى هذه العلامة بالمفتاح بشكل مشفر ، مما يعني أنه لا يمكن لخصم لديه حق الوصول إلى جميع أسرار العالم الآمن ولكن ليس لديه حق الوصول إلى محتوى العلامة فك تشفير المفتاح دون فرض العلامة بشكل غاشم المحتوى، والذي يمكن للتطبيقات منعه عن طريق تحديد محتوى عالي الإنتروبيا بدرجة كافية.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::APPLICATION_ID

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

عند توفيرها لـ generatorKey أو importKey ، تحدد هذه العلامة البيانات الضرورية أثناء جميع استخدامات المفتاح. على وجه الخصوص، تحتاج الاستدعاءات إلى exportKey و getKeyCharacteristics إلى توفير نفس القيمة في معلمة clientId ، كما تحتاج الاستدعاءات للبدء إلى توفير هذه العلامة ونفس البيانات المرتبطة بها كجزء من مجموعة inParams . إذا لم يتم توفير البيانات الصحيحة، تقوم الدالة بإرجاع ErrorCode::INVALID_KEY_BLOB .

يرتبط محتوى هذه العلامة بالمفتاح بشكل مشفر ، مما يعني أن الخصم الذي يمكنه الوصول إلى جميع أسرار العالم الآمنة - ولكن ليس لديه إمكانية الوصول إلى محتوى العلامة - لا يمكنه فك تشفير المفتاح (دون فرض محتوى العلامة بشكل غاشم ).

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ASSOCIATED_DATA

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يوفر "البيانات المرتبطة" لتشفير أو فك تشفير AES-GCM. يتم توفير هذه العلامة لتحديث وتحديد البيانات غير المشفرة/فك التشفير، ولكنها تُستخدم في حساب علامة GCM.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_APPLICATION_ID

الإصدار : 3، 4

قابل للتكرار ؟ لا

يُستخدم لتحديد مجموعة التطبيقات المحتملة التي بدأ أحدها في التصديق الرئيسي.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_CHALLENGE

الإصدار : 3، 4

قابل للتكرار ؟ لا

تستخدم لتقديم التحدي في الشهادة.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_BRAND

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر اسم العلامة التجارية للجهاز، كما تم إرجاعه بواسطة Build.BRAND في Android. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_DEVICE

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر اسم الجهاز الخاص بالجهاز، كما تم إرجاعه بواسطة Build.DEVICE في Android. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_IMEI

الإصدار : 3، 4

قابل للتكرار ؟ نعم

يوفر IMEIs لجميع أجهزة الراديو الموجودة على الجهاز. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_MANUFACTURER

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر اسم الشركة المصنعة للجهاز، كما تم إرجاعه بواسطة Build.MANUFACTURER في Android. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_MEID

الإصدار : 3، 4

قابل للتكرار ؟ نعم

يوفر أرقام MEID لجميع أجهزة الراديو الموجودة على الجهاز. سيتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_MODEL

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر اسم طراز الجهاز، كما تم إرجاعه بواسطة Build.MODEL في Android. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_PRODUCT

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر اسم منتج الجهاز، كما تم إرجاعه بواسطة Build.PRODUCT في Android. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::ATTESTATION_ID_SERIAL

الإصدار : 3، 4

قابل للتكرار ؟ لا

يوفر الرقم التسلسلي للجهاز. يتم تعيين هذا الحقل فقط عند طلب التصديق على معرفات الجهاز.

إذا كان الجهاز لا يدعم تصديق المعرف (أو تم استدعاء destroyAttestationIds() مسبقًا ولم يعد الجهاز قادرًا على تصديق المعرفات الخاصة به)، فسيفشل أي طلب تصديق مفتاح يتضمن هذه العلامة مع ErrorCode::CANNOT_ATTEST_IDS .

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::AUTH_TIMEOUT

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد الوقت بالثواني الذي يُسمح فيه باستخدام المفتاح، بعد المصادقة. إذا كانت العلامة::USER_SECURE_ID موجودة وكانت هذه العلامة غير موجودة، فإن المفتاح يحتاج إلى مصادقة لكل استخدام (راجع البدء للحصول على تفاصيل تدفق المصادقة لكل عملية).

القيمة عبارة عن عدد صحيح 32 بت يحدد الوقت بالثواني بعد المصادقة الناجحة للمستخدم المحدد بواسطة العلامة::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;

يمكن تحديد هذه العلامة أثناء إنشاء المفتاح للمطالبة بأن يكون المفتاح قابلاً للاستخدام في الحالة المحددة. يجب أن يتم إرجاعها بالخصائص الرئيسية من generatorKey و getKeyCharacteristics . إذا قام المتصل بتحديد Tag::BLOB_USAGE_REQUIREMENTS بالقيمة KeyBlobUsageRequirements::STANDALONE تقوم الثقة بإرجاع كائن ثنائي كبير الحجم يمكن استخدامه بدون دعم نظام الملفات. يعد هذا أمرًا بالغ الأهمية بالنسبة للأجهزة التي تحتوي على أقراص مشفرة، حيث قد لا يتوفر نظام الملفات إلا بعد استخدام مفتاح 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 الخاصة بـ begin . إذا لم يكن الوضع المحدد في الأوضاع المرتبطة بالمفتاح، فستفشل العملية مع ErrorCode::INCOMPATIBLE_BLOCK_MODE .

العلامة::BOOT_PATCHLEVEL

الإصدار : 4

يحدد Tag::BOOT_PATCHLEVEL مستوى تصحيح أمان صورة التمهيد (kernel) الذي يمكن استخدام المفتاح من خلاله. لا يتم إرسال هذه العلامة مطلقًا إلى keymaster TA، ولكن تتم إضافتها إلى قائمة التفويضات المفروضة على الأجهزة بواسطة 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

قابل للتكرار ؟ لا

يحدد فقط أن أداة تحميل التشغيل يمكنها استخدام المفتاح.

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

أي محاولة لاستخدام مفتاح مع Tag::BOOTLOADER_ONLY من نظام Android تفشل مع ErrorCode::INVALID_KEY_BLOB .

العلامة::CALLER_NONCE

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد أنه يمكن للمتصل توفير رقم للعمليات التي لا تتطلب أي شيء.

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

يتم استخدام هذه العلامة فقط لمفاتيح AES، وتكون ذات صلة فقط بأوضاع كتلة CBC وCTR وGCM. إذا لم تكن العلامة موجودة، فيجب أن ترفض التطبيقات أي عملية توفر Tag::NONCE لتبدأ بـ ErrorCode::CALLER_NONCE_PROHIBITED .

العلامة::CREATION_DATETIME

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد تاريخ ووقت إنشاء المفتاح، بالمللي ثانية منذ 1 يناير 1970. هذه العلامة اختيارية وإعلامية فقط.

العلامة::ملخص

الإصدار : 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 الخاصة بـ begin . إذا لم يكن الملخص المحدد موجودًا في الملخصات المرتبطة بالمفتاح، فستفشل العملية مع ErrorCode::INCOMPATIBLE_DIGEST .

العلامة::EC_CURVE

الإصدار : 2، 3، 4

قابل للتكرار ؟ لا

في Keymaster 1، تم تخمين المنحنى المستخدم لمفاتيح EC من حجم المفتاح المحدد. لتحسين المرونة في المضي قدمًا، قدم Keymaster 2 طريقة واضحة لتحديد المنحنيات. قد تحتوي طلبات إنشاء مفتاح EC على 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

قابل للتكرار ؟ لا

يتم تحديد هذه العلامة أثناء إنشاء المفتاح للإشارة إلى أن شهادة التصديق للمفتاح الذي تم إنشاؤه يجب أن تحتوي على معرف فريد للجهاز على نطاق التطبيق ومحدود بالوقت، كما هو محدد بواسطة Tag::UNIQUE_ID .

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

العلامة::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 ، حتى يتم إعادة تشغيل الجهاز. وهذا يعني أن الثقة تحتفظ بجدول عدادات الاستخدام للمفاتيح التي تحمل هذه العلامة. نظرًا لأن ذاكرة 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 .

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

العلامة::نونس

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يوفر أو يُرجع nonce أو ناقل التهيئة (IV) لتشفير أو فك تشفير AES GCM أو CBC أو CTR. يتم توفير هذه العلامة للبدء أثناء عمليات التشفير وفك التشفير. يتم توفيره للبدء فقط إذا كان المفتاح يحتوي على Tag::CALLER_NONCE . إذا لم يتم توفيره، فسيتم إنشاء الرقم المناسب أو IV بشكل عشوائي بواسطة Keymaster وإعادته من البداية.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات. تعتمد الأطوال المسموح بها على الوضع: يبلغ طول أرقام GCM 12 بايت؛ يبلغ طول CBC وCTR IVs 16 بايت.

العلامة::المنشأ

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد مكان إنشاء المفتاح، إذا كان معروفًا. لا يجوز تحديد هذه العلامة أثناء إنشاء المفتاح أو استيراده، ويجب إضافتها إلى الخصائص الرئيسية بواسطة Trustlet.

سيد المفاتيح 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 وتم استيراده إلى Keymaster. إذا كان موجودًا في قائمة فرض الأجهزة، فهو مرتبط بشكل دائم بالأجهزة، على الرغم من احتمال وجود نسخ خارج الأجهزة الآمنة. إذا كان المفتاح موجودًا في قائمة عمليات فرض البرامج، فقد تم استيراد المفتاح إلى SoftKeymaster وهو غير مرتبط بالأجهزة.

يجب أن يظهر UNKNOWN فقط في القائمة التي يتم فرضها على الأجهزة. ويشير إلى أن المفتاح مرتبط بالأجهزة، ولكن ليس من المعروف ما إذا كان المفتاح قد تم إنشاؤه في الأصل في أجهزة آمنة أو تم استيراده. يحدث هذا فقط عند استخدام جهاز keymaster0 لمحاكاة خدمات keymaster1.

العلامة::ORIGINATION_EXPIRE_DATETIME

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد التاريخ والوقت الذي تنتهي فيه صلاحية المفتاح لأغراض التوقيع والتشفير. بعد هذا الوقت، ستفشل أي محاولة لاستخدام مفتاح مع KeyPurpose::SIGN أو KeyPurpose::ENCRYPT المقدم للبدء مع ErrorCode::KEY_EXPIRED .

القيمة عبارة عن عدد صحيح 64 بت يمثل المللي ثانية منذ 1 يناير 1970.

العلامة::OS_PATCHLEVEL

الإصدار : 2، 3، 4

قابل للتكرار ؟ لا

لا يتم إرسال هذه العلامة مطلقًا إلى keymaster TA، ولكن تتم إضافتها إلى قائمة التفويضات المفروضة على الأجهزة بواسطة TA.

قيمة العلامة هي عدد صحيح بالصيغة YYYYMM، حيث YYYY هي السنة المكونة من أربعة أرقام لآخر تحديث وMM هو الشهر المكون من رقمين لآخر تحديث. على سبيل المثال، بالنسبة للمفتاح الذي تم إنشاؤه على جهاز Android تم تحديثه آخر مرة في ديسمبر 2015، ستكون القيمة 201512.

المفاتيح التي لها مستوى تصحيح مختلف عن مستوى التصحيح الحالي غير قابلة للاستخدام. محاولة استخدام مثل هذا المفتاح تؤدي إلى start أو getKeyCharacteristics أو ExportKey لإرجاع ErrorCode::KEY_REQUIRES_UPGRADE . راجع ربط الإصدار لمزيد من التفاصيل.

العلامة::OS_VERSION

الإصدار : 2، 3، 4

قابل للتكرار ؟ لا

لا يتم إرسال هذه العلامة مطلقًا إلى keymaster TA، ولكن تتم إضافتها إلى قائمة التفويضات المفروضة على الأجهزة بواسطة TA.

قيمة العلامة هي عدد صحيح على شكل MMmmss، حيث MM هو رقم الإصدار الرئيسي، وmm هو رقم الإصدار الثانوي، وss هو رقم الإصدار الفرعي. على سبيل المثال، بالنسبة للمفتاح الذي تم إنشاؤه على إصدار Android 4.0.3، ستكون القيمة 040003.

العلامة::الحشوة

الإصدار : 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 وحشوة RSA PKCS#1 v1.5 العشوائية، على التوالي. يتم استخدام PaddingMode::RSA_PSS و PaddingMode::RSA_PKCS1_1_5_SIGN فقط لمفاتيح التوقيع/التحقق من RSA وتحديد حشوة RSA PKCS#1v2 PSS وحشوة RSA PKCS#1 v1.5 الحتمية، على التوالي.

يمكن استخدام PaddingMode::NONE مع مفاتيح RSA أو AES. بالنسبة لمفاتيح AES، إذا تم استخدام PaddingMode::NONE مع وضع الكتلة ECB أو CBC وكانت البيانات التي سيتم تشفيرها أو فك تشفيرها ليست من مضاعفات حجم كتلة AES في الطول، فسيفشل استدعاء الإنهاء باستخدام ErrorCode::INVALID_INPUT_LENGTH .

لا يجوز استخدام PaddingMode::PKCS7 إلا مع مفاتيح AES، ومع الوضعين ECB وCBC فقط.

هذه العلامة قابلة للتكرار. يجب تحديد وضع الحشو في المكالمة للبدء . إذا كان الوضع المحدد غير معتمد للمفتاح، فستفشل العملية مع ErrorCode::INCOMPATIBLE_BLOCK_MODE .

العلامة::الغرض

الإصدار : 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;

هذه العلامة قابلة للتكرار؛ يمكن إنشاء المفاتيح بقيم متعددة، على الرغم من أن العملية لها غرض واحد. عندما يتم استدعاء الدالة start لبدء عملية ما ، يتم تحديد الغرض من العملية. إذا كان الغرض المحدد للعملية غير معتمد بواسطة المفتاح، فستفشل العملية باستخدام ErrorCode::INCOMPATIBLE_PURPOSE .

العلامة::RESET_SINCE_ID_ROTATION

الإصدار : 3، 4

قابل للتكرار ؟ لا

يحدد ما إذا كان الجهاز قد تمت إعادة ضبطه على إعدادات المصنع منذ آخر عملية تدوير للمعرف الفريد. تستخدم لشهادة المفتاح.

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

العلامة::ROLLBACK_RESISTANT

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يشير إلى أن المفتاح مقاوم للتراجع، مما يعني أنه عند حذفه بواسطة deleteKey أو deleteAllKeys ، يتم ضمان حذف المفتاح نهائيًا وعدم قابليته للاستخدام. من الممكن أن يتم حذف المفاتيح التي لا تحتوي على هذه العلامة ثم استعادتها من النسخة الاحتياطية.

هذه العلامة منطقية، لذا فإن القيم المحتملة صحيحة (إذا كانت العلامة موجودة) وخطأ (إذا كانت العلامة غير موجودة).

العلامة::ROOT_OF_TRUST

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد جذر الثقة ، وهو المفتاح الذي يستخدمه التمهيد الذي تم التحقق منه للتحقق من صحة نظام التشغيل الذي تم تمهيده (إن وجد). لا يتم توفير هذه العلامة مطلقًا أو إرجاعها من Keymaster في الخصائص الرئيسية.

العلامة::RSA_PUBLIC_EXPONENT

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد قيمة الأس العام لزوج مفاتيح RSA. هذه العلامة ذات صلة بمفاتيح RSA فقط، وهي ضرورية لجميع مفاتيح RSA.

القيمة عبارة عن عدد صحيح غير موقّع بحجم 64 بت يلبي متطلبات الأس العام لـ RSA. يجب أن تكون هذه القيمة عددًا أوليًا. تدعم Trustlets القيمة 2^16+1 وقد تدعم قيمًا معقولة أخرى، على وجه الخصوص القيمة 3. إذا لم يتم تحديد أس أو إذا كان الأس المحدد غير مدعوم، فسيفشل إنشاء المفتاح باستخدام ErrorCode::INVALID_ARGUMENT .

العلامة::UNIQUE_ID

الإصدار : 3، 4

قابل للتكرار ؟ لا

يستخدم لتقديم معرف فريد في الشهادة.

القيمة عبارة عن blob، وهي عبارة عن مصفوفة ذات طول عشوائي من البايتات.

العلامة::USAGE_EXPIRE_DATETIME

الإصدار : 1، 2، 3، 4

قابل للتكرار ؟ لا

يحدد التاريخ والوقت الذي تنتهي فيه صلاحية المفتاح لأغراض التحقق وفك التشفير. بعد هذا الوقت، ستفشل أي محاولة لاستخدام مفتاح مع KeyPurpose::VERIFY أو KeyPurpose::DECRYPT المقدمة للبدء مع 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.

يجب أن يقرأ IKeymasterDevice HAL مستوى تصحيح البائع الحالي من خاصية النظام ro.vendor.build.security_patch ويسلمه إلى البيئة الآمنة عند تحميل HAL لأول مرة (يتم تحديد الآلية من خلال التنفيذ). يجب ألا تقبل البيئة الآمنة مستوى تصحيح آخر إلا بعد التمهيد التالي.

يجب أن يتم فرض الأجهزة.