دوال Keymaster

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

ملاحظة: لتسهيل عملية نقل Keymaster 3 من واجهة برمجة التطبيقات القديمة لبنية برمجة التطبيقات بلغة C إلى واجهة برمجة التطبيقات لبنية برمجة التطبيقات بلغة C++ التي تم إنشاؤها من تعريف في لغة HIDL الجديدة لتعريف واجهة الأجهزة، تم تغيير أسماء الدوال في الإصدار Android 8.0. لإتاحة ذلك، أصبحت الدوالّ الآن مكتوبة بأسلوب "الكتابة بحرف كبير في كل كلمة". على سبيل المثال، get_key_characteristics أصبح الآن getKeyCharacteristics.

إرشادات عامة حول التنفيذ

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

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

الإصدار: 1 و2

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

إذا كانت مَعلمة الإدخال المطلوبة هي NULL، يجب أن تُعرِض طُرق Keymaster القيمة ErrorCode::UNEXPECTED_NULL_POINTER.

اعتبارًا من Keymaster 3، لم تعُد هناك مَعلمات مؤشر. يتم تمرير جميع المَعلمات بالقيمة أو الإحالات الثابتة.

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

الإصدار: 1 و2

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

اعتبارًا من Keymaster 3، لم تعُد هناك مَعلمات مؤشر. يتم تمرير جميع المَعلمات بالقيمة أو بالمراجع الثابتة.

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

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

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

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

تحذير: ينبغي أن تحاول عمليات تنفيذ Keymaster تشخيص الأخطاء العميقة، مثل حذف المَعلمات المطلوبة أو تحديد مَعلمات مطلوبة غير صالحة وغيرها من الأخطاء المشابهة التي تؤثر في سلامة تنفيذ Keymaster.

الدوال

getHardwareFeatures

الإصدار: 3

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

• يكون isSecure true إذا تم تخزين المفاتيح في جهاز آمن (مثل بيئة التنفيذ الموثوقة) ولم يتم نقلها مطلقًا.
• ‫supportsEllipticCurve هي true إذا كان الجهاز يتيح التشفير باستخدام منحنيات 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، لأنّ هذه المعلومات متوفّرة في ملفات خصائص النظام، وتقرأ عمليات تنفيذ المصنع هذه الملفات أثناء بدء التشغيل.

تُستخدَم لضبط Keymaster. يتمّ استدعاء هذه الطريقة مرّة واحدة بعد فتح الجهاز وقبل استخدامه. يتم استخدامه لتقديم KM_TAG_OS_VERSION و KM_TAG_OS_PATCHLEVEL إلى keymaster. إلى أن يتم استدعاء هذه الطريقة، تعرض جميع الطرق الأخرى 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 لإنشاء أرقام عشوائية ومفاتيح وملفات تشفير البدء وغيرها من العناصر.

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

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

generateKey

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

تم تقديم هذه الدالة في Keymaster 1 باسم generate_key وتم تغيير اسمها في Keymaster 3.

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

تعتمد المَعلمات المقدَّمة إلى generateKey على نوع المفتاح الذي يتم إنشاؤه. يلخِّص هذا القسم العلامات اللازمة والاختيارية لكل نوع من مفاتيح التشفير. يجب دائمًا استخدام السمة Tag::ALGORITHM لتحديد النوع.

مفاتيح RSA

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

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

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

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

مفاتيح ECDSA

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

يجب أيضًا استخدام Tag::DIGEST للحصول على مفتاح ECDSA مفيد، ولكنه ليس مطلوبًا لإنشاء المفتاح.

مفاتيح التشفير الموحّد للترميز (AES)

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

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

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

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

مفاتيح HMAC

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

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

السمات الرئيسية

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

بالإضافة إلى العلامات المقدَّمة، تُضيف القطعة الموثوق بها أيضًا Tag::ORIGIN، بالقيمة KeyOrigin::GENERATED، وإذا كان المفتاح مقاومًا للرجوع إلى إصدار سابق، Tag::ROLLBACK_RESISTANT.

الحماية من العودة إلى الحالة السابقة

تعني ميزة "منع التراجع" أنّه عند حذف مفتاح باستخدام deleteKey أو deleteAllKeys، يضمن لك الجهاز الآمن عدم إمكانية استخدامه مجددًا. في عمليات التنفيذ التي لا تتضمّن مقاومة التراجع، يتم عادةً إرجاع مادة المفتاح التي تم إنشاؤها أو استيرادها إلى المتصل ككتلة مفتاح، وهو نموذج مشفَّر ومصادق عليه. عندما يحذف ملف تخزين المفاتيح ملف تخزين المفتاح، يتم محو المفتاح، ولكن يمكن لمهاجم سبق له استرداد مادة المفتاح استعادته على الجهاز.

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

getKeyCharacteristics

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

تم تقديم هذه الدالة في Keymaster 1 باسم get_key_characteristics وتم تغيير اسمها في Keymaster 3.

تعرِض هذه الدالة المَعلمات والأذونات المرتبطة بالمفتاح المقدَّم، مقسّمة إلى مجموعتَين: مجموعة مفروضة من خلال الأجهزة ومجموعة مفروضة من خلال البرامج. ينطبق الوصف هنا بشكلٍ متساوٍ على قوائم السمات الرئيسية التي تعرضها generateKey وimportKey.

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

تصف السمات التي تُرجعها هذه الطريقة تمامًا نوع المفتاح المحدّد و استخدامه.

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

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

importKey

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

تم تقديم هذه الدالة في Keymaster 1 باسم import_key وتم تغيير اسمها في Keymaster 3.

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

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

exportKey

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

تم تقديم هذه الدالة في Keymaster 1 باسم export_key وتم تغيير اسمها في Keymaster 3.

تصدير مفتاح عام من مفتاحَي تشفير RSA أو EC من Keymaster

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

deleteKey

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

تم تقديم هذه الدالة في Keymaster 1 باسم delete_key وتم تغيير اسمها في Keymaster 3.

لحذف المفتاح المقدَّم. هذه الطريقة اختيارية، ولا يتم تنفيذها إلا من خلال وحدات Keymaster التي توفّر مقاومة للرجوع إلى إصدار سابق.

deleteAllKeys

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

تم تقديم هذه الدالة في Keymaster 1 باسم delete_all_keys وتم تغيير اسمها في Keymaster 3.

لحذف جميع المفاتيح هذه الطريقة اختيارية، ولا يتم تنفيذها إلا من خلال وحدات Keymaster التي توفّر مقاومة للرجوع إلى إصدار سابق.

destroyAttestationIds

الإصدار: 3

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

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

الإطلاق

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

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

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

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

فرض التفويض

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

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

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

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

مفاتيح RSA

تحدِّد جميع عمليات مفاتيح التشفير 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 حجم الخلاصة بالبايت. بخلاف ذلك، تعرض الطريقة القيمة ErrorCode::INCOMPATIBLE_DIGEST. حجم الملح هو D.
• تتطلّب إضافة PaddingMode::RSA_OAEP إلى المحتوى خلاصة لا يمكن Digest::NONE. إذا تم تحديد Digest::NONE، تعرض الطريقة القيمة ErrorCode::INCOMPATIBLE_DIGEST.

مفاتيح EC

تحدِّد عمليات مفاتيح التشفير العمومي وضعًا واحدًا بالضبط للترميز في inParams. إذا لم يتم تحديدها أو تم تحديدها أكثر من مرة، تعرِض الطريقةErrorCode::UNSUPPORTED_PADDING_MODE.

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

مفاتيح التشفير الموحّد للترميز (AES)

تحدِّد عمليات مفاتيح التشفير باستخدام مخطط 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، يجب استخدام مصفّف أو عدد عشوائي لبدء التشفير. في معظم الحالات، لا يحتاج المتصلون إلى تقديم مفتاح تشفير أو مفتاح عشوائي. في هذه الحالة، يُنشئ تنفيذ Keymaster مفتاح تشفير عشوائيًا أو عددًا عشوائيًا لمرّة واحدة ويعرضه مع Tag::NONCE في outParams. تبلغ قيمة مفتاح البدء في التشفير من جهة إلى جهة (CBC) وتشفير من جهة إلى أخرى (CTR) 16 بايت. تبلغ قيمة مفتاح GCM العشوائي 12 بايت. إذا كانت مفاتيح الإذن تحتوي على Tag::CALLER_NONCE، يمكن للمتصل تقديم مفتاح تشفير أو مفتاح عشوائي مع Tag::NONCE في inParams. إذا تم تقديم مفتاح عشوائي عندما يكون Tag::CALLER_NONCE غير مصرّح به، يجب عرض ErrorCode::CALLER_NONCE_PROHIBITED. إذا لم يتم تقديم مفتاح تشفير عشوائي عند تفويض Tag::CALLER_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. تستهلك عمليات التنفيذ دائمًا بايتًا واحدًا على الأقل، ما لم يكن بالإمكان تنفيذ عملية إضافية. وإذا تم تقديم أكثر من صفر بايت واستهلاك صفر بايت، يعتبر المُتصلون ذلك خطأً ويوقفون العملية.

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

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

