תגי הרשאה של Keymaster

בדף הזה מופיעים פרטים שיעזרו לנו להטמיע מערכות Keymaster HAL. הוא כולל כל תג ב-HAL, איזו גרסת Keymaster זמינה בו ואם ניתן לחזור על התג. למעט כפי שצוין בתיאורי התגים, כל התגים הבאים משמשים ליצירת מפתחות כדי לציין למאפיינים.

ב-Keymaster 4, התגים מוגדרים לפי platform/hardware/interfaces/keymaster/keymaster-version/types.hal, כמו 3.0/types.hal ל-Keymaster 3 ול-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.

תג::ALGORITHM

גרסה: 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

התוכן של התג הזה קשור למפתח קריפטוגרפית, כלומר אסור ליריב שיש לו גישה לכל סודות עולם מאובטחים אבל אין לו גישה לתוכן התג כדי לפענח את מבלי לאלץ אכיפה מסוג brute על תוכן התג, דבר שהאפליקציות יכולות למנוע על ידי שמציין תוכן באנטרופיה גבוהה מספיק.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::APPLICATION_ID

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

כשהיא מסופקת ל generateKey או ImportKey, התג הזה מציין את הנתונים שנחוצים לכל שימוש במפתח. לחשבון במיוחד, קריאות exportKey וגם getKeyCharacteristics צריך לספק את אותו הערך בפרמטר clientId, קריאות להתחיל צריכות לספק את התג הזה ואת אותם הנתונים המשויכים כחלק inParams הוגדר. אם לא תספקו את הנתונים הנכונים, הפונקציה הפונקציה מחזירה את הערך ErrorCode::INVALID_KEY_BLOB.

התוכן של התג הזה קשור למפתח קריפטוגרפית, כלומר, יריב שיכול לגשת לכל הסודות של העולם המאובטח — ל- אין גישה לתוכן התג - אינו יכול לפענח את מפתח (מבלי לאלץ אכיפה מסוג brute על תוכן התג).

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ASSOCIATED_DATA

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מספקת 'נתונים משויכים' להצפנה או לפענוח של AES-GCM. התג הזה סופקו לעדכון מציין נתונים שאינם מוצפנים/מפוענחים, אלא משמשים לחישוב תג GCM.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_APPLICATION_ID

גרסה: 3, 4

ניתן לחזרה? לא

משמש לזיהוי קבוצת האפליקציות האפשריות של כל אחת התחיל תהליך אימות (attestation) של מפתח.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTE מציינים_CHALLENGE

גרסה: 3, 4

ניתן לחזרה? לא

משמש לאתגר באימות (attestation).

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_BRAND

גרסה: 3, 4

ניתן לחזרה? לא

מספק את שם המותג של המכשיר, כפי שהוחזר על ידי Build.BRAND ב-Android. השדה הזה מוגדר רק כאשר מבקשים אימות (attestation) של המזהים של המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_DEVICE

גרסה: 3, 4

ניתן לחזרה? לא

כאן מוצג שם המכשיר של המכשיר, כפי שהוחזר על ידי Build.DEVICE ב-Android. השדה הזה מוגדר רק כאשר מבקשים אימות (attestation) של המזהים של המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_IMEI

גרסה: 3, 4

ניתן לחזרה? כן

מספקת את מספרי ה-IMEI של כל מכשירי הרדיו במכשיר. השדה הזה מוגדר בלבד כשמבקשים אימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_MANUFACTURER

גרסה: 3, 4

ניתן לחזרה? לא

מספק את שם היצרן של המכשיר, כפי שהוא מוחזר על ידי Build.MANUFACTURER ב-Android. השדה הזה מוגדר רק כאשר בקשה לאימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_MEID

גרסה: 3, 4

ניתן לחזרה? כן

מספקת את מזהי ה-MEID של כל מכשירי הרדיו במכשיר. השדה הזה יוגדר רק כשמבקשים אימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTE מציינים_ID_MODEL

גרסה: 3, 4

ניתן לחזרה? לא

מספק את שם הדגם של המכשיר, כפי שהוחזר על ידי Build.MODEL ב-Android. השדה הזה מוגדר רק כאשר בקשה לאימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTEstation_ID_PRODUCT

גרסה: 3, 4

ניתן לחזרה? לא

מספק את שם המוצר של המכשיר, כפי שהוחזר על ידי Build.PRODUCT ב-Android. השדה הזה מוגדר רק כאשר בקשה לאימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::ATTE מציינים_ID_SERIAL

גרסה: 3, 4

ניתן לחזרה? לא

מספקת את המספר הסידורי של המכשיר. השדה הזה מוגדר רק כאשר בקשה לאימות (attestation) של מזהי המכשיר.

אם המכשיר לא תומך באימות באמצעות מזהה (או בוצעה שיחה אל destroyAttestationIds(), והמכשיר יכול לא לאמת יותר את המזהים שלו), כל בקשת אימות (attestation) של מפתח שכוללת תג זה נכשל עם ErrorCode::CANNOT_ATTEST_IDS.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::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

ניתן לחזרה? לא

מספקת אימות אסימון to begin, update או סיום, כדי להוכיח אימות משתמש עבור פעולה של מפתח שדורשת (למפתח יש תג::USER_SECURE_ID).

הערך הוא blob שמכיל מבנה 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;

אפשר לציין את התג הזה במהלך יצירת מפתח כדי שהמפתח ידרוש שאפשר להשתמש בהן בתנאי שצוין. צריך להחזיר אותו עם המפתח מאפיינים מתוך generateKey וגם getKeyCharacteristics. אם המתקשר מציין Tag::BLOB_USAGE_REQUIREMENTS עם ערך KeyBlobUsageRequirements::STANDALONE, ה-Trustlet מחזיר blob של מפתח שאפשר להשתמש בהם בלי תמיכה במערכת הקבצים. הפעולה הזו קריטית למכשירים עם דיסקים מוצפנים, שבהם מערכת הקבצים לא תהיה זמינה אחרי שנעשה שימוש במפתח ראשי כדי לפענח את הדיסק.

תג::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 של מתחילים. אם המצב שצוין לא נמצא במצבים שמשויכים למפתח, הפעולה נכשלה עם ErrorCode::INCOMPATIBLE_BLOCK_MODE.

תג::BOOT_PATCHLEVEL

גרסה: 4

תג::BOOT_PATCHLEVEL מציין את רמת תיקון האבטחה של תמונת האתחול (kernel) שבאמצעותם ניתן להשתמש במפתח. התג הזה אף פעם לא נשלח לת"א של מחזיקי מפתחות, אבל נוסף לרשימת ההרשאות שנאכפות באמצעות חומרה. בכל ניסיון משתמשים במפתח עם ערך 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

ניתן לחזרה? לא

מציינת שרק תוכנת האתחול יכולה להשתמש במפתח.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-FALSE (אם התג לא קיים).

כל ניסיון להשתמש במפתח עם Tag::BOOTLOADER_ONLY מערכת Android נכשלה עם ErrorCode::INVALID_KEY_BLOB.

תג::CALLER_NONCE

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציינת שהקוראים יכולים לספק קוד צופן חד-פעמי (nonce) לפעולות שלא נדרשות.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-FALSE (אם התג לא קיים).

התג הזה משמש רק למפתחות AES, והוא רלוונטי רק ל-CBC, ל-CTR ול-GCM מצבי חסימה. אם התג לא קיים, ההטמעה צריכה לדחות כל פעולה שמספקת Tag::NONCE ל- מתחילים עם ErrorCode::CALLER_NONCE_PROHIBITED.

תג::CREATION_DATETIME

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציין את התאריך והשעה שבהם המפתח נוצר, באלפיות השנייה מאז 1 בינואר 1970. התג הזה הוא אופציונלי ואינפורמטיבי בלבד.

תג::DIGEST

גרסה: 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 של מתחילים. אם התקציר שצוין לא נמצא בתקצירים שמשויכים למפתח, הפעולה נכשלה עם ErrorCode::INCOMPATIBLE_DIGEST.

תג::EC_CURVE

גרסה: 2, 3, 4

ניתן לחזרה? לא

ב-Keymaster 1, המערכת ביצעה ניחוש של העקומה שמשמשת את מפתחות ההמרות המשופרות מהמפתח שצוין גודל. כדי לשפר את הגמישות בהמשך, 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

ניתן לחזרה? לא

התג הזה מצוין בזמן יצירת המפתח כדי לציין אימות (attestation) האישור למפתח שנוצר צריך להכיל היקף ברמת האפליקציה מזהה ייחודי למכשיר לזמן מוגבל, כפי שצוין תג::UNIQUE_ID.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-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

ניתן לחזרה? לא

מציינת את משך הזמן המינימלי המותר בין פרק הזמן המותר באמצעות מפתח. אפשר להשתמש באפשרות הזו כדי להגביל את קצב השימוש במפתחות בהקשרים שונים מקרים שבהם שימוש בלתי מוגבל עלול לאפשר התקפות מסוג bruteForce.

הערך הזה הוא מספר שלם בן 32 ביט שמייצג את השניות המותרות ב-AI.

כאשר משתמשים במפתח עם התג הזה בפעולה, יש להפעיל טיימר במהלך סיום ביטול שיחה. כלשהו להתחיל, שהתקבלו לפני הטיימר מציין שמרווח הזמן שצוין הזמן שחלף: 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.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-FALSE (אם התג לא קיים).

