برچسب های مجوز Keymaster

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

برای Keymaster 4، برچسب‌ها در platform/hardware/interfaces/keymaster/ keymaster-version /types.hal تعریف می‌شوند، مانند 3.0/types.hal برای Keymaster 3 و 4.0/types.hal برای Keymaster 4. برای Keymaster 2 و پایین‌تر، برچسب ها در platform/hardware/libhardware/include/hardware/keymaster_defs.h تعریف شده اند.

برای توابع، صفحه Keymaster Functions را ببینید.

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

برچسب::ACTIVE_DATETIME

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

مقدار یک عدد صحیح 64 بیتی است که نشان دهنده میلی ثانیه از 1 ژانویه 1970 است.

برچسب::الگوریتم

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

برچسب::ALL_APPLICATIONS

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

برای استفاده در آینده رزرو شده است.

برچسب::ALLOW_WHILE_ON_BODY

نسخه : 2، 3، 4

قابل تکرار ؟ خیر

این برچسب فقط برای دستگاه‌های Android Wear با حسگرهای روی بدنه قابل اجرا است. در این مرحله، انتظار نمی رود که هیچ TEE بتواند دسترسی ایمن به یک حسگر روی بدنه را فراهم کند، یا اینکه حسگرهای روی بدنه بسیار ایمن هستند، بنابراین انتظار می رود که این یک ویژگی صرفاً نرم افزاری باشد.

برچسب::ALL_USERS

نسخه : 3، 4

قابل تکرار ؟ خیر

برای استفاده در آینده رزرو شده است.

برچسب::APPLICATION_DATA

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

هنگامی که این تگ برای generateKey یا importKey ارائه می‌شود، داده‌هایی را مشخص می‌کند که در تمام استفاده‌های کلید ضروری هستند. به طور خاص، فراخوانی‌های exportKey و getKeyCharacteristics باید مقدار یکسانی را برای پارامتر clientId ارائه کنند و فراخوان‌ها برای شروع باید این تگ و همان داده‌های مرتبط را به عنوان بخشی از مجموعه inParams ارائه دهند. اگر داده‌های صحیح ارائه نشده باشد، تابع ErrorCode::INVALID_KEY_BLOB برمی‌گرداند.

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

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::APPLICATION_ID

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

هنگامی که این تگ برای generateKey یا importKey ارائه می‌شود، داده‌هایی را مشخص می‌کند که در تمام استفاده‌های کلید ضروری هستند. به طور خاص، فراخوانی‌های exportKey و getKeyCharacteristics باید مقدار یکسانی را در پارامتر clientId ارائه دهند، و فراخوانی‌ها برای شروع نیاز به ارائه این برچسب و همان داده‌های مرتبط به عنوان بخشی از مجموعه inParams دارند. اگر داده‌های صحیح ارائه نشده باشد، تابع ErrorCode::INVALID_KEY_BLOB برمی‌گرداند.

محتوای این تگ از نظر رمزنگاری به کلید متصل است، به این معنی که دشمنی که می‌تواند به تمام اسرار جهان امن دسترسی داشته باشد – اما به محتوای برچسب دسترسی ندارد – نمی‌تواند کلید را رمزگشایی کند (بدون اجبار کردن برچسب محتوا).

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ASSOCIATED_DATA

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

"داده های مرتبط" را برای رمزگذاری یا رمزگشایی AES-GCM ارائه می دهد. این تگ برای به‌روزرسانی ارائه شده است و داده‌هایی را مشخص می‌کند که رمزگذاری/رمزگشایی نشده‌اند، اما در محاسبه تگ GCM استفاده می‌شوند.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_APPLICATION_ID

نسخه : 3، 4

قابل تکرار ؟ خیر

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

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_CHALLENGE

نسخه : 3، 4

قابل تکرار ؟ خیر

برای ارائه چالش در گواهینامه استفاده می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_BRAND

نسخه : 3، 4

قابل تکرار ؟ خیر

نام تجاری دستگاه را که توسط Build.BRAND در Android بازگردانده شده است، ارائه می دهد. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_DEVICE

نسخه : 3، 4

قابل تکرار ؟ خیر

نام دستگاه را که توسط Build.DEVICE در Android برگردانده شده است، ارائه می‌کند. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_IMEI

نسخه : 3، 4

قابل تکرار ؟ بله

IMEI را برای همه رادیوهای دستگاه ارائه می دهد. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_MANUFACTURER

نسخه : 3، 4

قابل تکرار ؟ خیر

نام سازنده دستگاه را که توسط Build.MANUFACTURER در Android بازگردانده شده است، ارائه می دهد. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_MEID

نسخه : 3، 4

قابل تکرار ؟ بله

MEID را برای همه رادیوهای موجود در دستگاه فراهم می کند. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_MODEL

نسخه : 3، 4

قابل تکرار ؟ خیر

نام مدل دستگاه را که توسط Build.MODEL در Android برگردانده شده است، ارائه می‌کند. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_PRODUCT

نسخه : 3، 4

قابل تکرار ؟ خیر

نام محصول دستگاه را که توسط Build.PRODUCT در Android بازگردانده شده است، ارائه می دهد. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::ATTESTATION_ID_SERIAL

نسخه : 3، 4

قابل تکرار ؟ خیر

شماره سریال دستگاه را ارائه می دهد. این فیلد فقط هنگام درخواست تأیید شناسه های دستگاه تنظیم می شود.

اگر دستگاه از تأیید شناسه پشتیبانی نمی کند (یا قبلاً فراخوانی شده بود destroyAttestationIds() و دستگاه دیگر نمی تواند شناسه های خود را تأیید کند)، هر درخواست تأیید کلیدی که شامل این برچسب باشد با ErrorCode::CANNOT_ATTEST_IDS ناموفق می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::AUTH_TIMEOUT

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

زمانی را بر حسب ثانیه مشخص می کند که کلید برای استفاده از آن پس از احراز هویت مجاز است. اگر Tag::USER_SECURE_ID وجود داشته باشد و این برچسب وجود نداشته باشد، کلید برای هر استفاده نیاز به احراز هویت دارد (برای جزئیات جریان احراز هویت در هر عملیات به شروع مراجعه کنید).

مقدار یک عدد صحیح 32 بیتی است که زمان را بر حسب ثانیه پس از احراز هویت موفقیت آمیز کاربر مشخص شده توسط Tag::USER_SECURE_ID با روش احراز هویت مشخص شده توسط Tag::USER_AUTH_TYPE مشخص می کند که می توان از کلید استفاده کرد.

برچسب::AUTH_TOKEN

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

یک نشانه احراز هویت برای شروع ، به‌روزرسانی یا پایان ، برای اثبات احراز هویت کاربر برای عملیات کلیدی که به آن نیاز دارد ارائه می‌کند (کلید دارای برچسب::USER_SECURE_ID است).

مقدار یک لکه است که شامل ساختار hw_auth_token_t است.

برچسب::BLOB_USAGE_REQUIREMENTS

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

این تگ می تواند در طول تولید کلید مشخص شود تا نیاز باشد که کلید در شرایط مشخص شده قابل استفاده باشد. باید با ویژگی های کلیدی geneKey و getKeyCharacteristics برگردانده شود. اگر تماس گیرنده Tag::BLOB_USAGE_REQUIREMENTS با مقدار KeyBlobUsageRequirements::STANDALONE مشخص کند، Trustlet یک حباب کلید را برمی‌گرداند که می‌تواند بدون پشتیبانی از سیستم فایل استفاده شود. این برای دستگاه‌هایی با دیسک‌های رمزگذاری‌شده بسیار مهم است، جایی که سیستم فایل ممکن است تا زمانی که از کلید Keymaster برای رمزگشایی دیسک استفاده نشود، در دسترس نباشد.

