وظائف Keymaster، وظائف Keymaster

توفر هذه الصفحة تفاصيل لمساعدة منفذي طبقات تجريد أجهزة Keymaster (HALs). وهو يغطي كل وظيفة في واجهة برمجة التطبيقات (API) وإصدار Keymaster الذي تتوفر فيه هذه الوظيفة ويصف التنفيذ الافتراضي. بالنسبة للعلامات، راجع صفحة علامات Keymaster .

المبادئ التوجيهية العامة للتنفيذ

تنطبق الإرشادات التالية على جميع الوظائف في واجهة برمجة التطبيقات.

معلمات مؤشر الإدخال

الإصدار : 1، 2

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

إذا كانت معلمة الإدخال المطلوبة NULL، فيجب أن تقوم أساليب Keymaster بإرجاع ErrorCode::UNEXPECTED_NULL_POINTER .

بدءًا من Keymaster 3، لا توجد معلمات للمؤشر. يتم تمرير كافة المعلمات حسب القيمة أو مراجع const.

معلمات مؤشر الإخراج

الإصدار : 1، 2

كما هو الحال مع معلمات مؤشر الإدخال، قد تكون معلمات مؤشر الإخراج غير المستخدمة NULL . إذا احتاجت إحدى الطرق إلى إرجاع البيانات في معلمة إخراج وجدت أنها NULL ، فيجب أن تُرجع ErrorCode::OUTPUT_PARAMETER_NULL .

بدءًا من Keymaster 3، لا توجد معلمات للمؤشر. يتم تمرير كافة المعلمات حسب القيمة أو مراجع const.

إساءة استخدام واجهة برمجة التطبيقات

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

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

تقع على عاتق التطبيقات وإطار العمل ومخزن مفاتيح Android مسؤولية التأكد من أن الاستدعاءات إلى وحدات Keymaster معقولة ومفيدة.

المهام

ميزات الأجهزة

الإصدار : 3

تعرض طريقة getHardwareFeatures الجديدة للعملاء بعض الخصائص المهمة للأجهزة الآمنة الأساسية. لا تأخذ الطريقة أي وسيطات وترجع أربع قيم، جميعها منطقية:

  • يكون isSecure true إذا تم تخزين المفاتيح في أجهزة آمنة (TEE، وما إلى ذلك) ولا تتركها أبدًا.
  • يكون supportsEllipticCurve true إذا كان الجهاز يدعم تشفير Elliptic Curve باستخدام منحنيات NIST (P-224 وP-256 وP-384 وP-521).
  • يعد supportsSymmetricCryptography true إذا كان الجهاز يدعم التشفير المتماثل، بما في ذلك AES وHMAC.
  • يكون supportsAttestation true إذا كان الجهاز يدعم إنشاء شهادات تصديق المفتاح العام لـ Keymaster، موقعة بمفتاح تم إدخاله في بيئة آمنة.

رموز الخطأ الوحيدة التي قد ترجعها هذه الطريقة هي ErrorCode:OK أو ErrorCode::KEYMASTER_NOT_CONFIGURED أو أحد رموز الخطأ التي تشير إلى فشل الاتصال بالأجهزة الآمنة.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

تهيئة

الإصدار 2

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

تكوين مدير المفاتيح. يتم استدعاء هذه الطريقة مرة واحدة بعد فتح الجهاز وقبل استخدامه. يتم استخدامه لتوفير KM_TAG_OS_VERSION و KM_TAG_OS_PATCHLEVEL إلى مدير المفاتيح. حتى يتم استدعاء هذه الطريقة، تقوم جميع الطرق الأخرى بإرجاع KM_ERROR_KEYMASTER_NOT_CONFIGURED . يتم قبول القيم التي توفرها هذه الطريقة بواسطة keymaster مرة واحدة فقط لكل تمهيد. تُرجع الاستدعاءات اللاحقة KM_ERROR_OK ، لكن لا تفعل شيئًا.

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

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

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

تم تقديم هذه الوظيفة في Keymaster 1 باسم add_rng_entropy وتمت إعادة تسميتها في Keymaster 3.

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

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

تفترض تطبيقات Keymaster التي تحاول تقدير الإنتروبيا في مجموعتها الداخلية أن البيانات المقدمة من addRngEntropy لا تحتوي على إنتروبيا. قد تُرجع تطبيقات Keymaster ErrorCode::INVALID_INPUT_LENGTH إذا تم إعطاؤها أكثر من 2 كيلو بايت من البيانات في مكالمة واحدة.

createKey

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

تم تقديم هذه الوظيفة في Keymaster 1 باسم generate_key وتمت إعادة تسميتها في Keymaster 3.

يُنشئ مفتاح تشفير جديدًا، مع تحديد التفويضات المرتبطة والمرتبطة بشكل دائم بالمفتاح. تجعل تطبيقات Keymaster من المستحيل استخدام المفتاح بأي طريقة لا تتوافق مع التفويضات المحددة في وقت الإنشاء. فيما يتعلق بالتفويضات التي لا يمكن للأجهزة الآمنة تنفيذها، يقتصر التزام الأجهزة الآمنة على ضمان عدم إمكانية تعديل التفويضات غير القابلة للتنفيذ المرتبطة بالمفتاح، بحيث تقوم كل استدعاء لـ getKeyCharacteristics بإرجاع القيمة الأصلية. بالإضافة إلى ذلك، تقوم الخصائص التي يتم إرجاعها بواسطة generateKey بتخصيص التفويضات بشكل صحيح بين القوائم التي يتم فرضها بواسطة الأجهزة والقوائم التي يتم فرضها بواسطة البرامج. راجع getKeyCharacteristics لمزيد من التفاصيل.

تعتمد المعلمات المتوفرة لـ generateKey على نوع المفتاح الذي يتم إنشاؤه. يلخص هذا القسم العلامات الضرورية والاختيارية لكل نوع من المفاتيح. العلامة::ALGORITHM ضرورية دائمًا لتحديد النوع.

