دوال Keymaster

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

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

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

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

الإصدار: 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 منطقية ومفيدة.

الدوال

getHardwareFeatures

الإصدار: 3

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

• isSecure true إذا تم تخزين المفاتيح في جهاز آمن (وحدة معالجة مهام آمنة، وما إلى ذلك) وعدم نقلها مطلقًا.
• تكون قيمة supportsEllipticCurve هي true إذا كان الجهاز متوافقًا مع تشفير Eliptic 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 إلى Keymaster. وحتى يتم استدعاء هذه الطريقة، تعرض جميع الطرق الأخرى KM_ERROR_KEYMASTER_NOT_CONFIGURED. لا يقبل برنامج Keymaster القيم المقدَّمة من خلال هذه الطريقة إلا مرة واحدة لكل عملية تمهيد. تعرِض الطلبات التاليةKM_ERROR_OK، ولكنها لا تُجري أي إجراء.

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

تنشئ مفتاح تشفير جديدًا، تحدد التفويضات المرتبطة، والتي ترتبط دائمًا بالمفتاح. عمليات تنفيذ 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 خطأ في حال حذف هذه المَعلمات.

• تحدّد العلامة::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، على التوالي.

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

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

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

ترتبط المَعلمات التالية بمفاتيح 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 يحدِّد الحد الأدنى لطول حِزم التحكّم في الوصول (MAC) التي يمكن إنشاؤها أو التحقّق منها باستخدام هذا المفتاح. أن تكون القيمة مضاعفة من 8 و64 على الأقل
• Tag::DIGEST يحدِّد خوارزمية تجميع المفتاح. يتم تحديد خلاصة واحدة بالضبط، وإلا يتم عرض ErrorCode::UNSUPPORTED_DIGEST. إذا لم يكن الملخّص متوافقًا مع وحدة الثقة، يجب عرض ErrorCode::UNSUPPORTED_DIGEST.

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

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

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

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

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

يكون المفتاح مقاومًا للرجوع إلى الحالة السابقة إذا كان الجهاز الآمن يضمن عدم إمكانية استعادة مفاتيح الصعق العميق المحذوفة لاحقًا. ويتم ذلك بشكل عام من خلال تخزين مفاتيح إضافية للبيانات الوصفية في موقع موثوق لا يمكن للمهاجم التلاعب به. في الأجهزة الجوّالة، تكون الآلية المستخدَمة لهذا الغرض عادةً هي وحدات ذاكرة محمية من إعادة التشغيل (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 هي خصائص أساسية للمفتاح. بالنسبة إلى أي مفتاح يتم تأمينه باستخدام الأجهزة، تكون هذه العلامات مضمّنة في القائمة المفروضة على الأجهزة.
• يتم وضع قيم العلامة::DIGEST المتوافقة مع الأجهزة الآمنة في القائمة المتوافقة مع الأجهزة. يتم إدراج الملخّصات غير المتوافقة في قائمة البرامج المتوافقة.
• تظهر قيم العلامة::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::الكثير التي تم عرضها لها القيمة نفسها مثل KeyOrigin::IMPORTED.

مفتاح التصدير

الإصدار: 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 عملية متزامنة على الأقل. يستخدم ملف تخزين المفاتيح 15 أداة، ويمكن استخدام ملف تخزين آخر لتشفير كلمات المرور. عندما يكون لدى 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.
• لا يمكن فرض العلامة::المراجعة_السابقة_EXPIRE_DATETIME إلا في حال توفّر مصدر موثوق به للوقت بالتوقيت العالمي المتفق عليه. إذا كان التاريخ والوقت الحاليان لاحقَين لقيمة العلامة وكان الغرض هو KeyPurpose::ENCRYPT أو KeyPurpose::SIGN، تعرض الطريقة القيمة ErrorCode::KEY_EXPIRED.
• لا يمكن فرض Tag::USAGE_EXPIRE_DATETIME إلا إذا كان هناك مصدر وقت موثوق به بالتوقيت العالمي المتفق عليه. إذا كان التاريخ والوقت الحاليان لاحقَين لقيمة العلامة وكان الغرض هو 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. إذا كان المفتاح يحتوي على كليهما، يجب أن تتلقّى هذه الطريقة قيمة 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

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

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

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

مفاتيح RSA

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

مفاتيح ECDSA

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

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

مفاتيح AES

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

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

إنهاء

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

تُنهي عملية جارية بدأت باستخدام begin، وتعالج جميع البيانات التي لم تتم معالجتها بعد والتي تقدّمها عمليات التحديث.

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

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

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

فرض الحصول على الأذونات

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

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

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

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

مفاتيح 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 في البداية كخوارزمية تجزئة 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.

أوضاع_الحصول على_الحظر_المدعوم

الإصدار: 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. لا يتيح وضعا 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