תגי אישור Keymaster

דף זה מספק פרטים כדי לסייע למיישמים של Keymaster HALs. זה מכסה כל תג ב-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 .

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::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 באנדרואיד. שדה זה מוגדר רק כאשר מבקשים אישור של מזהי המכשיר.

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_DEVICE

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

מספק את שם המכשיר של המכשיר, כפי שהוחזר על ידי Build.DEVICE באנדרואיד. שדה זה מוגדר רק כאשר מבקשים אישור של מזהי המכשיר.

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_IMEI

גרסה : 3, 4

ניתן לחזור על עצמו ? כן

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_MANUFACTURER

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_MEID

גרסה : 3, 4

ניתן לחזור על עצמו ? כן

מספק את ה-MEIDs עבור כל מכשירי הרדיו במכשיר. שדה זה יוגדר רק בעת בקשת אישור של מזהי המכשיר.

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_MODEL

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_PRODUCT

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::ATTESTATION_ID_SERIAL

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

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

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

הערך הוא בלוק, מערך באורך שרירותי של בתים.

תג::AUTH_TIMEOUT

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

ניתן לחזור על עצמו ? לא

מציין את הזמן בשניות שעבורו המפתח מורשה לשימוש, לאחר האימות. אם תג::USER_SECURE_ID קיים ותג זה אינו, אז המפתח זקוק לאימות עבור כל שימוש (ראה התחלה לפרטים של זרימת האימות לכל פעולה).

הערך הוא מספר שלם של 32 סיביות המציין את הזמן בשניות לאחר אימות מוצלח של המשתמש שצוין על ידי Tag::USER_SECURE_ID עם שיטת האימות שצוינה על ידי Tag::USER_AUTH_TYPE שבו ניתן להשתמש במפתח.

תג::AUTH_TOKEN

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

ניתן לחזור על עצמו ? לא

מספק אסימון אימות להתחלה , עדכון או סיום , כדי להוכיח אימות משתמש עבור פעולת מפתח הדורשת זאת (למפתח יש Tag::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;

ניתן לציין תג זה במהלך יצירת המפתח כדי לדרוש שהמפתח יהיה שמיש במצב שצוין. יש להחזיר אותו עם מאפייני המפתח מ- generateKey ו- 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 של begin . אם המצב שצוין אינו במצבים המשויכים למפתח, הפעולה נכשלת עם 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 היא היום הדו ספרתי של העדכון האחרון. לדוגמה, עבור מפתח שנוצר במכשיר אנדרואיד שעודכן לאחרונה ב-5 ביוני 2018, הערך יהיה 20180605. אם היום אינו ידוע, ניתן להחליף 00.

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

חייב להיות נאכף חומרה.

תג::BOOTLOADER_ONLY

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

ניתן לחזור על עצמו ? לא

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

תג זה הוא בוליאני, כך שהערכים האפשריים הם true (אם התג קיים) ו-false (אם התג אינו קיים).

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

תג::CALLER_NONCE

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

ניתן לחזור על עצמו ? לא

מציין שהמתקשר יכול לספק התראה לפעולות שאינן דורשות.

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

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

ניתן לחזור על עצמו ? לא

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

הערך הוא מספר שלם של 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

ניתן לחזור על עצמו ? לא

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

תג זה הוא בוליאני, כך שהערכים האפשריים הם true (אם התג קיים) ו-false (אם התג אינו קיים).

תגית::NONCE

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

ניתן לחזור על עצמו ? לא

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

הערך הוא כתם, מערך באורך שרירותי של בתים. האורכים המותרים תלויים במצב: ה-GCM nonces הם באורך 12 בתים; אורך CBC ו-CTR IV הוא 16 בתים.

תגית::ORIGIN

גרסה : 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 ויובא ל-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 . ראה כריכת גרסה לפרטים נוספים.

תג::OS_VERSION

גרסה : 2, 3, 4

ניתן לחזור על עצמו ? לא

תג זה לעולם לא נשלח ל-keymaster TA, אלא הוא מתווסף לרשימת ההרשאות שנאכפת על ידי החומרה על ידי ה-TA.

הערך של התג הוא מספר שלם מהצורה MMmmss, כאשר MM הוא מספר הגרסה הראשית, mm הוא מספר הגרסה המשנית ו-ss הוא מספר הגרסה המשנית. לדוגמה, עבור מפתח שנוצר בגרסה 4.0.3 של אנדרואיד, הערך יהיה 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.

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

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

תג::RESET_SINCE_ID_ROTATION

גרסה : 3, 4

ניתן לחזור על עצמו ? לא

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

תג זה הוא בוליאני, כך שהערכים האפשריים הם true (אם התג קיים) ו-false (אם התג אינו קיים).

תג::ROLLBACK_RESISTANT

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

ניתן לחזור על עצמו ? לא

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

תג זה הוא בוליאני, כך שהערכים האפשריים הם true (אם התג קיים) ו-false (אם התג אינו קיים).

תג::ROOT_OF_TRUST

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

ניתן לחזור על עצמו ? לא

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

ניתן לחזור על עצמו ? לא

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

הערך הוא כתם, מערך באורך שרירותי של בתים.

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

ניתן לחזור על עצמו ? לא

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

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

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

תג::VENDOR_PATCHLEVEL

גרסה : 4

תג זה מציין את רמת תיקון האבטחה של תמונת הספק שאיתה ניתן להשתמש במפתח. תג זה לעולם לא נשלח ל-keymaster TA, אלא הוא מתווסף לרשימת ההרשאות שנאכפת על ידי החומרה על ידי ה-TA. כל ניסיון להשתמש במפתח עם ערך Tag::VENDOR_PATCHLEVEL שונה מרמת התיקון הנוכחית של המערכת חייב לגרום begin() , getKeyCharacteristics() או exportKey() להחזיר ErrorCode::KEY_REQUIRES_UPGRADE . ראה upgradeKey() לפרטים.

הערך של התג הוא מספר שלם של הצורה YYYYMMDD, כאשר YYYY היא השנה בת ארבע הספרות של העדכון האחרון, MM היא החודש הדו ספרתי ו-DD היא היום הדו ספרתי של העדכון האחרון. לדוגמה, עבור מפתח שנוצר במכשיר אנדרואיד שעודכן לאחרונה ב-5 ביוני 2018, הערך יהיה 20180605.

ה-IKeymasterDevice HAL חייב לקרוא את רמת התיקון הנוכחית של הספק ממאפיין המערכת ro.vendor.build.security_patch ולמסור אותו לסביבה המאובטחת כאשר ה-HAL נטען לראשונה (המנגנון מוגדר ביישום). אסור לסביבה המאובטחת לקבל רמת תיקון אחרת עד לאחר האתחול הבא.

חייב להיות נאכף חומרה.