مفاتيح آر إس إيه

المعلمات التالية ضرورية لإنشاء مفتاح RSA.

  • يحدد Tag::KEY_SIZE حجم المعامل العام بالبت. إذا تم حذفه، فستُرجع الطريقة ErrorCode::UNSUPPORTED_KEY_SIZE . القيم المدعومة هي 1024 و2048 و3072 و4096. القيم الموصى بها هي جميع أحجام المفاتيح التي تكون من مضاعفات الرقم 8.
  • العلامة::RSA_PUBLIC_EXPONENT تحدد قيمة الأس العامة لـ RSA. إذا تم حذفه، فستُرجع الطريقة ErrorCode::INVALID_ARGUMENT . القيم المدعومة هي 3 و65537. القيم الموصى بها هي جميع القيم الأولية حتى 2^64.

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

  • العلامة::PURPOSE تحدد الأغراض المسموح بها. يجب دعم جميع الأغراض لمفاتيح RSA، بأي مجموعة.
  • يحدد Tag::DIGEST خوارزميات الملخص التي يمكن استخدامها مع المفتاح الجديد. تحتاج التطبيقات التي لا تدعم جميع خوارزميات الملخص إلى قبول طلبات إنشاء المفاتيح التي تتضمن ملخصات غير مدعومة. يجب وضع الملخصات غير المدعومة في قائمة "البرامج المفروضة" في خصائص المفاتيح التي تم إرجاعها. وذلك لأن المفتاح قابل للاستخدام مع تلك الملخصات الأخرى، ولكن يتم تنفيذ عملية الهضم في البرنامج. ثم يتم استدعاء الأجهزة لتنفيذ العملية باستخدام Digest::NONE .
  • يحدد Tag::PADDING أوضاع الحشو التي يمكن استخدامها مع المفتاح الجديد. تحتاج التطبيقات التي لا تدعم جميع خوارزميات الملخص إلى وضع PaddingMode::RSA_PSS و PaddingMode::RSA_OAEP في قائمة الخصائص الرئيسية التي يفرضها البرنامج في حالة تحديد أي خوارزميات ملخص غير مدعومة.

مفاتيح ECDSA

فقط العلامة::KEY_SIZE ضرورية لإنشاء مفتاح ECDSA. يتم استخدامه لتحديد مجموعة EC. القيم المدعومة هي 224 و256 و384 و521، والتي تشير إلى منحنيات NIST p-224 وp-256 وp-384 وp521، على التوالي.

العلامة::DIGEST ضرورية أيضًا لمفتاح ECDSA مفيد، ولكنها غير مطلوبة للإنشاء.

مفاتيح الخدمات المعمارية والهندسية

فقط العلامة::KEY_SIZE ضرورية لإنشاء مفتاح AES. إذا تم حذفه، فستُرجع الطريقة ErrorCode::UNSUPPORTED_KEY_SIZE . القيم المدعومة هي 128 و256، مع دعم اختياري لمفاتيح AES 192 بت.

المعلمات التالية ذات صلة بشكل خاص بمفاتيح AES، ولكنها ليست ضرورية لإنشاء واحدة:

  • يحدد Tag::BLOCK_MODE أوضاع الحظر التي يمكن استخدام المفتاح الجديد بها.
  • يحدد Tag::PADDING أوضاع الحشو التي يمكن استخدامها. هذا ينطبق فقط على وضعي ECB وCBC.

إذا تم تحديد وضع كتلة GCM، فقم بتوفير العلامة::MIN_MAC_LENGTH . إذا تم حذفه، تقوم الطريقة بإرجاع ErrorCode::MISSING_MIN_MAC_LENGTH . قيمة العلامة هي من مضاعفات الرقم 8 وبين 96 و128.

مفاتيح HMAC

المعلمات التالية مطلوبة لإنشاء مفتاح HMAC:

  • تحدد العلامة::KEY_SIZE حجم المفتاح بالبت. القيم الأصغر من 64 والقيم التي ليست من مضاعفات الرقم 8 غير مدعومة. يتم دعم جميع مضاعفات الرقم 8، من 64 إلى 512. قد يتم دعم القيم الأكبر.
  • تحدد العلامة::MIN_MAC_LENGTH الحد الأدنى لطول أجهزة MAC التي يمكن إنشاؤها أو التحقق منها باستخدام هذا المفتاح. القيمة هي من مضاعفات 8 و64 على الأقل.
  • يحدد Tag::DIGEST خوارزمية الملخص للمفتاح. يتم تحديد ملخص واحد بالضبط، وإلا فسيتم إرجاع ErrorCode::UNSUPPORTED_DIGEST . إذا لم يكن الملخص مدعومًا من قبل Trustlet، فقم بإرجاع ErrorCode::UNSUPPORTED_DIGEST .

الخصائص الرئيسية

إذا كانت وسيطة الخصائص غير NULL، فإن generateKey يُرجع خصائص المفتاح الذي تم إنشاؤه حديثًا مقسمة بشكل مناسب إلى قوائم يتم فرضها بواسطة الأجهزة وقوائم يتم فرضها بواسطة البرامج. راجع getKeyCharacteristics للحصول على وصف للخصائص الموجودة في أي قائمة. تتضمن الخصائص التي تم إرجاعها كافة المعلمات المحددة لإنشاء المفاتيح، باستثناء Tag::APPLICATION_ID و Tag::APPLICATION_DATA . إذا تم تضمين هذه العلامات في المعلمات الرئيسية، فسيتم إزالتها من الخصائص التي تم إرجاعها بحيث لا يكون من الممكن العثور على قيمها عن طريق فحص النقطة الرئيسية التي تم إرجاعها. ومع ذلك، فهي مرتبطة بشكل مشفر بنقطة المفتاح، بحيث إذا لم يتم توفير القيم الصحيحة عند استخدام المفتاح، يفشل الاستخدام. وبالمثل، فإن العلامة::ROOT_OF_TRUST مرتبطة بالمفتاح تشفيرًا، ولكن قد لا يتم تحديدها أثناء إنشاء المفتاح أو استيراده ولا يتم إرجاعها أبدًا.

بالإضافة إلى العلامات المتوفرة، تضيف الثقة أيضًا Tag::ORIGIN ، بالقيمة KeyOrigin::GENERATED ، وإذا كان المفتاح مقاومًا للتراجع،

العلامة::ROLLBACK_RESISTANT .

مقاومة التراجع

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

يكون المفتاح مقاومًا للتراجع إذا كانت الأجهزة الآمنة تضمن عدم إمكانية استعادة المفاتيح المحذوفة لاحقًا. يتم ذلك عمومًا عن طريق تخزين بيانات التعريف الرئيسية الإضافية في موقع موثوق به لا يمكن للمهاجم معالجته. على الأجهزة المحمولة، عادةً ما تكون الآلية المستخدمة لذلك هي إعادة تشغيل كتل الذاكرة المحمية (RPMB). نظرًا لأن عدد المفاتيح التي يمكن إنشاؤها غير محدود بشكل أساسي وأن مساحة التخزين الموثوقة المستخدمة لمقاومة التراجع قد تكون محدودة الحجم، فيجب أن تنجح هذه الطريقة حتى لو لم يكن من الممكن توفير مقاومة التراجع للمفتاح الجديد. في هذه الحالة، لا ينبغي إضافة Tag::ROLLBACK_RESISTANT إلى الخصائص الرئيسية.

getKeyCharacteristics

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

تم تقديم هذه الوظيفة في Keymaster 1 باسم get_key_characteristics وتمت إعادة تسميتها في Keymaster 3.

إرجاع المعلمات والتفويضات المرتبطة بالمفتاح المقدم، مقسمة إلى مجموعتين: فرضها الأجهزة وفرضها البرمجيات. ينطبق الوصف هنا بالتساوي على قوائم الخصائص الرئيسية التي يتم إرجاعها بواسطة generatorKey و importKey .

إذا تم توفير Tag::APPLICATION_ID أثناء إنشاء المفتاح أو الاستيراد، فسيتم توفير نفس القيمة لهذه الطريقة في وسيطة clientId . بخلاف ذلك، تقوم الطريقة بإرجاع ErrorCode::INVALID_KEY_BLOB . وبالمثل، إذا تم توفير Tag::APPLICATION_DATA أثناء الإنشاء أو الاستيراد، فسيتم توفير نفس القيمة لهذه الطريقة في وسيطة appData .

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

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

  • Tag::ALGORITHM و Tag::KEY_SIZE و Tag::RSA_PUBLIC_EXPONENT هي خصائص جوهرية للمفتاح. بالنسبة لأي مفتاح مؤمن بواسطة الأجهزة، ستكون هذه العلامات موجودة في القائمة التي يتم فرضها بواسطة الأجهزة.
  • يتم وضع قيم العلامة::DIGEST التي يدعمها الجهاز الآمن في القائمة المدعومة بالجهاز. يتم إدراج الملخصات غير المدعومة في القائمة المدعومة بالبرامج.
  • يتم وضع قيم Tag::PADDING بشكل عام في القائمة المدعومة بالأجهزة، ما لم يكن هناك احتمال أن يتم تنفيذ وضع الحشو المحدد بواسطة البرنامج. وفي هذه الحالة، يتم إدراجهم في القائمة المفروضة بواسطة البرامج. ينشأ مثل هذا الاحتمال بالنسبة لمفاتيح RSA التي تسمح بحشو PSS أو OAEP مع خوارزميات الملخص التي لا تدعمها الأجهزة الآمنة.
  • يتم فرض العلامة::USER_SECURE_ID و Tag::USER_AUTH_TYPE عن طريق الأجهزة فقط إذا كانت مصادقة المستخدم مفروضة على الأجهزة. ولتحقيق ذلك، يجب أن يكون كل من Keymaster Trustlet وصندوق المصادقة ذي الصلة آمنين وأن يتشاركا مفتاح HMAC السري المستخدم للتوقيع والتحقق من صحة رموز المصادقة المميزة. راجع صفحة المصادقة للحصول على التفاصيل.
  • تتطلب العلامات::ACTIVE_DATETIME ، و Tag::ORIGINATION_EXPIRE_DATETIME ، و Tag::USAGE_EXPIRE_DATETIME الوصول إلى ساعة حائط صحيحة يمكن التحقق منها. لا تتمتع معظم الأجهزة الآمنة إلا بإمكانية الوصول إلى معلومات الوقت التي يوفرها نظام التشغيل غير الآمن، مما يعني أن العلامات يتم فرضها بواسطة البرامج.
  • العلامة::ORIGIN موجودة دائمًا في قائمة الأجهزة للمفاتيح المرتبطة بالأجهزة. إن وجوده في تلك القائمة هو الطريقة التي تحدد بها الطبقات العليا أن المفتاح مدعوم بالأجهزة.

importKey

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

تم تقديم هذه الوظيفة في Keymaster 1 باسم import_key وتمت إعادة تسميتها في Keymaster 3.

يستورد المواد الرئيسية إلى أجهزة Keymaster. تتم معالجة معلمات تعريف المفتاح وخصائص الإخراج بنفس الطريقة التي يتم بها التعامل مع generateKey ، مع الاستثناءات التالية:

  • العلامة::KEY_SIZE والعلامة ::RSA_PUBLIC_EXPONENT (لمفاتيح RSA فقط) ليست ضرورية في معلمات الإدخال. إذا لم يتم توفيره، فإن Trustlet يستنتج القيم من المادة الرئيسية المقدمة ويضيف العلامات والقيم المناسبة إلى الخصائص الرئيسية. إذا تم توفير المعلمات، فإن Trustlet يتحقق من صحتها مقابل المادة الرئيسية. في حالة عدم التطابق، تقوم الطريقة بإرجاع ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • العلامة::ORIGIN التي تم إرجاعها لها نفس قيمة KeyOrigin::IMPORTED .

importKey

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

تم تقديم هذه الوظيفة في Keymaster 1 باسم export_key وتمت إعادة تسميتها في Keymaster 3.

يصدر مفتاحًا عامًا من زوج مفاتيح Keymaster RSA أو EC.

إذا تم توفير Tag::APPLICATION_ID أثناء إنشاء المفتاح أو الاستيراد، فسيتم توفير نفس القيمة لهذه الطريقة في وسيطة clientId . بخلاف ذلك، تقوم الطريقة بإرجاع ErrorCode::INVALID_KEY_BLOB . وبالمثل، إذا تم توفير Tag::APPLICATION_DATA أثناء الإنشاء أو الاستيراد، فسيتم توفير نفس القيمة لهذه الطريقة في وسيطة appData .

deleteKey

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

تم تقديم هذه الوظيفة في Keymaster 1 كـ delete_key وتمت إعادة تسميتها في Keymaster 3.

يحذف المفتاح المقدم. هذه الطريقة اختيارية، ويتم تنفيذها فقط من خلال وحدات Keymaster التي توفر مقاومة التراجع.

this.deleteAllKeys

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

تم تقديم هذه الوظيفة في Keymaster 1 كـ delete_all_keys وتمت إعادة تسميتها في Keymaster 3.

يحذف كافة المفاتيح. هذه الطريقة اختيارية، ويتم تنفيذها فقط من خلال وحدات Keymaster التي توفر مقاومة التراجع.

معرفات التدمير

الإصدار : 3

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

رموز الخطأ الوحيدة التي قد ترجعها هذه الطريقة هي ErrorCode::UNIMPLEMENTED (إذا لم تكن شهادة المعرف مدعومة)، أو ErrorCode:OK ، أو ErrorCode::KEYMASTER_NOT_CONFIGURED أو أحد رموز الخطأ التي تشير إلى فشل الاتصال بالأجهزة الآمنة.

يبدأ

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

تبدأ عملية تشفير، باستخدام المفتاح المحدد، للغرض المحدد، باستخدام المعلمات المحددة (حسب الاقتضاء)، وإرجاع مقبض العملية المستخدم مع التحديث والإنهاء لإكمال العملية. يُستخدم مقبض العملية أيضًا كرمز "التحدي" في العمليات التي تمت المصادقة عليها، ويتم تضمينه لمثل هذه العمليات في حقل challenge الخاص برمز المصادقة.

يدعم تطبيق Keymaster ما لا يقل عن 16 عملية متزامنة. يستخدم Keystore ما يصل إلى 15، ويترك واحدًا لـ vold لاستخدامه في تشفير كلمة المرور. عندما يكون لدى Keystore 15 عملية قيد التقدم (تم استدعاء begin ، ولكن لم يتم استدعاء finish أو abort بعد) ويتلقى طلبًا لبدء العملية السادسة عشرة، فإنه يستدعي abort العملية الأقل استخدامًا مؤخرًا لتقليل عدد العمليات النشطة إلى 14 قبل بدء الاتصال begin العملية المطلوبة حديثًا.

إذا تم تحديد Tag::APPLICATION_ID أو Tag::APPLICATION_DATA أثناء إنشاء المفتاح أو الاستيراد، فإن الاستدعاءات begin تتضمن تلك العلامات ذات القيم المحددة في الأصل في وسيطة inParams لهذه الطريقة.

إنفاذ الترخيص

خلال هذه الطريقة، يتم فرض تفويضات المفاتيح التالية بواسطة Trustlet إذا وضعها التنفيذ في خصائص "فرض الأجهزة" وإذا لم تكن العملية عملية مفتاح عام. يُسمح لعمليات المفتاح العام، أي KeyPurpose::ENCRYPT و KeyPurpose::VERIFY ، باستخدام مفاتيح RSA أو EC، بالنجاح حتى لو لم يتم استيفاء متطلبات الترخيص.

  • Tag::PURPOSE : يجب أن يتطابق الغرض المحدد في استدعاء begin() مع أحد الأغراض في تفويضات المفتاح، ما لم تكن العملية المطلوبة عبارة عن عملية مفتاح عام. إذا كان الغرض المحدد غير متطابق وكانت العملية ليست عملية مفتاح عام، فسيُرجع begin ErrorCode::UNSUPPORTED_PURPOSE . عمليات المفتاح العام هي عمليات تشفير أو تحقق غير متماثلة.
  • العلامة::ACTIVE_DATETIME لا يمكن فرضها إلا في حالة توفر مصدر وقت UTC موثوق به. إذا كان التاريخ والوقت الحاليان يسبقان قيمة العلامة، فستُرجع الطريقة ErrorCode::KEY_NOT_YET_VALID .
  • العلامة::ORIGINATION_EXPIRE_DATETIME لا يمكن فرضها إلا في حالة توفر مصدر وقت UTC موثوق به. إذا كان التاريخ والوقت الحاليان أحدث من قيمة العلامة والغرض هو KeyPurpose::ENCRYPT أو KeyPurpose::SIGN ، فستُرجع الطريقة ErrorCode::KEY_EXPIRED .
  • العلامة::USAGE_EXPIRE_DATETIME لا يمكن فرضها إلا في حالة توفر مصدر وقت UTC موثوق به. إذا كان التاريخ والوقت الحاليان أحدث من قيمة العلامة والغرض هو KeyPurpose::DECRYPT أو KeyPurpose::VERIFY ، فسترجع الطريقة ErrorCode::KEY_EXPIRED .
  • تتم مقارنة العلامة::MIN_SECONDS_BETWEEN_OPS بمؤقت نسبي موثوق به يشير إلى آخر استخدام للمفتاح. إذا كان وقت الاستخدام الأخير بالإضافة إلى قيمة العلامة أقل من الوقت الحالي، فستُرجع الطريقة ErrorCode::KEY_RATE_LIMIT_EXCEEDED . راجع وصف العلامة للحصول على تفاصيل التنفيذ المهمة.
  • تتم مقارنة العلامة::MAX_USES_PER_BOOT بعداد آمن يتتبع استخدامات المفتاح منذ وقت التمهيد. إذا تجاوز عدد الاستخدامات السابقة قيمة العلامة، فستُرجع الطريقة ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • يتم فرض Tag::USER_SECURE_ID بهذه الطريقة فقط إذا كان المفتاح يحتوي أيضًا على Tag::AUTH_TIMEOUT . إذا كان المفتاح يحتوي على كليهما، فيجب أن تتلقى هذه الطريقة علامة صالحة::AUTH_TOKEN في inParams . لكي يكون رمز المصادقة صالحًا، يجب أن يكون كل ما يلي صحيحًا:
    • يتم التحقق من صحة حقل HMAC بشكل صحيح.
    • تتطابق واحدة على الأقل من قيم Tag::USER_SECURE_ID من المفتاح مع واحدة على الأقل من قيم المعرف الآمن في الرمز المميز.
    • يحتوي المفتاح على علامة::USER_AUTH_TYPE التي تطابق نوع المصادقة في الرمز المميز.

    إذا لم يتم استيفاء أي من هذه الشروط، تقوم الطريقة بإرجاع ErrorCode::KEY_USER_NOT_AUTHENTICATED .

  • العلامة::CALLER_NONCE تسمح للمتصل بتحديد nonce أو متجه التهيئة (IV). إذا لم يكن المفتاح يحتوي على هذه العلامة، ولكن المتصل قدم العلامة::NONCE لهذه الطريقة، فسيتم إرجاع ErrorCode::CALLER_NONCE_PROHIBITED .
  • تحدد العلامة::BOOTLOADER_ONLY أن أداة تحميل التشغيل فقط هي التي يمكنها استخدام المفتاح. إذا تم استدعاء هذه الطريقة باستخدام مفتاح أداة تحميل التشغيل فقط بعد انتهاء تنفيذ أداة تحميل التشغيل، فإنها تُرجع ErrorCode::INVALID_KEY_BLOB .

