توفّر هذه الصفحة تفاصيل لمساعدة المستخدمين في تنفيذ 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
،
وإذا كان المفتاح مقاومًا للعودة،
الحماية من العودة إلى الحالة السابقة
تعني مقاومة التراجع أنه بمجرد حذف مفتاح باستخدام 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
.
فرض الحصول على الأذونات
يتم تنفيذ تفويض المفتاح بشكل أساسي في البداية. الاستثناء الوحيد هو الحالة التي يكون فيها المفتاح:
- واحدة أو أكثر من العلامة::USER_SECURE_IDs، و
- لا تحتوي على علامة::AUTH_ربح
في هذه الحالة، يتطلب المفتاح تفويضًا لكل عملية، ويتم تحديث
تتلقى علامة::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
، ولا يتم عرض أي نتائج.
فرض الحصول على الأذونات
يتم تنفيذ تفويض المفتاح بشكل أساسي في البدء. الاستثناء الوحيد هو الحالة التي يكون فيها المفتاح:
- واحد أو أكثر Tag::USER_SECURE_IDs، و
- لا تحتوي على العلامة::AUTH_shortcut
في هذه الحالة، يتطلب المفتاح تفويضًا لكل عملية، ويتم تحديث
تتلقى علامة::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