מידע על המבנה keymaster1_device

שדות נתונים
מידע על המבנה keymaster1_device

#include < keymaster1.h >

שדות נתונים

struct hw_device_t   נפוץ
 
uint32_t  client_version
 
uint32_t  דגלים
 
void *  context
 
int(*  generate_keypair )(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  import_keypair )(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
 
int(*  get_keypair_public )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
 
int(*  delete_keypair )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
 
int(*  delete_all )(const struct keymaster1_device *dev)
 
int(*  sign_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
 
int(*  verify_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
 
keymaster_error_t (*  get_supported_algorithms )(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)
 
keymaster_error_t (*  get_supported_block_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_padding_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)
 
keymaster_error_t (*  get_supported_digests )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)
 
keymaster_error_t (*  get_supported_import_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  get_supported_export_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)
 
keymaster_error_t (*  add_rng_entropy )(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length)
 
keymaster_error_t (*  generate_key )(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)
 
keymaster_error_t (*  get_key_characteristics )(const struct keymaster1_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)
 
keymaster_error_t (*  import_key )(const struct keymaster1_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_t **characteristics)
 
keymaster_error_t (*  export_key )(const struct keymaster1_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 *export_data)
 
keymaster_error_t (*  delete_key )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)
 
keymaster_error_t (*  delete_all_keys )(const struct keymaster1_device *dev)
 
keymaster_error_t (*  begin )(const struct keymaster1_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 *operation_handle)
 
keymaster_error_t (*  update )(const struct keymaster1_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_params, keymaster_blob_t *output)
 
keymaster_error_t (*  finish )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
 
keymaster_error_t (*  abort )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle)
 

תיאור מפורט

הגדרת מכשיר של Keymaster1

ההגדרה מופיעה בשורה 28 בקובץ keymaster1.h .

מסמכי תיעוד של שדה

keymaster_error_t (* abort)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle)

הפונקציה מפסיקה פעולה קריפטוגרפית שהתחילה ב- begin()‎ , משחררת את כל המשאבים הפנימיים ומבטלת את התוקף של operation_handle .

ההגדרה מופיעה בשורה 531 בקובץ keymaster1.h .

keymaster_error_t (* add_rng_entropy)(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length)

הוספת אנטרופיה ל-RNG שמשמש את keymaster. מובטח שהאנטרופיה שנוספת באמצעות השיטה הזו לא תהיה המקור היחיד של האנטרופיה שבה נעשה שימוש, ופונקציית המיקסום צריכה להיות מאובטחת, במובן שאם ה-RNG מקבל נתונים (מכל מקור) שהתוקף לא יכול לחזות (או לשלוט בהם), הפלט של ה-RNG לא ניתן להבדיל מנתונים אקראיים. לכן, אם האנטרופיה מכל מקור טובה, הפלט יהיה טוב.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] נתונים נתונים אקראיים שרוצים לערבב.
[in] data_length אורך של data .

ההגדרה מופיעה בשורה 242 בקובץ keymaster1.h .

keymaster_error_t (* begin)(const struct keymaster1_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 *operation_handle)

התחלת פעולה קריפטוגרפית באמצעות המפתח שצוין. אם הכל תקין, הפונקציה begin() תחזיר את הערך KM_ERROR_OK ותיצור טיפול בפעולה, שצריך להעביר לקריאות הבאות ל- update() , finish() או abort() .