مفاتيح آر إس إيه

تحدد جميع عمليات مفتاح RSA وضعًا واحدًا للحشوة في inParams . إذا لم يتم تحديده أو تحديده أكثر من مرة، فستُرجع الطريقة ErrorCode::UNSUPPORTED_PADDING_MODE .

تحتاج عمليات التوقيع والتحقق من RSA إلى ملخص، كما هو الحال مع عمليات تشفير وفك تشفير RSA مع وضع الحشو OAEP. في تلك الحالات، يحدد المتصل ملخصًا واحدًا بالضبط في inParams . إذا لم يتم تحديده أو تحديده أكثر من مرة، فستُرجع الطريقة ErrorCode::UNSUPPORTED_DIGEST .

تحتاج عمليات المفتاح الخاص ( KeyPurpose::DECYPT و KeyPurpose::SIGN ) إلى تفويض للملخص والحشو، مما يعني أن تفويضات المفتاح يجب أن تحتوي على القيم المحددة. إذا لم يكن الأمر كذلك، تقوم الطريقة بإرجاع ErrorCode::INCOMPATIBLE_DIGEST أو ErrorCode::INCOMPATIBLE_PADDING ، حسب الاقتضاء. يُسمح بعمليات المفتاح العام ( KeyPurpose::ENCRYPT و KeyPurpose::VERIFY ) مع ملخص أو حشوة غير مصرح بها.

باستثناء PaddingMode::NONE ، تنطبق جميع أوضاع الحشو RSA على أغراض معينة فقط. على وجه التحديد، يدعم PaddingMode::RSA_PKCS1_1_5_SIGN و PaddingMode::RSA_PSS التوقيع والتحقق فقط، بينما يدعم PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT و PaddingMode::RSA_OAEP التشفير وفك التشفير فقط. تقوم الطريقة بإرجاع ErrorCode::UNSUPPORTED_PADDING_MODE إذا كان الوضع المحدد لا يدعم الغرض المحدد.

هناك بعض التفاعلات المهمة بين أوضاع الحشو والخلاصات:

  • يشير PaddingMode::NONE إلى أنه تم تنفيذ عملية RSA "أولية". في حالة التوقيع أو التحقق، يتم تحديد Digest::NONE للملخص. لا يوجد ملخص ضروري للتشفير أو فك التشفير غير المبطن.
  • PaddingMode::RSA_PKCS1_1_5_SIGN تتطلب الحشوة ملخصًا. قد يكون الملخص Digest::NONE ، وفي هذه الحالة لا يمكن لتطبيق Keymaster إنشاء بنية توقيع PKCS#1 v1.5 مناسبة، لأنه لا يمكنه إضافة بنية DigestInfo. بدلاً من ذلك، ينشئ التطبيق 0x00 || 0x01 || PS || 0x00 || M ، حيث M هي الرسالة المقدمة وPS هي سلسلة الحشو. يجب أن يكون حجم مفتاح RSA أكبر من الرسالة بـ 11 بايت على الأقل، وإلا تقوم الطريقة بإرجاع ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT لا تتطلب الحشوة ملخصًا.
  • تتطلب الحشوة PaddingMode::RSA_PSS ملخصًا، والذي قد لا يكون Digest::NONE . إذا تم تحديد Digest::NONE ، فستُرجع الطريقة ErrorCode::INCOMPATIBLE_DIGEST . بالإضافة إلى ذلك، يجب أن يكون حجم مفتاح RSA أكبر بمقدار 2 + D بايت على الأقل من حجم إخراج الملخص، حيث D هو حجم الملخص بالبايت. وإلا فإن الطريقة ترجع ErrorCode::INCOMPATIBLE_DIGEST . حجم الملح د.
  • تتطلب الحشوة PaddingMode::RSA_OAEP ملخصًا، والذي قد لا يكون Digest::NONE . إذا تم تحديد Digest::NONE ، فستُرجع الطريقة ErrorCode::INCOMPATIBLE_DIGEST .

