פונקציות של Keymaster

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

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

ההנחיות הבאות רלוונטיות לכל הפונקציות ב-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 הגיוניות ומועילות.

פונקציות

תכונות getHardwareFeature

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

generateKey

גרסה: 1, 2, 3

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

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

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

מפתחות RSA

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

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

מפתחות ECDSA

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

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

מפתחות AES

כדי ליצור מפתח AES צריך רק תג::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:

  • תג::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. אחרת, ה-method מחזירה את הערך 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) שלא נתמכים בחומרה המאובטחת.
  • תג::USER_SECURE_ID ו-תג::USER_AUTH_TYPE נאכפים באמצעות חומרה רק אם מתבצעת אכיפה של אימות חומרה. כדי לעשות זאת, צריך לוודא שה-trustlet של Keymaster וה-trustlet הרלוונטי לאימות מאובטחים ושהם משתפים מפתח HMAC סודי שמשמש לחתימה על אסימוני אימות ולתיקוף שלהם. פרטים נוספים זמינים בדף אימות.
  • התגים Tag::ACTIVE_DATETIME,‏ Tag::ORIGINATION_EXPIRE_DATETIME ו-Tag::USAGE_EXPIRE_DATETIME דורשים גישה לשעון קיר תקין שאפשר לאמת. לחומרה המאובטחת ביותר יש גישה רק למידע על זמן שמסופק על ידי מערכת ההפעלה הלא מאובטחת, כלומר האכיפה של התגים מתבצעת באמצעות תוכנה.
  • המאפיין Tag::ORIGIN תמיד מופיע ברשימת החומרה של מפתחות שמקושרים לחומרה. נוכחותו ברשימה הזו היא הדרך שבה שכבות גבוהות יותר קובעות שמפתח מסוים מגובה בחומרה.

מפתח ייבוא

גרסה: 1, 2, 3

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

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

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

מפתח ייצוא

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

מחיקתAllKeys

גרסה: 1, 2, 3

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

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

destroyAttestationIds

גרסה: 3

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

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

התחלה

גרסה: 1, 2, 3

הפונקציה מתחילה פעולה קריפטוגרפית באמצעות המפתח שצוין, למטרה שצוינה, עם הפרמטרים שצוינו (לפי הצורך), ומחזירה את ה-handle של הפעולה שמשמש את הפונקציות update ו-finish כדי להשלים את הפעולה. מזהה הפעולה משמש גם כאסימון 'אתגר' בפעולות מאומתות, ובפעולות כאלה הוא נכלל בשדה 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. אם המפתח מכיל את שניהם, השיטה הזו צריכה לקבל 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 מציין שרק אתחול האתחול יכול להשתמש במפתח. אם מתבצעת קריאה לשיטה הזו באמצעות מפתח תוכנת אתחול בלבד אחרי שתוכנת האתחול מסיימת לפעול, היא מחזירה ErrorCode::INVALID_KEY_BLOB.

מפתחות RSA

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

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

לפעולות מפתח פרטי (KeyPurpose::DECYPT ו-KeyPurpose::SIGN) צריך הרשאה של תקציר ומרווח פנימי, כלומר ההרשאות של המפתח צריכות להכיל את הערכים שצוינו. אחרת, ה-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. אין צורך בתקציר כדי לבצע הצפנה ללא מרווח או לפענוח.
  • כדי להוסיף PaddingMode::RSA_PKCS1_1_5_SIGN למרווח הפנימי נדרש סיכום (digest). אפשר להשתמש ב-digest‏ Digest::NONE. במקרה כזה, ההטמעה של Keymaster לא יכולה ליצור מבנה חתימה תקין של PKCS#1 v1.5 כי היא לא יכולה להוסיף את המבנה DigestInfo. במקום זאת, ההטמעה יוצרת את 0x00 || 0x01 || PS || 0x00 || M, כאשר M היא ההודעה שסופקה ו-PS היא מחרוזת המילוי. הגודל של מפתח ה-RSA צריך להיות גדול ב-11 בייטים לפחות מההודעה, אחרת ה-method מחזירה ErrorCode::INVALID_INPUT_LENGTH.
  • למרווח הפנימי של PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT לא נדרש סיכום.
  • המרווח הפנימי של PaddingMode::RSA_PSS מחייב תקציר, ולא יכול להיות 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) נדרשת הרשאה של תקציר ומרווח פנימי, כלומר ההרשאות של המפתח צריכות להכיל את הערכים שצוינו. אחרת, מחזירים את הערך 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. CBC ו-CTR IV הם 16 בייטים. מפתחות GCM חד-פעמיים הם באורך 12 בייטים. אם ההרשאות למפתחות מכילות את הערך Tag::CALLER_NONCE, מבצע הקריאה החוזרת יכול לספק IV או nonce עם 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::AUTH_TOKEN בארגומנט inParams. HMAC מאמת שהאסימון חוקי ומכיל מזהה משתמש מאובטח תואם, תואם ל-Tag::USER_AUTH_TYPE של המפתח, ומכיל את נקודת האחיזה של הפעולה של הפעולה הנוכחית בשדה האתגר. אם התנאים האלה לא מתקיימים, מחזירים את הערך 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.

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

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

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

אכיפה של הרשאות

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

במקרה כזה, המפתח דורש הרשאה לכל פעולה, ושיטת העדכון מקבלת את הערך Tag::AUTH_TOKEN בארגומנט inParams. ‏HMAC מאמת שהאסימון תקף, מכיל מזהה משתמש מאובטח תואם, תואם ל-Tag::USER_AUTH_TYPE של המפתח ומכיל את ה-operation handle של הפעולה הנוכחית בשדה האתגר. אם התנאים האלה לא מתקיימים, מחזירים את הערך 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. האלגוריתם של הסכימה ליצירת סיכום (digest) שמוגדר באמצעות Tag::DIGEST ב-inputParams בקטע begin משמש כאלגוריתם ליצירת סיכום של OAEP, ו-SHA1 משמש כאלגוריתם ליצירת סיכום של MGF1.

מפתחות ECDSA

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

מפתחות AES

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

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