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

• הערך של 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 אם הן מקבלות יותר מ-2 KiB של נתונים בקריאה אחת.

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) שבהם אפשר להשתמש עם המפתח החדש. הטמעות שלא תומכות בכל אלגוריתמי הדגימה צריכות לקבל בקשות ליצירת מפתחות שכוללות דגימות שלא נתמכות. יש להוסיף את הדיגסטים שלא נתמכים לרשימת המאפיינים של המפתח שהוחזרו, שמופעלת על ידי התוכנה. הסיבה לכך היא שאפשר להשתמש במפתח עם תקצירי ה-digest האחרים האלה, אבל יצירת תקצירי ה-digest מתבצעת בתוכנה. לאחר מכן, החומרה נקראת לבצע את הפעולה עם Digest::NONE.
• Tag::PADDING מציין את אופני המילוי שאפשר להשתמש בהם עם המפתח החדש. אם מציינים אלגוריתמים של סיכום (digest) שלא נתמכים, יש להוסיף את הערכים PaddingMode::RSA_PSS ו-PaddingMode::RSA_OAEP לרשימה של מאפייני המפתחות שנאכפים באמצעות תוכנה, בהטמעות שלא תומכות בכל אלגוריתמי הסיכום.

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

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

התחלה

גרסה: 1, 2, 3

הפונקציה מתחילה פעולה קריפטוגרפית באמצעות המפתח שצוין, למטרה שצוינה, עם הפרמטרים שצוינו (לפי הצורך), ומחזירה את ה-handle של הפעולה שמשמש עם update ו-finish כדי להשלים את הפעולה. מזהה הפעולה משמש גם כאסימון האתגר (challenge token) בפעולות מאומתות, ובפעולות כאלה הוא נכלל בשדה 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 מאפשר למתקשר לציין וקטור אתחול (IV) או קוד חד-פעמי (nonce). אם התג הזה לא מופיע במפתח, אבל מבצע הקריאה הפנימית סיפק את הערך Tag::NONCE לשיטה הזו, הערך ErrorCode::CALLER_NONCE_PROHIBITED יוחזר.
• Tag::BOOTLOADER_ONLY מציין שרק מנהל האתחול יכול להשתמש במפתח. אם השיטה הזו נקראת עם מפתח ל-bootloader בלבד אחרי ש-bootloader סיים לפעול, היא מחזירה את הערך ErrorCode::INVALID_KEY_BLOB.

מפתחות RSA

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

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

כדי לבצע פעולות במפתח פרטי (KeyPurpose::DECYPT ו-KeyPurpose::SIGN), צריך הרשאה ל-digest ולמילוי, כלומר הרשאות המפתח צריכות להכיל את הערכים שצוינו. אחרת, ה-method מחזיר את הערך 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.

יש כמה אינטראקציות חשובות בין מצבי הוספת שטח אחסון לבין סיכומי דחיסה:

• הערך PaddingMode::NONE מציין שבוצעה פעולת RSA גולמית. אם חותמים או מאמתים, הערך Digest::NONE מצוין ל-digest. אין צורך ב-digest להצפנה או לפענוח ללא תוספת שטח.
• כדי להוסיף PaddingMode::RSA_PKCS1_1_5_SIGN נדרש סיכום (digest). הגיבוב יכול להיות Digest::NONE, ובמקרה כזה ההטמעה של Keymaster לא יכולה ליצור מבנה חתימה תקין של PKCS#1 v1.5, כי היא לא יכולה להוסיף את המבנה DigestInfo. במקום זאת, ההטמעה יוצרת את 0x00 || 0x01 || PS || 0x00 || M, כאשר M היא ההודעה שסופקה ו-PS היא מחרוזת המילוי. הגודל של מפתח ה-RSA חייב להיות גדול מההודעה ב-11 בייטים לפחות, אחרת המטה-פוטנציה מחזירה את הערך ErrorCode::INVALID_INPUT_LENGTH.
• למרווח הפנימי של 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 או אסימון חד-פעמי עם הערך Tag::NONCE בשדה inParams. אם מציינים nonce כש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 של המפתח ומכיל את ה-handle של הפעולה הנוכחית בשדה challenge. אם התנאים האלה לא מתקיימים, מחזירים את הערך 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 לא יכולה לדעת אם זו ההפעלה האחרונה, היא מעבדת את כל הנתונים מלבד אורך התג ומאחסנת ב-buffer את נתוני התג האפשריים במהלך 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 של המפתח ומכיל את ה-handle של הפעולה הנוכחית בשדה challenge. אם התנאים האלה לא מתקיימים, מחזירים את הערך ErrorCode::KEY_USER_NOT_AUTHENTICATED.

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

מפתחות RSA

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

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

מפתחות ECDSA

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

מפתחות AES

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

• BlockMode::ECB או BlockMode::CBC. אם המילוי הוא PaddingMode::NONE ואורך הנתונים לא הוא מכפיל של גודל הבלוק של AES, מחזירים את הערך ErrorCode::INVALID_INPUT_LENGTH. אם הערך של ה-padding הוא PaddingMode::PKCS7, צריך להוסיף לאותיות הנתונים תווים לפי מפרט 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 (הקבוצה המלאה של הסכמות ה-digest שהוגדרו).

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