בדף הזה מופיעים פרטים שיעזרו לנו להטמיע מערכות 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 3enum class Algorithm : uint32_t { RSA = 1, EC = 3, AES = 32, HMAC = 128, };
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 3enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };
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 3enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };
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 3enum 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, };
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 3enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };
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 בייטים באורך.
תג::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_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 3enum 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, };
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 3enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };
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 3enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };
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 עד אחרי האתחול הבא.
נדרשת אכיפה של החומרה.