פונקציות Keymaster

דף זה מספק פרטים כדי לסייע למיישמים של Keymaster Hardware Abstraction Layers (HALs). זה מכסה כל פונקציה ב-API ואיזו גרסת Keymaster פונקציה זו זמינה ומתאר את יישום ברירת המחדל. לתגים, עיין בדף Keymaster Tags .

הנחיות יישום כלליות

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

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

גרסה : 1, 2

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

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

פונקציות

getHardwareFeatures

גרסה : 3

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

  • isSecure true אם מפתחות מאוחסנים בחומרה מאובטחת (TEE וכו') ולעולם לא עוזבים אותה.
  • supportsEllipticCurve true אם החומרה תומכת בקריפטוגרפיה Elliptic Curve עם עקומות 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 ליצירת מספרים אקראיים, עבור מפתחות, IVs וכו'.

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

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

genereKey

גרסה : 1, 2, 3

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

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

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

מפתחות RSA

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

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

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

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

מפתחות ECDSA

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

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

מפתחות AES

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

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

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

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

מפתחות HMAC

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

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

מאפיינים מרכזיים

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

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

תג::ROLLBACK_RESISTANT .

התנגדות לאחור

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

מפתח הוא עמיד לחזרה אם החומרה המאובטחת מבטיחה שלא ניתן לשחזר מפתחות שנמחקו מאוחר יותר. זה נעשה בדרך כלל על ידי אחסון מטא נתונים מרכזיים נוספים במיקום מהימן שלא ניתן לתמרן על ידי תוקף. במכשירים ניידים, המנגנון המשמש לכך הוא בדרך כלל Replay Protected Memory Blocks (RPMB). מכיוון שמספר המפתחות שניתן ליצור הוא למעשה בלתי מוגבל והאחסון המהימן המשמש להתנגדות לאחור עשוי להיות מוגבל בגודלו, שיטה זו צריכה להצליח גם אם לא ניתן לספק התנגדות לאחור עבור המפתח החדש. במקרה זה, אין להוסיף תג::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 .

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

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

  • תג::ALGORITHM , תג::KEY_SIZE ותג::RSA_PUBLIC_EXPONENT הם מאפיינים מהותיים של המפתח. עבור כל מפתח שמאובטח על ידי חומרה, תגים אלה יהיו ברשימה שנאכפת על ידי החומרה.
  • ערכי תג::DIGEST הנתמכים על ידי החומרה המאובטחת ממוקמים ברשימה הנתמכת בחומרה. תקצירים לא נתמכים נכנסים לרשימה הנתמכת בתוכנה.
  • ערכי תגית::PADDING נכנסים בדרך כלל לרשימה הנתמכת בחומרה, אלא אם קיימת אפשרות שמצב ריפוד ספציפי יצטרך להתבצע על ידי תוכנה. במקרה כזה, הם נכנסים לרשימה שנאכפת על ידי תוכנה. אפשרות כזו מתעוררת עבור מפתחות RSA המאפשרים ריפוד PSS או OAEP עם אלגוריתמי תקציר שאינם נתמכים על ידי החומרה המאובטחת.
  • תג::USER_SECURE_ID ותג::USER_AUTH_TYPE נאכפים בחומרה רק אם אימות המשתמש נאכף בחומרה. כדי להשיג זאת, ה-Trustlet Keymaster ו-trustlet האימות הרלוונטיים צריכים להיות מאובטחים ולשתף מפתח HMAC סודי המשמש לחתימה ולאימות אסימוני אימות. עיין בדף האימות לפרטים.
  • תגיות::ACTIVE_DATETIME , תגיות::ORIGINATION_EXPIRE_DATETIME ותגיות: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 .
  • לתג המוחזר::ORIGIN יש אותו ערך כמו KeyOrigin::IMPORTED .

מפתח ייצוא

גרסה : 1, 2, 3

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

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

אם 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

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

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

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

אכיפת הרשאה

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

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

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

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

מפתחות RSA

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

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

פעולות מפתח פרטיות ( KeyPurpose::DECYPT ו- KeyPurpose::SIGN ) זקוקות להרשאה של תקציר וריפוד, מה שאומר שהרשאות המפתח צריכות להכיל את הערכים שצוינו. אם לא, השיטה מחזירה 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 מצוין עבור התקציר. אין צורך בתקציר להצפנה או פענוח ללא ריפוד.
  • PaddingMode::RSA_PKCS1_1_5_SIGN ריפוד דורש תקציר. התקציר עשוי להיות 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::NONE . אם צוין Digest::NONE , השיטה מחזירה ErrorCode::INCOMPATIBLE_DIGEST . בנוסף, הגודל של מפתח RSA צריך להיות לפחות 2 + D בתים גדול יותר מגודל הפלט של התקציר, כאשר D הוא גודל התקציר, בבתים. אחרת השיטה מחזירה ErrorCode::INCOMPATIBLE_DIGEST . גודל המלח הוא D.
  • ריפוד PaddingMode::RSA_OAEP דורש תקציר, שאולי אינו 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 או לא. במקרה זה, היישום של Keymaster יוצר IV אקראי או nonce ומחזיר אותו באמצעות Tag::NONCE ב- outParams . CBC ו-CTR IV הם 16 בתים. GCM nonces הם 12 בתים. אם הרשאות המפתח מכילות Tag::CALLER_NONCE , אזי המתקשר עשוי לספק IV/nonce עם Tag::NONCE ב- inParams . אם תג::CALLER_NONCE אינו מורשה, החזר ErrorCode::CALLER_NONCE_PROHIBITED . אם לא מסופק כאשר Tag::CALLER_NONCE מורשה, צור IV/nonce אקראי.

מפתחות HMAC

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

עדכון

גרסה : 1, 2, 3

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

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

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

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

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

אכיפת הרשאה

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

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

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

מפתחות RSA

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

מפתחות ECDSA

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

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

מפתחות AES

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

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

סיים

גרסה : 1, 2, 3

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure