توابع Keymaster

این صفحه جزئیاتی را برای کمک به پیاده‌کنندگان لایه‌های انتزاعی سخت‌افزار Keymaster (HAL) ارائه می‌کند. هر تابع در API و نسخه Keymaster که آن تابع در آن موجود است را پوشش می دهد و پیاده سازی پیش فرض را توصیف می کند. برای برچسب‌ها، صفحه Keymaster Tags را ببینید.

توجه: برای پشتیبانی از انتقال Keymaster 3 از ساختار قدیمی HAL به رابط C++ HAL که از تعریفی در زبان تعریف رابط سخت افزاری جدید (HIDL) ایجاد شده است، نام توابع در Android 8.0 تغییر کرده است. برای پشتیبانی از این، توابع در حال حاضر در مورد شتر است. برای مثال، get_key_characteristics اکنون getKeyCharacteristics است.

دستورالعمل اجرای عمومی

دستورالعمل های زیر برای همه توابع موجود در API اعمال می شود.

پارامترهای اشاره گر ورودی

نسخه : 1، 2

پارامترهای اشاره گر ورودی که برای یک تماس مشخص استفاده نمی شوند ممکن است NULL باشند. تماس‌گیرنده نیازی به ارائه متغیرهایی ندارد. برای مثال، برخی از انواع و حالت‌های کلید ممکن است از هیچ مقداری از آرگومان inParams برای شروع استفاده نکنند، بنابراین تماس‌گیرنده ممکن است inParams روی NULL تنظیم کند یا یک مجموعه پارامتر خالی ارائه دهد. تماس گیرندگان همچنین می توانند پارامترهای استفاده نشده را ارائه دهند و روش های Keymaster نباید خطا صادر کنند.

اگر یک پارامتر ورودی مورد نیاز NULL باشد، متدهای Keymaster باید ErrorCode::UNEXPECTED_NULL_POINTER برگردانند.

با شروع در Keymaster 3، هیچ پارامتر نشانگر وجود ندارد. همه پارامترها توسط ارجاعات مقدار یا const ارسال می شوند.

پارامترهای اشاره گر خروجی

نسخه : 1، 2

مشابه پارامترهای اشاره گر ورودی، پارامترهای اشاره گر خروجی استفاده نشده ممکن است NULL باشند. اگر روشی باید داده‌ها را در پارامتر خروجی NULL برگرداند، باید ErrorCode::OUTPUT_PARAMETER_NULL برگرداند.

با شروع در Keymaster 3، هیچ پارامتر نشانگر وجود ندارد. همه پارامترها توسط ارجاعات مقدار یا const ارسال می شوند.

سوء استفاده از API

نسخه : 1، 2، 3

راه‌های زیادی وجود دارد که تماس‌گیرندگان می‌توانند درخواست‌هایی را ارائه دهند که منطقی یا احمقانه هستند، اما از نظر فنی اشتباه نیستند. در چنین مواردی نیازی به اجرای Keymaster نیست که با شکست مواجه شوند یا عیب‌یابی صادر کنند. استفاده از کلیدهای خیلی کوچک، مشخص کردن پارامترهای ورودی نامربوط، استفاده مجدد از IV یا nonces، تولید کلیدهای بدون هدف (بنابراین بی فایده) و مواردی از این قبیل نباید توسط پیاده سازی تشخیص داده شوند. حذف پارامترهای مورد نیاز، مشخص کردن پارامترهای مورد نیاز نامعتبر و خطاهای مشابه باید تشخیص داده شود.

این مسئولیت برنامه‌ها، چارچوب و فروشگاه کلید اندروید است که اطمینان حاصل کنند که تماس‌ها با ماژول‌های Keymaster معقول و مفید هستند.

احتیاط: پیاده سازی های Keymaster باید برای تشخیص خطاهای جدی، مانند حذف پارامترهای مورد نیاز، مشخص کردن پارامترهای مورد نیاز نامعتبر، و خطاهای مشابهی که یکپارچگی اجرای Keymaster را به خطر می اندازند، تلاش کنند.

توابع

GetHardware Features

نسخه : 3

روش جدید getHardwareFeatures برخی از ویژگی های مهم سخت افزار ایمن زیربنایی را در معرض دید مشتریان قرار می دهد. این متد هیچ آرگومان نمی گیرد و چهار مقدار را برمی گرداند که همه آنها بولی هستند:

• اگر کلیدها در سخت افزار امن (TEE و غیره) ذخیره شده باشند و هرگز آن را ترک نکنید، isSecure true است.
• supportsEllipticCurve اگر سخت افزار از رمزنگاری منحنی بیضی با منحنی های NIST (P-224، P-256، P-384، و P-521) پشتیبانی کند، true است.
• supportsSymmetricCryptography در صورتی true است که سخت افزار از رمزنگاری متقارن، از جمله AES و HMAC پشتیبانی کند.
• supportsAttestation در صورتی true است که سخت‌افزار از تولید گواهی‌های تأیید کلید عمومی Keymaster، امضا شده با کلید تزریق شده در یک محیط امن پشتیبانی کند.