برچسب::BLOCK_MODE

نسخه : 1، 2، 3، 4

قابل تکرار ؟ بله

حالت‌های رمزگذاری بلوکی را مشخص می‌کند که کلید می‌تواند با آنها استفاده شود. این تگ فقط مربوط به کلیدهای AES است.

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

این تگ قابل تکرار است و برای عملیات کلید AES حالتی را در آرگومان additionalParams در start مشخص کنید. اگر حالت مشخص شده در حالت های مرتبط با کلید نباشد، عملیات با ErrorCode::INCOMPATIBLE_BLOCK_MODE با شکست مواجه می شود.

برچسب::BOOT_PATCHLEVEL

نسخه : 4

برچسب::BOOT_PATCHLEVEL سطح وصله امنیتی تصویر بوت (هسته) را مشخص می کند که کلید می تواند با آن استفاده شود. این تگ هرگز به keymaster TA ارسال نمی شود، بلکه توسط TA به لیست مجوزهای اعمال شده توسط سخت افزار اضافه می شود. هرگونه تلاش برای استفاده از کلیدی با مقدار Tag::BOOT_PATCHLEVEL متفاوت از سطح patchlevel سیستم در حال اجرا، باعث begin() , getKeyCharacteristics() یا exportKey() برای بازگرداندن ErrorCode::KEY_REQUIRES_UPGRADE می شود. برای جزئیات بیشتر به upgradeKey() مراجعه کنید.

مقدار تگ یک عدد صحیح از فرم YYYYMMDD است که در آن YYYY سال چهار رقمی آخرین به روز رسانی، MM ماه دو رقمی و DD روز دو رقمی آخرین به روز رسانی است. به عنوان مثال، برای کلیدی که در یک دستگاه Android آخرین بار در 5 ژوئن 2018 به‌روزرسانی شده است، مقدار آن 20180605 خواهد بود. اگر روز مشخص نباشد، 00 می‌تواند جایگزین شود.

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

باید سخت افزاری اجرا شود.

برچسب::BOOTLOADER_ONLY

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

هرگونه تلاش برای استفاده از کلید با Tag::BOOTLOADER_ONLY از سیستم Android با ErrorCode::INVALID_KEY_BLOB ناموفق است.

برچسب::CALLER_NONCE

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

مشخص می‌کند که تماس‌گیرنده می‌تواند برای عملیات‌های غیرنیازمند یک Noce ارائه کند.

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

این تگ فقط برای کلیدهای AES استفاده می شود و فقط برای حالت های بلوک CBC، CTR و GCM کاربرد دارد. اگر برچسب وجود نداشته باشد، پیاده‌سازی‌ها باید هر عملیاتی را که Tag::NONCE ارائه می‌کند رد کنند تا با ErrorCode::CALLER_NONCE_PROHIBITED شروع شود .

برچسب::CREATION_DATETIME

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

تاریخ و زمان ایجاد کلید را بر حسب میلی ثانیه از 1 ژانویه 1970 مشخص می کند. این برچسب اختیاری و فقط اطلاعاتی است.

برچسب::هضم

نسخه : 1، 2، 3، 4

قابل تکرار ؟ بله

الگوریتم‌های خلاصه را که می‌توان با کلید برای انجام عملیات امضا و تأیید استفاده کرد، مشخص می‌کند. این تگ مربوط به کلیدهای RSA، ECDSA و HMAC است.

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

این تگ قابل تکرار است. برای عملیات امضا و تأیید، یک خلاصه در آرگومان additionalParams در start مشخص کنید. اگر خلاصه مشخص شده در خلاصه های مرتبط با کلید نباشد، عملیات با ErrorCode::INCOMPATIBLE_DIGEST با شکست مواجه می شود.

برچسب::EC_CURVE

نسخه : 2، 3، 4

قابل تکرار ؟ خیر

در Keymaster 1، منحنی مورد استفاده برای کلیدهای EC از اندازه کلید مشخص شده حدس زده شد. برای بهبود انعطاف پذیری در حرکت رو به جلو، Keymaster 2 یک روش صریح برای تعیین منحنی ها معرفی کرد. درخواست‌های تولید کلید EC می‌توانند دارای Tag::EC_CURVE ، Tag::KEY_SIZE یا هر دو باشند.

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};

Keymaster 2 و قبل از آن

enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

اگر درخواست تولید فقط حاوی Tag::KEY_SIZE باشد، به منطق Keymaster 1 برگردید و منحنی NIST مناسب را انتخاب کنید.

اگر درخواست فقط حاوی Tag::EC_CURVE باشد، از منحنی مشخص شده استفاده کنید. برای Keymaster 3 به بعد، منحنی ها در EcCurve تعریف می شوند. برای Keymaster 2 و نسخه های قبلی، منحنی ها در keymaster_ec_curve_t تعریف می شوند.

اگر درخواست شامل هر دو باشد، از منحنی مشخص شده توسط Tag::EC_CURVE استفاده کنید و تأیید کنید که اندازه کلید مشخص شده برای آن منحنی مناسب است. اگر نه، ErrorCode::INVALID_ARGUMENT برگردانید.

برچسب::INCLUDE_UNIQUE_ID

نسخه : 2، 3، 4

قابل تکرار ؟ خیر

این تگ در طول تولید کلید مشخص می‌شود تا نشان دهد که گواهی تأیید برای کلید تولید شده باید دارای شناسه منحصر به فرد دستگاه با محدوده برنامه و محدود به زمان باشد، همانطور که توسط Tag::UNIQUE_ID مشخص شده است.

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

برچسب::KEY_SIZE

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

اندازه کلید را بر حسب بیت مشخص می کند که به روش معمولی برای الگوریتم کلید اندازه گیری می شود. به عنوان مثال، برای کلیدهای RSA، Tag::KEY_SIZE اندازه مدول عمومی را مشخص می کند. برای کلیدهای AES طول مواد کلید مخفی را مشخص می کند.

توجه: در Keymaster 2 و جدیدتر، Tag::KEY_SIZE دیگر مکانیسم ترجیحی برای انتخاب منحنی‌های ECC (رمز نگاری منحنی بیضی) نیست. در حالی که برای انواع کلیدهای دیگر تغییری نکرده است، منحنی‌های ECC با استفاده از برچسب Tag::EC_CURVE انتخاب می‌شوند.

برچسب::MAC_LENGTH

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

طول درخواستی یک تگ احراز هویت MAC یا GCM را در بیت ارائه می کند.

مقدار طول MAC بر حسب بیت است. این مضرب 8 است و حداقل به اندازه مقدار Tag::MIN_MAC_LENGTH مرتبط با کلید است.

برچسب::MAX_USES_PER_BOOT

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

مقدار یک عدد صحیح 32 بیتی است که نشان دهنده استفاده در هر بوت است.

هنگامی که یک کلید با این برچسب در یک عملیات استفاده می شود، یک شمارنده مرتبط با کلید باید در طول تماس شروع افزایش یابد. پس از اینکه شمارنده کلید از این مقدار فراتر رفت، تمام تلاش‌های بعدی برای استفاده از کلید با ErrorCode::MAX_OPS_EXCEEDED شکست می‌خورد تا زمانی که دستگاه مجدداً راه‌اندازی شود. این بدان معناست که یک Trustlet جدولی از شمارنده های استفاده برای کلیدهای دارای این تگ نگه می دارد. از آنجایی که حافظه Keymaster اغلب محدود است، این جدول می‌تواند حداکثر اندازه ثابتی داشته باشد و Keymaster می‌تواند عملیاتی را که سعی در استفاده از کلیدها با این برچسب زمانی که جدول پر است، با شکست مواجه کند. میز باید حداقل 16 کلید داشته باشد. اگر عملیاتی به دلیل پر بودن جدول شکست بخورد، Keymaster ErrorCode::TOO_MANY_OPERATIONS را برمی‌گرداند.