إذا كانت هذه الطريقة تعرِض رمز خطأ غير ErrorCode::OK، يتم إلغاء العملية وإبطال معرّف العملية. أي استخدام مستقبلي للاسم المعرِّف باستخدام هذه الطريقة أو باستخدام finish أو abort يؤدي إلى عرض القيمة ErrorCode::INVALID_OPERATION_HANDLE.

فرض التفويض

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

• أن تتضمّن Tag::USER_SECURE_IDs واحدًا أو أكثر
• لا يتوفّر لديه Tag::AUTH_TIMEOUT

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

يقدّم المتصل الرمز المميّز للمصادقة في كل مكالمة إلى update و finish. ولا يحتاج التنفيذ إلى التحقّق من الرمز المميّز إلا مرّة واحدة.

مفاتيح RSA

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

مفاتيح ECDSA

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

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

مفاتيح التشفير الموحّد للترميز (AES)

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

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

إنهاء

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

إنهاء عملية جارية بدأت باستخدام begin، ومعالجة جميع البيانات التي لم تتم معالجتها بعد والتي تقدّمها موارد update

هذه الطريقة هي الطريقة الأخيرة التي يتمّ استدعاؤها في أيّ عملية، لذا يتمّ عرض كلّ البيانات التي تمت معالجتها.

سواء اكتملت العملية بنجاح أو ظهرت رسالة خطأ، تُنهي هذه الطريقة العملية وبالتالي تلغي معرّف العملية المقدَّم. يؤدي أي استخدام مستقبلي للاسم المعرِّف، باستخدام هذه الطريقة أو update أو abort، إلى عرض القيمة ErrorCode::INVALID_OPERATION_HANDLE.

تعرض عمليات التوقيع التوقيع كناتج. عمليات التحقّق تقبّل التوقيع في المَعلمة signature، ولا تعرِض أيّ مخرجات.

فرض التفويض

يتم تنفيذ فرض التفويض الرئيسي بشكل أساسي في begin. والاستثناء الوحيد هو الحالة التي يتضمّن فيها المفتاح كلاً من السمتَين التاليتَين:

• أن تتضمّن علامة واحدة أو أكثر Tag::USER_SECURE_IDs
• لا يتضمّن Tag::AUTH_TIMEOUT

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

يقدّم المُتصل الرمز المميّز للمصادقة في كلّ مكالمة إلى update وfinish. ولا يحتاج التنفيذ إلى التحقّق من الرمز المميّز إلا مرّة واحدة.

مفاتيح RSA

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

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

مفاتيح ECDSA

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

مفاتيح التشفير الموحّد للترميز (AES)

بعض الشروط الإضافية، استنادًا إلى وضع الحظر:

• BlockMode::ECB أو BlockMode::CBC. إذا كان التوسيع هو PaddingMode::NONE وطول data ليس مضاعِفًا لحجم كتلة AES، يجب عرض ErrorCode::INVALID_INPUT_LENGTH. إذا كان الإدراج هو PaddingMode::PKCS7، أضِف بيانات إضافية إلى البيانات وفقًا لمواصفات PKCS#7. يُرجى العِلم أنّ معيار PKCS#7 ينصح بإضافة كتلة تعبئة إضافية إذا كانت البيانات مضاعفة لطول الكتلة.
• BlockMode::GCM. أثناء التشفير، بعد معالجة كل النص العادي، احتسِب العلامة (Tag::MAC_LENGTH بايت) وأضِفها إلى النص المشفَّر الذي تم إرجاعه. أثناء فك التشفير، يجب معالجة Tag::MAC_LENGTH البايتات الأخيرة باعتبارها العلامة. إذا تعذّر إثبات ملكية العلامة، أعِد إرسال ErrorCode::VERIFICATION_FAILED.

مسح

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

تؤدي إلى إيقاف العملية الجارية. بعد طلب الإيقاف، يجب عرض القيمة ErrorCode::INVALID_OPERATION_HANDLE عند أي استخدام لاحق لاسم معرِّف العملية المقدَّم مع update أو finish أو abort.

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 الإصدار 1.5
• مفتاح تشفير متغير الطول (PSS) بحد أدنى لطول الملح يبلغ 20
• OAEP

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

get_supported_digests

الإصدار: 1

تُرجِع قائمة أوضاع الملخّص المتوافقة مع تنفيذ الأجهزة في 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، كما تتيح استيراد ملف RAW لمواد مفاتيح AES وHMAC.

get_supported_export_formats

الإصدار: 1

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

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

الوظائف السابقة

Keymaster 0

تنتمي الدوالّ التالية إلى تعريف Keymaster 0 الأصلي. كانت هذه العناصر متوفرة في بنية Keymaster 1‏ 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