פונקציות 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 או 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

מסיים פעולה מתמשכת שהתחילה ב- start , ומעבד את כל הנתונים שעדיין לא מעובדים שסופקו על ידי עדכון (ים).

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

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

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

אכיפת הרשאה

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

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

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

מקשי RSA

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

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

מפתחות ECDSA

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

AES Keys

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

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

לְהַפִּיל

גרסה : 1, 2, 3

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

get_supported_algorithms

גרסה : 1

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

יישומי Keymaster 1 תומכים ב- RSA, EC, AES ו- HMAC.

get_supported_block_modes

גרסה : 1

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

עבור RSA, EC ו- HMAC, שאינם חוסמים ציונים, השיטה מחזירה רשימה ריקה לכל המטרות התקפות. מטרות לא חוקיות צריכות לגרום לשיטה להחזיר 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 תומכים ללא ריפוד ו- PKCS#7 Padding. מצבי CTR ו- GCM תומכים רק בריפוד.

get_supported_digests

גרסה : 1

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

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

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

get_supported_import_formats

גרסה : 1

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

יישומי Keymaster 1 תומכים בפורמט PKCS#8 (ללא הגנת סיסמא) לייבוא ​​זוגות מפתח RSA ו- EC, ותומכים ביבוא גולמי של חומר מקש AES ו- HMAC.

get_supported_export_formats

גרסה : 1

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

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

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

Keymaster 0

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

  • 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