تنها کدهای خطایی که این روش می تواند برگرداند عبارتند از ErrorCode:OK ، ErrorCode::KEYMASTER_NOT_CONFIGURED یا یکی از کدهای خطایی که نشان دهنده نقص در برقراری ارتباط با سخت افزار ایمن است.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

پیکربندی کنید

نسخه : 2

این تابع در Keymaster 2 معرفی شد و در Keymaster 3 منسوخ شد، زیرا این اطلاعات در فایل‌های ویژگی‌های سیستم موجود است و پیاده‌سازی‌های سازنده آن فایل‌ها را در هنگام راه‌اندازی می‌خوانند.

کی مستر را پیکربندی می کند. این روش یک بار پس از باز شدن دستگاه و قبل از استفاده از آن فراخوانی می شود. برای ارائه KM_TAG_OS_VERSION و KM_TAG_OS_PATCHLEVEL به keymaster استفاده می‌شود. تا زمانی که این متد فراخوانی نشود، همه متدهای دیگر KM_ERROR_KEYMASTER_NOT_CONFIGURED را برمی‌گردانند. مقادیر ارائه شده توسط این روش تنها یک بار توسط keymaster در هر بوت پذیرفته می شود. تماس‌های بعدی KM_ERROR_OK را برمی‌گردانند، اما کاری انجام نمی‌دهند.

اگر اجرای Keymaster در سخت‌افزار امن باشد و نسخه سیستم‌عامل و مقادیر سطح وصله ارائه‌شده با مقادیر ارائه‌شده به سخت‌افزار امن توسط بوت‌لودر مطابقت نداشته باشد (یا اگر بوت‌لودر مقادیری را ارائه نکرده باشد)، این روش 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 برای تولید اعداد تصادفی، برای کلیدها، IV و غیره اضافه می کند.

پیاده سازی های Keymaster باید به طور ایمن آنتروپی ارائه شده را با مخزن خود مخلوط کنند، که همچنین باید حاوی آنتروپی تولید شده داخلی از یک مولد اعداد تصادفی سخت افزاری باشد. اختلاط باید به گونه‌ای انجام شود که مهاجمی که کنترل کامل بیت‌های ارائه‌شده با addRngEntropy یا بیت‌های تولید شده توسط سخت‌افزار را دارد، اما نه هر دو، هیچ مزیتی در پیش‌بینی بیت‌های تولید شده از استخر آنتروپی نداشته باشد.

پیاده سازی های Keymaster که سعی در تخمین آنتروپی در استخر داخلی خود دارند، فرض می کنند که داده های ارائه شده توسط addRngEntropy فاقد آنتروپی هستند. پیاده‌سازی‌های Keymaster می‌توانند ErrorCode::INVALID_INPUT_LENGTH برگردانند اگر بیش از 2 کیلوبایت داده در یک تماس به آنها داده شود.

generateKey

نسخه : 1، 2، 3

این تابع در Keymaster 1 با عنوان generate_key معرفی شد و در Keymaster 3 تغییر نام داد.

یک کلید رمزنگاری جدید ایجاد می کند و مجوزهای مرتبط را مشخص می کند که به طور دائم به کلید متصل هستند. پیاده سازی های Keymaster استفاده از کلید را به هر نحوی که با مجوزهای مشخص شده در زمان تولید ناسازگار باشد غیرممکن می کند. با توجه به مجوزهایی که سخت‌افزار ایمن نمی‌تواند اجرا کند، تعهد سخت‌افزار امن محدود به اطمینان از این است که مجوزهای غیرقابل اجرا مرتبط با کلید را نمی‌توان تغییر داد، به طوری که هر تماس با getKeyCharacteristics مقدار اصلی را برمی‌گرداند. علاوه بر این، ویژگی‌های بازگردانده‌شده توسط generateKey مجوزها را به درستی بین لیست‌های سخت‌افزاری و اعمال‌شده توسط نرم‌افزار تخصیص می‌دهد. برای جزئیات بیشتر به getKeyCharacteristics مراجعه کنید.

پارامترهای ارائه شده برای generateKey به نوع کلید تولید شده بستگی دارد. این بخش تگ های ضروری و اختیاری برای هر نوع کلید را خلاصه می کند. برچسب::الگوریتم همیشه برای تعیین نوع ضروری است.

کلیدهای 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، در هر ترکیبی، پشتیبانی شوند.
• Tag::DIGEST الگوریتم‌های digest را مشخص می‌کند که می‌توان با کلید جدید استفاده کرد. پیاده‌سازی‌هایی که از همه الگوریتم‌های خلاصه پشتیبانی نمی‌کنند، باید درخواست‌های تولید کلیدی را بپذیرند که شامل خلاصه‌های پشتیبانی‌نشده است. خلاصه‌های پشتیبانی‌نشده باید در لیست «نرم‌افزار اعمال‌شده» در ویژگی‌های کلیدی بازگشتی قرار بگیرند. این به این دلیل است که کلید با آن هضم های دیگر قابل استفاده است، اما هضم در نرم افزار انجام می شود. سپس سخت افزار فراخوانی می شود تا عملیات را با Digest::NONE انجام دهد.
• Tag::PADDING حالت های padding را مشخص می کند که می توان با کلید جدید استفاده کرد. پیاده‌سازی‌هایی که از همه الگوریتم‌های خلاصه پشتیبانی نمی‌کنند، باید PaddingMode::RSA_PSS و PaddingMode::RSA_OAEP در لیست ویژگی‌های کلیدی نرم‌افزاری قرار دهند، اگر الگوریتم‌های خلاصه پشتیبانی‌نشده مشخص شده باشند.

کلیدهای ECDSA

فقط Tag::KEY_SIZE برای ایجاد یک کلید ECDSA ضروری است. برای انتخاب گروه EC استفاده می شود. مقادیر پشتیبانی شده 224، 256، 384 و 521 هستند که به ترتیب منحنی های NIST p-224، p-256، p-384 و p521 را نشان می دهند.

برچسب::DIGEST همچنین برای یک کلید مفید ECDSA ضروری است، اما برای تولید لازم نیست.

کلیدهای AES

فقط Tag::KEY_SIZE برای تولید یک کلید AES ضروری است. اگر حذف شود، روش ErrorCode::UNSUPPORTED_KEY_SIZE را برمی گرداند. مقادیر پشتیبانی شده 128 و 256 با پشتیبانی اختیاری از کلیدهای 192 بیتی AES هستند.

پارامترهای زیر به ویژه برای کلیدهای AES مرتبط هستند، اما برای ایجاد یکی ضروری نیستند:

• Tag::BLOCK_MODE حالت های بلوکی را مشخص می کند که کلید جدید می تواند با آنها استفاده شود.
• Tag::PADDING حالت های padding قابل استفاده را مشخص می کند. این فقط برای حالت های ECB و CBC مرتبط است.

اگر حالت بلوک GCM مشخص شده است، Tag::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 است.
• Tag::DIGEST الگوریتم خلاصه را برای کلید مشخص می کند. دقیقاً یک خلاصه مشخص شده است، در غیر این صورت ErrorCode::UNSUPPORTED_DIGEST برگردانید. اگر خلاصه توسط Trustlet پشتیبانی نمی‌شود، ErrorCode::UNSUPPORTED_DIGEST برگردانید.

ویژگی های کلیدی

اگر آرگومان مشخصه غیر NULL باشد، generateKey مشخصه های کلید تازه تولید شده را برمی گرداند که به طور مناسب به لیست های سخت افزاری و اعمال شده توسط نرم افزار تقسیم شده اند. برای توضیح اینکه کدام ویژگی در کدام لیست قرار می گیرد به getKeyCharacteristics مراجعه کنید. مشخصه های برگشتی شامل تمام پارامترهای مشخص شده برای تولید کلید است، به جز Tag::APPLICATION_ID و Tag::APPLICATION_DATA . اگر این تگ ها در پارامترهای کلیدی گنجانده شده بودند، از ویژگی های برگشتی حذف می شوند تا با بررسی حباب کلید برگشتی، مقادیر آنها را پیدا نکنید. با این حال، آنها از نظر رمزنگاری به حباب کلید متصل می شوند، به طوری که اگر مقادیر صحیح در هنگام استفاده از کلید ارائه نشود، استفاده با شکست مواجه می شود. به طور مشابه، Tag::ROOT_OF_TRUST از نظر رمزنگاری به کلید متصل است، اما نمی توان آن را در هنگام ایجاد یا وارد کردن کلید مشخص کرد و هرگز بازگردانده نمی شود.

علاوه بر تگ های ارائه شده، Trustlet همچنین Tag::ORIGIN را با مقدار KeyOrigin::GENERATED اضافه می کند، و اگر کلید در برابر بازگشت مقاوم باشد،

برچسب::ROLLBACK_RESISTANT .

مقاومت عقبگرد

مقاومت برگشتی به این معنی است که هنگامی که یک کلید با deleteKey یا deleteAllKeys حذف می شود، توسط سخت افزار ایمن تضمین می شود که دیگر قابل استفاده نخواهد بود. پیاده سازی های بدون مقاومت برگشتی معمولاً مواد کلید تولید شده یا وارد شده را به عنوان یک حباب کلید، یک فرم رمزگذاری شده و تأیید شده به تماس گیرنده برمی گرداند. وقتی Keystore حباب کلید را حذف می‌کند، کلید از بین می‌رود، اما مهاجمی که قبلاً موفق به بازیابی مواد کلیدی شده است، می‌تواند به طور بالقوه آن را به دستگاه بازگرداند.

