توابع Keymaster

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

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

دستورالعمل های زیر برای همه توابع موجود در 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 معقول و مفید هستند.

توابع

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::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 اضافه می کند، و اگر کلید در برابر بازگشت مقاوم باشد،

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

مقاومت برگشتی به این معنی است که هنگامی که یک کلید با 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() باید با یکی از اهداف در مجوزهای کلید مطابقت داشته باشد، مگر اینکه عملیات درخواستی یک عملیات کلید عمومی باشد. اگر هدف مشخص شده مطابقت نداشته باشد و عملیات یک عملیات کلید عمومی نباشد، 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 باشد. اگر کلید دارای هر دو باشد، این روش باید یک 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_ID ، و
• برچسب::AUTH_TIMEOUT ندارد

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

کلیدهای ECDSA

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

کلیدهای AES

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

• BlockMode::ECB یا BlockMode::CBC . اگر padding PaddingMode::NONE است و طول داده مضربی از اندازه بلوک AES نیست، ErrorCode::INVALID_INPUT_LENGTH را برگردانید. اگر padding PaddingMode::PKCS7 است، داده ها را مطابق با مشخصات PKCS#7 قرار دهید. توجه داشته باشید که PKCS#7 توصیه می‌کند در صورتی که داده‌ها مضربی از طول بلوک هستند، یک بلوک padding اضافی اضافه کنید.
• BlockMode::GCM . در طول رمزگذاری، پس از پردازش تمام متن ساده، تگ ( Tag::MAC_LENGTH بایت) را محاسبه کرده و آن را به متن رمزی برگشتی اضافه کنید. در طول رمزگشایی، آخرین Tag::MAC_LENGTH بایت را به عنوان برچسب پردازش کنید. اگر تأیید تگ ناموفق بود، 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

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

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

برای RSA، Keymaster 1 از پیاده سازی ها پشتیبانی می کند:

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

برای AES در حالت‌های ECB و CBC، پیاده‌سازی‌های Keymaster 1 بدون padding و PKCS#7-padding پشتیبانی می‌کنند. حالت‌های CTR و GCM فقط از هیچ بالشتکی پشتیبانی نمی‌کنند.

get_supported_digests

نسخه : 1

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

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

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

get_supported_import_formats

نسخه : 1

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

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

get_supported_export_formats

نسخه : 1

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

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

کارکردهای تاریخی

کی مستر 0

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

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

کی مستر 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

کی مستر 2

توابع زیر به تعریف Keymaster 2 تعلق دارند، اما در Keymaster 3 به همراه توابع Keymaster 1 که در بالا ذکر شده است حذف شدند.

• configure

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

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

دستورالعمل های زیر برای همه توابع موجود در 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 معقول و مفید هستند.

توابع

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::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 اضافه می کند، و اگر کلید در برابر بازگشت مقاوم باشد،

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

مقاومت برگشتی به این معنی است که هنگامی که یک کلید با 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() باید با یکی از اهداف در مجوزهای کلید مطابقت داشته باشد، مگر اینکه عملیات درخواستی یک عملیات کلید عمومی باشد. اگر هدف مشخص شده مطابقت نداشته باشد و عملیات یک عملیات کلید عمومی نباشد، 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 باشد. اگر کلید دارای هر دو باشد، این روش باید یک 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_ID ، و
• برچسب::AUTH_TIMEOUT ندارد

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

کلیدهای ECDSA

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

کلیدهای AES

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

• BlockMode::ECB یا BlockMode::CBC . اگر padding PaddingMode::NONE است و طول داده مضربی از اندازه بلوک AES نیست، ErrorCode::INVALID_INPUT_LENGTH را برگردانید. اگر padding PaddingMode::PKCS7 است، داده ها را مطابق با مشخصات PKCS#7 قرار دهید. توجه داشته باشید که PKCS#7 توصیه می‌کند در صورتی که داده‌ها مضربی از طول بلوک هستند، یک بلوک padding اضافی اضافه کنید.
• BlockMode::GCM . در طول رمزگذاری، پس از پردازش تمام متن ساده، تگ ( Tag::MAC_LENGTH بایت) را محاسبه کرده و آن را به متن رمزی برگشتی اضافه کنید. در طول رمزگشایی، آخرین Tag::MAC_LENGTH بایت را به عنوان برچسب پردازش کنید. اگر تأیید تگ ناموفق بود، 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

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

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

برای RSA، Keymaster 1 از پیاده سازی ها پشتیبانی می کند:

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

برای AES در حالت‌های ECB و CBC، پیاده‌سازی‌های Keymaster 1 بدون padding و PKCS#7-padding پشتیبانی می‌کنند. حالت‌های CTR و GCM فقط از هیچ بالشتکی پشتیبانی نمی‌کنند.

get_supported_digests

نسخه : 1

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

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

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

get_supported_import_formats

نسخه : 1

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

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

get_supported_export_formats

نسخه : 1

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

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

کارکردهای تاریخی

کی مستر 0

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

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

کی مستر 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

کی مستر 2

توابع زیر به تعریف Keymaster 2 تعلق دارند، اما در Keymaster 3 به همراه توابع Keymaster 1 که در بالا ذکر شده است حذف شدند.

• configure