חשוב מאוד שכל קריאה ל- begin()‎ תהיה מותאמת לקריאה הבאה ל- finish()‎ או ל- abort()‎ , כדי לאפשר להטמעה של Keymaster לנקות את כל מצב הפעולה הפנימי. אם לא עושים זאת, יכול להיות שיהיה זליגת מידע במרחב המצב הפנימי או במשאבים פנימיים אחרים, ובסופו של דבר הפונקציה begin()‎ תחזיר את הערך KM_ERROR_TOO_MANY_OPERATIONS כשנגמר המרחב לפעולות. כל תוצאה שאינה KM_ERROR_OK מ- begin() , update() או finish() גורמת לביטול האופרטורה באופן משתמע, במקרה כזה לא צריך להפעיל את abort() (אם תפעילו אותה, תקבלו את הערך KM_ERROR_INVALID_OPERATION_HANDLE).

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] מטרה מטרת הפעולה, אחת מהאפשרויות הבאות: KM_PURPOSE_ENCRYPT, ‏ KM_PURPOSE_DECRYPT, ‏ KM_PURPOSE_SIGN או KM_PURPOSE_VERIFY. שימו לב שבמצבי AEAD, הצפנה ופענוח כוללים חתימה ואימות, בהתאמה, אבל צריך לציין אותם כ-KM_PURPOSE_ENCRYPT ו-KM_PURPOSE_DECRYPT.
[in] מפתח המפתח שישמש לביצוע הפעולה. key חייב להיות בעל מטרה תואמת ל- purpose וכל דרישות השימוש שלו חייבות להתקיים, אחרת begin()‎ תחזיר קוד שגיאה מתאים.
[in] 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. לפעולות AEAD, הערך KM_TAG_CHUNK_SIZE מצוין כאן.
[out] out_params פרמטרים של פלט. משמש להחזרת נתונים נוספים מהפעלת הפעולה, במיוחד להחזרת ה-IV או ה-nonce מפעולות שיוצרות IV או nonce. מבצע הקריאה מקבל בעלות על מערך הפרמטרים של הפלט, וצריך לפנות אותו באמצעות keymaster_free_param_set() . אפשר להגדיר את out_params כ-NULL אם לא צפויים פרמטרים של פלט. אם out_params הוא NULL, ופרמטרים של פלט נוצרים, הפונקציה begin()‎ תחזיר את הערך KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] operation_handle ה-handle של הפעולה שנוצרה, שצריך להעביר ל- update()‎ , ל- finish()‎ או ל- abort()‎ . אם הערך של operation_handle הוא NULL, הפונקציה begin()‎ תחזיר את הערך KM_ERROR_OUTPUT_PARAMETER_NULL.

ההגדרה נמצאת בשורה 451 בקובץ keymaster1.h .

uint32_t client_version

האפשרות הזו הוצאה משימוש. במקום זאת, צריך להשתמש בשדות החדשים module_api_version ו-hal_api_version בהפעלה של keymaster_module.

ההגדרה מופיעה בשורה 41 בקובץ keymaster1.h .

struct hw_device_t common

שיטות נפוצות של מכשיר ה-keymaster. הוא חייב להיות המאפיין הראשון של keymaster_device, כי משתמשים במבנה הזה יבצעו המרה של hw_device_t למצביע keymaster_device בהקשרים שבהם ידוע ש- hw_device_t מפנה ל-keymaster_device.

ההגדרה מופיעה בשורה 35 בקובץ keymaster1.h .

void* context

ההגדרה מופיעה בשורה 48 בקובץ keymaster1.h .

int(* delete_all)(const struct keymaster1_device *dev)
הוצא משימוש:
מחיקת כל המפתחות במאגר המפתחות בחומרה. משמש כשמאגר המפתחות מתאפס לחלוטין.

הפונקציה הזו היא אופציונלית, וצריך להגדיר אותה ל-NULL אם היא לא מיושמת.

הפונקציה מחזירה 0 אם הפעולה בוצעה בהצלחה, או קוד שגיאה שקטן מ-0.

ההגדרה מופיעה בשורה 100 בקובץ keymaster1.h .

keymaster_error_t (* delete_all_keys)(const struct keymaster1_device *dev)

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

הפונקציה הזו היא אופציונלית, וצריך להגדיר אותה ל-NULL אם היא לא מיושמת.

פרמטרים
[in] dev המבנה של מכשיר keymaster.

ההגדרה מופיעה בשורה 407 בקובץ keymaster1.h .

keymaster_error_t (* delete_key)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)

מחיקה של המפתח או של צמד המפתחות שמשויך ל-blob של המפתח. אחרי הקריאה לפונקציה הזו לא תהיה אפשרות להשתמש במפתח לפעולות אחרות. אפשר להחיל אותו על מפתחות משורשי אמון זרים (מפתחות שלא ניתן להשתמש בהם בשורש האמון הנוכחי).

הפונקציה הזו היא אופציונלית, וצריך להגדיר אותה ל-NULL אם היא לא מיושמת.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] מפתח המפתח שרוצים למחוק.

ההגדרה מופיעה בשורה 395 בקובץ keymaster1.h .

int(* delete_keypair)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
הוצא משימוש:
מחיקת צמד המפתחות שמשויך ל-blob של המפתח.

הפונקציה הזו היא אופציונלית, וצריך להגדיר אותה ל-NULL אם היא לא מיושמת.

הפונקציה מחזירה 0 אם הפעולה בוצעה בהצלחה, או קוד שגיאה שקטן מ-0.

ההגדרה מופיעה בשורה 88 בקובץ keymaster1.h .

keymaster_error_t (* export_key)(const struct keymaster1_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 *export_data)