اگر سخت افزار ایمن تضمین کند که کلیدهای حذف شده نمی توانند بعداً بازیابی شوند، یک کلید مقاوم در برابر برگشت است. این معمولاً با ذخیره ابرداده های کلیدی اضافی در یک مکان قابل اعتماد انجام می شود که توسط مهاجم قابل دستکاری نیست. در دستگاه های تلفن همراه، مکانیسم مورد استفاده برای این کار معمولاً Replay Protected Memory Blocks (RPMB) است. از آنجایی که تعداد کلیدهایی که می توان ایجاد کرد اساساً نامحدود است و فضای ذخیره قابل اعتماد مورد استفاده برای مقاومت برگشتی ممکن است از نظر اندازه محدود باشد، این روش نیاز به موفقیت دارد حتی اگر مقاومت برگشتی برای کلید جدید ارائه نشود. در آن صورت، Tag::ROLLBACK_RESISTANT نباید به ویژگی های کلیدی اضافه شود.

getKeyCharacteristics

نسخه : 1، 2، 3

این تابع در Keymaster 1 با عنوان get_key_characteristics معرفی شد و در Keymaster 3 تغییر نام داد.

پارامترها و مجوزهای مرتبط با کلید ارائه شده را برمی‌گرداند که به دو مجموعه تقسیم می‌شود: سخت‌افزاری و نرم‌افزاری اعمال‌شده. توضیحات در اینجا به طور یکسان برای لیست های مشخصه های کلیدی که توسط geneKey و importKey برگردانده شده اند اعمال می شود.

اگر Tag::APPLICATION_ID در طول تولید یا وارد کردن کلید ارائه شده باشد، همان مقدار در آرگومان clientId به این روش ارائه می شود. در غیر این صورت، روش ErrorCode::INVALID_KEY_BLOB را برمی گرداند. به طور مشابه، اگر Tag::APPLICATION_DATA در حین تولید یا واردات ارائه شده باشد، همان مقدار در آرگومان appData به این روش ارائه می شود.

مشخصه های برگردانده شده توسط این روش به طور کامل نوع و استفاده از کلید مشخص شده را توصیف می کند.

قاعده کلی برای تصمیم گیری در مورد اینکه آیا یک برچسب معین به لیست اعمال شده توسط سخت افزار یا نرم افزار تعلق دارد این است که اگر معنای برچسب توسط سخت افزار ایمن کاملاً تضمین شود، سخت افزار اعمال می شود. در غیر این صورت، این نرم افزار اعمال می شود. در زیر لیستی از برچسب های خاص که تخصیص صحیح آنها ممکن است نامشخص باشد آمده است:

• Tag::ALGORITHM ، Tag::KEY_SIZE ، و Tag::RSA_PUBLIC_EXPONENT ویژگی‌های ذاتی کلید هستند. برای هر کلیدی که توسط سخت افزار ایمن شده است، این برچسب ها در لیست سخت افزاری قرار دارند.
• برچسب:: مقادیر DIGEST که توسط سخت افزار ایمن پشتیبانی می شوند در لیست پشتیبانی از سخت افزار قرار می گیرند. خلاصه های پشتیبانی نشده در لیست پشتیبانی شده توسط نرم افزار قرار می گیرند.
• برچسب::مقادیر PADDING عموماً در لیست پشتیبانی از سخت‌افزار قرار می‌گیرند، مگر اینکه این احتمال وجود داشته باشد که یک حالت padding خاص ممکن است توسط نرم‌افزار انجام شود. در این صورت، آنها وارد لیست نرم افزاری می شوند. چنین امکانی برای کلیدهای RSA به وجود می‌آید که به PSS یا OAEP اجازه می‌دهند با الگوریتم‌های خلاصه‌ای که توسط سخت‌افزار امن پشتیبانی نمی‌شوند، پد شوند.
• برچسب::USER_SECURE_ID و Tag::USER_AUTH_TYPE تنها در صورتی اعمال می‌شوند که احراز هویت کاربر سخت‌افزاری باشد. برای انجام این کار، Trustlet Keymaster و Trustlet احراز هویت مربوطه هر دو باید ایمن باشند و یک کلید HMAC مخفی را که برای امضا و تایید توکن‌های احراز هویت استفاده می‌شود، به اشتراک بگذارند. برای جزئیات بیشتر به صفحه احراز هویت مراجعه کنید.
• برچسب‌ها::ACTIVE_DATETIME ، برچسب::ORIGINATION_EXPIRE_DATETIME ، و برچسب::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 را برمی‌گرداند.
• Tag::ORIGIN بازگشتی همان مقدار KeyOrigin::IMPORTED را دارد.

exportKey

نسخه : 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 که مقاومت برگشتی را ارائه می‌کنند، اجرا می‌شود.

از بین بردنAttestationIds

نسخه : 3

از متد destroyAttestationIds() برای غیرفعال کردن دائمی ویژگی جدید (اختیاری، اما بسیار توصیه شده) شناسه استفاده می شود. اگر TEE پس از فراخوانی این روش راهی برای اطمینان از غیرفعال شدن دائمی گواهی ID نداشته باشد، گواهی ID به هیچ وجه نباید پیاده سازی شود، در این صورت این روش هیچ کاری انجام نمی دهد و ErrorCode::UNIMPLEMENTED برمی گرداند. اگر تأیید شناسه پشتیبانی می‌شود، این روش باید پیاده‌سازی شود و باید تمام تلاش‌های بعدی برای تأیید شناسه را برای همیشه غیرفعال کند. این روش را می توان هر تعداد بار فراخوانی کرد. اگر تأیید ID قبلاً برای همیشه غیرفعال شده باشد، این روش کاری انجام نمی دهد و ErrorCode::OK برمی گرداند.

تنها کدهای خطایی که این روش می تواند برگرداند عبارتند از ErrorCode::UNIMPLEMENTED (اگر تأیید شناسه پشتیبانی نمی شود)، ErrorCode:OK ، ErrorCode::KEYMASTER_NOT_CONFIGURED یا یکی از کدهای خطا که نشان دهنده عدم برقراری ارتباط با سخت افزار ایمن است.

آغاز شود

نسخه : 1، 2، 3

یک عملیات رمزنگاری را با استفاده از کلید مشخص شده برای هدف مشخص شده با پارامترهای مشخص شده (در صورت لزوم) آغاز می کند و یک دسته عملیات را برمی گرداند که با به روز رسانی و پایان برای تکمیل عملیات استفاده می شود. دسته عملیات همچنین به عنوان نشانه "چالش" در عملیات احراز هویت استفاده می شود و برای چنین عملیاتی در زمینه challenge نشانه احراز هویت گنجانده شده است.

پیاده سازی Keymaster حداقل از 16 عملیات همزمان پشتیبانی می کند. Keystore تا 15 مورد استفاده می کند، و یکی را برای ولد باقی می گذارد تا برای رمزگذاری رمز عبور استفاده شود. هنگامی که Keystore دارای 15 عملیات در حال انجام است ( begin فراخوانی شده است، اما finish یا abort فراخوانی نشده است) و درخواستی برای شروع یک 16 دریافت می کند، برای کاهش تعداد عملیات فعال، عملیاتی را که اخیراً کمتر استفاده شده است abort می کند. به 14 قبل از begin تماس برای شروع عملیات درخواستی جدید.

اگر Tag::APPLICATION_ID یا Tag::APPLICATION_DATA در طول تولید یا وارد کردن کلید مشخص شده باشد، فراخوانی‌های begin شامل آن برچسب‌هایی با مقادیر مشخص‌شده اولیه در آرگومان inParams در این روش می‌شود.

اجرای مجوز

در طول این روش، مجوزهای کلیدی زیر توسط Trustlet اعمال می‌شوند، اگر پیاده‌سازی آن‌ها را در ویژگی‌های «تحت اجرای سخت‌افزار» قرار دهد و اگر عملیات یک عملیات کلید عمومی نباشد. عملیات کلید عمومی، به معنی KeyPurpose::ENCRYPT و KeyPurpose::VERIFY ، با کلیدهای RSA یا EC، مجاز به موفقیت هستند حتی اگر الزامات مجوز برآورده نشده باشند.

• Tag::PURPOSE : هدف مشخص شده در فراخوانی begin() باید با یکی از اهداف در مجوزهای کلید مطابقت داشته باشد، مگر اینکه عملیات درخواستی یک عملیات کلید عمومی باشد. اگر هدف مشخص شده مطابقت ندارد و عملیات یک عملیات کلید عمومی نیست، بازگشت ErrorCode::UNSUPPORTED_PURPOSE begin . عملیات کلید عمومی، عملیات رمزگذاری یا تأیید نامتقارن است.
• برچسب::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 باشد. اگر کلید دارای هر دو باشد، این روش باید یک Tag::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 برگردانده می شود.
• Tag::BOOTLOADER_ONLY مشخص می کند که فقط بوت لودر می تواند از کلید استفاده کند. اگر این متد با یک کلید فقط بوت لودر پس از اتمام اجرای بوت لودر فراخوانی شود، ErrorCode::INVALID_KEY_BLOB برمی گرداند.

کلیدهای RSA

همه عملیات کلید RSA دقیقاً یک حالت padding را در inParams مشخص می‌کنند. اگر بیش از یک بار مشخص نشده باشد یا مشخص شود، روش ErrorCode::UNSUPPORTED_PADDING_MODE را برمی گرداند.

عملیات امضا و تأیید RSA، همانطور که عملیات رمزگذاری و رمزگشایی RSA با حالت padding OAEP نیاز به خلاصه دارد. برای این موارد، تماس‌گیرنده دقیقاً یک خلاصه در inParams را مشخص می‌کند. اگر بیش از یک بار مشخص نشده باشد یا مشخص شود، روش ErrorCode::UNSUPPORTED_DIGEST را برمی گرداند.

