דף זה מספק פרטים כדי לסייע למיישמים של 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
, ואם המפתח עמיד בפני גלגול,
התנגדות לאחור
התנגדות לאחור פירושה שברגע שמפתח נמחק עם 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
.
אכיפת הרשאה
אכיפת הרשאות מפתח מתבצעת בעיקר בהתחלה . החריג היחיד הוא המקרה שבו למפתח יש:
- תג אחד או יותר ::USER_SECURE_IDs ו
- אין לו תג::AUTH_TIMEOUT
במקרה זה, המפתח דורש הרשאה לכל פעולה, ושיטת העדכון מקבלת תג::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:
- One or more Tag::USER_SECURE_IDs , and
- Does not have a Tag::AUTH_TIMEOUT
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, returnErrorCode::INVALID_ARGUMENT
. For verification and decryption operations, the data must be exactly as long as the key. Otherwise, returnErrorCode::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 ininputParams
on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm. -
PaddingMode::RSA_OAEP
. The digest specified with Tag::DIGEST ininputParams
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
orBlockMode::CBC
. If padding isPaddingMode::NONE
and the data length is not a multiple of the AES block size, returnErrorCode::INVALID_INPUT_LENGTH
. If padding isPaddingMode::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, returnErrorCode::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