برچسب::MIN_MAC_LENGTH

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

این تگ حداقل طول MAC را که می توان با این کلید برای کلیدهای HMAC و کلیدهای AES که از حالت GCM پشتیبانی می کنند درخواست یا تأیید کرد، مشخص می کند.

این مقدار حداقل طول MAC، بر حسب بیت است. این مضرب 8 است. برای کلیدهای HMAC، مقدار حداقل 64 است. برای کلیدهای GCM، مقدار حداقل 96 است و بیش از 128 نیست.

برچسب::MIN_SECONDS_BETWEEN_OPS

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

حداقل مدت زمانی را که بین عملیات مجاز با استفاده از یک کلید سپری می شود، مشخص می کند. این می‌تواند برای نرخ‌گذاری محدودیت استفاده از کلیدها در زمینه‌هایی استفاده شود که استفاده نامحدود ممکن است حملات brute force را ممکن کند.

مقدار یک عدد صحیح 32 بیتی است که ثانیه های بین عملیات مجاز را نشان می دهد.

هنگامی که از کلیدی با این برچسب در عملیاتی استفاده می شود، تایمر را در حین پایان یا لغو تماس شروع کنید. هر تماسی برای شروع که قبل از تایمر دریافت می‌شود نشان می‌دهد که بازه زمانی مشخص‌شده توسط Tag::MIN_SECONDS_BETWEEN_OPS سپری شده است با ErrorCode::KEY_RATE_LIMIT_EXCEEDED ناموفق است. این بدان معناست که یک Trustlet جدولی از شمارنده های استفاده برای کلیدهای دارای این تگ نگه می دارد. از آنجایی که حافظه Keymaster اغلب محدود است، این جدول می‌تواند حداکثر اندازه ثابتی داشته باشد و Keymaster می‌تواند عملیاتی را که سعی در استفاده از کلیدها با این برچسب زمانی که جدول پر است، با شکست مواجه کند. این جدول باید حداقل 32 کلید در حال استفاده را در خود جای دهد و در صورت انقضای فواصل زمانی حداقل استفاده از کلید، از شیارهای جدول به شدت استفاده شود. اگر عملیاتی به دلیل پر بودن جدول شکست بخورد، Keymaster ErrorCode::TOO_MANY_OPERATIONS را برمی‌گرداند.

برچسب::NO_AUTH_REQUIRED

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

مشخص می کند که برای استفاده از این کلید نیازی به احراز هویت نیست. این تگ با Tag::USER_SECURE_ID به صورت متقابل انحصاری است.

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

برچسب:: غیرممکن است

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

یک nonce یا بردار اولیه (IV) را برای رمزگذاری یا رمزگشایی AES GCM، CBC یا CTR ارائه می دهد یا برمی گرداند. این تگ برای شروع عملیات رمزگذاری و رمزگشایی ارائه شده است. فقط در صورتی برای شروع ارائه می شود که کلید دارای Tag::CALLER_NONCE باشد. اگر ارائه نشود، یک nonce یا IV مناسب به طور تصادفی توسط Keymaster تولید می‌شود و از ابتدا بازگردانده می‌شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها. طول های مجاز به حالت بستگی دارد: nonces GCM 12 بایت طول دارند. طول CBC و CTR IV 16 بایت است.

برچسب:: مبدا

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

محل ایجاد کلید را مشخص می‌کند، اگر مشخص باشد. این برچسب را نمی توان در طول تولید یا وارد کردن کلید مشخص کرد و باید توسط Trustlet به ویژگی های کلیدی اضافه شود.

کی مستر 3

مقادیر ممکن در android::hardware::keymaster::v3_0::KeyOrigin :

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};

Keymaster 2 و قبل از آن

مقادیر ممکن در keymaster_origin_t تعریف شده است:

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

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

GENERATED نشان می دهد که Keymaster کلید را تولید کرده است. اگر در لیست سخت‌افزاری، کلید در سخت‌افزار امن تولید شده است و به‌طور دائمی سخت‌افزار محدود است. اگر در لیست اعمال شده توسط نرم افزار، کلید در SoftKeymaster تولید شده است و محدود به سخت افزار نیست.

DERIVED نشان می دهد که کلید از داخل Keymaster مشتق شده است. به احتمال زیاد خارج از دستگاه وجود دارد.

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

UNKNOWN فقط باید در لیست سخت افزاری ظاهر شود. این نشان می دهد که کلید سخت افزاری است، اما مشخص نیست که آیا کلید در ابتدا در سخت افزار ایمن تولید شده است یا وارد شده است. این تنها زمانی اتفاق می‌افتد که از سخت‌افزار keymaster0 برای شبیه‌سازی سرویس‌های keymaster1 استفاده شود.

برچسب::ORIGINATION_EXPIRE_DATETIME

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

تاریخ و زمانی را مشخص می کند که در آن کلید برای اهداف امضا و رمزگذاری منقضی می شود. پس از این زمان، هر تلاشی برای استفاده از کلید با KeyPurpose::SIGN یا KeyPurpose::ENCRYPT ارائه شده برای شروع با ErrorCode::KEY_EXPIRED با شکست مواجه می شود.

مقدار یک عدد صحیح 64 بیتی است که نشان دهنده میلی ثانیه از 1 ژانویه 1970 است.

برچسب::OS_PATCHLEVEL

نسخه : 2، 3، 4

قابل تکرار ؟ خیر

این تگ هرگز به keymaster TA ارسال نمی شود، بلکه توسط TA به لیست مجوزهای اعمال شده توسط سخت افزار اضافه می شود.

مقدار تگ یک عدد صحیح از فرم YYYYMM است که در آن YYYY سال چهار رقمی آخرین به روز رسانی و MM ماه دو رقمی آخرین به روز رسانی است. به عنوان مثال، برای یک کلید تولید شده در دستگاه اندرویدی که آخرین بار در دسامبر 2015 به روز شده است، مقدار آن 201512 خواهد بود.

کلیدهایی که سطح وصله متفاوتی با سطح وصله فعلی دارند، قابل استفاده نیستند. تلاش برای استفاده از چنین کلیدی باعث شروع ، getKeyCharacteristics یا exportKey برای بازگرداندن ErrorCode::KEY_REQUIRES_UPGRADE می شود. برای جزئیات بیشتر به نسخه Binding مراجعه کنید.

برچسب::OS_VERSION

نسخه : 2، 3، 4

قابل تکرار ؟ خیر

این تگ هرگز به keymaster TA ارسال نمی شود، بلکه توسط TA به لیست مجوزهای اعمال شده توسط سخت افزار اضافه می شود.

مقدار تگ یک عدد صحیح از فرم MMmmss است که در آن MM شماره نسخه اصلی، mm شماره نسخه فرعی و ss شماره نسخه فرعی است. به عنوان مثال، برای یک کلید تولید شده در اندروید نسخه 4.0.3، مقدار 040003 خواهد بود.

برچسب::پدینگ

نسخه : 1، 2، 3، 4

قابل تکرار ؟ بله

حالت های padding را که می توان با کلید استفاده کرد را مشخص می کند. این تگ مربوط به کلیدهای RSA و AES است.

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP و PaddingMode::RSA_PKCS1_1_5_ENCRYPT فقط برای کلیدهای رمزگذاری/رمزگشایی RSA استفاده می شوند و به ترتیب RSA PKCS#1v2 OAEP padding و RSA PKCS#1 v1.5 padding تصادفی شده را مشخص می کنند. PaddingMode::RSA_PSS و PaddingMode::RSA_PKCS1_1_5_SIGN فقط برای کلیدهای امضا/تأیید RSA استفاده می شود و به ترتیب RSA PKCS#1v2 PSS padding و RSA PKCS#1 v1.5 padding قطعی را مشخص می کند.

توجه: حالت padding RSA PSS با Digest::NONE سازگار نیست.

PaddingMode::NONE می توان با کلیدهای RSA یا AES استفاده کرد. برای کلیدهای AES، اگر PaddingMode::NONE با حالت بلوک ECB یا CBC استفاده می‌شود و داده‌هایی که باید رمزگذاری یا رمزگشایی شوند، مضربی از اندازه بلوک AES نیستند، تماس برای پایان با ErrorCode::INVALID_INPUT_LENGTH با شکست مواجه می‌شود.

PaddingMode::PKCS7 فقط با کلیدهای AES و فقط با حالت های ECB و CBC قابل استفاده است.

این تگ قابل تکرار است. برای شروع باید یک حالت padding در تماس مشخص شود. اگر حالت مشخص شده برای کلید مجاز نباشد، عملیات با ErrorCode::INCOMPATIBLE_BLOCK_MODE ناموفق است.

برچسب:: هدف

نسخه : 1، 2، 3، 4

قابل تکرار ؟ بله

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

مقادیر ممکن با شمارش زیر تعریف می شوند:

کی مستر 3

enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};

Keymaster 2 و قبل از آن

typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

این تگ قابل تکرار است. کلیدها را می توان با مقادیر متعدد تولید کرد، اگرچه یک عملیات یک هدف واحد دارد. هنگامی که تابع start برای شروع یک عملیات فراخوانی می شود، هدف عملیات مشخص می شود. اگر هدف مشخص شده برای عملیات توسط کلید مجاز نباشد، عملیات با ErrorCode::INCOMPATIBLE_PURPOSE با شکست مواجه می شود.

برچسب::RESET_SINCE_ID_ROTATION

نسخه : 3، 4

قابل تکرار ؟ خیر

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

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

برچسب::ROLLBACK_RESISTANT

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

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

این تگ Boolean است، بنابراین مقادیر ممکن درست (در صورت وجود تگ) و false (اگر تگ موجود نباشد) است.

برچسب::ROOT_OF_TRUST

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

ریشه اعتماد را مشخص می‌کند، کلیدی که توسط بوت تأیید شده برای تأیید اعتبار سیستم عامل راه‌اندازی شده (در صورت وجود) استفاده می‌شود. این تگ هرگز در ویژگی های کلیدی به Keymaster ارائه نمی شود یا از آن بازگردانده نمی شود.

برچسب::RSA_PUBLIC_EXPONENT

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

مقدار توان عمومی برای یک جفت کلید RSA را مشخص می کند. این برچسب فقط مربوط به کلیدهای RSA است و برای همه کلیدهای RSA ضروری است.

مقدار یک عدد صحیح بدون علامت 64 بیتی است که الزامات یک توان عمومی RSA را برآورده می کند. این مقدار باید یک عدد اول باشد. Trustlet ها از مقدار 2^16+1 پشتیبانی می کنند و می توانند مقادیر معقول دیگر، به ویژه مقدار 3 را پشتیبانی کنند. اگر توانی مشخص نشده باشد یا اگر توان مشخص شده پشتیبانی نشود، تولید کلید با ErrorCode::INVALID_ARGUMENT ناموفق است.

برچسب::UNIQUE_ID

نسخه : 3، 4

قابل تکرار ؟ خیر

برای ارائه شناسه منحصر به فرد در گواهی استفاده می شود.

مقدار یک لکه است، یک آرایه با طول دلخواه از بایت ها.

برچسب::USAGE_EXPIRE_DATETIME

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

تاریخ و زمانی را مشخص می کند که در آن کلید برای اهداف تأیید و رمزگشایی منقضی می شود. پس از این زمان، هر تلاشی برای استفاده از کلید با KeyPurpose::VERIFY یا KeyPurpose::DECRYPT ارائه شده برای شروع با ErrorCode::KEY_EXPIRED با شکست مواجه می شود.

مقدار یک عدد صحیح 64 بیتی است که نشان دهنده میلی ثانیه از 1 ژانویه 1970 است.

برچسب::USER_AUTH_TYPE

نسخه : 1، 2، 3، 4

قابل تکرار ؟ خیر

انواع احراز هویت کاربر را مشخص می کند که می توان از آنها برای مجوز دادن به این کلید استفاده کرد. هنگامی که از Keymaster خواسته می شود تا عملیاتی را با یک کلید با این تگ انجام دهد، یک نشانه احراز هویت دریافت می کند و فیلد authenticator_type توکن باید با مقدار موجود در تگ مطابقت داشته باشد. به عنوان مثال، (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 ، که در آن ntoh تابعی است که اعداد صحیح مرتب شده شبکه را به اعداد صحیح مرتب شده میزبان تبدیل می کند و auth_type_tag_value مقدار این تگ است.

مقدار یک بیت ماسک عدد صحیح 32 بیتی از مقادیر موجود در شمارش است:

کی مستر 3

enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};

Keymaster 2 و قبل از آن

typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

برچسب::USER_SECURE_ID

نسخه : 1، 2، 3، 4

قابل تکرار ؟ بله

مشخص می کند که یک کلید فقط تحت یک وضعیت احراز هویت کاربر امن خاص قابل استفاده است. این برچسب با Tag::NO_AUTH_REQUIRED انحصاری متقابل است.

این مقدار یک عدد صحیح 64 بیتی است که مقدار حالت سیاست احراز هویت را مشخص می‌کند که باید در یک نشانه احراز هویت (که برای شروع با Tag::AUTH_TOKEN ارائه می‌شود) وجود داشته باشد تا استفاده از کلید مجاز شود. هر فراخوانی برای شروع با کلیدی با این تگ که نشانه احراز هویت ارائه نمی‌کند، یا یک نشانه احراز هویت بدون مقدار وضعیت خط مشی منطبق ارائه می‌کند، با شکست مواجه می‌شود.

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

برچسب::VENDOR_PATCHLEVEL

نسخه : 4

این تگ سطح وصله امنیتی تصویر فروشنده را مشخص می کند که کلید می تواند با آن استفاده شود. این تگ هرگز به keymaster TA ارسال نمی شود، بلکه توسط TA به لیست مجوزهای اعمال شده توسط سخت افزار اضافه می شود. هرگونه تلاش برای استفاده از کلیدی با مقدار Tag::VENDOR_PATCHLEVEL متفاوت از سطح patch سیستم در حال اجرا باید باعث شود begin() , getKeyCharacteristics() یا exportKey() ErrorCode::KEY_REQUIRES_UPGRADE برگرداند. برای جزئیات بیشتر به upgradeKey() مراجعه کنید.

مقدار تگ یک عدد صحیح از فرم YYYYMMDD است که در آن YYYY سال چهار رقمی آخرین به روز رسانی، MM ماه دو رقمی و DD روز دو رقمی آخرین به روز رسانی است. به عنوان مثال، برای کلیدی که در یک دستگاه Android آخرین بار در 5 ژوئن 2018 به روز شده است، مقدار آن 20180605 خواهد بود.

IKeymasterDevice HAL باید سطح پچ فروشنده فعلی را از ویژگی سیستم ro.vendor.build.security_patch بخواند و هنگامی که HAL برای اولین بار بارگذاری شد آن را به محیط امن تحویل دهد (مکانیسم پیاده سازی تعریف شده است). محیط امن نباید تا پس از راه‌اندازی بعدی، Patchlevel دیگری را بپذیرد.

باید سخت افزاری اجرا شود.