عملیات کلید خصوصی ( KeyPurpose::DECYPT و KeyPurpose::SIGN ) به مجوز خلاصه و padding نیاز دارد، به این معنی که مجوزهای کلید باید حاوی مقادیر مشخص شده باشند. در غیر این صورت، روش ErrorCode::INCOMPATIBLE_DIGEST یا ErrorCode::INCOMPATIBLE_PADDING را بر می‌گرداند. عملیات کلید عمومی ( KeyPurpose::ENCRYPT و KeyPurpose::VERIFY ) با خلاصه یا padding غیرمجاز مجاز است.

به استثنای PaddingMode::NONE ، همه حالت‌های padding RSA فقط برای اهداف خاصی قابل اجرا هستند. به طور خاص، PaddingMode::RSA_PKCS1_1_5_SIGN و PaddingMode::RSA_PSS فقط از امضا و تأیید پشتیبانی می‌کنند، در حالی که PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT و PaddingMode::RSA_OAEP فقط از رمزگذاری و رمزگشایی پشتیبانی می‌کنند. اگر حالت مشخص شده از هدف مشخص شده پشتیبانی نمی کند، روش ErrorCode::UNSUPPORTED_PADDING_MODE را برمی گرداند.

برخی از تعاملات مهم بین حالت‌های padding و digest وجود دارد:

• PaddingMode::NONE نشان می دهد که یک عملیات RSA "خام" انجام شده است. در صورت امضا یا تأیید، Digest::NONE برای خلاصه مشخص شده است. هیچ خلاصه ای برای رمزگذاری یا رمزگشایی بدون پد لازم نیست.
• PaddingMode::RSA_PKCS1_1_5_SIGN padding نیاز به خلاصه دارد. خلاصه می تواند Digest::NONE باشد، در این صورت پیاده سازی Keymaster نمی تواند یک ساختار امضای مناسب PKCS#1 v1.5 ایجاد کند، زیرا نمی تواند ساختار DigestInfo را اضافه کند. در عوض، پیاده سازی 0x00 || 0x01 || PS || 0x00 || M را می سازد 0x00 || 0x01 || PS || 0x00 || M که M پیام ارائه شده و PS رشته padding است. اندازه کلید RSA باید حداقل 11 بایت بزرگتر از پیام باشد، در غیر این صورت روش ErrorCode::INVALID_INPUT_LENGTH برمی گرداند.
• PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding نیازی به خلاصه ندارد.
• PaddingMode::RSA_PSS padding به خلاصه نیاز دارد که نمی تواند Digest::NONE باشد. اگر Digest::NONE مشخص شده باشد، روش ErrorCode::INCOMPATIBLE_DIGEST برمی‌گرداند. علاوه بر این، اندازه کلید RSA باید حداقل 2 + D بایت بزرگتر از اندازه خروجی خلاصه باشد، که در آن D اندازه خلاصه است، در بایت. در غیر این صورت روش ErrorCode::INCOMPATIBLE_DIGEST را برمی گرداند. اندازه نمک D است.
• PaddingMode::RSA_OAEP padding به خلاصه نیاز دارد که نمی تواند Digest::NONE باشد. اگر Digest::NONE مشخص شده باشد، روش ErrorCode::INCOMPATIBLE_DIGEST برمی‌گرداند.

کلیدهای EC

عملیات کلید EC دقیقاً یک حالت padding را در inParams مشخص می کند. اگر بیش از یک بار مشخص نشده باشد یا مشخص شود، روش ErrorCode::UNSUPPORTED_PADDING_MODE را برمی گرداند.

عملیات کلید خصوصی ( KeyPurpose::SIGN ) به مجوز خلاصه و padding نیاز دارد، به این معنی که مجوزهای کلید باید حاوی مقادیر مشخص شده باشند. اگر نه، ErrorCode::INCOMPATIBLE_DIGEST را برگردانید. عملیات کلید عمومی ( KeyPurpose::VERIFY ) با خلاصه یا padding غیرمجاز مجاز است.

کلیدهای AES

عملیات کلید AES دقیقا یک حالت بلوک و یک حالت padding را در 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 باشد، حالت padding مشخص شده باید PaddingMode::NONE باشد. برای BlockMode::ECB یا BlockMode::CBC ، حالت می تواند PaddingMode::NONE یا PaddingMode::PKCS7 باشد. اگر حالت padding این شرایط را ندارد، ErrorCode::INCOMPATIBLE_PADDING_MODE برگردانید.

اگر حالت بلوک BlockMode::CBC ، BlockMode::CTR ، یا BlockMode::GCM باشد، یک بردار اولیه یا nonce مورد نیاز است. در بیشتر موارد، تماس گیرندگان نباید یک IV یا Nonce ارائه دهند. در آن صورت، پیاده‌سازی Keymaster یک IV یا nonce تصادفی تولید می‌کند و آن را با Tag::NONCE در outParams برمی‌گرداند. CBC و CTR IV 16 بایت هستند. نونس های GCM 12 بایت هستند. اگر مجوزهای کلیدی حاوی Tag::CALLER_NONCE باشند، تماس گیرنده می تواند یک IV یا nonce با Tag::NONCE در inParams ارائه دهد. اگر زمانی که Tag::CALLER_NONCE مجاز نیست، nonce ارائه شده است، ErrorCode::CALLER_NONCE_PROHIBITED برگردانید. اگر زمانی که Tag::CALLER_NONCE مجاز است، 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 مشخص می شود.