ייצוא מפתח ציבורי, והחזרת מערך בייט בפורמט שצוין.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] export_format הפורמט שבו ישמש לייצוא המפתח.
[in] key_to_export המפתח לייצוא.
[out] export_data חומר המפתח שיוצא. מבצע הקריאה החוזרת מקבל את הבעלות.
[out] export_data_length האורך של export_data .

ההגדרה מופיעה בשורה 377 בקובץ keymaster1.h .

keymaster_error_t (* finish)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

הפונקציה מסיימת פעולה קריפטוגרפית שהתחילה ב- begin()‎ ומבטלת את התוקף של operation_handle .

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] operation_handle ה-handle של הפעולה שמוחזר על ידי begin() . הכינוי הזה יבוטל.
[in] params פרמטרים נוספים של הפעולה. במצבים של AEAD, השדה הזה משמש לציון KM_TAG_ADDITIONAL_DATA, אבל רק אם לא סיפקו נתוני קלט ל- update()‎ .
[in] חתימה החתימה שצריך לאמת אם המטרה שצוינה בקריאה ל- begin()‎ הייתה KM_PURPOSE_VERIFY.
[out] output נתוני הפלט, אם יש כאלה. מבצע הקריאה החוזרת מקבל בעלות על המאגר שהוקצה.

אם הפעולה שמסתיימת היא אימות חתימה או פענוח במצב AEAD והאימות נכשל, הפונקציה finish()‎ תחזיר את הערך KM_ERROR_VERIFICATION_FAILED.

ההגדרה מופיעה בשורה 521 בקובץ keymaster1.h .

דגלים מסוג uint32_t

אפשר לעיין בדגלים שהוגדרו עבור keymaster0_devices::flags בקובץ keymaster_common.h

ההגדרה מופיעה בשורה 46 בקובץ keymaster1.h .

keymaster_error_t (* generate_key)(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics)

יצירת מפתח או זוג מפתחות, והחזרת blob של מפתח ו/או תיאור של המפתח.

פרמטרים ליצירת מפתחות מוגדרים כצמדי תג/ערך של מפתחות ראשיים, שמוצגים בקטע 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
פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] params מערך של פרמטרים ליצירת מפתחות.
[in] params_count אורך של params .
[out] key_blob מחזירה את המפתח שנוצר. הערך של key_blob חייב להיות שונה מ-NULL. מבצע הקריאה החוזרת מקבל בעלות על key_blob->key_material וצריך לבצע את הפונקציה free() עליו.
[out] מאפיינים הפונקציה מחזירה את המאפיינים של המפתח שנוצר, אם הוא לא NULL. אם הערך לא NULL, מבצע הקריאה החוזרת מקבל את הבעלות ועליו לבצע את הפעולה keymaster_free_characteristics() כדי לפנות את המכסה. חשוב לזכור שהמאפיינים KM_TAG_ROOT_OF_TRUST, ‏ KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA אף פעם לא מוחזרים.

ההגדרה מופיעה בשורה 282 בקובץ keymaster1.h .

int(* generate_keypair)(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length)
הוצא משימוש:
יוצר מפתח ציבורי ומפתח פרטי. ה-key-blob המוחזר הוא אטום, וצריך לספק אותו לאחר מכן לצורך חתימה ואימות.

הפונקציה מחזירה: 0 אם הפעולה בוצעה בהצלחה או קוד שגיאה שקטן מ-0.

ההגדרה מופיעה בשורה 56 בקובץ keymaster1.h .

keymaster_error_t (* get_key_characteristics)(const struct keymaster1_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)

הפונקציה מחזירה את המאפיינים של המפתח שצוין, או את הערך KM_ERROR_INVALID_KEY_BLOB אם המפתח key_blob לא תקין (ההטמעות צריכות לאמת באופן מלא את תקינות המפתח). הערכים של client_id ו-app_data חייבים להיות המזהה והנתונים שסופקו כשהמפתח נוצר או יובא, או ריקים אם לא צוינו הערכים KM_TAG_APPLICATION_ID ו/או KM_TAG_APPLICATION_DATA במהלך היצירה. הערכים האלה לא נכללים במאפיינים שמוחזרים. מבצע הקריאה החוזרת מקבל בעלות על אובייקט המאפיינים שהוקצה, וצריך לבטל את ההקצאה שלו באמצעות keymaster_free_characteristics() .

