ฟังก์ชันคีย์มาสเตอร์

หน้านี้แสดงรายละเอียดเพื่อช่วยเหลือผู้ที่ติดตั้งใช้งาน Keymaster เลเยอร์นามธรรมฮาร์ดแวร์ (HAL) ซึ่งครอบคลุมแต่ละฟังก์ชันในส่วน API และเวอร์ชัน Keymaster ที่ฟังก์ชันนั้นพร้อมใช้งานใน และ จะอธิบายการใช้งานเริ่มต้น สำหรับแท็ก โปรดดูส่วน แท็ก Keymaster

หลักเกณฑ์การใช้งานทั่วไป

ทุกฟังก์ชันใน API จะต้องปฏิบัติตามหลักเกณฑ์ต่อไปนี้

พารามิเตอร์ตัวชี้อินพุต

เวอร์ชัน: 1, 2

พารามิเตอร์ตัวชี้อินพุตที่ไม่ได้ใช้สำหรับการเรียกที่ระบุอาจ NULL ผู้โทรไม่จำเป็นต้องระบุตัวยึดตำแหน่ง เช่น คีย์บางประเภทและโหมดอาจไม่ใช้ค่าใดๆ จาก inParams เป็น begin ดังนั้นผู้โทรอาจ ตั้งค่า 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 ไม่เป็นไปตาม ไม่สำเร็จในกรณีดังกล่าวหรือดำเนินการวินิจฉัย ใช้คีย์ขนาดเล็กเกินไป การกำหนดพารามิเตอร์อินพุตที่ไม่เกี่ยวข้อง การใช้ IV หรือ nonces ซ้ำ การสร้างคีย์โดยไม่มีวัตถุประสงค์ใดๆ (จึงไร้ประโยชน์) และไม่ควรจะมี วินิจฉัยจากการติดตั้งใช้งาน การละเว้นพารามิเตอร์ที่จำเป็น ข้อกำหนดของ พารามิเตอร์ที่จำเป็นไม่ถูกต้อง และต้องวินิจฉัยข้อผิดพลาดที่คล้ายกัน

เฟรมเวิร์ก และคีย์สโตร์ของ Android มีหน้าที่ดังนี้ ตรวจสอบว่าการเรียกโมดูล Keymaster มีเหตุผลและเป็นประโยชน์

ฟังก์ชัน

รับฟีเจอร์ฮาร์ดแวร์

เวอร์ชัน: 3

เมธอด getHardwareFeatures ใหม่จะแสดงให้ลูกค้าบางส่วนเห็น ลักษณะสำคัญของฮาร์ดแวร์ความปลอดภัยพื้นฐาน เมธอดนี้ไม่ต้องใช้อาร์กิวเมนต์และแสดงผลค่า 4 ค่า โดยเป็นบูลีนทั้งหมด ดังนี้

• isSecure มีค่าเป็น true หากเก็บคีย์ไว้ใน ฮาร์ดแวร์ที่ปลอดภัย (TEE ฯลฯ) ไว้เสมอ
• supportsEllipticCurve มีค่าเป็น true หาก ฮาร์ดแวร์รองรับการเข้ารหัสแบบ Elliptic Curve ด้วยเส้นโค้ง NIST (P-224 P-256, P-384 และ P-521)
• supportsSymmetricCryptographytrue ในกรณีที่ฮาร์ดแวร์รองรับวิทยาการเข้ารหัสแบบสมมาตร ซึ่งรวมถึง 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 เนื่องจากข้อมูลนี้มีอยู่ในไฟล์คุณสมบัติของระบบ และผู้ผลิต จะอ่านไฟล์ดังกล่าวระหว่างเริ่มต้นได้

กำหนดค่าคีย์มาสเตอร์ ระบบจะเรียกวิธีนี้เพียงครั้งเดียวหลังจากเปิดอุปกรณ์ และก่อนที่จะนำไปใช้ ใช้เพื่อ KM_TAG_OS_VERSION และ KM_TAG_OS_PATCHLEVEL ถึง คีย์มาสเตอร์ เมธอดอื่นๆ ทั้งหมดจะแสดงผล จนกว่าจะมีการเรียกใช้เมธอดนี้ KM_ERROR_KEYMASTER_NOT_CONFIGURED ค่าที่ระบุโดย คีย์มาสเตอร์จะยอมรับเมธอดได้เพียงครั้งเดียวต่อการเปิดเครื่อง ลำดับต่อมา โทรกลับ KM_ERROR_OK แต่ไม่ทำอะไรเลย

การใช้งานคีย์มาสเตอร์ใช้ฮาร์ดแวร์ที่ปลอดภัยและเป็นเวอร์ชันระบบปฏิบัติการหรือไม่ ค่าระดับแพตช์ที่ระบุไม่ตรงกับค่าที่ให้ไว้กับ ฮาร์ดแวร์โดย Bootloader (หรือหาก Bootloader ไม่ระบุค่า) เมธอดนี้จะส่งคืน 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);

เพิ่มRngEntropy

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ add_rng_entropy และเปลี่ยนชื่อใน Keymaster 3

เพิ่มเอนโทรปีที่ได้จากผู้โทรไปยังพูลที่การใช้งาน Keymaster 1 ใช้ สำหรับสร้างตัวเลขแบบสุ่ม สำหรับคีย์ IV ฯลฯ

การติดตั้งใช้งาน Keymaster ต้องผสมผสานสัญญาณที่ให้ไว้อย่างปลอดภัย เอนโทรปีลงในพูลของมัน ซึ่งจะต้องมี เอนโทรปีที่สร้างขึ้นภายในจากเครื่องมือสร้างหมายเลขสุ่มของฮาร์ดแวร์ ควรจัดการการผสมผสานเพื่อให้ผู้โจมตีที่ควบคุมได้โดยสมบูรณ์ ของบิตที่ให้ไว้ addRngEntropy หรือที่ฮาร์ดแวร์สร้างขึ้น แต่ไม่ใช่ทั้ง 2 การตั้งค่า ไม่มีข้อได้เปรียบที่ไม่ส่งผลเสียในการคาดการณ์ส่วนบิต ที่สร้างขึ้นจากเอนโทรปีพูล

การติดตั้งใช้งาน Keymaster ที่พยายามจะประมาณเอนโทรปีใน พูลภายในจะถือว่าข้อมูลมาจาก addRngEntropy ไม่มีเอนโทรปี การติดตั้งใช้งาน Keymaster อาจ แสดงผล ErrorCode::INVALID_INPUT_LENGTH หากได้รับโฆษณามากกว่า 2 KiB ของข้อมูลในการโทรครั้งเดียว

คีย์สร้าง

เวอร์ชัน: 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 ตามลำดับ

แท็ก::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 ระบุความยาวขั้นต่ำของ MAC ที่สร้างหรือยืนยันได้ด้วยคีย์นี้ ค่าคือ ผลคูณของ 8 และอย่างน้อย 64
• แท็ก::DIGEST ระบุอัลกอริทึมไดเจสต์สำหรับคีย์ ตรงทั้งหมด ระบุไดเจสต์ 1 รายการ มิเช่นนั้นให้แสดงผล ErrorCode::UNSUPPORTED_DIGEST หากระบบไม่รองรับไดเจสต์ โดย Trustlet ส่งคืน ErrorCode::UNSUPPORTED_DIGEST

ลักษณะสำคัญ

หากอาร์กิวเมนต์ลักษณะไม่ใช่ค่าว่าง generateKey จะแสดงผล ลักษณะของคีย์ที่สร้างขึ้นใหม่โดยแบ่งอย่างเหมาะสม รายการที่ใช้ฮาร์ดแวร์และซอฟต์แวร์ โปรดดู getKeyCharacteristics สำหรับคำอธิบาย ว่าลักษณะเฉพาะใดบ้างที่อยู่ในลิสต์ ลักษณะเฉพาะที่แสดงผล รวมพารามิเตอร์ทั้งหมดที่ระบุให้กับการสร้างคีย์ ยกเว้น แท็ก::APPLICATION_ID และ แท็ก::APPLICATION_DATA หากแท็กเหล่านี้รวมอยู่ในพารามิเตอร์หลัก แท็กดังกล่าวจะถูกนำออกจาก ลักษณะที่แสดงขึ้นมาเพื่อไม่ให้ค้นหาค่า โดยการตรวจสอบ BLOB คีย์ที่แสดงผล อย่างไรก็ตาม คุกกี้ดังกล่าวอยู่ภายใต้การเข้ารหัส ลงใน BLOB คีย์ เพื่อที่ว่าหากไม่มีการระบุค่าที่ถูกต้องเมื่อคีย์ ใช้แล้ว การใช้งานล้มเหลว ในทำนองเดียวกัน Tag::ROOT_OF_TRUST คือ เชื่อมโยงกับคีย์แบบเข้ารหัส แต่ไม่สามารถระบุได้ระหว่าง การสร้างหรือนำเข้าคีย์และไม่มีการส่งคืน

นอกจากแท็กที่มีให้ Trustlet ยัง เพิ่ม Tag::ORIGIN, ที่มีค่า KeyOrigin::GENERATED และหากคีย์ป้องกันการย้อนกลับได้

Tag::ROLLBACK_RESISTANT

ป้องกันการย้อนกลับ

การป้องกันการย้อนกลับหมายถึงเมื่อลบคีย์ด้วย deleteKeyหรือ deleteAllKeys ซึ่งมีการรับประกันโดยฮาร์ดแวร์ที่ปลอดภัย ใช้งานไม่ได้อีก โดยทั่วไปการติดตั้งใช้งานที่ไม่มีการปฏิเสธการย้อนกลับ ส่งคืนเนื้อหาคีย์ที่สร้างขึ้นหรือนำเข้าไปยังผู้โทรเป็น BLOB คีย์ ที่มีการเข้ารหัสและตรวจสอบสิทธิ์แล้ว เมื่อคีย์สโตร์ลบ BLOB คีย์ คีย์นั้นจะ หายไป แต่ผู้โจมตีที่ก่อนหน้านี้สามารถสืบค้นเนื้อหาสำคัญดังกล่าวได้ อาจคืนค่าการเข้าถึงไปยังอุปกรณ์ได้

คีย์ป้องกันการย้อนกลับหากฮาร์ดแวร์ที่ปลอดภัยรับประกันว่าถูกลบไปแล้ว คีย์จะกู้คืนในภายหลังไม่ได้ ซึ่งโดยทั่วไปจะทำโดยการจัดเก็บคีย์เพิ่มเติม ข้อมูลเมตาในตำแหน่งที่เชื่อถือได้ซึ่งผู้โจมตีไม่สามารถดัดแปลงได้ เปิด อุปกรณ์เคลื่อนที่ ซึ่งกลไกนี้มักใช้การเล่นซ้ำหน่วยความจำที่มีการป้องกัน การบล็อก (RPMB) เนื่องจากหลักๆ แล้ว จำนวนคีย์ที่อาจสร้างขึ้นได้ ไม่จำกัดและพื้นที่เก็บข้อมูลที่เชื่อถือได้ซึ่งใช้สำหรับการป้องกันการย้อนกลับอาจมีจำกัด จะต้องใช้วิธีนี้ได้สำเร็จแม้จะมีการต้านทานย้อนกลับ ไม่สามารถให้คีย์ใหม่ ในกรณีดังกล่าว แท็ก::ROLLBACK_RESISTANT ไม่ควรเพิ่มไว้ในลักษณะเด่น

getKeyCharacteristics

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ get_key_characteristics และเปลี่ยนชื่อใน Keymaster 3

แสดงผลพารามิเตอร์และการให้สิทธิ์ที่เชื่อมโยงกับคีย์ที่ระบุ จะแบ่งออกเป็น 2 ชุด ได้แก่ แบบใช้ฮาร์ดแวร์กับซอฟต์แวร์ คำอธิบาย ค่าต่อไปนี้จะมีผลกับรายการลักษณะสำคัญที่แสดงโดย generateKey และ importKey

หากระบุ Tag::APPLICATION_ID ในระหว่างการสร้างคีย์ หรือนำเข้า ระบบจะระบุค่าเดียวกันให้กับ เมธอดนี้ในอาร์กิวเมนต์ clientId มิเช่นนั้น แอตทริบิวต์ เมธอดจะแสดง ErrorCode::INVALID_KEY_BLOB ในทำนองเดียวกัน หากมีการจัดเตรียม Tag::APPLICATION_DATA ไว้ระหว่างการสร้าง หรือนำเข้า ระบบจะระบุค่าเดียวกันให้กับ เมธอดนี้ในอาร์กิวเมนต์ appData

ลักษณะที่แสดงโดยวิธีการนี้จะอธิบายประเภทและ ของคีย์ที่ระบุ

กฎทั่วไปในการตัดสินว่าแท็กหนึ่งๆ เป็นของแท็ก รายการที่บังคับใช้ด้วยฮาร์ดแวร์หรือซอฟต์แวร์ คือถ้าความหมายของแท็ก ด้วยฮาร์ดแวร์ที่ปลอดภัย มั่นใจได้ทุกอย่าง เพราะมีการบังคับใช้ด้วยฮาร์ดแวร์ มิเช่นนั้น มีการบังคับใช้ซอฟต์แวร์ ด้านล่างนี้คือรายการของแท็กเฉพาะซึ่งมีการจัดสรรที่ถูกต้อง อาจไม่ชัดเจน

• แท็ก::อัลกอริทึม แท็ก::KEY_SIZE, และ Tag::RSA_PUBLIC_EXPONENT เป็นคุณสมบัติเฉพาะของคีย์ สำหรับคีย์ที่ฮาร์ดแวร์รักษาความปลอดภัย แท็กเหล่านี้จะอยู่ในรายการที่บังคับใช้ด้วยฮาร์ดแวร์
• ค่า Tag::DIGEST ที่ฮาร์ดแวร์ที่ปลอดภัยรองรับจะอยู่ใน รายการที่ฮาร์ดแวร์สนับสนุน ไดเจสต์ที่ไม่รองรับจะอยู่ในรายการที่ซอฟต์แวร์รองรับ
• ค่า Tag::PADDING จะอยู่ในรายการที่สนับสนุนฮาร์ดแวร์ ยกเว้นกรณีที่มี เป็นไปได้ว่าซอฟต์แวร์อาจต้องทำโหมดระยะห่างจากขอบที่เจาะจง ในกรณีนี้ แอปดังกล่าวจะอยู่ในรายการที่ซอฟต์แวร์บังคับใช้ ที่เป็นไปได้ เกิดขึ้นสำหรับคีย์ RSA ที่อนุญาตระยะห่างจากขอบของ PSS หรือ OAEP กับอัลกอริทึมไดเจสต์ ที่ฮาร์ดแวร์การรักษาความปลอดภัยไม่สนับสนุน
• แท็ก::USER_SECURE_ID และแท็ก::USER_AUTH_TYPE บังคับใช้ฮาร์ดแวร์เฉพาะเมื่อการตรวจสอบสิทธิ์ผู้ใช้มีการบังคับใช้ด้วยฮาร์ดแวร์เท่านั้น ถึง คีย์มาสเตอร์ และการตรวจสอบสิทธิ์ที่เกี่ยวข้อง ทั้ง Trustlet ต้องปลอดภัยและแชร์คีย์ HMAC ลับที่ใช้ในการลงนาม ตรวจสอบโทเค็นการตรวจสอบสิทธิ์ โปรดดู หน้าการตรวจสอบสิทธิ์เพื่อดูรายละเอียด
• แท็ก::ACTIVE_DATETIME, แท็ก::ORIGINATION_EXPIRE_DATETIME, และแท็ก Tag::USAGE_EXPIRE_DATETIME ต้องมีการเข้าถึงนาฬิกาติดผนังที่ยืนยันได้ว่าถูกต้อง ฮาร์ดแวร์ที่ปลอดภัยที่สุด มีสิทธิ์เข้าถึงเฉพาะข้อมูลเวลาจากระบบปฏิบัติการที่ไม่ปลอดภัย หมายความว่าแท็กมีการบังคับใช้ด้วยซอฟต์แวร์
• แท็ก::ORIGIN คือ อยู่ในรายการฮาร์ดแวร์เสมอสำหรับคีย์ที่เชื่อมโยงกับฮาร์ดแวร์ การมีอยู่ของโซลูชัน คือการที่เลเยอร์ที่สูงขึ้นพิจารณาว่าคีย์เป็นคีย์สำรอง

คีย์นำเข้า

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ import_key และเปลี่ยนชื่อใน Keymaster 3

นำเข้าเนื้อหาคีย์ไปยังฮาร์ดแวร์ Keymaster พารามิเตอร์คำจำกัดความคีย์และ มีการจัดการลักษณะเอาต์พุตเช่นเดียวกับ generateKey โดยมีข้อยกเว้นต่อไปนี้

• แท็ก::KEY_SIZE และ แท็ก::RSA_PUBLIC_EXPONENT (สำหรับคีย์ RSA เท่านั้น) ไม่จำเป็นในพารามิเตอร์อินพุต หากไม่ได้ระบุ Trustlet จะอนุมานค่าจากเนื้อหาคีย์ที่ระบุและเพิ่ม แท็กและค่าที่เหมาะสมกับลักษณะคีย์ หากพารามิเตอร์คือ ที่ให้ไว้ ความน่าเชื่อถือจะตรวจสอบความถูกต้องของข้อมูลกับเนื้อหาของคีย์ ใน เหตุการณ์ที่ไม่ตรงกัน เมธอดจะแสดง ErrorCode::IMPORT_PARAMETER_MISMATCH
• แท็ก::ORIGIN ที่แสดงผลมี ค่าเดียวกับ KeyOrigin::IMPORTED

ExportKey

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ export_key และเปลี่ยนชื่อใน Keymaster 3

ส่งออกคีย์สาธารณะจากคู่คีย์ RSA หรือ EC ของ Keymaster

หากระบุ Tag::APPLICATION_ID ระหว่างการสร้างคีย์ หรือ ระบบจะระบุค่าเดียวกันให้กับเมธอดนี้ใน อาร์กิวเมนต์ clientId มิฉะนั้น ระบบจะแสดงเมธอด ErrorCode::INVALID_KEY_BLOB ในทำนองเดียวกัน หาก Tag::APPLICATION_DATA มีการระบุระหว่างการสร้างหรือการนําเข้า ค่าเดียวกันจะมีการระบุให้กับ เมธอดนี้ในอาร์กิวเมนต์ appData

คีย์ลบ

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ delete_key และเปลี่ยนชื่อใน Keymaster 3

ลบคีย์ที่ระบุ วิธีนี้เป็นขั้นตอนที่ไม่บังคับ และมีเพียง ซึ่งติดตั้งใช้งานโดยโมดูล Keymaster ที่ให้การป้องกันย้อนกลับ

deleteAllKeys

เวอร์ชัน: 1, 2, 3

ฟังก์ชันนี้เปิดตัวใน Keymaster 1 ในชื่อ delete_all_keys และเปลี่ยนชื่อใน Keymaster 3

ลบคีย์ทั้งหมด วิธีการนี้เป็นแบบไม่บังคับ และจะใช้เฉพาะ โดยโมดูล Keymaster ที่มอบความต้านทานการย้อนกลับ

รหัสการรับรองการทำลาย

เวอร์ชัน: 3

เมธอด destroyAttestationIds() ใช้เพื่อ ปิดใช้โฆษณาใหม่ (ไม่บังคับแต่แนะนำอย่างยิ่ง) เอกสารรับรองรหัส หาก TEE ไม่มีวิธีที่จะมั่นใจได้ว่าเอกสารรับรองของรหัสอย่างถาวร ปิดใช้หลังจากเรียกใช้เมธอดนี้ เอกสารรับรองรหัสจะต้องไม่ใช่ เลย ซึ่งในกรณีนี้ วิธีการนี้ไม่ดำเนินการใดๆ และ แสดงผล ErrorCode::UNIMPLEMENTED หากเอกสารรับรองรหัสคือ รองรับ ต้องมีการติดตั้งใช้งานวิธีนี้และต้องปิดใช้อย่างถาวร ความพยายามในการรับรองรหัสทั้งหมดในอนาคต วิธีการนี้อาจเรียกว่าจำนวนใดก็ได้ของ ครั้ง หากปิดใช้เอกสารรับรองรหัสอย่างถาวรแล้ว เมธอดจะ ไม่มีผลลัพธ์และแสดงผล ErrorCode::OK

รหัสข้อผิดพลาดเดียวที่วิธีนี้อาจแสดงได้คือ ErrorCode::UNIMPLEMENTED (หากไม่รองรับเอกสารรับรองของรหัส) ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED หรือ หนึ่งในรหัสข้อผิดพลาดที่ระบุว่าการสื่อสารล้มเหลวกับ ฮาร์ดแวร์

เริ่มต้น

เวอร์ชัน: 1, 2, 3

เริ่มการดำเนินการเข้ารหัสโดยใช้คีย์ที่ระบุ ด้วยพารามิเตอร์ที่ระบุ (ตามความเหมาะสม) และแสดง แฮนเดิลดำเนินการที่ใช้กับ update และ finish เพื่อให้การดำเนินการเสร็จสมบูรณ์ แฮนเดิลการดำเนินการคือ ยังใช้เป็น "ภารกิจ" โทเค็นในการดำเนินงานที่ตรวจสอบสิทธิ์แล้ว และสำหรับการดำเนินการดังกล่าว จะรวมอยู่ในฟิลด์ challenge ของ โทเค็นการตรวจสอบสิทธิ์

การใช้งาน Keymaster รองรับการทำงานพร้อมกันอย่างน้อย 16 รายการ การดำเนินงาน คีย์สโตร์ใช้ได้สูงสุด 15 รายการ เหลือไว้ 1 รายการสำหรับ vold ที่จะใช้เป็นรหัสผ่าน การเข้ารหัส เมื่อคีย์สโตร์มีการดำเนินการ 15 รายการอยู่ระหว่างดำเนินการ (begin มีการดำเนินการที่กำลังดำเนินการอยู่ ถูกเรียก แต่ finish หรือ abort ยังไม่ได้รับการโทร ) และได้รับคำขอเพื่อเริ่มต้นในวันที่ 16 ระบบโทร abort ในการดำเนินการที่ใช้น้อยที่สุดเพื่อลดจำนวนของ การดำเนินการที่ดำเนินอยู่เป็น 14 ก่อนเรียก begin เพื่อเริ่มต้น การดำเนินการที่ขอใหม่

ถ้าเป็น Tag::APPLICATION_ID หรือ Tag::APPLICATION_DATA แล้ว ในระหว่างการสร้างหรือนำเข้าคีย์ การเรียก begin จะรวม ด้วยค่าที่ระบุในตอนแรกในอาร์กิวเมนต์ inParams วิธีนี้

การบังคับใช้การให้สิทธิ์

ระหว่างวิธีการนี้ การให้สิทธิ์คีย์ต่อไปนี้จะถูกบังคับใช้โดย Trustlet หากการใช้งานนั้นอยู่ในประเภท "ใช้ฮาร์ดแวร์" ลักษณะหนึ่ง และหากการดำเนินการดังกล่าวไม่ใช่การดำเนินการคีย์สาธารณะ คีย์สาธารณะ การดำเนินการ หมายถึง KeyPurpose::ENCRYPT และ KeyPurpose::VERIFY ด้วยคีย์ RSA หรือ EC จะได้รับอนุญาต แม้ว่าจะได้รับสิทธิ์ ไม่ตรงตามข้อกำหนด

• Tag::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 หากคีย์มีทั้ง 2 อย่าง เมธอดนี้ต้องได้รับแอตทริบิวต์ที่ถูกต้อง แท็ก::AUTH_TOKEN ใน inParams เพื่อให้โทเค็นการตรวจสอบสิทธิ์ใช้งานได้ เงื่อนไขทุกข้อต่อไปนี้ ต้องเป็นจริง
  • ช่อง HMAC ได้รับการตรวจสอบอย่างถูกต้อง
  • อย่างน้อย 1 แท็ก::USER_SECURE_ID จากคีย์ตรงกับค่ารหัสที่ปลอดภัยอย่างน้อย 1 ค่าใน โทเค็น
  • คีย์จะมี แท็ก::USER_AUTH_TYPE ที่ตรงกับประเภทการตรวจสอบสิทธิ์ในโทเค็น

  หากไม่เป็นไปตามเงื่อนไขใดๆ ต่อไปนี้ ระบบจะแสดงเมธอด ErrorCode::KEY_USER_NOT_AUTHENTICATED

• แท็ก::CALLER_NONCE อนุญาตให้ผู้โทรระบุ Nonce หรือเวกเตอร์การเริ่มต้น (IV) หากคีย์ ไม่มีแท็กนี้ แต่ผู้โทรระบุไว้ แท็ก::NONCE กับเมธอดนี้ ระบบส่งกลับ ErrorCode::CALLER_NONCE_PROHIBITED
• แท็ก::BOOTLOADER_ONLY ระบุว่ามีเพียง Bootloader เท่านั้นที่ใช้คีย์ได้ หากวิธีนี้คือ ด้วยคีย์ Bootloader เท่านั้นหลังจากที่ Bootloader ดำเนินการเสร็จแล้ว จะแสดง ErrorCode::INVALID_KEY_BLOB

คีย์ RSA

การดำเนินการคีย์ RSA ทั้งหมดจะระบุโหมดระยะห่างจากขอบเพียงโหมดเดียวใน inParams หากไม่ได้ระบุหรือระบุมากกว่า 1 ครั้ง ระบบจะแสดงผลเมธอด ErrorCode::UNSUPPORTED_PADDING_MODE

การดำเนินการลงชื่อและยืนยัน RSA จำเป็นต้องมีข้อมูลสรุป เช่นเดียวกับการเข้ารหัส RSA และการดำเนินการถอดรหัสด้วยโหมด Padding แบบ OAEP สำหรับกรณีเหล่านั้น ผู้โทร ระบุไดเจสต์เพียง 1 รายการใน inParams หากไม่ได้ระบุหรือระบุไว้ มากกว่า 1 ครั้ง เมธอดนี้จะแสดง ErrorCode::UNSUPPORTED_DIGEST

การดำเนินการของคีย์ส่วนตัว (KeyPurpose::DECYPT และ KeyPurpose::SIGN) ต้องมีสิทธิ์ไดเจสต์และระยะห่างจากขอบ ซึ่งหมายความว่าการให้สิทธิ์คีย์ ต้องมีค่าที่ระบุ หากไม่เป็นเช่นนั้น เมธอดจะแสดง ErrorCode::INCOMPATIBLE_DIGEST หรือ ErrorCode::INCOMPATIBLE_PADDING ได้ตามความเหมาะสม การดำเนินการคีย์สาธารณะ (KeyPurpose::ENCRYPT และ KeyPurpose::VERIFY) ได้รับอนุญาตกับ ไดเจสต์หรือระยะห่างจากขอบที่ไม่ได้รับอนุญาต

โหมดระยะห่างจากขอบของ RSA ทั้งหมด ยกเว้น PaddingMode::NONE ใช้ได้กับวัตถุประสงค์บางอย่างเท่านั้น โดยเฉพาะอย่างยิ่ง 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 ระบุโหมดระยะห่างจากขอบ 1 โหมดใน inParams หากไม่ได้ระบุหรือระบุมากกว่า 1 ครั้ง แสดงผล ErrorCode::UNSUPPORTED_PADDING_MODE

การดำเนินการคีย์ส่วนตัว (KeyPurpose::SIGN) ต้องได้รับอนุญาต หรือไดเจสต์และระยะห่างจากขอบ ซึ่งหมายความว่าการให้สิทธิ์ที่สำคัญ ต้องมีค่าที่ระบุ หากไม่ ให้ส่งคืน ErrorCode::INCOMPATIBLE_DIGEST การดำเนินการคีย์สาธารณะ (KeyPurpose::VERIFY) อนุญาตให้มีไดเจสต์หรือระยะห่างจากขอบที่ไม่ได้รับอนุญาต

คีย์ AES

การทำงานของปุ่ม AES ระบุโหมดบล็อก 1 โหมดและโหมดระยะห่างจากขอบอย่างละ 1 โหมด ใน inParams หากไม่ได้ระบุหรือระบุค่ามากกว่า มากกว่า 1 ครั้ง ส่งคืน 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 ต้องมีเวกเตอร์การเริ่มต้นหรือ Nonce ในกรณีส่วนใหญ่ ผู้โทรไม่ควรระบุ IV หรือ Nonce ในกรณีดังกล่าว ค่า การติดตั้งใช้งาน Keymaster จะสร้าง IV หรือ Nonce แบบสุ่มและแสดงผลผ่าน แท็ก::NONCE ใน outParams CBC และ CTR IV มีขนาด 16 ไบต์ Nonces ใน GCM มีขนาด 12 ไบต์ หากคีย์ การให้สิทธิ์ประกอบด้วย แท็ก::CALLER_NONCE ผู้โทรอาจให้ IV/nonce แท็ก::NONCE ใน inParams หากมีการระบุ Nonce เมื่อ แท็ก::CALLER_NONCE ไม่ได้รับอนุญาต ส่งคืน ErrorCode::CALLER_NONCE_PROHIBITED หากไม่ได้ระบุ Nonce เมื่อ แท็ก::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

ให้ข้อมูลสำหรับประมวลผลในการดำเนินการที่ต่อเนื่องซึ่งเริ่มต้นด้วย begin การดำเนินการถูกระบุโดยพารามิเตอร์ operationHandle

การใช้เมธอดนี้เพื่อให้จัดการบัฟเฟอร์ได้อย่างยืดหยุ่นมากขึ้น จะมีทางเลือกในการใช้ข้อมูลน้อยกว่าที่ระบุไว้ ผู้โทรคือ มีหน้าที่วนซ้ำเพื่อป้อนข้อมูลที่เหลือในการเรียกครั้งต่อๆ ไป และจะแสดงผลปริมาณอินพุตในพารามิเตอร์ inputConsumed การติดตั้งใช้งานจะใช้อย่างน้อย 1 ไบต์เสมอ เว้นแต่ การดำเนินการไม่สามารถยอมรับได้อีกต่อไป หากมีการระบุมากกว่า 0 ไบต์และ 0 จำนวนไบต์ที่ใช้ไป ผู้โทรจะถือว่านี่เป็นข้อผิดพลาดและล้มเลิกการดำเนินการ

การติดตั้งใช้งานอาจเลือกปริมาณข้อมูลที่จะแสดงด้วย ซึ่งเป็นผลมาจาก อัปเดต การตั้งค่านี้เกี่ยวข้องกับการดำเนินการเข้ารหัสและถอดรหัสเท่านั้นเนื่องจาก การลงชื่อและการยืนยันจะไม่แสดงข้อมูลจนกว่าจะเสร็จสิ้น แสดงผลข้อมูลให้เร็วที่สุดเท่าที่จะทำได้ แทนที่จะบัฟเฟอร์ไว้

การจัดการข้อผิดพลาด

หากวิธีนี้แสดงรหัสข้อผิดพลาดอื่นที่ไม่ใช่ ErrorCode::OK ล้มเลิกการดำเนินการ และแฮนเดิลการดำเนินการจะใช้ไม่ได้ ช่วง ของแฮนเดิลนั้นในอนาคต ด้วยวิธีนี้ เสร็จสิ้น หรือล้มเลิก แสดงผล ErrorCode::INVALID_OPERATION_HANDLE

การบังคับใช้การให้สิทธิ์

การบังคับใช้การให้สิทธิ์คีย์จะดำเนินการในเริ่มต้นเป็นหลัก ยกเว้นกรณีที่คีย์มีลักษณะดังนี้

• Tag::USER_SECURE_IDs อย่างน้อย 1 รายการ และ
• ไม่มีแท็ก::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 สนับสนุน "ข้อมูลการตรวจสอบสิทธิ์ที่เชื่อมโยง" ที่ให้บริการผ่าน แท็ก::ASSOCIATED_DATA ในอาร์กิวเมนต์ inParams ข้อมูลที่เกี่ยวข้องอาจมีให้ในการเรียกซ้ำ (สำคัญหาก ข้อมูลมีขนาดใหญ่เกินกว่าจะส่งได้บล็อกเดียว) แต่จะแสดงก่อนข้อมูลเสมอ เพื่อเข้ารหัสหรือถอดรหัส การเรียกใช้เพื่ออัปเดตอาจได้รับทั้งข้อมูลที่เชื่อมโยง และข้อมูลที่จะเข้ารหัส/ถอดรหัส แต่การอัปเดตในครั้งต่อๆ ไปอาจไม่รวม หากผู้โทรให้ข้อมูลที่เกี่ยวข้องสำหรับการโทรที่อัปเดตแล้วหลังจากการโทร ที่มีข้อมูลที่จะเข้ารหัส/ถอดรหัส ให้แสดงผล ErrorCode::INVALID_TAG

สำหรับการเข้ารหัส GCM แท็กจะต่อท้ายข้อความเข้ารหัสโดย เสร็จสิ้น ในระหว่างการถอดรหัส Tag::MAC_LENGTH ไบต์ของข้อมูลที่ให้ไว้ไปยัง การเรียกใช้การอัปเดตคือแท็ก ตั้งแต่การเรียกใช้ update ไม่สามารถทราบได้ว่าเป็นการเรียกสุดท้ายหรือไม่ ระบบจะประมวลผลทั้งหมดยกเว้นความยาวของแท็กและบัฟเฟอร์ข้อมูลแท็กที่เป็นไปได้ ระหว่างสิ้นสุด

เสร็จสิ้น

เวอร์ชัน: 1, 2, 3

สิ้นสุดการดำเนินการที่ดำเนินอยู่โดยเริ่มจาก begin การประมวลผลข้อมูลที่ยังไม่ได้ประมวลผลทั้งหมดที่ได้รับจาก การอัปเดต

วิธีนี้เป็นวิธีสุดท้ายที่ถูกเรียกใช้ในการดำเนินการ ดังนั้น ข้อมูลที่ประมวลผลแล้วจะส่งกลับ

วิธีนี้จะทำให้การดำเนินการเสร็จสมบูรณ์ไม่ว่าจะเสร็จสมบูรณ์หรือส่งคืนข้อผิดพลาด การดำเนินการและทำให้แฮนเดิลการดำเนินการที่ระบุเป็นโมฆะ ช่วง การใช้แฮนเดิลในอนาคต โดยใช้เมธอดนี้หรืออัปเดต หรือ abort แสดงผล ErrorCode::INVALID_OPERATION_HANDLE

การดำเนินการลงชื่อจะส่งคืนลายเซ็นเป็นเอาต์พุต การดำเนินการยืนยัน ยอมรับลายเซ็นในพารามิเตอร์ signature และไม่แสดงผลเอาต์พุต

การบังคับใช้การให้สิทธิ์

การบังคับใช้การให้สิทธิ์คีย์จะเกิดขึ้นใน begin ยกเว้นกรณีที่คีย์มีลักษณะดังนี้

• อย่างน้อย 1 รายการ แท็ก::USER_SECURE_IDs และ
• ไม่มี แท็ก::AUTH_TIMEOUT

ในกรณีนี้ คีย์จะต้องมีการให้สิทธิ์ต่อการดำเนินการและการอัปเดต จะได้รับ แท็ก::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 Salt ของ PSS คือขนาดของไดเจสต์ของข้อความและสร้างขึ้นแบบสุ่ม ไดเจสต์ที่ระบุด้วย Tag::DIGEST ใน inputParams บน begin มีการใช้เป็นไดเจสต์ PSS และในฐานะอัลกอริทึมไดเจสต์ MGF1
• PaddingMode::RSA_OAEP ไดเจสต์ที่ระบุด้วย แท็ก::DIGEST ใน inputParams ใน begin ถูกใช้เป็น OAEP อัลกอริทึมไดเจสต์ และใช้ SHA1 เป็นอัลกอริทึมไดเจสต์ MGF1

คีย์ ECDSA

หากข้อมูลที่ระบุสำหรับการลงนามหรือการยืนยันที่ไม่ได้ใส่อักขระเพิ่มเติมยาวเกินไป ให้ตัดให้สั้นลง ได้

คีย์ AES

เงื่อนไขเพิ่มเติมบางประการ โดยขึ้นอยู่กับโหมดการบล็อก

• BlockMode::ECB หรือ BlockMode::CBC หากระยะห่างจากขอบเป็น PaddingMode::NONE และ ความยาวของข้อมูลไม่ได้เป็นผลคูณของขนาดบล็อก AES, ErrorCode::INVALID_INPUT_LENGTH หากระยะห่างจากขอบเป็น PaddingMode::PKCS7 ป้อนข้อมูลตามข้อกำหนด PKCS#7 โปรดทราบว่า PKCS#7 แนะนำให้เพิ่มบล็อกระยะห่างจากขอบเพิ่มเติม ถ้าข้อมูลเป็นพหุคูณของความยาวบล็อก
• BlockMode::GCM ระหว่างการเข้ารหัสหลังการประมวลผล ข้อความธรรมดาทั้งหมด คำนวณแท็ก (แท็ก::MAC_LENGTH ไบต์) แล้วนำไปต่อท้ายข้อความเข้ารหัสที่แสดง ในระหว่างการถอดรหัส ให้ประมวลผล แท็ก::MAC_LENGTH สุดท้าย เท่ากับแท็ก หากยืนยันแท็กไม่สำเร็จ ให้แสดงผล ErrorCode::VERIFICATION_FAILED

ล้มเลิก

เวอร์ชัน: 1, 2, 3

ล้มเลิกการดำเนินการที่กำลังดำเนินการ หลังจากโทรเพื่อล้มเลิกแล้ว ให้ย้อนกลับ ErrorCode::INVALID_OPERATION_HANDLE สำหรับ การใช้แฮนเดิลการดำเนินการที่ระบุหลังจากนั้นกับ update เสร็จสิ้น หรือล้มเลิก

อัลกอริทึม get_supported_

เวอร์ชัน: 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 ความยาว Salt ขั้นต่ำที่ 20
• OAEP

สำหรับ AES ในโหมด ECB และ CBC การติดตั้งใช้งาน Keymaster 1 จะไม่รองรับหมายเลข และ PKCS#7 โหมด 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 และรองรับการนำเข้า RAW เนื้อหาคีย์ AES และ HMAC

get_supported_export_formats

เวอร์ชัน: 1

แสดงรายการรูปแบบการส่งออกที่ฮาร์ดแวร์ Keymaster รองรับ การใช้งานอัลกอริทึมที่ระบุ

การติดตั้งใช้งาน Keymaster1 รองรับรูปแบบ X.509 สำหรับการส่งออก RSA และ คีย์สาธารณะ EC ไม่รองรับการส่งออกคีย์ส่วนตัวหรือคีย์อสมมาตร

ฟังก์ชันที่ผ่านมา

คีย์มาสเตอร์ 0

ฟังก์ชันต่อไปนี้เป็นของคำจำกัดความ Keymaster 0 ต้นฉบับ โฆษณาเหล่านี้ มีอยู่ใน struct keymaster1_device_t ของ Keymaster 1 อย่างไรก็ตาม ใน Keymaster 1.0 ไม่มีการใช้งาน และตัวชี้ฟังก์ชันมีการตั้งค่าเป็น NULL

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

คีย์มาสเตอร์ 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

คีย์มาสเตอร์ 2

ฟังก์ชันต่อไปนี้เป็นของคำจำกัดความของ Keymaster 2 แต่ ที่นำออกใน Keymaster 3 รวมถึงฟังก์ชัน Keymaster 1 ที่แสดงอยู่ด้านบน

• configure