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

توفر هذه الصفحة تفاصيل لمساعدة منفذي طبقات تجريد أجهزة Keymaster (HALs). يغطي كل وظيفة في API وأي إصدار 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 ، لا توجد معلمات للمؤشر. يتم تمرير جميع المعلمات بالقيمة أو المراجع الثابتة.

إساءة استخدام API

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

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

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

المهام

ميزات getHardware

الإصدار : 3

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

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

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

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

addRngEntropy

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

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

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

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

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

توليد مفتاح

الإصدار : 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 خطأ إذا تم حذف هذه المعلمات.

• العلامة :: الغرض تحدد الأغراض المسموح بها. يجب دعم جميع الأغراض لمفاتيح RSA ، في أي مجموعة.
• تحدد العلامة :: DIGEST خوارزميات الملخص التي يمكن استخدامها مع المفتاح الجديد. تحتاج التطبيقات التي لا تدعم جميع خوارزميات الملخص إلى قبول طلبات إنشاء المفاتيح التي تتضمن ملخصات غير مدعومة. يجب وضع الملخصات غير المدعومة في قائمة "فرض البرامج" في خصائص المفتاح المرتجع. هذا لأن المفتاح قابل للاستخدام مع تلك الملخصات الأخرى ، ولكن يتم إجراء عملية الهضم في البرنامج. ثم يتم استدعاء الأجهزة لإجراء العملية باستخدام Digest::NONE .
• تحدد العلامة :: 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 ، فقم بتوفير العلامة :: 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 . إذا لم يكن الملخص مدعومًا بواسطة Trustlet ، فقم بإرجاع ErrorCode::UNSUPPORTED_DIGEST .

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

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

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

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

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

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

getKeyCharacteristics

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

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

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

إذا تم توفير 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 مع خوارزميات ملخصة غير مدعومة من قبل الأجهزة الآمنة.
• يتم فرض علامة :: USER_SECURE_ID و Tag :: USER_AUTH_TYPE عن طريق الأجهزة فقط إذا تم فرض مصادقة المستخدم على الأجهزة. لإنجاز ذلك ، يجب أن يكون كل من Keymaster Trustlet و Trustlet المصادقة ذات الصلة آمنًا وأن يتشاركا مفتاح HMAC السري المستخدم لتوقيع رموز المصادقة والتحقق منها. راجع صفحة المصادقة للحصول على التفاصيل.
• تتطلب العلامات :: ACTIVE_DATETIME و Tag :: ORIGINATION_EXPIRE_DATETIME و Tag :: USAGE_EXPIRE_DATETIME الوصول إلى ساعة حائط صحيحة يمكن التحقق منها. تتمتع معظم الأجهزة الآمنة بإمكانية الوصول فقط إلى معلومات الوقت التي يوفرها نظام التشغيل غير الآمن ، مما يعني أن العلامات يتم فرضها بواسطة البرامج.
• تكون العلامة :: ORIGIN دائمًا في قائمة الأجهزة للمفاتيح المرتبطة بالأجهزة. وجوده في تلك القائمة هو الطريقة التي تحدد بها الطبقات العليا أن المفتاح مدعوم من الأجهزة.

importKey

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

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

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

• علامة :: KEY_SIZE و Tag :: RSA_PUBLIC_EXPONENT (لمفاتيح RSA فقط) ليست ضرورية في معلمات الإدخال. إذا لم يتم توفيرها ، فإن Trustlet تستنتج القيم من المادة الرئيسية المقدمة وتضيف العلامات والقيم المناسبة إلى الخصائص الرئيسية. إذا تم توفير المعلمات ، يقوم Trustlet بالتحقق من صحتها مقابل المادة الأساسية. في حالة عدم التطابق ، تقوم الطريقة بإرجاع ErrorCode::IMPORT_PARAMETER_MISMATCH .
• العلامة التي تم إرجاعها :: ORIGIN لها نفس قيمة 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 .

deleteKey

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

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

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

deleteAllKeys

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

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

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

تدمير التصديق

الإصدار : 3

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

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

