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

توفر هذه الصفحة تفاصيل لمساعدة منفذي Keymaster HALs. يغطي كل علامة في HAL ، وإصدار Keymaster الذي تتوفر به هذه العلامة ، وما إذا كانت العلامة قابلة للتكرار. باستثناء ما هو مذكور في أوصاف العلامات ، يتم استخدام جميع العلامات أدناه أثناء إنشاء المفتاح لتحديد الخصائص الرئيسية.

بالنسبة إلى Keymaster 4 ، يتم تحديد العلامات في النظام الأساسي / الأجهزة / الواجهات platform/hardware/interfaces/keymaster/ keymaster-version /types.hal / أنواع . يتم تحديد العلامات في platform/hardware/libhardware/include/hardware/keymaster_defs.h .

للوظائف ، انظر صفحة Keymaster Functions .

علامة :: ACTIVE_DATETIME

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

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

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

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

بطاقة :: ALGORITHM

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

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

يحدد خوارزمية التشفير التي يتم استخدام المفتاح معها.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

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

علامة :: ALL_USERS

الإصدار : 3 ، 4

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

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

علامة :: APPLICATION_DATA

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

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

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

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

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

علامة :: APPLICATION_ID

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

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

عند توفيرها لإنشاء مفتاح أو استيراد مفتاح ، تحدد هذه العلامة البيانات الضرورية أثناء جميع استخدامات المفتاح. على وجه الخصوص ، يجب أن توفر استدعاءات 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

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

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

إذا كان الجهاز لا يدعم شهادة المعرف (أو تم استدعاء 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

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

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

القيمة هي عدد صحيح 32 بت يحدد الوقت بالثواني بعد مصادقة ناجحة للمستخدم المحدد بواسطة Tag :: USER_SECURE_ID مع طريقة المصادقة المحددة بواسطة Tag :: USER_AUTH_TYPE التي يمكن استخدام المفتاح.

علامة :: AUTH_TOKEN

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

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

يوفر رمزًا مميزًا للمصادقة للبدء أو التحديث أو الانتهاء ، لإثبات مصادقة المستخدم لعملية المفتاح التي تتطلبها (المفتاح له علامة :: USER_SECURE_ID ).

القيمة عبارة عن blob يحتوي على بنية hw_auth_token_t .

علامة :: BLOB_USAGE_REQUIREMENTS

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

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

يحدد شروط بيئة النظام الضرورية لاستخدام المفتاح الذي تم إنشاؤه.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

enum 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;

يمكن تحديد هذه العلامة أثناء إنشاء المفتاح للمطالبة بأن يكون المفتاح قابلاً للاستخدام في الحالة المحددة. يجب إعادته مع الخصائص الرئيسية من إنشاء مفتاح و getKeyCharacteristics . إذا حدد المتصل Tag::BLOB_USAGE_REQUIREMENTS بقيمة KeyBlobUsageRequirements::STANDALONE يقوم Trustlet بإرجاع blob مفتاح يمكن استخدامه بدون دعم نظام الملفات. يعد هذا أمرًا بالغ الأهمية بالنسبة للأجهزة ذات الأقراص المشفرة ، حيث قد لا يكون نظام الملفات متاحًا إلا بعد استخدام مفتاح Keymaster لفك تشفير القرص.

علامة :: BLOCK_MODE

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

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

يحدد وضع (أوضاع) تشفير الكتلة التي يمكن استخدام المفتاح معها. هذه العلامة ذات صلة فقط بمفاتيح AES.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

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

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

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

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

تُستخدم هذه العلامة فقط لمفاتيح 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.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

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,
};

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 طريقة واضحة لتحديد المنحنيات. قد تحتوي طلبات إنشاء مفتاح EC على Tag::EC_CURVE أو Tag::KEY_SIZE أو كليهما.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

enum 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

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

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

علامة :: NO_AUTH_REQUIRED

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

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

يحدد عدم الحاجة إلى مصادقة لاستخدام هذا المفتاح. هذه العلامة حصرية بشكل متبادل مع العلامة :: USER_SECURE_ID .

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

علامة :: NONCE

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

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

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

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

علامة :: ORIGIN

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

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

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

يتم تحديد القيم الممكنة في 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 واستيراده إلى 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.

المفاتيح التي لها مستوى تصحيح مختلف عن مستوى التصحيح الحالي غير قابلة للاستخدام. تبدأ محاولة استخدام مثل هذه الأسباب الرئيسية ، أو 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.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

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,
};

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 padding و 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

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

يحدد مجموعة الأغراض التي يمكن استخدام المفتاح من أجلها.

يتم تحديد القيم الممكنة من خلال التعداد التالي:

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
};

typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

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

enum 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 لأول مرة (الآلية معرّفة من قبل التنفيذ). يجب ألا تقبل البيئة الآمنة patchlevel آخر إلا بعد التمهيد التالي.

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