תג::NONCE

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מספק או מחזיר צופן חד-פעמי (nonce) או Initialization Vector (IV) בשביל AES GCM, CBC, או הצפנה או פענוח של שיעור קליקים. תג זה מסופק ל מתחילים במהלך פעולות הצפנה ופענוח. הוא מסופק רק ל מתחילים אם במפתח יש Tag::CALLER_NONCE. אם לא תספקו אותו, צופן חד-פעמי (nonce או IV) מתאים ייווצר באופן אקראי מאסטר מפתח ומוחזר מההתחלה.

הערך הוא blob, מערך בייטים באורך שרירותי. אורכים מותרים תלויים במצב: צפנים חד-פעמיים של GCM הם באורך של 12 בייטים. CBC ו-CTR IV הם 16 בייטים באורך.

תג::BRAND

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציינת איפה המפתח נוצר, אם הוא ידוע. לא ניתן לציין את התג הזה במהלך היצירה או הייבוא של מפתחות, ויש להוסיף אותם למאפיינים המרכזיים על ידי ה-Trustlet.

Keymaster 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, ומיובאים אל 'מנהל מפתחות'. אם הוא מופיע ברשימה של אכיפת החומרה, הוא קשור באופן קבוע לחומרה, למרות שייתכן שיהיו עותקים מחוץ לחומרה מאובטחת. אם בתוך של תוכנת התוכנה, המפתח יובא אל SoftKeymaster קשור לחומרה.

האפליקציה UNKNOWN אמורה להופיע רק ברשימה שנאכפת על ידי החומרה. הוא מציין שהמפתח קשורה לחומרה, אבל לא ידוע אם המפתח נוצר במקור חומרה מאובטחת או שיובאה. זה מתרחש רק כאשר חומרת Keymaster0 שמשמש לאמולציה של שירותי keymaster1.

תג::POLICYATION_EXPIRE_DATETIME

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציינת את התאריך והשעה שבהם יפוג תוקף המפתח לחתימה למטרות הצפנה. לאחר פרק הזמן הזה, כל ניסיון להשתמש במפתח עם מטרת המפתח::SIGN או מטרה ראשית::ENCRYPT סופקה כדי להתחיל נכשל עם ErrorCode::KEY_EXPIRED.

הערך הזה הוא מספר שלם בן 64 ביט, שמייצג אלפיות שנייה 1 בינואר 1970.

תג::OS_PATCHLEVEL

גרסה: 2, 3, 4

ניתן לחזרה? לא

התג הזה אף פעם לא נשלח לת"א של 'מפתח', אבל הוא מתווסף רשימת הרשאות שנאכפות באמצעות חומרה על ידי TA.

ערך התג הוא מספר שלם בצורת YYYYMM, כאשר YYYY הוא השנה (4 הספרות) של העדכון האחרון ו-MM הוא שתי הספרות של החודש לדוגמה, למפתח שנוצר במכשיר Android שעודכן לאחרונה ב- הערך של דצמבר 2015 יהיה 201512.