برای ارائه انعطاف‌پذیری بیشتر برای مدیریت بافر، پیاده‌سازی‌های این روش این گزینه را دارند که داده‌های کمتری نسبت به آنچه ارائه شده بود مصرف کنند. تماس گیرنده مسئول حلقه زدن برای تغذیه بقیه داده ها در تماس های بعدی است. مقدار ورودی مصرف شده در پارامتر inputConsumed برگردانده می شود. پیاده‌سازی‌ها همیشه حداقل یک بایت مصرف می‌کنند، مگر اینکه عملیات نتواند بیش از این را بپذیرد. اگر بیش از صفر بایت ارائه شود و صفر بایت مصرف شود، تماس گیرندگان این را یک خطا در نظر می گیرند و عملیات را لغو می کنند.

پیاده‌سازی‌ها همچنین می‌توانند انتخاب کنند که در نتیجه به‌روزرسانی چه مقدار داده را برگردانند. این فقط برای عملیات رمزگذاری و رمزگشایی مرتبط است، زیرا امضا و تأیید هیچ داده ای را تا پایان باز نمی گرداند. داده‌ها را در اسرع وقت برگردانید، نه اینکه آن‌ها را بافر کنید.

رسیدگی به خطا

اگر این روش کد خطایی غیر از ErrorCode::OK را برگرداند، عملیات لغو می شود و دسته عملیات باطل می شود. هر گونه استفاده در آینده از دسته، با این روش، پایان ، یا لغو ، ErrorCode::INVALID_OPERATION_HANDLE را برمی‌گرداند.

اجرای مجوز

اجرای مجوزهای کلیدی در ابتدا در ابتدا انجام می شود. تنها استثنا موردی است که کلید دارای موارد زیر است:

• یک یا چند برچسب::USER_SECURE_ID ، و
• برچسب::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

یک عملیات در حال انجام که با شروع شروع شده است را به پایان می رساند و تمام داده های هنوز پردازش نشده ارائه شده توسط به روز رسانی (ها) را پردازش می کند.

این روش آخرین روشی است که در یک عملیات فراخوانی شده است، بنابراین تمام داده های پردازش شده برگردانده می شوند.

این که آیا با موفقیت کامل می شود یا خطایی را برمی گرداند ، این روش عملکرد را نهایی می کند و بنابراین دسته عملیاتی ارائه شده را باطل می کند. هرگونه استفاده آینده از دسته ، با این روش یا به روزرسانی یا سقط ، ErrorCode::INVALID_OPERATION_HANDLE .

امضای عملیات امضای را به عنوان خروجی برگردانید. عملیات تأیید امضای موجود در پارامتر signature را قبول می کند و هیچ خروجی را باز نمی گرداند.

اجرای مجوز

اجرای مجوز کلیدی در ابتدا در ابتدا انجام می شود. یک استثناء موردی است که کلید در آن وجود دارد:

• یک یا چند برچسب :: user_secure_ids ، و
• برچسب ندارد :: auth_timeout

در این حالت ، کلید نیاز به مجوز در هر عملیات دارد و روش بروزرسانی یک برچسب را دریافت می کند :: 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 اندازه پیام هضم و به طور تصادفی تولید می شود. Digest مشخص شده با Tag :: Digest in inputParams در آغاز به عنوان الگوریتم PSS Digest و به عنوان الگوریتم Digest MGF1 استفاده می شود.
• PaddingMode::RSA_OAEP . Digest مشخص شده با Tag :: Digest in inputParams در آغاز به عنوان الگوریتم OAEP Digest استفاده می شود و از SHA1 به عنوان الگوریتم Digest MGF1 استفاده می شود.

کلیدهای ECDSA

اگر داده های ارائه شده برای امضای یا تأیید نشده بسیار طولانی است ، آن را کوتاه کنید.

کلیدهای AES

برخی از شرایط اضافی ، بسته به حالت بلوک:

• BlockMode::ECB یا BlockMode::CBC . اگر padding PaddingMode::NONE و طول داده ها چند مورد از اندازه بلوک AES نیست ، ErrorCode::INVALID_INPUT_LENGTH . اگر padding PaddingMode::PKCS7 است ، داده ها را در مشخصات PKCS#7 قرار دهید. توجه داشته باشید که PKCS#7 توصیه می کند اگر داده ها چند طول از طول بلوک باشد ، یک بلوک بالشتک اضافی اضافه کنید.
• BlockMode::GCM . در حین رمزگذاری ، پس از پردازش تمام متن های ساده ، برچسب ( برچسب :: mac_l طول) را محاسبه کرده و آن را به رمزنگاری برگشتی اضافه کنید. در حین رمزگشایی ، آخرین برچسب را پردازش کنید :: Mac_L طول بایت به عنوان برچسب. اگر تأیید برچسب انجام نشود ، ErrorCode::VERIFICATION_FAILED .

سقط

نسخه : 1 ، 2 ، 3

عملکرد در حال پیشرفت را قطع می کند. پس از تماس برای سقط ، بازگشت به ErrorCode::INVALID_OPERATION_HANDLE برای هرگونه استفاده بعدی از دسته عملیاتی ارائه شده با بروزرسانی ، پایان یا سقط .

get_supported_algorithms

نسخه : 1

لیست الگوریتم های پشتیبانی شده توسط اجرای سخت افزار KeyMaster را برمی گرداند. اجرای نرم افزار یک لیست خالی را برمی گرداند. یک اجرای ترکیبی لیستی را شامل می شود که فقط شامل الگوریتم هایی است که توسط سخت افزار پشتیبانی می شوند.

اجرای KEYMASTER 1 از RSA ، EC ، AES و HMAC پشتیبانی می کند.

get_supported_block_modes

نسخه : 1

لیست حالتهای بلوک AES را که توسط اجرای سخت افزار KeyMaster برای یک الگوریتم و هدف مشخص شده پشتیبانی می شود ، برمی گرداند.

برای RSA ، EC و HMAC ، که رمزهای مسدود کننده نیستند ، این روش لیست خالی را برای همه اهداف معتبر برمی گرداند. اهداف نامعتبر باید باعث شود روش برای بازگشت ErrorCode::INVALID_PURPOSE .

اجرای KEYMASTER 1 از ECB ، CBC ، CTR و GCM برای رمزگذاری و رمزگشایی AES پشتیبانی می کند.

get_supported_padding_modes

نسخه : 1

لیست حالت های بالشتک پشتیبانی شده توسط اجرای سخت افزار KeyMaster را برای یک الگوریتم و هدف مشخص باز می گرداند.

HMAC و EC هیچ تصوری از بالشتک ندارند ، بنابراین این روش لیست خالی را برای همه اهداف معتبر برمی گرداند. اهداف نامعتبر باید باعث شود روش برای بازگشت ErrorCode::INVALID_PURPOSE .

برای RSA ، پشتیبانی KEYMASTER 1 پشتیبانی:

• رمزگذاری ، رمزگشایی ، امضای و تأیید غیرقانونی. برای رمزگذاری و امضای غیرقابل استفاده ، اگر پیام کوتاه تر از مدول عمومی باشد ، پیاده سازی ها باید آن را با صفحات چپ بکشند. برای رمزگشایی و تأیید صحت ، طول ورودی باید با اندازه مدول عمومی مطابقت داشته باشد.
• PKCS#1 V1.5 رمزگذاری و امضای حالت های بالشتک
• PSS با حداقل طول نمک 20
• اواز

برای AE در حالت های ECB و CBC ، پیاده سازی KEYMASTER 1 از بدون PADDING و PKCS#7-Padding پشتیبانی می کند. حالت های CTR و GCM فقط از هیچ بالشتگی پشتیبانی نمی کنند.

get_supported_digests

نسخه : 1

لیست حالت های Digest را که توسط اجرای سخت افزار KeyMaster برای یک الگوریتم و هدف مشخص شده پشتیبانی می شود ، برمی گرداند.

هیچ حالت AES پشتیبانی نمی کند یا نیاز به هضم دارد ، بنابراین این روش یک لیست خالی را برای اهداف معتبر برمی گرداند.

پیاده سازی KEYMASTER 1 می تواند زیر مجموعه ای از هضم های تعریف شده را پیاده سازی کند. پیاده سازی ها SHA-256 را ارائه می دهد و می تواند MD5 ، SHA1 ، SHA-224 ، SHA-256 ، SHA384 و SHA512 (مجموعه کامل هضم های تعریف شده) را فراهم کند.

get_supported_import_formats

نسخه : 1

لیست قالب های وارداتی پشتیبانی شده توسط اجرای سخت افزار KeyMaster یک الگوریتم مشخص را برمی گرداند.

اجرای KEYMASTER 1 از فرمت PKCS#8 (بدون محافظت از رمز عبور) برای وارد کردن جفت های کلید RSA و EC پشتیبانی می کند و از واردات خام AES و مواد اصلی HMAC پشتیبانی می کند.

get_supported_export_formats

نسخه : 1

لیست قالب های صادراتی پشتیبانی شده توسط اجرای سخت افزار KeyMaster یک الگوریتم مشخص را برمی گرداند.

پیاده سازی KEYMASTER1 از فرمت X.509 برای صادرات کلیدهای عمومی RSA و EC پشتیبانی می کند. صادرات کلیدهای خصوصی یا کلیدهای نامتقارن پشتیبانی نمی شود.

عملکردهای تاریخی

KEYMASTER 0

توابع زیر متعلق به تعریف اصلی KeyMaster 0 است. آنها در Keymaster 1 ساختار keymaster1_device_t حضور داشتند. با این حال ، در Keymaster 1.0 آنها اجرا نشدند ، و نشانگرهای عملکردی آنها تهی شد.

• 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