مفاتيح المفوضية الأوروبية

تحدد عمليات مفتاح EC وضعًا واحدًا للحشوة في inParams . إذا لم يتم تحديده أو تحديده أكثر من مرة، فستُرجع الطريقة ErrorCode::UNSUPPORTED_PADDING_MODE .

تحتاج عمليات المفتاح الخاص ( KeyPurpose::SIGN ) إلى تفويض للملخص والحشو، مما يعني أن تفويضات المفتاح يجب أن تحتوي على القيم المحددة. إذا لم يكن الأمر كذلك، قم بإرجاع ErrorCode::INCOMPATIBLE_DIGEST . يُسمح بعمليات المفتاح العام ( KeyPurpose::VERIFY ) مع ملخص أو حشوة غير مصرح بها.

مفاتيح الخدمات المعمارية والهندسية

تحدد عمليات مفتاح AES وضع كتلة واحدًا ووضعًا حشوًا واحدًا بالضبط في inParams . إذا كانت إحدى القيمتين غير محددة أو تم تحديدها أكثر من مرة، فقم بإرجاع ErrorCode::UNSUPPORTED_BLOCK_MODE أو ErrorCode::UNSUPPORTED_PADDING_MODE . يجب أن يتم ترخيص الأوضاع المحددة بواسطة المفتاح، وإلا فسترجع الطريقة ErrorCode::INCOMPATIBLE_BLOCK_MODE أو ErrorCode::INCOMPATIBLE_PADDING_MODE .

إذا كان وضع الكتلة هو BlockMode::GCM ، فإن inParams يحدد Tag::MAC_LENGTH ، والقيمة المحددة هي من مضاعفات 8 والتي لا تزيد عن 128 أو أقل من قيمة Tag::MIN_MAC_LENGTH في تفويضات المفاتيح. بالنسبة لأطوال MAC الأكبر من 128 أو غير مضاعفات 8، قم بإرجاع ErrorCode::UNSUPPORTED_MAC_LENGTH . بالنسبة للقيم الأقل من الحد الأدنى لطول المفتاح، قم بإرجاع ErrorCode::INVALID_MAC_LENGTH .

إذا كان وضع الكتلة هو BlockMode::GCM أو BlockMode::CTR ، فيجب أن يكون وضع الحشو المحدد هو PaddingMode::NONE . بالنسبة إلى BlockMode::ECB أو BlockMode::CBC ، قد يكون الوضع هو PaddingMode::NONE أو PaddingMode::PKCS7 . إذا كان وضع الحشو لا يستوفي هذه الشروط، فقم بإرجاع ErrorCode::INCOMPATIBLE_PADDING_MODE .

إذا كان وضع الكتلة هو BlockMode::CBC أو BlockMode::CTR أو BlockMode::GCM ، فستكون هناك حاجة إلى ناقل التهيئة أو nonce. في معظم الحالات، لا ينبغي للمتصلين تقديم الوريد أو عدمه. في هذه الحالة، يقوم تطبيق Keymaster بإنشاء IV أو nonce عشوائيًا ويعيده عبر Tag::NONCE في outParams . يبلغ حجم CBC وCTR IVs 16 بايت. أرقام GCM هي 12 بايت. إذا كانت تفويضات المفتاح تحتوي على Tag::CALLER_NONCE ، فيمكن للمتصل تقديم IV/nonce مع Tag::NONCE في inParams . إذا تم توفير الرقم nonce عندما يكون Tag::CALLER_NONCE غير مصرح به، فقم بإرجاع ErrorCode::CALLER_NONCE_PROHIBITED . إذا لم يتم توفير رقم nonce عند ترخيص Tag::CALLER_NONCE ، فقم بإنشاء رقم IV/nonce عشوائي.

مفاتيح HMAC

تحدد عمليات مفتاح HMAC Tag::MAC_LENGTH في inParams . يجب أن تكون القيمة المحددة من مضاعفات الرقم 8 بحيث لا تكون أكبر من طول الملخص أو أقل من قيمة Tag::MIN_MAC_LENGTH في تفويضات المفتاح. بالنسبة لأطوال MAC الأكبر من طول الملخص أو غير مضاعفات 8، قم بإرجاع ErrorCode::UNSUPPORTED_MAC_LENGTH . بالنسبة للقيم الأقل من الحد الأدنى لطول المفتاح، قم بإرجاع ErrorCode::INVALID_MAC_LENGTH .

تحديث

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

يوفر بيانات للمعالجة في عملية مستمرة تبدأ بـ begin . يتم تحديد العملية بواسطة معلمة operationHandle .

لتوفير المزيد من المرونة لمعالجة المخزن المؤقت، تتمتع تطبيقات هذه الطريقة بخيار استهلاك بيانات أقل مما تم توفيره. يكون المتصل مسؤولاً عن التكرار لتغذية بقية البيانات في المكالمات اللاحقة. يتم إرجاع مقدار الإدخال المستهلك في المعلمة inputConsumed . تستهلك عمليات التنفيذ دائمًا بايتًا واحدًا على الأقل، إلا إذا لم تتمكن العملية من قبول المزيد؛ إذا تم توفير أكثر من صفر بايت وتم استهلاك صفر بايت، يعتبر المتصلون هذا خطأ ويقومون بإحباط العملية.

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

معالجة الأخطاء

إذا قامت هذه الطريقة بإرجاع رمز خطأ آخر غير ErrorCode::OK ، فسيتم إحباط العملية وإبطال مقبض العملية. أي استخدام مستقبلي للمقبض، بهذه الطريقة، إنهاء أو إحباط ، يُرجع ErrorCode::INVALID_OPERATION_HANDLE .

إنفاذ الترخيص

يتم تنفيذ تفويض المفتاح بشكل أساسي في البداية . الاستثناء الوحيد هو الحالة التي يكون فيها المفتاح:

في هذه الحالة، يتطلب المفتاح ترخيصًا لكل عملية، ويتلقى أسلوب التحديث علامة::AUTH_TOKEN في وسيطة inParams . يتحقق HMAC من صلاحية الرمز المميز ويحتوي على معرف مستخدم آمن مطابق، ويطابق علامة المفتاح::USER_AUTH_TYPE ، ويحتوي على مقبض العملية للعملية الحالية في حقل الاختبار. إذا لم يتم استيفاء هذه الشروط، قم بإرجاع ErrorCode::KEY_USER_NOT_AUTHENTICATED .

يوفر المتصل رمز المصادقة لكل مكالمة للتحديث والإنهاء . يحتاج التنفيذ إلى التحقق من صحة الرمز مرة واحدة فقط إذا كان يفضل ذلك.

مفاتيح آر إس إيه

بالنسبة لعمليات التوقيع والتحقق باستخدام Digest::NONE ، تقبل هذه الطريقة توقيع الكتلة بأكملها أو التحقق منها في تحديث واحد. لا يجوز أن تستهلك سوى جزء من الكتلة. ومع ذلك، إذا اختار المتصل توفير البيانات في تحديثات متعددة، فإن هذه الطريقة تقبلها. إذا قدم المتصل بيانات للتوقيع أكثر مما يمكن استخدامه (طول البيانات يتجاوز حجم مفتاح RSA)، قم بإرجاع ErrorCode::INVALID_INPUT_LENGTH .

مفاتيح ECDSA

بالنسبة لعمليات التوقيع والتحقق باستخدام Digest::NONE ، تقبل هذه الطريقة توقيع الكتلة بأكملها أو التحقق منها في تحديث واحد. لا يجوز لهذه الطريقة أن تستهلك سوى جزء من الكتلة.

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

مفاتيح الخدمات المعمارية والهندسية

يدعم وضع AES GCM "بيانات المصادقة المرتبطة"، المقدمة عبر علامة Tag::ASSOCIATED_DATA في وسيطة inParams . قد يتم توفير البيانات المرتبطة في مكالمات متكررة (مهم إذا كانت البيانات كبيرة جدًا بحيث لا يمكن إرسالها في كتلة واحدة) ولكنها تسبق دائمًا البيانات المراد تشفيرها أو فك تشفيرها. قد تتلقى مكالمة التحديث كلاً من البيانات المرتبطة والبيانات للتشفير/فك التشفير، ولكن التحديثات اللاحقة قد لا تتضمن البيانات المرتبطة. إذا قدم المتصل بيانات مرتبطة بمكالمة تحديث بعد مكالمة تتضمن بيانات للتشفير/فك التشفير، فقم بإرجاع ErrorCode::INVALID_TAG .

بالنسبة لتشفير GCM، يتم إلحاق العلامة بالنص المشفر بواسطة Finish . أثناء فك التشفير، فإن آخر بايت Tag::MAC_LENGTH من البيانات المقدمة لاستدعاء التحديث الأخير هو العلامة. نظرًا لأن استدعاء معين للتحديث لا يمكنه معرفة ما إذا كان هذا هو الاستدعاء الأخير، فإنه يعالج كل شيء ما عدا طول العلامة ويخزن مؤقتًا بيانات العلامة المحتملة أثناء Finish .

ينهي

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

تنتهي عملية مستمرة بدأت بـ begin ، لمعالجة كافة البيانات التي لم تتم معالجتها بعد والتي يوفرها التحديث (التحديثات).

هذه الطريقة هي الأخيرة التي تسمى عملية ما ، لذلك يتم إرجاع جميع البيانات المعالجة.

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

عمليات التوقيع إرجاع التوقيع على أنه الإخراج. تقبل عمليات التحقق التوقيع في المعلمة signature ، وعدم إرجاع أي إخراج.

إنفاذ التفويض

يتم تنفيذ التفويض الرئيسي في المقام الأول في البداية . الاستثناء الوحيد هو الحالة التي يوجد فيها المفتاح:

في هذه الحالة ، يتطلب المفتاح ترخيصًا لكل عملية ، وتتلقى طريقة التحديث علامة :: auth_token في وسيطة inParams . يتحقق HMAC من أن الرمز المميز صالح ويحتوي على معرف مستخدم آمن مطابق ، ويطابق علامة المفتاح :: user_auth_type ، ويحتوي على مقبض التشغيل للعملية الحالية في حقل التحدي. إذا لم يتم استيفاء هذه الشروط ، فاحرص على إرجاع ErrorCode::KEY_USER_NOT_AUTHENTICATED .

يوفر المتصل رمز المصادقة لكل مكالمة للتحديث والانتهاء . يحتاج التنفيذ إلى التحقق من صحة الرمز المميز مرة واحدة فقط إذا كان يفضل.

مفاتيح RSA

بعض المتطلبات الإضافية ، اعتمادًا على وضع الحشو:

  • PaddingMode::NONE . بالنسبة لعمليات التوقيع والتشفير غير المدمجة ، إذا كانت البيانات المقدمة أقصر من المفتاح ، فستكون البيانات غير متقطعة على اليسار قبل التوقيع/التشفير. إذا كانت البيانات بنفس طول المفتاح ، ولكنها أكبر عدديًا ، فإن ErrorCode::INVALID_ARGUMENT . لعمليات التحقق وفك التشفير ، يجب أن تكون البيانات طالما أن المفتاح. خلاف ذلك ، return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . بالنسبة لعمليات توقيع PSS المغطاة ، فإن ملح PSS هو حجم رسالة الرسالة وتوليدها بشكل عشوائي. يتم استخدام Digest المحددة مع TAG :: Digest في inputParams على البداية كخوارزمية PSS Digest ، وكخوارزمية MGF1 Digest.
  • PaddingMode::RSA_OAEP . يتم استخدام Digest المحددة مع Tag :: Digest في inputParams على البداية كخوارزمية OAEP Digest ، ويستخدم SHA1 كخوارزمية MGF1 Digest.

مفاتيح ECDSA

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

مفاتيح AES

بعض الشروط الإضافية ، اعتمادًا على وضع الكتلة:

  • BlockMode::ECB أو BlockMode::CBC . إذا كانت الحشوة هي PaddingMode::NONE وطول البيانات ليس مضاعفًا لحجم كتلة AES ، Return ErrorCode::INVALID_INPUT_LENGTH . إذا كان الحشو هو PaddingMode::PKCS7 ، قم بتجميع البيانات لكل مواصفات PKCS#7. لاحظ أن PKCS#7 توصي بإضافة كتلة حشوة إضافية إذا كانت البيانات مضاعفة لطول الكتلة.
  • BlockMode::GCM . أثناء التشفير ، بعد معالجة جميع النص العادي ، قم بحساب العلامة ( العلامة :: mac_length bytes) وقم بإلحاقها إلى النص المشفر الذي تم إرجاعه. أثناء فك التشفير ، قم بمعالجة العلامة الأخيرة :: mac_length بايت كعلامة. في حالة فشل التحقق من العلامة ، return ErrorCode::VERIFICATION_FAILED .

إحباط

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

إحباط العملية الجارية. بعد مكالمة الإجهاض ، Return ErrorCode::INVALID_OPERATION_HANDLE للحصول على أي استخدام لاحق لمقبض التشغيل المقدم مع التحديث أو النهاية أو الإحباط .

get_supported_algorithms

النسخة 1

إرجاع قائمة الخوارزميات المدعومة من قبل تنفيذ أجهزة Keymaster. يقوم تطبيق البرامج بإرجاع قائمة فارغة ؛ يقوم التنفيذ المختلط بإرجاع قائمة تحتوي فقط على الخوارزميات التي تدعمها الأجهزة.

تدعم تطبيقات Keymaster 1 RSA و EC و AES و HMAC.

get_supported_block_modes

النسخة 1

إرجاع قائمة أوضاع كتلة AES المدعومة من قبل تطبيق أجهزة Keymaster لخوارزمية محددة والغرض.

بالنسبة إلى RSA و EC و HMAC ، والتي لا تمنع الأصفار ، فإن الطريقة تُرجع قائمة فارغة لجميع الأغراض الصالحة. يجب أن تتسبب أغراض غير صالحة في إرجاع طريقة ErrorCode::INVALID_PURPOSE .

تدعم تطبيقات Keymaster 1 ECB و CBC و CTR و GCM لتشفير AES وفك التشفير.

get_supported_padding_modes

النسخة 1

إرجاع قائمة أوضاع الحشو التي يدعمها تطبيق أجهزة Keymaster لخوارزمية محددة والغرض.

ليس لدى HMAC و EC فكرة الحشو ، لذا فإن الطريقة تُرجع قائمة فارغة لجميع الأغراض الصالحة. يجب أن تتسبب أغراض غير صالحة في إرجاع طريقة ErrorCode::INVALID_PURPOSE .

بالنسبة إلى RSA ، دعم تطبيقات Keymaster 1:

  • التشفير غير المتهور ، فك التشفير ، التوقيع والتحقق. بالنسبة للتشفير والتوقيع غير المتجانسة ، إذا كانت الرسالة أقصر من المعامل العام ، فيجب على التطبيقات أن تسير مع الأصفار. من أجل فك التشفير غير المتجول والتحقق ، يجب أن يتطابق طول الإدخال مع حجم المعامل العام.
  • PKCS#1 V1.5 تشفير وتوقيع أوضاع الحشو
  • PSS مع الحد الأدنى لطول الملح 20
  • OAEP

بالنسبة إلى AEs في أوضاع ECB و CBC ، تدعم تطبيقات Keymaster 1 أي حشوة و PKCS#7-padding. أوضاع CTR و GCM تدعم فقط حشوة.

get_supported_digests

النسخة 1

إرجاع قائمة أوضاع Digest التي يدعمها تطبيق Hameaster لأجهزة Keymaster لخوارزمية محددة والغرض.

لا تدعم أوضاع AES أو تتطلب الهضم ، وبالتالي فإن الطريقة تُرجع قائمة فارغة لأغراض صالحة.

يمكن للتطبيقات Keymaster 1 تنفيذ مجموعة فرعية من الهضم المحدد. توفر التطبيقات SHA-256 ويمكن أن توفر MD5 و SHA1 و SHA-224 و SHA-256 و SHA384 و SHA512 (المجموعة الكاملة من الهضم المحدد).

get_supported_import_formats

النسخة 1

إرجاع قائمة تنسيقات الاستيراد التي يدعمها تطبيق أجهزة Keymaster لخوارزمية محددة.

تدعم تطبيقات Keymaster 1 تنسيق PKCS#8 (بدون حماية كلمة المرور) لاستيراد أزواج RSA و EC الرئيسية ، ودعم الاستيراد الخام للمواد الرئيسية AES و HMAC.

get_supported_export_formats

النسخة 1

إرجاع قائمة تنسيقات التصدير التي يدعمها تنفيذ أجهزة Keymaster لخوارزمية محددة.

تدعم تطبيقات Keymaster1 تنسيق X.509 لتصدير مفاتيح RSA و EC العامة. لا يتم دعم تصدير المفاتيح الخاصة أو المفاتيح غير المتماثلة.

الوظائف التاريخية

Keymaster 0

الوظائف التالية تنتمي إلى تعريف Keymaster الأصلي 0. كانت موجودة في keymaster 1 struct keymaster1_device_t. ومع ذلك ، في Keymaster 1.0 لم يتم تنفيذها ، وتم تعيين مؤشرات وظائفها على Null.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

تنتمي الوظائف التالية إلى تعريف Keymaster 1 ، ولكن تمت إزالتها في Keymaster 2 ، إلى جانب وظائف Keymaster 0 المذكورة أعلاه.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

تنتمي الوظائف التالية إلى تعريف Keymaster 2 ، ولكن تمت إزالتها في Keymaster 3 ، إلى جانب وظائف Keymaster 1 المذكورة أعلاه.

  • configure