פונקציות של Keymaster

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

הערה: כדי לתמוך במעבר של Keymaster 3 מה-HAL מסוג מבנה C הישן לממשק HAL מסוג C++ שנוצר מהגדרה בשפת ההגדרה החדשה של ממשק החומרה (HIDL), שמות הפונקציות השתנו ב-Android 8.0. כדי לתמוך בכך, הפונקציות הן עכשיו באותיות רישיות עם אות גדולה בתחילת המילה. לדוגמה, get_key_characteristics הוא עכשיו getKeyCharacteristics.

הנחיות כלליות להטמעה

ההנחיות הבאות חלות על כל הפונקציות ב-API.

פרמטרים של מצביע קלט

גרסה: 1, 2

פרמטרים של מצביעה להזנת נתונים שלא משמשים לשיחה מסוימת יכולים להיות NULL. מבצע הקריאה החוזרת לא חייב לספק placeholder. לדוגמה, יכול להיות שבסוגים ובמצבים מסוימים של מפתחות לא נעשה שימוש בערכים מהארגומנט inParams ל-begin, ולכן מבצע הקריאה החוזרת עשוי להגדיר את inParams לערך NULL או לספק קבוצת פרמטרים ריקה. מבצעי הקריאה יכולים גם לספק פרמטרים שלא בשימוש, ושיטות של Keymaster לא אמורות להוציא שגיאות.

אם פרמטר קלט נדרש הוא NULL, שיטות Keymaster צריכות להחזיר את הערך ErrorCode::UNEXPECTED_NULL_POINTER.

החל מ-Keymaster 3, אין פרמטרים של מצביע. כל הפרמטרים מועברים לפי ערך או לפי הפניות const.

פרמטרים של מצביע פלט

גרסה: 1, 2

בדומה לפרמטרים של מצביע קלט, פרמטרים של מצביע פלט שלא בשימוש יכולים להיות NULL. אם שיטת צריכה להחזיר נתונים בפרמטר פלט שנמצא שהוא NULL, היא צריכה להחזיר את הערך ErrorCode::OUTPUT_PARAMETER_NULL.

החל מ-Keymaster 3, אין פרמטרים של מצביע. כל הפרמטרים מועברים לפי ערך או לפי הפניות const.

שימוש לרעה ב-API

גרסה: 1, 2, 3

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

האפליקציות, המסגרת ואחסון המפתחות של Android אחראים לוודא שהקריאות למודולים של Keymaster הגיוניות ומועילות.

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

פונקציות

getHardwareFeatures

גרסה: 3

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

• הערך של isSecure הוא true אם המפתחות מאוחסנים בחומרה מאובטחת (TEE וכו') ואף פעם לא יוצאים ממנה.
• הערך של supportsEllipticCurve הוא true אם החומרה תומכת בהצפנה של עקומה אליפטית עם עקומות NIST‏ (P-224,‏ P-256,‏ P-384 ו-P-521).
• הערך של supportsSymmetricCryptography הוא true אם החומרה תומכת בקריפטוגרפיה סימטרית, כולל AES ו-HMAC.
• הערך של supportsAttestation הוא true אם החומרה תומכת ביצירת אישורי אימות של מפתחות ציבוריים של Keymaster, חתומים על ידי מפתח שהוזן בסביבה מאובטחת.

קודי השגיאה היחידים שהשיטה הזו יכולה להחזיר הם ErrorCode:OK,‏ ErrorCode::KEYMASTER_NOT_CONFIGURED או אחד מקודי השגיאה שמציינים כי לא ניתן לתקשר עם החומרה המאובטחת.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

הגדרה

גרסה: 2

הפונקציה הזו הוצגה ב-Keymaster 2 והוצאה משימוש ב-Keymaster 3, כי המידע הזה זמין בקובצי מאפייני המערכת, והטמעות של יצרנים קוראות את הקבצים האלה במהלך ההפעלה.

הגדרת Keymaster. המערכת קוראת לשיטה הזו פעם אחת אחרי פתיחת המכשיר, לפני שמשתמשים בו. הוא משמש כדי לספק את הערכים KM_TAG_OS_VERSION ו-KM_TAG_OS_PATCHLEVEL ל-Keymaster. עד שמפעילים את השיטה הזו, כל השיטות האחרות מחזירות את הערך KM_ERROR_KEYMASTER_NOT_CONFIGURED. הערכים שסופקו בשיטה הזו יתקבלו על ידי keymaster רק פעם אחת בכל הפעלה. קריאות חוזרות מחזירות את הערך KM_ERROR_OK, אבל לא מבצעות שום פעולה.

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

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור add_rng_entropy והשם שלה השתנה ב-Keymaster 3.

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

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

הטמעות של Keymaster שמנסות להעריך את האנטרופיה במאגר הפנימי שלהן מניחות שהנתונים שסופקו על ידי addRngEntropy לא מכילים אנטרופיה. הטמעות של Keymaster יכולות להחזיר את הערך ErrorCode::INVALID_INPUT_LENGTH אם הן מקבלות יותר מ-2KiB של נתונים בקריאה אחת.

generateKey

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור generate_key והשם שלה השתנה ב-Keymaster 3.

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

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

מפתחות RSA

הפרמטרים הבאים נדרשים ליצירת מפתח RSA.

• Tag::KEY_SIZE מציין את הגודל של המכפיל הציבורי, ביטים. אם השדה הזה יושמט, השיטה תחזיר את הערך ErrorCode::UNSUPPORTED_KEY_SIZE. הערכים הנתמכים הם 1024, ‏ 2048, ‏ 3072 ו-4096. הערכים המומלצים הם כל גודלי המפתחות שהם מכפלות של 8.
• Tag::RSA_PUBLIC_EXPONENT מציין את הערך של החזקה הציבורית של RSA. אם השדה הזה יושמט, השיטה תחזיר את הערך ErrorCode::INVALID_ARGUMENT. הערכים הנתמכים הם 3 ו-65537. הערכים המומלצים הם כל הערכים הראשוניים עד 2^64.

הפרמטרים הבאים לא נחוצים ליצירת מפתח RSA, אבל יצירת מפתח RSA בלי הפרמטרים האלה יוצרת מפתח שלא ניתן להשתמש בו. עם זאת, הפונקציה generateKey לא מחזירה שגיאה אם משמיטים את הפרמטרים האלה.

• Tag::PURPOSE מציין את המטרות המותרות. צריך לתמוך בכל המטרות למפתחות RSA, בכל שילוב.
• Tag::DIGEST מציין את אלגוריתמי הסיכום (digest) שאפשר להשתמש בהם עם המפתח החדש. הטמעות שלא תומכות בכל אלגוריתמי הדגימה צריכות לקבל בקשות ליצירת מפתחות שכוללות דגימות שלא נתמכות. יש להוסיף את הדיגסטים שלא נתמכים לרשימה 'enforced-by-software' במאפייני המפתח שהוחזרו. הסיבה לכך היא שאפשר להשתמש במפתח עם תקצירי ה-digest האחרים האלה, אבל יצירת התקצירים מתבצעת בתוכנה. לאחר מכן, החומרה נקראת לבצע את הפעולה עם Digest::NONE.
• Tag::PADDING מציין את סוגי המילוי שאפשר להשתמש בהם עם המפתח החדש. אם מציינים אלגוריתמים של סיכום (digest) שלא נתמכים, יש להוסיף את PaddingMode::RSA_PSS ו-PaddingMode::RSA_OAEP לרשימה של מאפייני המפתחות שנאכפת באמצעות תוכנה בהטמעות שלא תומכות בכל האלגוריתמים של סיכום (digest).

מפתחות ECDSA

כדי ליצור מפתח ECDSA, נדרש רק Tag::KEY_SIZE. הוא משמש לבחירת קבוצת EC. הערכים הנתמכים הם 224, ‏ 256, ‏ 384 ו-521, שמציינים את העקומות NIST p-224, ‏ p-256, ‏ p-384 ו-p521, בהתאמה.

גם התג Tag::DIGEST נדרש למפתח ECDSA שימושי, אבל הוא לא נדרש ליצירה.

מפתחות AES

כדי ליצור מפתח AES, נדרש רק Tag::KEY_SIZE. אם השדה הזה יושמט, השיטה תחזיר את הערך ErrorCode::UNSUPPORTED_KEY_SIZE. הערכים הנתמכים הם 128 ו-256, עם תמיכה אופציונלית במפתחות AES של 192 ביט.

הפרמטרים הבאים רלוונטיים במיוחד למפתחות AES, אבל הם לא חיוניים ליצירת מפתח:

• Tag::BLOCK_MODE מציין את מצבי החסימה שבהם אפשר להשתמש במפתח החדש.
• Tag::PADDING מציין את שיטות המילוי שניתן להשתמש בהן. האפשרות הזו רלוונטית רק למצבים ECB ו-CBC.

אם צוין מצב חסימה של GCM, צריך לספק את הערך Tag::MIN_MAC_LENGTH. אם השדה הזה יושמט, השיטה תחזיר את הערך ErrorCode::MISSING_MIN_MAC_LENGTH. הערך של התג הוא כפולה של 8 ובין 96 ל-128.

מפתחות HMAC

הפרמטרים הבאים נדרשים ליצירת מפתח HMAC:

• Tag::KEY_SIZE מציין את גודל המפתח בביטים. המערכת לא תומכת בערכים קטנים מ-64 ובערכים שאינם מכפילים של 8. יש תמיכה בכל המכפילים של 8, מ-64 עד 512. יכול להיות שהמערכת תתמוך בערכים גדולים יותר.
• Tag::MIN_MAC_LENGTH מציין את האורך המינימלי של MACs שאפשר ליצור או לאמת באמצעות המפתח הזה. הערך חייב להיות כפולה של 8 ולפחות 64.
• Tag::DIGEST מציין את אלגוריתם התקציר (digest) של המפתח. צריך לציין רק סיכום אחד, אחרת תוחזר הערך ErrorCode::UNSUPPORTED_DIGEST. אם ה-digest לא נתמך על ידי ה-trustlet, מחזירים את הערך ErrorCode::UNSUPPORTED_DIGEST.

מאפיינים עיקריים

אם הארגומנט characteristics הוא לא NULL, הפונקציה generateKey מחזירה את המאפיינים של המפתח החדש שנוצר, שמחולקים כראוי לרשימות שמאוכפות בחומרה וברמת התוכנה. בתיאור של getKeyCharacteristics מוסבר אילו מאפיינים נכללים בכל רשימה. המאפיינים המוחזרים כוללים את כל הפרמטרים שצוינו ליצירת המפתח, מלבד Tag::APPLICATION_ID ו-Tag::APPLICATION_DATA. אם התגים האלה נכללו בפרמטרים של המפתח, הם יוסרו מהמאפיינים המוחזרים כדי שלא יהיה אפשר למצוא את הערכים שלהם על ידי בדיקת blob המפתח המוחזר. עם זאת, הם מקושרים באופן קריפטוגרפי ל-blob של המפתח, כך שאם לא יסופקו הערכים הנכונים כשמשתמשים במפתח, השימוש נכשל. באופן דומה, התג Tag::ROOT_OF_TRUST קשור באופן קריפטוגרפי למפתח, אבל אי אפשר לציין אותו בזמן יצירת המפתח או הייבוא שלו, והוא אף פעם לא מוחזר.

בנוסף לתגים שסופקו, ל-trustlet מתווסף גם Tag::ORIGIN עם הערך KeyOrigin::GENERATED, ואם המפתח עמיד בפני ביטול קוד, גם Tag::ROLLBACK_RESISTANT.

עמידות לרולבק

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

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

getKeyCharacteristics

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור get_key_characteristics ושמו שונה ב-Keymaster 3.

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

אם הערך Tag::APPLICATION_ID סופק במהלך יצירת המפתח או הייבוא שלו, אותו ערך מסופק לשיטה הזו בארגומנט clientId. אחרת, השיטה מחזירה את הערך ErrorCode::INVALID_KEY_BLOB. באופן דומה, אם הערך Tag::APPLICATION_DATA סופק במהלך היצירה או הייבוא, אותו ערך מסופק לשיטה הזו בארגומנט appData.

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

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

• Tag::ALGORITHM,‏ Tag::KEY_SIZE ו-Tag::RSA_PUBLIC_EXPONENT הם מאפיינים מובנים של המפתח. כל מפתח שמאובטח באמצעות חומרה נכלל ברשימה שמאובטחת בחומרה.
• ערכים של Tag::DIGEST שנתמכים בחומרה המאובטחת מופיעים ברשימה של הערכים שנתמכים בחומרה. תקצירי חדשות שלא נתמכים מופיעים ברשימה של התקצירים הנתמכים בתוכנה.
• בדרך כלל, הערכים של Tag::PADDING מופיעים ברשימה של התמיכה בחומרה, אלא אם יש אפשרות שצריך לבצע אופן מילוי ספציפי באמצעות תוכנה. במקרה כזה, הם מופיעים ברשימה שנאכפת באמצעות תוכנה. האפשרות הזו מתרחשת במפתחות RSA שמאפשרים תוספת נתונים (padding) מסוג PSS או OAEP עם אלגוריתמי סיכום (digest) שלא נתמכים בחומרה המאובטחת.
• Tag::USER_SECURE_ID ו-Tag::USER_AUTH_TYPE מופעלים באכיפה בחומרה רק אם אימות המשתמש מופעל באכיפה בחומרה. כדי לעשות זאת, צריך לוודא שה-trustlet של Keymaster וה-trustlet הרלוונטי של האימות מאובטחים ושהם משתפים מפתח HMAC סודי שמשמש לחתימה על אסימוני אימות ולתיקוף שלהם. לפרטים נוספים, ראו את הדף אימות.
• התגים Tag::ACTIVE_DATETIME,‏ Tag::ORIGINATION_EXPIRE_DATETIME ו-Tag::USAGE_EXPIRE_DATETIME דורשים גישה לשעון קיר תקין שאפשר לאמת. לחומרה המאובטחת ביותר יש גישה רק למידע על זמן שמסופק על ידי מערכת ההפעלה הלא מאובטחת, כלומר התגים מופעלים על ידי תוכנה.
• המאפיין Tag::ORIGIN תמיד מופיע ברשימת החומרה של מפתחות שמקושרים לחומרה. נוכחותו ברשימה הזו היא הדרך שבה שכבות גבוהות יותר קובעות שמפתח מסוים מגובה בחומרה.

importKey

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור import_key והשם שלה השתנה ב-Keymaster 3.

ייבוא חומר מפתח לחומרה של Keymaster. הטיפול בפרמטרים של הגדרת המפתח ובמאפייני הפלט זהה לטיפול ב-generateKey, מלבד במקרים הבאים:

• הפרמטרים Tag::KEY_SIZE ו-Tag::RSA_PUBLIC_EXPONENT (למפתחות RSA בלבד) לא נדרשים בפרמטרים של הקלט. אם לא מציינים את הערכים, ה-trustlet מסיק את הערכים מחומר המפתח שסופק ומוסיף תגים וערכים מתאימים למאפייני המפתח. אם הפרמטרים יסופקו, ה-trustlet יאמת אותם מול חומר המפתח. במקרה של אי-התאמה, ה-method מחזיר את הערך ErrorCode::IMPORT_PARAMETER_MISMATCH.
• הערך המוחזר של Tag::ORIGIN זהה לערך של KeyOrigin::IMPORTED.

exportKey

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור export_key והשם שלה השתנה ב-Keymaster 3.

ייצוא מפתח ציבורי מזוג מפתחות RSA או EC של Keymaster.

אם הערך Tag::APPLICATION_ID סופק במהלך יצירת המפתח או הייבוא שלו, אותו ערך מסופק לשיטה הזו בארגומנט clientId. אחרת, השיטה מחזירה את הערך ErrorCode::INVALID_KEY_BLOB. באופן דומה, אם הערך Tag::APPLICATION_DATA סופק במהלך היצירה או הייבוא, אותו ערך מסופק לשיטה הזו בארגומנט appData.

deleteKey

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור delete_key והשם שלה השתנה ב-Keymaster 3.

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

deleteAllKeys

גרסה: 1, 2, 3

הפונקציה הזו הוצגה ב-Keymaster 1 בתור delete_all_keys והשם שלה השתנה ב-Keymaster 3.

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

destroyAttestationIds

גרסה: 3

השיטה destroyAttestationIds() משמשת להשבתה קבועה של התכונה החדשה (אופציונלית, אבל מומלצת מאוד) של אימות הזהות. אם ל-TEE אין דרך להבטיח שהאימות המזהה יושבת באופן סופי אחרי הקריאה לשיטה הזו, אסור ליישם אימות מזהה בכלל. במקרה כזה, השיטה הזו לא תעשה כלום ותחזיר את הערך ErrorCode::UNIMPLEMENTED. אם יש תמיכה באימות זהות, צריך להטמיע את השיטה הזו ולהשבית באופן סופי את כל הניסיונות העתידיים לאימות זהות. אפשר לקרוא לשיטה כמה פעמים שרוצים. אם אימות הזהות כבר מושבת באופן סופי, השיטה לא מבצעת שום פעולה ומחזירה את הערך ErrorCode::OK.

קודי השגיאה היחידים שהשיטה הזו יכולה להחזיר הם ErrorCode::UNIMPLEMENTED (אם אימות הזהות לא נתמך), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED או אחד מקודי השגיאה שמציינים כשל בתקשורת עם החומרה המאובטחת.

התחלה

גרסה: 1, 2, 3

הפונקציה מתחילה פעולה קריפטוגרפית באמצעות המפתח שצוין, למטרה שצוינה, עם הפרמטרים שצוינו (לפי הצורך), ומחזירה את ה-handle של הפעולה שמשמש עם update ו-finish כדי להשלים את הפעולה. ה-handle של הפעולה משמש גם כאסימון 'אתגר' בפעולות מאומתות, ובפעולות כאלה הוא נכלל בשדה challenge של אסימון האימות.

הטמעה של Keymaster תומכת לפחות ב-16 פעולות בו-זמנית. ב-Keystore נעשה שימוש ב-15 מפתחות לכל היותר, כך שאחד מהם נשאר ל-vold לצורך הצפנת סיסמאות. כשיש ב-Keystore 15 פעולות מתמשכות (begin הופעל, אבל finish או abort לא הופעלו) ומגיעה בקשה להתחיל פעולה 16, המערכת קוראת ל-abort על הפעולה שבה נעשה שימוש לאחרונה כדי להפחית את מספר הפעולות הפעילות ל-14, ואז קוראת ל-begin כדי להתחיל את הפעולה שהתבקשה.

אם ציינתם את Tag::APPLICATION_ID או את Tag::APPLICATION_DATA במהלך יצירת המפתח או הייבוא שלו, הקריאות ל-begin יכללו את התגים האלה עם הערכים שציינתם במקור בארגומנט inParams של השיטה הזו.

אכיפת הרשאות

במהלך השיטה הזו, הרשאות המפתחות הבאות נאכפות על ידי ה-trustlet אם ההטמעה הגדירה אותן בתור מאפיינים 'מופעלים בחומרה', ואם הפעולה היא לא פעולה של מפתח ציבורי. פעולות של מפתחות ציבוריים, כלומר KeyPurpose::ENCRYPT ו-KeyPurpose::VERIFY, עם מפתחות RSA או EC, יכולות להצליח גם אם דרישות ההרשאה לא מתקיימות.

• Tag::PURPOSE: המטרה שצוינה בקריאה ל-begin() חייבת להתאים לאחת מהמטרות שמפורטות בהרשאות המפתח, אלא אם הפעולה המבוקשת היא פעולה במפתח ציבורי. אם המטרה שצוינה לא תואמת והפעולה היא לא פעולה של מפתח ציבורי, begin מחזירה את הערך ErrorCode::UNSUPPORTED_PURPOSE. פעולות של מפתחות ציבוריים הן פעולות של הצפנה אסימטרית או פעולות אימות.
• אפשר לאכוף את התג Tag::ACTIVE_DATETIME רק אם יש מקור זמן מהימן לפי שעון UTC. אם התאריך והשעה הנוכחיים קודמים לערך התג, השיטה מחזירה את הערך ErrorCode::KEY_NOT_YET_VALID.
• אפשר לאכוף את התג Tag::ORIGINATION_EXPIRE_DATETIME רק אם יש מקור זמן מהימן לפי שעון UTC. אם התאריך והשעה הנוכחיים מאוחרים יותר מערך התג והמטרה היא KeyPurpose::ENCRYPT או KeyPurpose::SIGN, השיטה מחזירה את הערך ErrorCode::KEY_EXPIRED.
• אפשר לאכוף את התג Tag::USAGE_EXPIRE_DATETIME רק אם יש מקור זמן מהימן של UTC. אם התאריך והשעה הנוכחיים מאוחרים יותר מערך התג והמטרה היא KeyPurpose::DECRYPT או KeyPurpose::VERIFY, השיטה מחזירה את הערך ErrorCode::KEY_EXPIRED.
• הערך של Tag::MIN_SECONDS_BETWEEN_OPS משווה לטיימרים יחסיים מהימנים שמציינים את השימוש האחרון במפתח. אם זמן השימוש האחרון בתוספת ערך התג נמוך מהשעה הנוכחית, הפונקציה מחזירה את הערך ErrorCode::KEY_RATE_LIMIT_EXCEEDED. בתיאור התג מפורטים פרטים חשובים לגבי ההטמעה.
• הערך של Tag::MAX_USES_PER_BOOT משווה למונה מאובטח שמתעד את השימושים במפתח מאז הפעלת המכשיר. אם מספר השימושים הקודמים חורג מערך התג, השיטה מחזירה את הערך ErrorCode::KEY_MAX_OPS_EXCEEDED.
• השיטה הזו אוכפת את Tag::USER_SECURE_ID רק אם המפתח מכיל גם את Tag::AUTH_TIMEOUT. אם המפתח מכיל את שניהם, ה-method הזה צריך לקבל Tag::AUTH_TOKEN תקין ב-inParams. כדי שטוקן האימות יהיה תקף, כל התנאים הבאים צריכים להתקיים:
  • השדה HMAC עובר אימות בצורה תקינה.
  • לפחות אחד מהערכים של Tag::USER_SECURE_ID מהמפתח תואם לפחות לאחד מהערכים של המזהה המאובטח באסימון.
  • המפתח מכיל את הערך Tag::USER_AUTH_TYPE שתואם לסוג האימות בטוקן.

  אם אף אחד מהתנאים האלה לא מתקיים, השיטה מחזירה את הערך ErrorCode::KEY_USER_NOT_AUTHENTICATED.

• Tag::CALLER_NONCE מאפשר למבצע הקריאה לציין nonce או וקטור אתחול (IV). אם התג הזה לא מופיע במפתח, אבל מבצע הקריאה הפנימית סיפק את הערך Tag::NONCE לשיטה הזו, הערך ErrorCode::CALLER_NONCE_PROHIBITED יוחזר.
• Tag::BOOTLOADER_ONLY מציין שרק אתחול האתחול יכול להשתמש במפתח. אם שולחים קריאה ל-method הזה עם מפתח ל-bootloader בלבד אחרי ש-bootloader מסיים לפעול, הוא מחזיר את הערך ErrorCode::INVALID_KEY_BLOB.

מפתחות RSA

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

פעולות חתימה ואימות של RSA זקוקות ל-digest, וכך גם פעולות הצפנה ופענוח של RSA במצב תוספת נתונים (padding) של OAEP. במקרים כאלה, מבצע הקריאה החוזרת מציין בדיוק סיכום אחד ב-inParams. אם לא צוין או צוין יותר מפעם אחת, השיטה מחזירה את הערך ErrorCode::UNSUPPORTED_DIGEST.

כדי לבצע פעולות במפתח פרטי (KeyPurpose::DECYPT ו-KeyPurpose::SIGN), צריך הרשאה ל-digest ולמילוי, כלומר הרשאות המפתח צריכות להכיל את הערכים שצוינו. אחרת, השיטה מחזירה את הערך ErrorCode::INCOMPATIBLE_DIGEST או ErrorCode::INCOMPATIBLE_PADDING, בהתאם. פעולות עם מפתח ציבורי (KeyPurpose::ENCRYPT ו-KeyPurpose::VERIFY) מותרות עם תוספת או תקציר לא מורשים.

מלבד PaddingMode::NONE, כל שיטות המילוי של מודעות RSA רלוונטיות רק למטרות מסוימות. באופן ספציפי, PaddingMode::RSA_PKCS1_1_5_SIGN ו-PaddingMode::RSA_PSS תומכים רק בחתימה ואימות, ואילו PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ו-PaddingMode::RSA_OAEP תומכים רק בהצפנה ופענוח. אם המצב שצוין לא תומך במטרה שצוינה, השיטה מחזירה את הערך ErrorCode::UNSUPPORTED_PADDING_MODE.

יש כמה אינטראקציות חשובות בין מצבי התמלאוּת לבין סיכומי ה-digest:

• PaddingMode::NONE מציין שבוצעה פעולת RSA 'גולמית'. אם חותמים או מאמתים, הערך Digest::NONE מצוין ל-digest. אין צורך ב-digest להצפנה או לפענוח ללא תוספת שטח.
• כדי להשתמש ב-PaddingMode::RSA_PKCS1_1_5_SIGN padding נדרש digest. הערך של הדיגסט יכול להיות Digest::NONE. במקרה כזה, ההטמעה של Keymaster לא יכולה ליצור מבנה חתימה תקין של PKCS#1 v1.5 כי היא לא יכולה להוסיף את המבנה של DigestInfo. במקום זאת, ההטמעה יוצרת את הערך 0x00 || 0x01 || PS || 0x00 || M, שבו M היא ההודעה שסופקה ו-PS היא מחרוזת המילוי. גודל מפתח ה-RSA צריך להיות גדול מההודעה ב-11 בייטים לפחות, אחרת המטהד מחזיר את הערך ErrorCode::INVALID_INPUT_LENGTH.
• לא נדרשת סיכום (digest) כדי לבצע מילוי (padding) של PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT.
• כדי להוסיף PaddingMode::RSA_PSS למחרוזת, צריך לצרף לה סיכום (digest), שאי אפשר להוסיף ל-Digest::NONE. אם מציינים את Digest::NONE, השיטה מחזירה את הערך ErrorCode::INCOMPATIBLE_DIGEST. בנוסף, הגודל של מפתח ה-RSA צריך להיות גדול לפחות ב-2 + D בייטים מגודל הפלט של הסיכום, כאשר D הוא גודל הסיכום, בבייטים. אחרת, השיטה מחזירה את הערך ErrorCode::INCOMPATIBLE_DIGEST. גודל המלח הוא D.
• כדי להוסיף PaddingMode::RSA_OAEP למחרוזת, צריך לצרף לה סיכום (digest), שאי אפשר להוסיף ל-Digest::NONE. אם מציינים את Digest::NONE, השיטה מחזירה את הערך ErrorCode::INCOMPATIBLE_DIGEST.

מפתחות EC

פעולות של מפתחות EC מציינות בדיוק מצב אחד של מילוי ב-inParams. אם לא מציינים את השדה או מציינים אותו יותר מפעם אחת, השיטה מחזירה את הערך ErrorCode::UNSUPPORTED_PADDING_MODE.

כדי לבצע פעולות במפתח פרטי (KeyPurpose::SIGN), צריך הרשאה ל-digest ולמילוי, כלומר הרשאות המפתח צריכות להכיל את הערכים שצוינו. אם לא, מחזירים את הערך ErrorCode::INCOMPATIBLE_DIGEST. פעולות עם מפתח ציבורי (KeyPurpose::VERIFY) מותרות עם תקציר או תוספת לא מורשים.

מפתחות AES

פעולות של מפתחות AES מציינות בדיוק מצב בלוק אחד ומצב מילוי אחד ב-inParams. אם אחד מהערכים לא צוין או צוין יותר מפעם אחת, מחזירים את הערך ErrorCode::UNSUPPORTED_BLOCK_MODE או את הערך ErrorCode::UNSUPPORTED_PADDING_MODE. המצבים שצוינו צריכים להיות מורשים על ידי המפתח, אחרת הפונקציה מחזירה את הערך ErrorCode::INCOMPATIBLE_BLOCK_MODE או ErrorCode::INCOMPATIBLE_PADDING_MODE.

אם סטטוס החסימה הוא BlockMode::GCM, הערך של inParams הוא Tag::MAC_LENGTH והערך שצוין הוא כפולה של 8 שאינו גדול מ-128 או קטן מהערך של Tag::MIN_MAC_LENGTH בהרשאות המפתח. אם אורך ה-MAC גדול מ-128 או שהוא לא מכפיל של 8, מחזירים את הערך ErrorCode::UNSUPPORTED_MAC_LENGTH. לערכים קצרים יותר מהאורך המינימלי של המפתח, מחזירים את הערך ErrorCode::INVALID_MAC_LENGTH.

אם מצב הבלוק הוא BlockMode::GCM או BlockMode::CTR, צריך לציין את מצב המילוי PaddingMode::NONE. עבור BlockMode::ECB או BlockMode::CBC, המצב יכול להיות PaddingMode::NONE או PaddingMode::PKCS7. אם התנאים האלה לא מתקיימים במצב המילוי, מחזירים את הערך ErrorCode::INCOMPATIBLE_PADDING_MODE.

אם אופן החסימה הוא BlockMode::CBC,‏ BlockMode::CTR או BlockMode::GCM, צריך וקטור אתחול או קוד חד-פעמי. ברוב המקרים, מבצעי הקריאה החוזרת לא צריכים לספק IV או nonce. במקרה כזה, הטמעת Keymaster יוצרת IV או nonce אקראי ומחזירה אותו עם Tag::NONCE ב-outParams. מפתחות IV של CBC ו-CTR הם באורך 16 בייטים. ערכים חד-פעמיים של GCM הם באורך 12 בייטים. אם ההרשאות למפתחות מכילות את הערך Tag::CALLER_NONCE, מבצע הקריאה החוזרת יכול לספק IV או nonce עם Tag::NONCE ב-inParams. אם מציינים מספר חד-פעמי כשTag::CALLER_NONCE לא מורשה, מחזירים את הערך ErrorCode::CALLER_NONCE_PROHIBITED. אם לא מציינים מספר חד-פעמי כשמתבצעת ההרשאה של Tag::CALLER_NONCE, יוצרים IV/מספר חד-פעמי אקראי.

מפתחות HMAC

פעולות של מפתחות HMAC מציינות את Tag::MAC_LENGTH ב-inParams. הערך שצוין חייב להיות כפולה של 8, לא גדול מאורך הדגימה או קטן מהערך של Tag::MIN_MAC_LENGTH בהרשאות המפתח. באורכי MAC שגדולים מאורך הדיגסט או באורך שאינו מכפלה של 8, מחזירים את הערך ErrorCode::UNSUPPORTED_MAC_LENGTH. לערכים שקצרים מהאורך המינימלי של המפתח, מחזירים את הערך ErrorCode::INVALID_MAC_LENGTH.

עדכון

גרסה: 1, 2, 3

הפונקציה מספקת נתונים לעיבוד בפעולה מתמשכת שהתחילה באמצעות begin. הפעולה מצוינה באמצעות הפרמטר operationHandle.

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

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

טיפול בשגיאות

אם השיטה הזו מחזירה קוד שגיאה שאינו ErrorCode::OK, הפעולה מבוטלת והטיפול בפעולה לא תקף. כל שימוש עתידי במזהה באמצעות השיטה הזו, finish או abort, יחזיר את הערך ErrorCode::INVALID_OPERATION_HANDLE.

אכיפת הרשאות

אכיפת הרשאות המפתחות מתבצעת בעיקר ב-begin. החריגה היחידה היא במקרה שבו המפתח כולל:

• תג Tag::USER_SECURE_IDs אחד או יותר, וגם
• אין לו את השדה Tag::AUTH_TIMEOUT

במקרה כזה, נדרשת הרשאה לכל פעולה במפתח, ושיטת העדכון מקבלת את הערך Tag::AUTH_TOKEN בארגומנט inParams. ‏HMAC מאמת שהטוקן תקף, מכיל מזהה משתמש מאובטח תואם, תואם ל-Tag::USER_AUTH_TYPE של המפתח ומכיל את ה-operation handle של הפעולה הנוכחית בשדה האתגר. אם התנאים האלה לא מתקיימים, מחזירים את הערך ErrorCode::KEY_USER_NOT_AUTHENTICATED.

מבצע הקריאה מספק את אסימון האימות לכל קריאה ל-update ול-finish. אם רוצים, אפשר לאמת את האסימון רק פעם אחת במהלך ההטמעה.

מפתחות RSA

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

מפתחות ECDSA

בשיטה הזו, אפשר לחתום על כל הבלוק או לאמת אותו בעדכון אחד, לצורך פעולות חתימה ואימות באמצעות Digest::NONE. אי אפשר לצרוך רק חלק מהבלוק באמצעות השיטה הזו.

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

מפתחות AES

מצב AES GCM תומך ב'נתוני אימות משויכים', שסופקו באמצעות התג Tag::ASSOCIATED_DATA בארגומנט inParams. אפשר לספק את הנתונים המשויכים בקריאות חוזרות (חשוב אם הנתונים גדולים מדי כדי לשלוח אותם בבלוק אחד), אבל הם תמיד מופיעים לפני הנתונים שרוצים להצפין או לפענח. קריאה לעדכון יכולה לקבל גם נתונים משויכים וגם נתונים להצפנה/פענוח, אבל עדכונים הבאים לא יכולים לכלול נתונים משויכים. אם מבצע הקריאה מספק נתונים משויכים לקריאת עדכון אחרי שיחה שכוללת נתונים להצפנה/לפענוח, מחזירים את הערך ErrorCode::INVALID_TAG.

בהצפנת GCM, התג מצורף למטמון המוצפן באמצעות finish. במהלך פענוח הנתונים, Tag::MAC_LENGTH הבייטים האחרונים של הנתונים שסופקו לקריאת העדכון האחרונה הם התג. מכיוון שקריאה מסוימת ל-update לא יכולה לדעת אם היא הקריאה האחרונה, היא מעבדת את כל הפרטים מלבד אורך התג ומאחסנת את נתוני התג האפשריים במטמון במהלך finish.

סיום

גרסה: 1, 2, 3

הפונקציה מסיימת פעולה מתמשכת שהתחילה באמצעות begin, ומעבדת את כל הנתונים שעדיין לא עברו עיבוד שסופקו על ידי update.

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

בין שהיא מסתיימת בהצלחה ובין שהיא מחזירה שגיאה, השיטה הזו מסיימת את הפעולה ולכן מבטלת את ה-handle של הפעולה שסופק. כל שימוש עתידי במזהה, באמצעות השיטה הזו או באמצעות update או abort, יחזיר את הערך ErrorCode::INVALID_OPERATION_HANDLE.

פעולות חתימה מחזירות את החתימה כפלט. פעולות האימות מקבלות את החתימה בפרמטר signature ולא מחזירות פלט.

אכיפת הרשאות

אכיפת הרשאות המפתחות מתבצעת בעיקר ב-begin. החריגה היחידה היא במקרה שבו המפתח כולל:

• תג אחד או יותר מסוג Tag::USER_SECURE_IDs, וגם
• אין בו את הערך Tag::AUTH_TIMEOUT

במקרה כזה, נדרשת הרשאה לכל פעולה במפתח, ושיטת העדכון מקבלת את הערך Tag::AUTH_TOKEN בארגומנט inParams. ‏HMAC מאמת שהטוקן תקין, מכיל מזהה משתמש מאובטח תואם, תואם ל-Tag::USER_AUTH_TYPE של המפתח ומכיל את ה-operation handle של הפעולה הנוכחית בשדה האתגר. אם התנאים האלה לא מתקיימים, מחזירים את הערך ErrorCode::KEY_USER_NOT_AUTHENTICATED.

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

מפתחות RSA

דרישות נוספות מסוימות, בהתאם לאפשרות של הוספת הפסקה:

• PaddingMode::NONE. בפעולות חתימה והצפנה ללא תוספת פסילות, אם הנתונים שסופקו קצרים יותר מהמפתח, הנתונים יתווספו פסילות אפס בצד ימין לפני החתימה או ההצפנה. אם אורך הנתונים זהה לאורכו של המפתח, אבל הוא גדול יותר מבחינה מספרית, מחזירים את הערך ErrorCode::INVALID_ARGUMENT. כדי לבצע פעולות אימות ופענוח, אורך הנתונים חייב להיות זהה לאורכו של המפתח. אחרת, מחזירים את הערך ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. בפעולות חתימה עם חיפוי PSS, המלח של PSS הוא בגודל של סיכום ההודעה ונוצר באופן אקראי. האלגוריתם של הסיכום המחושב (digest) שצוין באמצעות Tag::DIGEST ב-inputParams ב-begin משמש כאלגוריתם של הסיכום המחושב של PSS וכאלגוריתם של הסיכום המחושב של MGF1.
• PaddingMode::RSA_OAEP. האלגוריתם של הגיבוב (digest) שצוין באמצעות Tag::DIGEST ב-inputParams בקטע begin משמש כאלגוריתם הגיבוב של OAEP, ו-SHA1 משמש כאלגוריתם הגיבוב של MGF1.

מפתחות ECDSA

אם הנתונים שסופקו לחתימה או לאימות ללא תוספת שטח ריווחי ארוכים מדי, צריך לקצר אותם.

מפתחות AES

תנאים נוספים, בהתאם למצב החסימה:

• BlockMode::ECB או BlockMode::CBC. אם המילוי הוא PaddingMode::NONE ואורך הנתונים לא מכפיל של גודל הבלוק של AES, מחזירים את הערך ErrorCode::INVALID_INPUT_LENGTH. אם ה-padding הוא PaddingMode::PKCS7, צריך להוסיף לנתונים את ה-padding בהתאם למפרט PKCS#7. שימו לב שב-PKCS#7 מומלץ להוסיף עוד בלוק של מילוי אם הנתונים הם מכפלה של אורך הבלוק.
• BlockMode::GCM. במהלך ההצפנה, אחרי עיבוד כל הטקסט ללא הצפנה, מחשבים את התג (Tag::MAC_LENGTH בייטים) ומצרפים אותו למחרוזת המוצפנת שמוחזרת. במהלך פענוח, מעבדים את הבייטים האחרונים של Tag::MAC_LENGTH בתור התג. אם האימות של התג נכשל, מחזירים את הערך ErrorCode::VERIFICATION_FAILED.

ביטול

גרסה: 1, 2, 3

הפעולה המתבצעת מבוטלת. אחרי הקריאה לביטול, צריך להחזיר את הערך ErrorCode::INVALID_OPERATION_HANDLE בכל שימוש נוסף במזהה הפעולה שסופק באמצעות update,‏ finish או abort.

get_supported_algorithms

גרסה: 1

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

הטמעות של Keymaster 1 תומכות ב-RSA, ב-EC, ב-AES וב-HMAC.

get_supported_block_modes

גרסה: 1

הפונקציה מחזירה את רשימת מצבי הבלוק של AES שנתמכים בהטמעת החומרה של Keymaster לאלגוריתם ולמטרה מסוימים.

עבור RSA, ‏ EC ו-HMAC, שהם לא הצפנות בלוקים, ה-method מחזיר רשימה ריקה לכל המטרות התקינות. מטרות לא חוקיות אמורות לגרום לשיטה להחזיר את הערך ErrorCode::INVALID_PURPOSE.

הטמעות של Keymaster 1 תומכות ב-ECB, ‏ CBC, ‏ CTR ו-GCM להצפנה ולפענוח של AES.

get_supported_padding_modes

גרסה: 1

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

ל-HMAC ול-EC אין מושג של מילוי, ולכן השיטה מחזירה רשימה ריקה לכל המטרות התקינות. מטרות לא חוקיות אמורות לגרום לכך שהשיטה תחזיר את הערך ErrorCode::INVALID_PURPOSE.

בהטמעות של RSA עם Keymaster 1 יש תמיכה באפשרויות הבאות:

• הצפנה, פענוח, חתימה ואימות ללא תוספת שטח. בהצפנה ובחתימה ללא תוספת שטח, אם ההודעה קצרה מהמודולוס הציבורי, ההטמעות צריכות להוסיף לה אפסים בצד ימין. כדי לבצע פעולות של פענוח ואימות ללא תוספת מרווחים, אורך הקלט צריך להתאים לגודל המודולוס הציבורי.
• מצבי תוספת נתונים להצפנה ולחתימה של PKCS#1 v1.5
• PSS באורך מינימלי של מלח 20
• OAEP

ב-AES במצבים ECB ו-CBC, הטמעות של Keymaster 1 תומכות ב-no padding וב-PKCS#7-padding. המצבים CTR ו-GCM תומכים רק באפשרות 'ללא מילוי'.

get_supported_digests

גרסה: 1

הפונקציה מחזירה את רשימת מצבי התקציר שנתמכים בהטמעת החומרה של Keymaster לאלגוריתם ולמטרה שצוינו.

אף אחד ממצבי ה-AES לא תומך ב-digesting או מחייב אותו, ולכן ה-method מחזיר רשימה ריקה למטרות תקינות.

הטמעות של Keymaster 1 יכולות ליישם קבוצת משנה של הסכמות ה-digest שהוגדרו. ההטמעות מספקות SHA-256 ויכולות לספק גם MD5, ‏ SHA1, ‏ SHA-224,‏ SHA-256, ‏ SHA384 ו-SHA512 (הקבוצה המלאה של הסכסוכים שהוגדרו).

get_supported_import_formats

גרסה: 1

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

הטמעות של Keymaster 1 תומכות בפורמט PKCS#8 (ללא הגנה באמצעות סיסמה) לייבוא של צמדי מפתחות RSA ו-EC, ותומכות בייבוא RAW של חומר מפתחות AES ו-HMAC.

get_supported_export_formats

גרסה: 1

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

הטמעות של Keymaster1 תומכות בפורמט X.509 לייצוא מפתחות ציבוריים של RSA ו-EC. אין תמיכה בייצוא של מפתחות פרטיים או מפתחות אסימטריים.

פונקציות היסטוריות

Keymaster 0

הפונקציות הבאות שייכות להגדרה המקורית של Keymaster 0. הם היו נוכחים במבנה keymaster1_device_t של Keymaster 1. עם זאת, ב-Keymaster 1.0 הן לא יושמו, והצבענו הפונקציות שלהן הוגדרו ל-NULL.

• generate_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• Verify_data

Keymaster 1

הפונקציות הבאות שייכות להגדרה של Keymaster 1, אבל הוסרו ב-Keymaster 2, יחד עם הפונקציות של Keymaster 0 שמפורטות למעלה.

• get_supported_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_supported_export_formats

Keymaster 2

הפונקציות הבאות שייכות להגדרה של Keymaster 2, אבל הוסרו ב-Keymaster 3, יחד עם הפונקציות של Keymaster 1 שמפורטות למעלה.

• configure