מפתחות עם רמת תיקון שונה מרמת התיקון הנוכחית לא שימושי. ניסיון להשתמש בגורמים עיקריים כאלה begin, getKeyCharacteristics ( או exportKey כדי להחזיר את ErrorCode::KEY_REQUIRES_UPGRADE. צפייה קישור גרסאות עבור אפשרויות נוספות פרטים.

תג::OS_VERSION

גרסה: 2, 3, 4

ניתן לחזרה? לא

התג הזה אף פעם לא נשלח לת"א של 'מפתח', אבל הוא מתווסף רשימת הרשאות שנאכפות באמצעות חומרה על ידי TA.

ערך התג הוא מספר שלם בצורת MMmmss, כאשר MM הוא מספר שלם מספר הגרסה, mm הוא מספר הגרסה המשנית ו-ss הוא הגרסה המשנית מספר. לדוגמה, למפתח שנוצר בגרסה 4.0.3 של Android, הערך הוא 040003.

תג::PADDING

גרסה: 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 ריווח ומרווח פנימי אקראי של RSA PKCS#1 v1.5, בהתאמה. PaddingMode::RSA_PSS והקבוצה PaddingMode::RSA_PKCS1_1_5_SIGN משמשים רק למודעות RSA חתימה/אימות וציון RSA PKCS#1v2 PSS ריווח ומרווח פנימי דטרמיניסטי של RSA PKCS#1 v1.5, בהתאמה.

ניתן להשתמש ב-PaddingMode::NONE עם RSA או מפתחות AES. למפתחות AES, אם נעשה שימוש ב-PaddingMode::NONE באמצעות מצב בלוקים של ECB או CBC והנתונים שיוצפנו או יפוענחו אינה כפולה של גודל בלוק AES באורך, הקריאה לסיום נכשל עם ErrorCode::INVALID_INPUT_LENGTH.

ניתן להשתמש ב-PaddingMode::PKCS7 רק עם מפתחות AES, וגם רק במצבי ECB ו-CBC.

התג הזה ניתן לחזרה. צריך לציין מצב מרווח פנימי בקריאה ל- begin. אם המצב שצוין לא מאושר עבור המפתח, הפעולה תיכשל עם ErrorCode::INCOMPATIBLE_BLOCK_MODE.

תג::PURPOSE

גרסה: 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;

אפשר לחזור על התג הזה עשויים ליצור מפתחות עם כמה ערכים, למרות שלפעולה יש מטרה אחת ויחידה. כאשר הפונקציה begin נקראת כדי להתחיל פעולה, מטרת הפעולה מצוינת. אם המטרה שצוינה לפעולה לא אושרה על ידי המפתח, הפעולה נכשלת עם ErrorCode::INCOMPATIBLE_PURPOSE.

תג::RESET_ שמשתמשים_ID_ROTATION

גרסה: 3, 4

ניתן לחזרה? לא

המדיניות הזו מציינת אם המכשיר אופס להגדרות המקוריות מאז הרוטציה האחרונה של המזהים הייחודיים. משמשת לאימות (attestation) של מפתח.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-FALSE (אם התג לא קיים).

תג::ROLLBACK_RESISTANT

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציין שהמפתח עמיד בפני החזרה למצב קודם, כלומר כשמוחקים אותו באמצעות deleteKey או deleteAllKeys, מובטח שהמפתח יימחק באופן סופי ולא יהיה ניתן להשתמש בו. ייתכן שניתן למחוק מפתחות ללא התג הזה ואז לשחזר אותם מהגיבוי.

תג זה הוא בוליאני, לכן הערכים האפשריים הם True (אם התג קיים) ו-FALSE (אם התג לא קיים).

תג::ROOT_OF_TRUST

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציין את Root of Trust, המפתח שמשמש את ההפעלה המאומתת לבדוק אם מערכת ההפעלה הופעלה (אם בכלל). התג הזה אף פעם לא מסופק ל-Keymaster או מוחזר ממנה באמצעות מאפייני המפתח.

תג::RSA_PUBLIC_EXPONENT

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציינת את הערך של המעריך הציבורי בזוג מפתחות RSA. התג הזה רלוונטי רק למפתחות RSA, ונדרש לכל מפתחות ה-RSA.

הערך הזה הוא מספר שלם לא חתום של 64 ביט שעומד בדרישות של מעריך ציבורי של RSA. הערך הזה חייב להיות מספר ראשוני. ה-Trustlets תומכים ב 2^16+1 ועשוי לתמוך בערכים סבירים אחרים, במיוחד בערך 3. אם לא צוין מעריך או אם המעריך שצוין לא נתמך, יצירת מפתחות נכשלה עם ErrorCode::INVALID_ARGUMENT.

תג::UNIQUE_ID

גרסה: 3, 4

ניתן לחזרה? לא

משמש למתן מזהה ייחודי באימות.

הערך הוא blob, מערך בייטים באורך שרירותי.

תג::USAGE_EXPIRE_DATETIME

גרסה: 1, 2, 3, 4

ניתן לחזרה? לא

מציינת את התאריך והשעה שבהם התוקף של המפתח יפוג לצורך אימות, למטרות פענוח. לאחר פרק הזמן הזה, כל ניסיון להשתמש במפתח עם מטרת המפתח::אימות או מטרת המפתח::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

ניתן לחזרה? כן

מציינת שאפשר להשתמש במפתח רק אצל משתמש מאובטח מסוים במצב האימות של ה-AI. התג הזה בלעדי עם תג::NO_AUTH_REQUIRED.

הערך הוא מספר שלם בגרסת 64 ביט, שמציין את המצב של מדיניות האימות. שהערך שלו צריך להימצא באסימון אימות (מסופק ל מתחיל ב- תג::AUTH_TOKEN) כדי לאשר את השימוש במפתח. כלשהו קריאה להתחלה באמצעות מפתח עם התג הזה שלא מספק באסימון אימות, או שהיא מספקת אסימון אימות ללא ערך מצב מדיניות תואם, נכשל.

התג הזה ניתן לחזרה. אם אחד מהערכים שצוינו תואם למדיניות כלשהי באסימון האימות, המפתח מורשה להשתמש בו. אחרת, הפעולה תיכשל עם ErrorCode::KEY_USER_NOT_AUTHENTICATED

תג::VENDOR_PATCHLEVEL

גרסה: 4

התג הזה מציין את רמת התיקון באבטחת תמונת הספק שבה המפתח . התג הזה אף פעם לא נשלח לת"א של 'מפתח', אבל הוא מתווסף רשימת הרשאות שנאכפות באמצעות חומרה על ידי 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 עד אחרי האתחול הבא.

נדרשת אכיפה של החומרה.