תגי הרשאה של 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.

Tag::ACTIVE_DATETIME

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

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

מציין את התאריך והשעה שבהם המפתח יהפוך לפעיל. לפני כן כל ניסיון להשתמש במפתח ייכשל ErrorCode::KEY_NOT_YET_VALID

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

Tag::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

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

שמור לשימוש בעתיד.

Tag::ALLOW_WHILE_ON_BODY

גרסה: 2, 3, 4

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

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

Tag::ALL_USERS

גרסה: 3, 4

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

שמור לשימוש בעתיד.

תג::APPLICATION_DATA

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

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

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

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

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

Tag::APPLICATION_ID

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

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

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

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

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

Tag::ASSOCIATED_DATA

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

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

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

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

תג::ATTEstation_APPLICATION_ID

גרסה: 3, 4

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

משמש לזיהוי קבוצת האפליקציות האפשריות, שאחת מהן יזמה אימות מפתח.

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

Tag::ATTESTATION_CHALLENGE

גרסה: 3, 4

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

משמש לספק אתגר באימות.

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

תג::ATTEstation_ID_BRAND

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_DEVICE

גרסה: 3, 4

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

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

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

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

תג::ATTESTATION_ID_IMEI

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_MANUFACTURER

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_MEID

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_MODEL

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_PRODUCT

גרסה: 3, 4

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

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

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

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

Tag::ATTESTATION_ID_SERIAL

גרסה: 3, 4

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

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

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

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

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

תג::BOOT_PATCHLEVEL

גרסה: 4

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

Tag::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. התג הזה הוא אופציונלי ומכיל מידע בלבד.

Tag::DIGEST

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

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

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

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

Tag::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 שמשויכים למפתח.

Tag::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.

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

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

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

הערך הוא blob, מערך בייטים באורך שרירותי. האורך המותרת תלוי במצב: מפתחות GCM חד-פעמיים באורך 12 בייטים, ומפתחות IV של CBC ו-CTR באורך 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 ויובא אליו. אם הוא נמצא ברשימה שנאכף באמצעות חומרה, הוא קשור באופן קבוע לחומרה, למרות שייתכן שקיימים עותקים מחוץ לחומרה מאובטחת. אם המפתח נמצא ברשימה 'אכיפה באמצעות תוכנה', הוא יובא ל-SoftKeymaster ולא קשור לחומרה.

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

תג::POLICYATION_EXPIRE_DATETIME

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

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

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

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

Tag::OS_PATCHLEVEL

גרסה: 2, 3, 4

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

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

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

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

תג::OS_VERSION

גרסה: 2, 3, 4

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

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

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

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

Tag::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.

Tag::RESET_SINCE_ID_ROTATION

גרסה: 3, 4

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

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

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

תג::ROLLBACK_RESISTANT

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

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

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

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

Tag::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.

Tag::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;

Tag::USER_SECURE_ID

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

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

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

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

חובה לאכוף את ההצפנה באמצעות חומרה.