وظائف Keymaster

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

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

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

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

الإصدار: 1، 2

قد تكون معلمات مؤشر الإدخال غير المستخدمة لاستدعاء معين NULL وليس مطلوبًا من المتصل تقديم عناصر نائبة. على سبيل المثال، لا يجوز أن تستخدم بعض أنواع المفاتيح والأوضاع أي قيم من inParams إلى البدء، لذلك قد يسمح المتصل ضبط 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 لازمة للإخفاق في مثل هذه الحالات أو إجراء تشخيص. أو استخدام مفاتيح صغيرة جدًا تحديد معلَمات الإدخال غير ذات الصلة، أو إعادة استخدام وحدات IV أو nonces، إنشاء مفاتيح بدون أغراض (وبالتالي عديمة الفائدة) وما شابه ذلك ينبغي عدم تشخيصه بواسطة عمليات التنفيذ. حذف المعلَمات المطلوبة ومواصفات معلمات مطلوبة غير صالحة، ويجب تشخيص أخطاء مماثلة.

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

الدوال

الحصول على ميزات الجهاز

الإصدار: 3

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

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

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

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

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

إضافة إنتروبيا

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

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

إضافة القصور المقدَّم من المتّصل إلى المجموعة التي يستخدمها تنفيذ Keymaster 1 لتوليد أرقام عشوائية، للمفاتيح، والرموز IV، وما إلى ذلك.

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

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

إنشاء مفتاح

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

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

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

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

مفاتيح RSA

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

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

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

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

مفاتيح ECDSA

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

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

مفاتيح AES

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

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

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

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

مفاتيح HMAC

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

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

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

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

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

العلامة::ROLLBACK_RESISTANT.

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

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

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

الحصول على الخصائص الرئيسية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

حذف مفتاح

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

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

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

حذف جميع المفاتيح

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

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

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

أرقام تعريف الإبطالAttestationId

الإصدار: 3

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

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

بداية

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

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

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

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

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

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

  • العلامة::الغرض: الغرض المحدد في مكالمة begin() يجب أن يتطابق مع أحد الأغراض في التفويضات الرئيسية، ما لم تكن العملية المطلوبة مفتاحًا عامًا العملية. إذا كان الغرض المحدد غير مطابق ولم تكن العملية عملية مفتاح عام، سيرجع begin ErrorCode::UNSUPPORTED_PURPOSE عمليات المفتاح العام هي عمليات التشفير أو التحقق غير المتماثل.
  • العلامة::ACTIVE_DATETIME يمكن فرضها فقط في حال توفُّر مصدر موثوق به للوقت بالتوقيت العالمي المتفق عليه. إذا كانت التاريخ والوقت الحاليين قبل قيمة العلامة، فإن الطريقة تُرجع ErrorCode::KEY_NOT_YET_VALID
  • العلامة::ENTITYATION_EXPIRE_DATETIME يمكن فرضها فقط في حال توفُّر مصدر موثوق به للوقت بالتوقيت العالمي المتفق عليه. إذا كانت التاريخ والوقت الحاليان بعد قيمة العلامة والغرض هو KeyPurpose::ENCRYPT أو KeyPurpose::SIGN، الطريقة وإرجاع ErrorCode::KEY_EXPIRED.
  • العلامة::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.
  • العلامة::USER_SECURE_ID بهذه الطريقة فقط إذا كان المفتاح يحتوي أيضًا على العلامة::AUTH_تذكير. إذا كان المفتاح يحتوي على كليهما، يجب أن تحصل هذه الطريقة على عنوان URL صالح العلامة::AUTH_TOKEN في inParams لكي يكون رمز المصادقة صالحًا، يجب تنفيذ ما يلي: صحيح:
    • يتم التحقق من حقل HMAC بشكل صحيح.
    • يجب أن يكون واحد على الأقل من العلامة::USER_SECURE_ID من المفتاح تطابق قيمة واحدة على الأقل من قيم المعرف الآمن في ملف الرمز المميز.
    • يحتوي المفتاح على العلامة::USER_AUTH_TYPE تطابق نوع المصادقة في الرمز المميّز

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

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

مفاتيح 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، تتم إضافة جميع أوضاع المساحة المتروكة للإعلانات المتجاوبة على شبكة البحث. قابلة للتطبيق فقط على أغراض معينة. على وجه التحديد، PaddingMode::RSA_PKCS1_1_5_SIGN وPaddingMode::RSA_PSS تتيح عملية التوقيع وإثبات الملكية فقط، في حين أنّ ميزة PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT لا يتيح تطبيق PaddingMode::RSA_OAEP سوى التشفير وفك التشفير. تُرجع الطريقة ErrorCode::UNSUPPORTED_PADDING_MODE إذا كانت لا يدعم الوضع المحدد الغرض المحدد.

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

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

مفاتيح EC

تحدّد العمليات الرئيسية لـ 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، يلزم وجود متجه إعداد أو nonce. في معظم الحالات، يجب على المتصلين عدم تقديم رقم IV أو رقم non. في هذه الحالة، يؤدي تنفيذ Keymaster إلى إنشاء IV عشوائيًا أو nonce وإرجاعه عبر العلامة::NONCE في outParams. حجم CBC ونسبة النقر إلى الظهور IV هي 16 بايت. يبلغ حجم أرقام إرسال رسائل GCM 12 بايت. إذا لم يكن المفتاح تحتوي التفويضات على العلامة::CALLER_NONCE, يمكن للمتصل تقديم رقم IV/رقم هاتف غير شخصي العلامة::NONCE في inParams. في حال تقديم رقم غير خاص عندما العلامة::CALLER_NONCE غير مسموح به، يُرجى إرجاع ErrorCode::CALLER_NONCE_PROHIBITED. في حال عدم تقديم رقم غير خاص عند العلامة::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

توفّر هذه السمة البيانات المطلوب معالجتها في عملية جارية بدأت بالبدء. يتم تحديد العملية من خلال المعلمة operationHandle.

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

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

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

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

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

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

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

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

مفاتيح RSA

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

مفاتيح ECDSA

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

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

مفاتيح AES

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

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

إنهاء

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

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

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

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

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

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

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

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

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

مفاتيح RSA

في ما يلي بعض المتطلبات الإضافية التي تستند إلى وضع المساحة المتروكة:

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

مفاتيح ECDSA

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

مفاتيح AES

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

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

مسح

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

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

الحصول على خوارزميات_مدعومة

الإصدار: 1

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

تتوافق عمليات تنفيذ Keymaster 1 مع RSA وEC وAES وHMAC.

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

الإصدار: 1

عرض قائمة أوضاع حظر AES التي يوفّرها جهاز Keymaster لخوارزمية محددة والغرض المحدد.

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

عمليات تنفيذ Keymaster 1 تدعم ECB، وCBC، ونسبة النقر إلى الظهور، وGCM لمعيار AES التشفير وفك التشفير.

أوضاع_الحصول على_المساحة المتروكة

الإصدار: 1

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

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

بالنسبة إلى الإعلانات المتجاوبة على شبكة البحث، دعم عمليات تنفيذ Keymaster 1:

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

بالنسبة إلى بروتوكول التشفير المتقدّم (AES) في وضعَي ECB وCBC، لا تتيح عمليات تنفيذ Keymaster 1 استخدام المساحة المتروكة والمساحة المتروكة PKCS#7. في وضعَي نسبة النقر إلى الظهور وGCM، لا تتيحان مساحة متروكة فقط.

الحصول على ملخصات_supported

الإصدار: 1

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

لا تدعم أوضاع AES أو تتطلب استيعابًا، لذا تعرض الطريقة حقلاً فارغًا قائمة لأغراض صالحة.

يمكن لعمليات تنفيذ Keymaster 1 تنفيذ مجموعة فرعية من الملخصات. توفر عمليات التنفيذ خوارزمية SHA-256 ويمكن أن توفر خوارزمية MD5 وSHA1 وSHA-224 SHA-256 وSHA384 وSHA512 (المجموعة الكاملة من الملخصات المحددة).

الحصول على_تنسيقات_الاستيراد_المتوافقة

الإصدار: 1

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

تتوافق عمليات تنفيذ Keymaster 1 مع تنسيق PKCS#8 (بدون كلمة مرور لاستيراد مفاتيح التشفير RSA وEC، والسماح باستيراد ملفات RAW إلى المواد الأساسية لمفاتيح التشفير AES وHMAC

تنسيقات_تصدير_المحتوى_المدعوم

الإصدار: 1

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

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

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

Keymaster 0

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

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

Keymaster 1

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

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

Keymaster 2

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

  • configure