يبدأ

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

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

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

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

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

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

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

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

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

مفاتيح RSA

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

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

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

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

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

• PaddingMode::NONE إلى إجراء عملية RSA "خام". في حالة التوقيع أو التحقق ، يتم تحديد Digest::NONE للملخص. لا يوجد ملخص ضروري للتشفير أو فك التشفير غير المبطن.
• PaddingMode::RSA_PKCS1_1_5_SIGN المساحة المتروكة ملخصًا. قد يكون الملخص هو Digest::NONE ، وفي هذه الحالة لا يمكن لتطبيق Keymaster إنشاء بنية توقيع PKCS # 1 v1.5 مناسبة ، لأنه لا يمكنه إضافة بنية DigestInfo. بدلاً من ذلك ، ينشئ التطبيق 0x00 || 0x01 || PS || 0x00 || M ، حيث M هي الرسالة المقدمة و PS هي سلسلة الحشو. يجب أن يكون حجم مفتاح RSA أكبر من الرسالة بـ 11 بايت على الأقل ، وإلا فإن الطريقة تُرجع ErrorCode::INVALID_INPUT_LENGTH .
• PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT لا تتطلب المساحة المتروكة ملخصًا.
• PaddingMode::RSA_PSS تتطلب حشوة الملخص ، والتي قد لا تكون Digest::NONE . إذا تم تحديد Digest::NONE ، تقوم الطريقة بإرجاع ErrorCode::INCOMPATIBLE_DIGEST . بالإضافة إلى ذلك ، يجب أن يكون حجم مفتاح RSA على الأقل 2 + D بايت أكبر من حجم إخراج الملخص ، حيث D هو حجم الملخص ، بالبايت. وإلا فإن الطريقة ترجع ErrorCode::INCOMPATIBLE_DIGEST . حجم الملح هو D.
• 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 أو nonce. في هذه الحالة ، يولد تنفيذ Keymaster عشوائيًا IV أو nonce ويعيده عبر Tag :: NONCE في outParams . CBC و CTR IVs هي 16 بايت. حجم GCM nonces هو 12 بايت. إذا كانت تصاريح المفاتيح تحتوي على Tag :: CALLER_NONCE ، فقد يوفر المتصل IV / nonce مع Tag :: NONCE في inParams . إذا تم توفير nonce عندما لا يتم ترخيص Tag :: CALLER_NONCE ، فقم بإرجاع ErrorCode::CALLER_NONCE_PROHIBITED . إذا لم يتم توفير رقم nonce عند ترخيص Tag :: CALLER_NONCE ، فقم بإنشاء IV / nonce عشوائي.

مفاتيح HMAC

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

تحديث

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

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

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

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

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

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

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

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

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

في هذه الحالة ، يتطلب المفتاح ترخيصًا لكل عملية ، ويتلقى أسلوب التحديث الوسيطة Tag :: 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 "بيانات المصادقة المرتبطة" المتوفرة عبر علامة Tag :: ASSOCIATED_DATA في وسيطة inParams . قد يتم توفير البيانات المرتبطة في مكالمات متكررة (مهمة إذا كانت البيانات كبيرة جدًا بحيث لا يمكن إرسالها في كتلة واحدة) ولكنها تسبق البيانات دائمًا ليتم تشفيرها أو فك تشفيرها. قد تتلقى مكالمة التحديث كلاً من البيانات والبيانات المرتبطة لتشفير / فك تشفير ، لكن التحديثات اللاحقة قد لا تتضمن البيانات المرتبطة. إذا قدم المتصل بيانات مرتبطة بمكالمة تحديث بعد مكالمة تتضمن بيانات لتشفير / فك تشفير ، فقم بإرجاع ErrorCode::INVALID_TAG .

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

إنهاء

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

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

• One or more Tag::USER_SECURE_IDs , and
• Does not have a Tag::AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

• PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
• PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

• BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
• BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

• Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
• PKCS#1 v1.5 encryption and signing padding modes
• PSS with a minimum salt length of 20
• OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

• configure