دوال Keymaster

تقدّم هذه الصفحة تفاصيل لمساعدة مطوّري Keymaster طبقات HAL (Hardware Abstraction Layers). ويتناول كل وظيفة في واجهة برمجة التطبيقات وإصدار 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 بشكل آمن ناتج chaotizm المقدَّم في مجموعة مفتاح التشفير، والتي يجب أن تحتوي أيضًا علىchaotizm من إنشاء الأجهزة من خلال أداة إنشاء أرقام عشوائية. يجب التعامل مع عملية المزج بحيث لا يحصل المهاجم الذي يتحكّم بشكل كامل في أيّ من الوحدات التي يوفّرها 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 يحدِّد الحد الأدنى لطول حِزم التحكّم في الوصول (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، وإذا كان المفتاح مقاومًا للرجوع إلى الحالة السابقة، 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 مفتاحًا، ويترك مفتاحًا واحدًا لاستخدامه في ميزة "التشفير باستخدام كلمة المرور". عندما يكون لدى 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 إلى خلاصة، كما هو الحال مع عمليات التشفير وفك التشفير باستخدام وضع الحشو 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 إلى أنّه تم تنفيذ عملية إعلان متجاوب على شبكة البحث "خامة". في حال التوقيع أو التحقّق، يتم تحديد Digest::NONE للملخّص. لا يلزم توفُّر ملخّص لعملية التشفير أو فك التشفير بدون حشو.
• تتطلّب المساحة المتروكة في PaddingMode::RSA_PKCS1_1_5_SIGN خلاصة. يمكن أن يكون ملف هضم diges 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، يمكن للمتصل تقديم مفتاح تشفير أو مفتاح 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. تستهلك عمليات التنفيذ دائمًا بايتة واحدة على الأقل، ما لم يكن بالإمكان أن تقبل العملية المزيد من البايتات. وإذا تم تقديم أكثر من صفر بايتات ولم يتم استهلاك صفر بايتات، يعتبر المُتصلون ذلك خطأً ويوقفون العملية.

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

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

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

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

مفاتيح التشفير بتنسيق AES

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

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

إنهاء

الإصدار: 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.

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

مفاتيح التشفير RSA

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

• PaddingMode::NONE. بالنسبة إلى عمليات التوقيع والتشفير غير المزوّدة بحشو، إذا كانت البيانات المقدَّمة أقصر من المفتاح، تتم إضافة أصفار إلى يمين البيانات قبل التوقيع/التشفير. إذا كانت البيانات بطول المفتاح نفسه، ولكن أكبر رقميًا، أعِد القيمة ErrorCode::INVALID_ARGUMENT. بالنسبة إلى عمليات التحقّق وفك التشفير، يجب أن تكون البيانات بطول المفتاح بالضبط. بخلاف ذلك، عرض القيمة ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. بالنسبة إلى عمليات التوقيع المُكمّلة بتقنية PSS، يكون ملح PSS هو حجم خلاصة الرسالة ويتم إنشاؤه عشوائيًا. يتم استخدام الملخّص المحدّد باستخدام Tag::DIGEST في inputParams عند البدء كخوارزمية ملخّص 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.

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 ما يلي:

• التشفير وفك التشفير والتوقيع والتحقّق من الصحة بدون إضافة حشو بالنسبة إلى التشفير والتوقيع بدون إضافة بادئة، إذا كانت الرسالة أقصر من الوحدة العامة، يجب أن تتم إضافة بادئة من اليمين إلى الرسالة باستخدام الأصفار. لفك التشفير بدون إضافة حشو و التحقّق، يجب أن يتطابق طول الإدخال مع حجم المُعلّمة العامة.
• أوضاع تعبئة التشفير والتوقيع في الإصدار 1.5 من معيار PKCS#1
• دالة 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