keymaster2_device Struct Reference
#include < keymaster2.h >
תיאור מפורט
הגדרת מכשיר Keymaster2
הגדרה בשורה 28 של הקובץ keymaster2.h .
תיעוד שטח
| keymaster_error_t (* abort)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle) |
מבטל פעולת הצפנה שהחלה ב- begin() , משחרר את כל המשאבים הפנימיים ומבטל operation_handle .
הגדרה בשורה 415 של הקובץ keymaster2.h .
| keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length) |
מוסיף אנטרופיה ל-RNG המשמש את keymaster. מובטחת כי אנטרופיה שנוספה באמצעות שיטה זו אינה מקור האנטרופיה היחיד בו נעשה שימוש, ופונקציית הערבוב נדרשת להיות מאובטחת, במובן זה שאם ה-RNG זורע (ממקור כלשהו) עם נתונים כלשהם, התוקף לא יכול לחזות (או control), אז לא ניתן להבחין בין פלט RNG לאקראי. לפיכך, אם האנטרופיה ממקור כלשהו היא טובה, הפלט יהיה טוב.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] נתונים נתונים אקראיים לשילוב. [ב] data_length אורך data.
הגדרה בשורה 74 של הקובץ keymaster2.h .
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
יוצר שרשרת אישור X.509 חתומה המעידה על קיומו של key_to_attest ב-keymaster (TODO(swillden): תאר את תוכן האישור ביתר פירוט). האישור יכיל הרחבה עם OID 1.3.6.1.4.1.11129.2.1.17 וערך המוגדר ב-<TODO:swillden – הכנס קישור כאן> המכיל את תיאור המפתח.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] key_to_test מפתח המפתח שעבורו יופק אישור האישור. [ב] attest_params פרמטרים המגדירים כיצד לבצע את האישור. כרגע הפרמטר היחיד הוא KM_TAG_ALGORITHM, שעליו להיות KM_ALGORITHM_EC או KM_ALGORITHM_RSA. זה בוחר באילו ממפתחות האישור המסופקים ישמש לחתימה על האישור. [הַחוּצָה] שרשרת_cert מערך של תעודות X.509 מקודדות DER. הראשון יהיה האישור עבור key_to_attest. הערכים הנותרים ישרפו בחזרה לשורש. המתקשר לוקח בעלות וחייב להקצות עם keymaster_free_cert_chain.
הגדרה בשורה 239 של הקובץ keymaster2.h .
| keymaster_error_t (* begin)(const struct keymaster2_device *dev, keymaster_purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t ) |
מתחיל פעולת הצפנה באמצעות המפתח שצוין. אם הכל בסדר, begin() יחזיר את KM_ERROR_OK ויצור נקודת אחיזה פעולה שאותה יש להעביר לקריאות עוקבות ל- update() , finish() או abort() .
זה קריטי שכל קריאה להתחלה() תוצמד לקריאה עוקבת לסיים() או לבטל() , כדי לאפשר למימוש keymaster לנקות כל מצב פעולה פנימי. אי ביצוע פעולה זו עלולה לדלוף שטח מצב פנימי או משאבים פנימיים אחרים ועלול לגרום בסופו של דבר ל-start() להחזיר KM_ERROR_TOO_MANY_OPERATIONS כשיגמר לו המקום לפעולות. כל תוצאה מלבד KM_ERROR_OK מ- begin() , update() או finish() מבטלת באופן מרומז את הפעולה, ובמקרה זה אין צורך לקרוא abort() (ותחזיר את KM_ERROR_INVALID_OPERATION_HANDLE אם נקרא).
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] מַטָרָה מטרת הפעולה, אחת מ-KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN או KM_PURPOSE_VERIFY. שים לב שבמצבי AEAD, הצפנה ופענוח מרמזים על חתימה ואימות, בהתאמה, אך יש לציין אותם כ-KM_PURPOSE_ENCRYPT ו-KM_PURPOSE_DECRYPT. [ב] מַפְתֵחַ המפתח שישמש עבור הפעולה. keyחייב להיות מטרה התואמתpurposeוכל דרישות השימוש בו חייבות להתקיים, או ש-start() יחזיר קוד שגיאה מתאים.[ב] in_params פרמטרים נוספים לפעולה. זה משמש בדרך כלל כדי לספק נתוני אימות, עם KM_TAG_AUTH_TOKEN. אם KM_TAG_APPLICATION_ID או KM_TAG_APPLICATION_DATA סופקו במהלך היצירה, יש לספק אותם כאן, אחרת הפעולה תיכשל עם KM_ERROR_INVALID_KEY_BLOB. עבור פעולות הדורשות nonce או IV, במפתחות שנוצרו עם KM_TAG_CALLER_NONCE, in_params עשוי להכיל תג KM_TAG_NONCE. [הַחוּצָה] out_params פרמטרי פלט. משמש להחזרת נתונים נוספים מאתחול הפעולה, בעיקר להחזרת IV או nonce מפעולות שיוצרות IV או nonce. המתקשר לוקח בעלות על מערך פרמטרי הפלט ועליו לשחרר אותו באמצעות keymaster_free_param_set() . out_params עשוי להיות מוגדר ל-NULL אם לא צפויים פרמטרי פלט. אם out_params הוא NULL, ופרמטרי פלט נוצרים, begin() יחזיר KM_ERROR_OUTPUT_PARAMETER_NULL. [הַחוּצָה] handling_operation ידית הפעולה החדשה שנוצרה שיש להעביר ל- update() , finish() או abort() . אם operation_handle הוא NULL, begin() יחזיר KM_ERROR_OUTPUT_PARAMETER_NULL.
הגדרה בשורה 332 של הקובץ keymaster2.h .
| struct hw_device_t נפוץ |
שיטות נפוצות של התקן keymaster. זה חייב להיות החבר הראשון ב-keymaster_device מכיוון שמשתמשים במבנה זה ישליכו מצביע hw_device_t למצביע keymaster_device בהקשרים שבהם ידוע שה- hw_device_t מפנה ל-keymaster_device.
הגדרה בשורה 35 של הקובץ keymaster2.h .
| keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
מגדיר 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.
הגדרה בשורה 58 של הקובץ keymaster2.h .
| ריק* הקשר |
הגדרה בשורה 37 של הקובץ keymaster2.h .
| keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev) |
מוחק את כל המפתחות במאגר המפתחות של החומרה. משמש כאשר מאגר המקשים מאופס לחלוטין. לאחר קריאת פונקציה זו, לא יהיה ניתן להשתמש באף כתמי מפתח שנוצרו או מיובאים בעבר עבור פעולות כלשהן.
פונקציה זו היא אופציונלית ויש להגדיר אותה ל-NULL אם היא לא מיושמת.
- פרמטרים
[ב] dev מבנה מכשיר keymaster.
הגדרה בשורה 288 של הקובץ keymaster2.h .
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
מוחק את המפתח, או צמד המפתחות, המשויכים לגוש המפתחות. לאחר קריאת פונקציה זו לא יהיה ניתן להשתמש במקש עבור כל פעולה אחרת. ניתן להחיל על מפתחות משורשי אמון זרים (מפתחות שאינם ניתנים לשימוש תחת שורש האמון הנוכחי).
פונקציה זו היא אופציונלית ויש להגדיר אותה ל-NULL אם היא לא מיושמת.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] מַפְתֵחַ המפתח שיימחק.
הגדרה בשורה 276 של הקובץ keymaster2.h .
| keymaster_error_t (* export_key)(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, * keymaster_blob_t ) |
מייצא מפתח ציבורי או סימטרי, מחזיר מערך בתים בפורמט שצוין.
שים לב שייצוא מפתח סימטרי מותר רק אם המפתח נוצר עם KM_TAG_EXPORTABLE, ורק אם כל הדרישות לשימוש במפתח (למשל אימות) מתקיימות.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] export_format הפורמט שישמש לייצוא המפתח. [ב] key_to_export המפתח לייצוא. [ב] מזהה_לקוח קוד זיהוי לקוח, שעליו להתאים לבלוק שסופק ב-KM_TAG_APPLICATION_ID במהלך יצירת המפתחות (אם יש). [ב] app_data כתם נתוני יישומים, אשר חייב להתאים לבלוק המסופק ב-KM_TAG_APPLICATION_DATA במהלך יצירת המפתחות (אם יש). [הַחוּצָה] export_data חומר המפתח המיוצא. המתקשר מקבל בעלות.
הגדרה בשורה 213 של הקובץ keymaster2.h .
| keymaster_error_t (* finish)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params , const keymaster_blob_t *input, const keymaster_blob_t *חתימה, * keymaster_key_param_param_set ,t |
מסיים פעולת הצפנה שהחלה ב- begin() ומבטל את operation_handle .
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] handling_operation ידית הפעולה שהוחזרה על ידי begin() . ידית זו תבוטל. [ב] in_params פרמטרים נוספים לפעולה. עבור מצבי AEAD, זה משמש לציון KM_TAG_ADDITIONAL_DATA, אך רק אם לא סופקו נתוני קלט לעדכון() . [ב] קֶלֶט נתונים לעיבוד, לפי הפרמטרים שנקבעו ב-call to begin() . finish() חייב לצרוך את כל הנתונים שסופקו או להחזיר KM_ERROR_INVALID_INPUT_LENGTH. [ב] חֲתִימָה החתימה שיש לאמת אם המטרה שצוינה בקריאת begin() הייתה KM_PURPOSE_VERIFY. [הַחוּצָה] תְפוּקָה נתוני הפלט, אם יש. המתקשר מקבל בעלות על המאגר המוקצה.
אם הפעולה שמסתיימת היא אימות חתימה או פענוח במצב AEAD והאימות נכשל אז finish() יחזיר את KM_ERROR_VERIFICATION_FAILED.
הגדרה בשורה 405 של הקובץ keymaster2.h .
| דגלים של uint32_t |
ראה דגלים שהוגדרו עבור keymaster0_devices::flags ב- keymaster_common.h . משמש רק עבור תאימות לאחור; התקני חומרה keymaster2 חייבים להגדיר זאת לאפס.
הגדרה בשורה 43 של הקובץ keymaster2.h .
| keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
יוצר מפתח, או זוג מפתחות, מחזיר כתם מפתח ו/או תיאור של המפתח.
פרמטרים של יצירת מפתח מוגדרים כצמדי תג/ערך keymaster, מסופקים params . ראה keymaster_tag_t לרשימה המלאה. כמה ערכים שנדרשים תמיד ליצירת מפתחות שימושיים הם:
- KM_TAG_ALGORITHM;
- KM_TAG_PURPOSE; ו
- (KM_TAG_USER_SECURE_ID ו-KM_TAG_USER_AUTH_TYPE) או KM_TAG_NO_AUTH_REQUIRED.
בדרך כלל יש לציין KM_TAG_AUTH_TIMEOUT אלא אם כן קיים KM_TAG_NO_AUTH_REQUIRED, או שהמשתמש יצטרך לאמת עבור כל שימוש.
יש לציין KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH ו-KM_TAG_DIGEST עבור אלגוריתמים הדורשים אותם.
לא ניתן לציין את התגים הבאים; הערכים שלהם יסופקו על ידי היישום.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] params מערך פרמטרים ליצירת מפתחות [הַחוּצָה] key_blob מחזיר את המפתח שנוצר. key_blobלא חייב להיות NULL. המתקשר מקבל בעלות key_blob->key_material ועליו לשחרר() אותו.[הַחוּצָה] מאפיינים מחזירה את המאפיינים של המפתח שנוצר, אם אינו NULL. אם אינו NULL, המתקשר מקבל בעלות וחייב להקצות עם keymaster_free_characteristics() . שים לב ש-KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA לעולם לא יוחזרו.
הגדרה בשורה 112 של הקובץ keymaster2.h .
| keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *characteristics_t) |
מחזירה את המאפיינים של המפתח שצוין, או KM_ERROR_INVALID_KEY_BLOB אם ה-key_blob לא חוקי (ישומים חייבים לאמת את שלמות המפתח באופן מלא). client_id ו-app_data חייבים להיות המזהה והנתונים שסופקו כאשר המפתח נוצר או יובא, או ריקים אם KM_TAG_APPLICATION_ID ו/או KM_TAG_APPLICATION_DATA לא סופקו במהלך היצירה. ערכים אלה אינם כלולים במאפיינים המוחזרים. המתקשר מקבל בעלות על אובייקט המאפיינים שהוקצה, אשר חייב להיות מוקצה עם keymaster_free_characteristics() .
שים לב ש-KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA לעולם לא יוחזרו.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] key_blob המפתח לאחזור מאפיינים מ. [ב] מזהה_לקוח נתוני מזהה הלקוח, או NULL אם לא משויכים. [ב] app_id נתוני האפליקציה, או NULL אם לא משויכים. [הַחוּצָה] מאפיינים מאפייני המפתח. לא חייב להיות NULL. המתקשר מקבל בעלות על התוכן ועליו להקצות עם keymaster_free_characteristics() .
הגדרה בשורה 139 של הקובץ keymaster2.h .
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_characteristics ) |
מייבא מפתח, או זוג מפתחות, מחזיר כתם מפתח ו/או תיאור של המפתח.
רוב פרמטרי הייבוא העיקריים מוגדרים כצמדי תג/ערך keymaster, מסופקים ב"פראמים". ראה keymaster_tag_t לרשימה המלאה. הערכים שנדרשים תמיד לייבוא מפתחות שימושיים הם:
- KM_TAG_ALGORITHM;
- KM_TAG_PURPOSE; ו
- (KM_TAG_USER_SECURE_ID ו-KM_TAG_USER_AUTH_TYPE) או KM_TAG_NO_AUTH_REQUIRED.
בדרך כלל יש לציין KM_TAG_AUTH_TIMEOUT. אם לא צוין, המשתמש יצטרך לבצע אימות עבור כל שימוש.
התגים הבאים יקבלו ערכי ברירת מחדל אם לא יצוינו:
- KM_TAG_KEY_SIZE יקבל כברירת מחדל את גודל המפתח שסופק.
- KM_TAG_RSA_PUBLIC_EXPONENT יקבע כברירת מחדל את הערך במפתח שסופק (עבור מפתחות RSA)
לא ניתן לציין את התגים הבאים; הערכים שלהם יסופקו על ידי היישום.
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] params פרמטרים המגדירים את המפתח המיובא. [ב] params_count מספר הכניסות params.[ב] מפתח_פורמט מציין את הפורמט של נתוני המפתח ב-key_data. [הַחוּצָה] key_blob משמש להחזרת כתם המפתח האטום. חייב להיות ללא NULL. המתקשר מקבל בעלות על המפתח_חומר הכלול. [הַחוּצָה] מאפיינים משמש להחזרת המאפיינים של המפתח המיובא. יכול להיות NULL, ובמקרה זה לא יוחזרו מאפיינים. אם אינו NULL, המתקשר מקבל בעלות על התוכן ועליו להקצות עם keymaster_free_characteristics() . שים לב ש-KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA לעולם לא יוחזרו.
הגדרה בשורה 186 של הקובץ keymaster2.h .
| keymaster_error_t (* עדכון)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle , const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_put) |
מספק נתונים, ואולי מקבל פלט מפעולת הצפנה מתמשכת שהחלה ב- begin() .
אם operation_handle לא חוקי, update() יחזיר את KM_ERROR_INVALID_OPERATION_HANDLE.
update() עשוי שלא לצרוך את כל הנתונים שסופקו במאגר הנתונים. update() יחזיר את הכמות שנצרכה ב-*data_consumed. המתקשר צריך לספק את הנתונים שלא נצרכו בשיחה הבאה.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] handling_operation ידית הפעולה שהוחזרה על ידי begin() . [ב] in_params פרמטרים נוספים לפעולה. עבור מצבי AEAD, זה משמש לציון KM_TAG_ADDITIONAL_DATA. שים לב שניתן לספק נתונים נוספים בקריאות מרובות לעדכון() , אך רק עד שיסופקו נתוני קלט. [ב] קֶלֶט נתונים לעיבוד, לפי הפרמטרים שנקבעו ב-call to begin() . שים לב ש- update() עשוי לצרוך או לא לצרוך את כל הנתונים שסופקו. ראה input_consumed.[הַחוּצָה] input_consumed כמות הנתונים שנצרכה על ידי update() . אם זה נמוך מהסכום שסופק, המתקשר צריך לספק את היתרה בקריאה נוספת לעדכון() . [הַחוּצָה] out_params פרמטרי פלט. משמש להחזרת נתונים נוספים מהפעולה המתקשר לוקח בעלות על מערך פרמטרי הפלט וחייב לשחרר אותו באמצעות keymaster_free_param_set() . out_params עשוי להיות מוגדר ל-NULL אם לא צפויים פרמטרי פלט. אם out_params הוא NULL, ופרמטרי פלט נוצרים, begin() יחזיר KM_ERROR_OUTPUT_PARAMETER_NULL. [הַחוּצָה] תְפוּקָה נתוני הפלט, אם יש. המתקשר מקבל בעלות על המאגר המוקצה. הפלט לא חייב להיות NULL.
שים לב ש- update() עשוי שלא לספק פלט כלשהו, ובמקרה זה פלט->data_length יהיה אפס, ו-output->data עשוי להיות NULL או באורך אפס (כך שהמתקשר תמיד צריך לשחרר אותו).
הגדרה בשורה 376 של הקובץ keymaster2.h .
| keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key) |
משדרג מפתח ישן. מפתחות יכולים להפוך ל"ישנים" בשתי דרכים: ניתן לשדרג את Keymaster לגרסה חדשה, או לעדכן את המערכת כדי לבטל את תוקף גרסת מערכת ההפעלה ו/או רמת התיקון. בכל מקרה, ניסיונות להשתמש במפתח ישן יגרמו לכך שה-keymaster יחזיר את KM_ERROR_KEY_REQUIRES_UPGRADE. לאחר מכן יש לקרוא לשיטה זו כדי לשדרג את המפתח.
- פרמטרים
[ב] dev מבנה מכשיר keymaster. [ב] מפתח_לשדרוג מפתח keymaster לשדרוג. [ב] upgrade_params פרמטרים הדרושים להשלמת השדרוג. בפרט, KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA יידרשו אם הם הוגדרו עבור המפתח. [הַחוּצָה] upgraded_key כתם המפתח המשודרג.
הגדרה בשורה 260 של הקובץ keymaster2.h .
התיעוד עבור מבנה זה נוצר מהקובץ הבא:
- hardware/libhardware/include/hardware/ keymaster2.h