חשוב לזכור שהמאפיינים KM_TAG_ROOT_OF_TRUST, ‏ KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA אף פעם לא מוחזרים.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] key_blob המפתח שממנו מאתרים את המאפיינים.
[in] client_id נתוני מזהה הלקוח, או NULL אם לא שויך מזהה לקוח.
[in] app_id נתוני האפליקציה, או NULL אם לא שויך אף נתון.
[out] מאפיינים המאפיינים העיקריים.

ההגדרה מופיעה בשורה 309 בקובץ keymaster1.h .

int(* get_keypair_public)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length)
הוצא משימוש:
מקבלת את החלק של המפתח הציבורי מזוג מפתחות. המפתח הציבורי חייב להיות מערך בייטים בקידוד X.509 (תקן Java).

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

ההגדרה מופיעה בשורה 76 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_algorithms)(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length)

אחזור האלגוריתמים הנתמכים.

פרמטרים
[in] dev המבנה של מכשיר ה-Keymaster.
[out] אלגוריתמים מערך של אלגוריתמים נתמכים. מבצע הקריאה מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] algorithms_length אורך של algorithms .

ההגדרה מופיעה בשורה 133 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_block_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length)

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

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] אלגוריתם האלגוריתם שעבורו יוחזרו המצבים הנתמכים.
[out] מצבים מערך של מצבים נתמכים. מבצע הקריאה החוזרת מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] modes_length אורך של modes .

ההגדרה מופיעה בשורה 149 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_digests)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length)

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

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] אלגוריתם האלגוריתם שעבורו יוחזרו סיכומי דוחות נתמכים.
[out] תקצירים יש תמיכה במערך של סיכומי נתונים. מבצע הקריאה מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] digests_length אורך של digests .

ההגדרה נמצאת בשורה 187 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_export_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

הפונקציה מקבלת את פורמטים הייצוא של המפתחות הנתמכים למפתחות של האלגוריתם שצוין. מבצע הקריאה מקבל בעלות על המערך שהוקצה.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] אלגוריתם האלגוריתם שעבורו יחזרו הפורמטים הנתמכים.
[out] פורמטים מערך של פורמטים נתמכים. מבצע הקריאה מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] formats_length אורך של formats .

ההגדרה מופיעה בשורה 224 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_import_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length)

הפונקציה מקבלת את הפורמטים הנתמכים לייבוא מפתחות של מפתחות מהאלגוריתם שצוין. מבצע הקריאה מקבל בעלות על המערך שהוקצה.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] אלגוריתם האלגוריתם שעבורו יחזרו הפורמטים הנתמכים.
[out] פורמטים מערך של פורמטים נתמכים. מבצע הקריאה מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] formats_length אורך של formats .

ההגדרה מופיעה בשורה 206 בקובץ keymaster1.h .

keymaster_error_t (* get_supported_padding_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length)

הפונקציה מקבלת את מצבי המילוי הנתמכים לאלגוריתם שצוין. מבצע הקריאה מקבל בעלות על המערך שהוקצה.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] אלגוריתם האלגוריתם שעבורו יוחזרו מצבי המילוי הנתמכים.
[out] מצבים מערך של מצבי ריבועים נתמכים. מבצע הקריאה מקבל בעלות על המערך וצריך לבצע את הפונקציה free() עליו.
[out] modes_length אורך של modes .

ההגדרה מופיעה בשורה 168 בקובץ keymaster1.h .

keymaster_error_t (* import_key)(const struct keymaster1_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_t **characteristics)

ייבוא של מפתח או של זוג מפתחות, עם החזרת blob של מפתח ו/או תיאור של המפתח.

רוב הפרמטרים של ייבוא מפתחות מוגדרים כצמדי תג/ערך של 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_KEY_SIZE יהיה בגודל של המפתח שסופק.
  • הערך שמוגדר כברירת מחדל של KM_TAG_RSA_PUBLIC_EXPONENT הוא הערך במפתח שסופק (למפתחות RSA)

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

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,‎
  • KM_TAG_CREATION_DATETIME
פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] params פרמטרים שמגדירים את המפתח שייבא.
[in] params_count מספר הרשומות ב- params .
[in] key_format מציין את הפורמט של נתוני המפתח ב-key_data.
[out] key_blob משמש להחזרת blob המפתח האטום. השדה לא יכול להיות NULL. מבצע הקריאה החוזרת מקבל בעלות על חומר המפתח שמכיל.
[out] מאפיינים משמש להחזרת המאפיינים של המפתח שיובאו. יכול להיות ערך NULL, ובמקרה כזה לא יוחזרו מאפיינים. אם הערך לא NULL, מבצע הקריאה החוזרת מקבל את הבעלות ועליו לבצע את הפעולה keymaster_free_characteristics() כדי לפנות את המכסה. חשוב לזכור שהמאפיינים KM_TAG_ROOT_OF_TRUST, ‏ KM_TAG_APPLICATION_ID ו-KM_TAG_APPLICATION_DATA אף פעם לא מוחזרים.

ההגדרה מופיעה בשורה 357 בקובץ keymaster1.h .

int(* import_keypair)(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length)
הוצא משימוש:
ייבוא של זוג מפתחות ציבורי ופרטי. המפתחות המיובאים יהיו בפורמט PKCS#8 עם קידוד DER (תקן Java). ה-key-blob המוחזר הוא אטום, והוא יועבר לאחר מכן לצורך חתימה ואימות.

הפונקציה מחזירה: 0 אם הפעולה בוצעה בהצלחה או קוד שגיאה שקטן מ-0.

ההגדרה מופיעה בשורה 66 בקובץ keymaster1.h .

int(* sign_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length)
הוצא משימוש:
החתמה על נתונים באמצעות blob של מפתח שנוצר קודם. אפשר להשתמש במפתח אסימטרי או במפתח סודי.

הפונקציה מחזירה: 0 אם הפעולה בוצעה בהצלחה או קוד שגיאה שקטן מ-0.

ההגדרה מופיעה בשורה 108 בקובץ keymaster1.h .

keymaster_error_t (* update)(const struct keymaster1_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_params, keymaster_blob_t *output)

ה-delegate מספק נתונים לפעולה קריפטוגרפית מתמשכת שהתחילה באמצעות begin() , ויכול לקבל ממנה פלט.

אם הערך של operation_handle לא תקין, הפונקציה update()‎ תחזיר את הערך KM_ERROR_INVALID_OPERATION_HANDLE.

יכול להיות ש- update() לא יעשה שימוש בכל הנתונים שסופקו במאגר הנתונים. update() תחזיר את כמות הנתונים שנצרכו ב-*data_consumed. מבצע הקריאה צריך לספק את הנתונים שלא נצרכו בקריאה הבאה.

פרמטרים
[in] dev המבנה של מכשיר keymaster.
[in] operation_handle ה-handle של הפעולה שמוחזר על ידי begin() .
[in] in_params פרמטרים נוספים של הפעולה. במצבים של AEAD, השדה הזה משמש לציון KM_TAG_ADDITIONAL_DATA. שימו לב שאפשר לספק נתונים נוספים במספר קריאות ל- update()‎ , אבל רק עד שמספקים את נתוני הקלט.
[in] קלט הנתונים לעיבוד, בהתאם לפרמטרים שהוגדרו בקריאה ל- begin()‎ . שימו לב ש- update()‎ עשויה או לא עשויה להשתמש בכל הנתונים שסופקו. מידע נוסף זמין במאמר input_consumed .
[out] input_consumed כמות הנתונים שנצרכו על ידי update()‎ . אם הסכום הזה נמוך מסכום הבקשה, מבצע הקריאה צריך לספק את היתרה בקריאה הבאה ל- update()‎ .
[out] out_params פרמטרים של פלט. משמש להחזרת נתונים נוספים מהפעולה. מבצע הקריאה החוזרת מקבל בעלות על מערך הפרמטרים של הפלט, ועליו לפנות אותו באמצעות keymaster_free_param_set() . אפשר להגדיר את out_params כ-NULL אם לא צפויים פרמטרים של פלט. אם out_params הוא NULL, ופרמטרים של פלט נוצרים, הפונקציה begin()‎ תחזיר את הערך KM_ERROR_OUTPUT_PARAMETER_NULL.
[out] output נתוני הפלט, אם יש כאלה. מבצע הקריאה מקבל בעלות על המאגר שהוקצה. הפלט לא יכול להיות NULL.

שימו לב ש- update()‎ עשויה לא לספק פלט. במקרה כזה, הערך של output->data_length יהיה אפס, ו-output->data יכול להיות NULL או באורך אפס (לכן מבצע הקריאה צריך תמיד לבצע free()‎ עליו).

ההגדרה מופיעה בשורה 495 בקובץ keymaster1.h .

int(* verify_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length)
הוצא משימוש:
אימות נתונים שנחתמו באמצעות blob של מפתח. אפשר להשתמש במפתח אסימטרי או במפתח סודי.

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

ההגדרה מופיעה בשורה 118 בקובץ keymaster1.h .

התיעוד של המבנה הזה נוצר מהקובץ הבא: