برچسب های مجوز 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 را ببینید.

برچسب::ACTIVE_DATETIME

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

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

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

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

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

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

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

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

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

Keymaster 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

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

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

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

Keymaster 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 است.

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

Keymaster 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 است.

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

Keymaster 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 یا هر دو باشند.

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

Keymaster 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 طول مواد کلید مخفی را مشخص می کند.

برچسب::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

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

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

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

Keymaster 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 قطعی را مشخص می کند.

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

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

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

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

Keymaster 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 بیتی از مقادیر موجود در شمارش است:

Keymaster 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 متفاوت از سطح patchlevel سیستم در حال اجرا، باید باعث شود 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 دیگری را بپذیرد.

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