علامات تفويض 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

لمعرفة الدوال، يُرجى الاطّلاع على صفحة وظائف Keymaster.

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

العلامة::ALL_المستخدمون

الإصدار: 3 و4

هل يمكن تكرار الإجراء؟ لا

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

العلامة::APPLICATION_DATA

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

هل يمكن تكرار الإجراء؟ لا

عند تقديمها إلى generateKey أو importKey، تحديدًا، تحدّد هذه العلامة البيانات اللازمة أثناء جميع استخدامات المفتاح. على سبيل المثال، يجب أن تقدّم المكالمات التي يتم إجراؤها لبدء exportKey وgetKeyCharacteristics القيمة نفسها للمَعلمة clientId، ويجب أن تقدّم المكالمات التي يتم إجراؤها لبدء begin هذه العلامة والبيانات المرتبطة نفسها كجزء من مجموعة inParams. إذا لم تتوفر البيانات الصحيحة، فستُرجع الدالة ErrorCode::INVALID_KEY_BLOB

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

القيمة هي ملفّ أرشيف، وهو صفيف من البايتات بحجم عشوائي.

Tag::APPLICATION_ID

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

هل يمكن تكرار الإجراء؟ لا

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

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

القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.

Tag::ASSOCIATED_DATA

الإصدار: 1 أو 2 أو 3 أو 4

هل يمكن تكرار الإجراء؟ لا

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

القيمة هي ملفّ أرشيف، وهو صفيف من البايتات بحجم عشوائي.

العلامة::ATTESTATION_APPLICATION_ID

الإصدار: 3 و4

هل يمكن تكرار الإجراء؟ لا

يُستخدَم لتحديد مجموعة التطبيقات المحتمَلة التي بدأ أحدها عملية إثبات ملكية المفتاح.

القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.

Tag::ATTESTATION_CHALLENGE

الإصدار: 3 و4

هل يمكن تكرار الإجراء؟ لا

تُستخدَم لتقديم تحدّي في الإقرار.

القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.

Tag::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.

القيمة هي ملفّ أرشيف، وهو صفيف من البايتات بحجم عشوائي.

Tag::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.

القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.

Tag::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.

القيمة هي كائن ثنائي كبير، وهو صفيف من وحدات بايت بالطول العشوائي.

Tag::AUTH_TIMEOUT

الإصدار: 1 أو 2 أو 3 أو 4

هل يمكن تكرار الإجراء؟ لا

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

والقيمة هي عدد صحيح 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 وسيطة begin. إذا لم يكُن الوضع المحدّد في الأوضاع المرتبطة بالمفتاح، سيتم تعذّر إتمام العملية مع ErrorCode::INCOMPATIBLE_BLOCK_MODE.

علامة::BOOT_PATCHLEVEL

الإصدار: 4

تحدِّد Tag::BOOT_PATCHLEVEL مستوى تصحيح أمان صورة التشغيل (النواة) الذي يمكن استخدام المفتاح معه. ولا يتم مطلقًا إرسال هذه العلامة إلى مساعد المفتاح الأساسي، ولكن يضيفه TA إلى قائمة التفويض التي تفرضها الأجهزة. أي محاولة استخدِم مفتاحًا بقيمة Tag::BOOT_PATCHLEVEL مختلفة عن ويسبب تشغيل مستوى تصحيح النظام حاليًا begin()، getKeyCharacteristics() أو exportKey() للإرجاع ErrorCode::KEY_REQUIRES_UPGRADE يمكنك الاطّلاع على upgradeKey(). لمزيد من التفاصيل.

قيمة العلامة هي عدد صحيح بالصيغة YYYYMMDD، حيث يشير YYYY إلى والسنة المكونة من أربعة أرقام لآخر تحديث، والحرف MM هو الشهر المكوّن من رقمين والرمز DD هو آخر تحديث ليوم مكون من رقمين. على سبيل المثال، بالنسبة إلى المفتاح الذي تم إنشاؤه على وكان آخر تحديث لجهاز Android في 5 حزيران (يونيو) 2018، ستكون القيمة 20180605. وإذا لم يكن اليوم معروفًا، يمكن استبدال 00.

أثناء كل عملية تشغيل، يجب أن يقدّم أداة تحميل البرامج مستوى التصحيح لصورة التشغيل إلى البيئة الآمنة (يتم تحديد الآلية من خلال التنفيذ).

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

Tag::BOOTLOADER_ONLY

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

هل يمكن تكراره؟ لا

يحدّد هذا الخيار أنّه لا يمكن استخدام المفتاح إلا من خلال أداة تحميل التشغيل.

هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم توفّر العلامة).

إنّ أي محاولة لاستخدام مفتاح مع 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. هذه العلامة اختيارية وإعلامية فقط.

العلامة::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 لسمة begin. إذا لم يكن الملخّص المحدّد مضمّنًا في الملخّصات المرتبطة بالمفتاح، تؤدي العملية إلى خطأ ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

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

هل يمكن تكرار الإجراء؟ لا

في Keymaster 1، تم تخمين المنحنى المستخدَم لمفاتيح التشفير المكافئ من حجم المفتاح المحدّد. لتحسين المرونة من الآن فصاعدًا، وفّرت أداة 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.

Tag::INCLUDE_UNIQUE_ID

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

هل يمكن تكرار الإجراء؟ لا

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

هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم توفّر العلامة).

Tag::KEY_SIZE

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

هل يمكن تكراره؟ لا

تُحدِّد هذه السمة حجم المفتاح بوحدة البت، ويتم القياس بالطريقة العادية لخوارزمية المفتاح. على سبيل المثال، بالنسبة إلى مفاتيح RSA، تحدّد الدالة Tag::KEY_SIZE. حجم المعامل العام. بالنسبة إلى مفاتيح AES، يحدِّد الطول لمادة المفتاح السري.

Tag::MAC_LENGTH

الإصدار: 1 أو 2 أو 3 أو 4

هل يمكن تكراره؟ لا

يوفّر الطول المطلوب لعلامة مصادقة MAC أو GCM، بالبت.

القيمة هي طول MAC بوحدات البت. وهو عدد مضاعَف لـ 8 ويجب أن يكون أكبر من قيمة Tag::MIN_MAC_LENGTH المرتبطة بالمفتاح.

Tag::MAX_USES_PER_BOOT

الإصدار: 1 أو 2 أو 3 أو 4

هل يمكن تكرار الإجراء؟ لا

تحدّد الحد الأقصى لعدد مرات استخدام المفتاح بين النظام. عمليات إعادة التشغيل. هذه آلية أخرى لتقييد معدّل استخدام المفاتيح.

القيمة هي عدد صحيح 32 بت يمثل الاستخدامات لكل تمهيد.

عند استخدام مفتاح بهذه العلامة في إحدى العمليات، يظهر العدّاد المرتبط بالمفتاح أثناء بدء الاتصال. بعد تجاوز مُعدّل التبديل للمفتاح هذه القيمة، تنتهي كل المحاولات اللاحقة لاستخدام المفتاح برمز الخطأ ErrorCode::MAX_OPS_EXCEEDED إلى أن تتم إعادة تشغيل الجهاز. ويشير ذلك إلى أنّ عنصر الثقة يحتفظ بجدول يتضمن عدادات الاستخدام للمفاتيح التي تحمل هذه العلامة . وبما أنّ ذاكرة Keymaster غالبًا ما تكون محدودة، يمكن أن يكون لهذا الجدول حجم أقصى ثابت، ويمكن أن يؤدي Keymaster إلى إيقاف العمليات التي تحاول استخدام المفاتيح التي تحتوي على هذه العلامة عندما يكون الجدول ممتلئًا. يجب أن يتضمّن الجدول 16 مفتاحًا على الأقل. إذا تعذّر إتمام عملية لأنّ الجدول ممتلئ، يعرض KeymasterErrorCode::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

Tag::NO_AUTH_REQUIRED

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

هل يمكن تكراره؟ لا

تشير إلى أنّه لا يلزم إجراء مصادقة لاستخدام هذا المفتاح. هذه العلامة حصرية باستخدام Tag::USER_SECURE_ID.

هذه العلامة منطقية، وبالتالي تكون القيم المحتملة صحيحة (في حالة وجود العلامة) وfalse (في حال عدم توفّر العلامة).

Tag::NONCE

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

هل يمكن تكرار الإجراء؟ لا

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

القيمة هي ملفّ أرشيف، وهو صفيف من البايتات بحجم عشوائي. الأطوال المسموح بها يعتمد على الوضع: يبلغ طول nonces في GCM 12 بايت؛ 16 عامًا على CBC ونسبة النقر إلى الظهور IV بايت.

Tag::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.

Tag::ORIGINATION_EXPIRE_DATETIME

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

هل يمكن تكراره؟ لا

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

القيمة هي عدد صحيح 64 بت يمثّل المللي ثانية منذ 1 كانون الثاني (يناير) 1970.

Tag::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

هل يمكن تكرار الإجراء؟ لا

لا يتم إرسال هذه العلامة مطلقًا إلى وحدة التحكّم في الإذن (TA) الخاصة ببرنامج Keymaster، ولكن تضيف وحدة التحكّم في الإذن هذه العلامة إلى قائمة الإذن المفروض من خلال الأجهزة.

قيمة العلامة هي عدد صحيح بالتنسيق 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 والحشو العشوائي 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 من حيث الطول، ستتعذّر الدعوة إلى finish باستخدام ErrorCode::INVALID_INPUT_LENGTH.

لا يمكن استخدام PaddingMode::PKCS7 إلا مع مفاتيح AES، ولا يمكن استخدامه إلا مع وضعَي ECB وCBC.

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

Tag::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 (في حال عدم توفّر العلامة).

Tag::ROLLBACK_RESISTANT

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

هل يمكن تكراره؟ لا

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

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

Tag::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

هل يمكن تكراره؟ لا

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

القيمة هي ملفّ أرشيف، وهو صفيف من البايتات بحجم عشوائي.

Tag::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

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

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