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

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

หมายเหตุ: ชื่อฟังก์ชันมีการเปลี่ยนแปลงใน Android 8.0 เพื่อรองรับการเปลี่ยนจาก HAL โครงสร้าง C แบบเก่าของ Keymaster 3 ไปใช้อินเทอร์เฟซ HAL ของ C++ ที่สร้างขึ้นจากคำจำกัดความในภาษาใหม่สำหรับกำหนดอินเทอร์เฟซฮาร์ดแวร์ (HIDL) ฟังก์ชันจึงอยู่ในรูปแบบ Camel Case เพื่อรองรับการใช้งานนี้ ตัวอย่างเช่น get_key_characteristics เปลี่ยนเป็น getKeyCharacteristics

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

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

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

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

ฟังก์ชัน

getHardwareFeatures

เวอร์ชัน: 3

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

• isSecure คือ true หากคีย์จัดเก็บไว้ในฮาร์ดแวร์ที่มีความปลอดภัย (เช่น TEE) และไม่มีการส่งออก
• supportsEllipticCurve คือ true หากฮาร์ดแวร์รองรับการเข้ารหัสด้วยเวกเตอร์รูปไข่ที่มีเวกเตอร์ 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 ระบบจะเรียกใช้เมธอดนี้ 1 ครั้งหลังจากเปิดอุปกรณ์และก่อนที่จะมีการใช้งาน ใช้เพื่อระบุ KM_TAG_OS_VERSION และ KM_TAG_OS_PATCHLEVEL ให้กับ Keymaster จนกว่าจะมีการเรียกใช้เมธอดนี้ เมธอดอื่นๆ ทั้งหมดจะแสดงผลเป็น KM_ERROR_KEYMASTER_NOT_CONFIGURED คีย์มาสเตอร์จะยอมรับค่าที่ได้จากวิธีนี้เพียงครั้งเดียวต่อการบูต การเรียกใช้ครั้งต่อๆ ไปจะแสดงผลลัพธ์เป็น 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 เพื่อใช้สร้างตัวเลขสุ่ม สําหรับคีย์ IV และอื่นๆ

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

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

generateKey

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

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

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

พารามิเตอร์ที่ระบุให้กับ generateKey จะขึ้นอยู่กับประเภทของคีย์ที่กำลังสร้างขึ้น ส่วนนี้จะสรุปแท็กที่จำเป็นและที่ไม่บังคับสำหรับคีย์แต่ละประเภท Tag::ALGORITHM ต้องระบุเสมอเพื่อระบุประเภท

คีย์ RSA

ต้องระบุพารามิเตอร์ต่อไปนี้เพื่อสร้างคีย์ RSA

• Tag::KEY_SIZE ระบุขนาดของโมดูลัสสาธารณะเป็นบิต หากไม่ระบุ เมธอดจะแสดงผล ErrorCode::UNSUPPORTED_KEY_SIZE ค่าที่รองรับคือ 1024, 2048, 3072 และ 4096 ค่าที่แนะนำคือขนาดคีย์ทั้งหมดที่หารด้วย 8 ได้
• Tag::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

มีเพียง Tag::KEY_SIZE เท่านั้นที่จําเป็นต่อการสร้างคีย์ ECDSA ใช้แท็กนี้เพื่อเลือกกลุ่ม EC ค่าที่รองรับคือ 224, 256, 384 และ 521 ซึ่งแสดงถึงโค้ง NIST p-224, p-256, p-384 และ p521 ตามลำดับ

Tag::DIGEST ยังเป็นสิ่งจําเป็นสําหรับคีย์ ECDSA ที่มีประโยชน์ด้วย แต่ก็ไม่จำเป็นต้องใช้ในการสร้าง

คีย์ AES

คุณต้องใช้เพียง Tag::KEY_SIZE เพื่อสร้างคีย์ AES หากไม่ระบุ เมธอดจะแสดงผล ErrorCode::UNSUPPORTED_KEY_SIZE ค่าที่รองรับคือ 128 และ 256 โดยรองรับคีย์ AES 192 บิต (ไม่บังคับ)

พารามิเตอร์ต่อไปนี้เกี่ยวข้องกับคีย์ AES โดยเฉพาะ แต่ไม่จำเป็นต้องสร้าง

• Tag::BLOCK_MODE ระบุโหมดบล็อกที่ใช้กับคีย์ใหม่ได้
• Tag::PADDING ระบุโหมดการเติมที่สามารถใช้ ตัวเลือกนี้ใช้ได้กับโหมด ECB และ CBC เท่านั้น

หากระบุโหมดบล็อก GCM ให้ระบุ Tag::MIN_MAC_LENGTH หากไม่ระบุ เมธอดจะแสดงผล ErrorCode::MISSING_MIN_MAC_LENGTH ค่าของแท็กต้องเป็นแบบหลายของ 8 และอยู่ระหว่าง 96 ถึง 128

คีย์ HMAC

ต้องระบุพารามิเตอร์ต่อไปนี้สำหรับการสร้างคีย์ HMAC

• Tag::KEY_SIZE ระบุขนาดคีย์เป็นบิต ระบบไม่รองรับค่าที่น้อยกว่า 64 และค่าที่ไม่ใช่จำนวนที่คูณด้วย 8 ระบบรองรับจำนวนที่หารด้วย 8 ทั้งหมดตั้งแต่ 64 ถึง 512 ระบบอาจรองรับค่าที่มากกว่า
• Tag::MIN_MAC_LENGTH ระบุความยาวขั้นต่ำของ MAC ที่สามารถสร้างหรือตรวจสอบได้ด้วยคีย์นี้ ค่าเป็นจํานวนเต็มหารด้วย 8 และอย่างน้อย 64
• Tag::DIGEST ระบุอัลกอริทึมไดเจสต์สำหรับคีย์ ระบุไฟล์สรุปเพียงไฟล์เดียว มิเช่นนั้นระบบจะแสดง ErrorCode::UNSUPPORTED_DIGEST หาก Trustlet ไม่รองรับข้อมูลสรุป ให้แสดง ErrorCode::UNSUPPORTED_DIGEST

ลักษณะสำคัญ

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

นอกจากแท็กที่ระบุแล้ว ทรัสต์เลตจะเพิ่ม Tag::ORIGIN ด้วยค่า KeyOrigin::GENERATED และหากคีย์ป้องกันการย้อนกลับ Tag::ROLLBACK_RESISTANT

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

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

คีย์จะป้องกันการย้อนกลับได้หากฮาร์ดแวร์ที่มีความปลอดภัยรับประกันว่าคีย์ที่ลบไปแล้วจะกู้คืนไม่ได้ในภายหลัง ซึ่งโดยทั่วไปจะทําโดยการเก็บข้อมูลเมตาเพิ่มเติมของคีย์ไว้ในตำแหน่งที่เชื่อถือได้ซึ่งผู้โจมตีไม่สามารถดัดแปลงได้ ในอุปกรณ์เคลื่อนที่ กลไกที่ใช้มักจะเป็น Replay Protected Memory Blocked (RPMB) เนื่องจากจำนวนคีย์ที่สร้างได้นั้นไม่มีขีดจำกัด และพื้นที่เก็บข้อมูลที่เชื่อถือได้ซึ่งใช้เพื่อป้องกันการย้อนกลับอาจมีขนาดจำกัด วิธีนี้จึงต้องดำเนินการให้สำเร็จแม้ว่าจะไม่สามารถระบุการป้องกันการย้อนกลับสำหรับคีย์ใหม่ได้ก็ตาม ในกรณีนี้ ไม่ควรเพิ่ม Tag::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

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

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

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

importKey

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

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

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

• Tag::KEY_SIZE และ Tag::RSA_PUBLIC_EXPONENT (สำหรับคีย์ RSA เท่านั้น) ไม่จำเป็นต้องระบุในพารามิเตอร์อินพุต หากไม่ได้ระบุไว้ ข้อมูลนี้จะอนุมานค่าจากเนื้อหาคีย์ที่ระบุและเพิ่มแท็กและค่าที่เหมาะสมลงในลักษณะคีย์ หากระบุพารามิเตอร์ไว้ ทรัสต์เลตจะตรวจสอบพารามิเตอร์เหล่านั้นเทียบกับเนื้อหาคีย์ ในกรณีที่ไม่ตรงกัน เมธอดจะแสดงผล ErrorCode::IMPORT_PARAMETER_MISMATCH
• Tag::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

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

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

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

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

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

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

• Tag::PURPOSE: วัตถุประสงค์ที่ระบุในการเรียกใช้ begin() ต้องตรงกับวัตถุประสงค์อย่างใดอย่างหนึ่งในการให้สิทธิ์คีย์ เว้นแต่การดำเนินการที่ขอจะเป็นการดำเนินการกับคีย์สาธารณะ หากวัตถุประสงค์ที่ระบุไม่ตรงกันและการดำเนินการไม่ใช่การดำเนินการกับคีย์สาธารณะ begin จะแสดงผลเป็น ErrorCode::UNSUPPORTED_PURPOSE การดำเนินการกับคีย์สาธารณะคือการเข้ารหัสแบบอสมมาตรหรือการยืนยัน
• Tag::ACTIVE_DATETIME จะบังคับใช้ได้ก็ต่อเมื่อมีแหล่งที่มาของเวลา UTC ที่เชื่อถือได้ หากวันที่และเวลาปัจจุบันอยู่ก่อนค่าแท็ก เมธอดจะแสดงผล ErrorCode::KEY_NOT_YET_VALID
• Tag::ORIGINATION_EXPIRE_DATETIME จะบังคับใช้ได้ก็ต่อเมื่อมีแหล่งที่มาของเวลา UTC ที่เชื่อถือได้ หากวันที่และเวลาปัจจุบันอยู่หลังค่าแท็กและวัตถุประสงค์คือ KeyPurpose::ENCRYPT หรือ KeyPurpose::SIGN วิธีการจะแสดงผล ErrorCode::KEY_EXPIRED
• Tag::USAGE_EXPIRE_DATETIME จะบังคับใช้ได้ก็ต่อเมื่อมีแหล่งที่มาของเวลา UTC ที่เชื่อถือได้ หากวันที่และเวลาปัจจุบันอยู่หลังค่าแท็กและวัตถุประสงค์คือ KeyPurpose::DECRYPT หรือ KeyPurpose::VERIFY วิธีการจะแสดงผล ErrorCode::KEY_EXPIRED
• Tag::MIN_SECONDS_BETWEEN_OPS เปรียบเทียบกับตัวจับเวลาแบบสัมพัทธ์ที่เชื่อถือได้ซึ่งระบุการใช้งานคีย์ครั้งล่าสุด หากเวลาใช้งานล่าสุดบวกค่าแท็กน้อยกว่าเวลาปัจจุบัน วิธีการจะแสดงผล ErrorCode::KEY_RATE_LIMIT_EXCEEDED ดูรายละเอียดการติดตั้งใช้งานที่สําคัญได้ในส่วนคําอธิบายแท็ก
• Tag::MAX_USES_PER_BOOT จะเปรียบเทียบกับตัวนับที่ปลอดภัยซึ่งติดตามการใช้คีย์ตั้งแต่เวลาบูต หากจํานวนการใช้งานก่อนหน้านี้เกินค่าแท็ก วิธีการจะแสดงผลเป็น ErrorCode::KEY_MAX_OPS_EXCEEDED
• ระบบจะใช้วิธีการนี้บังคับใช้ Tag::USER_SECURE_ID เฉพาะในกรณีที่คีย์มี Tag::AUTH_TIMEOUT ด้วย หากคีย์มีทั้ง 2 รายการ วิธีนี้ต้องได้รับ Tag::AUTH_TOKEN ที่ถูกต้องใน inParams เงื่อนไขต่อไปนี้ทั้งหมดต้องเป็นจริงเพื่อให้โทเค็นการตรวจสอบสิทธิ์ถูกต้อง
  • ช่อง HMAC ตรวจสอบถูกต้อง
  • ค่าจากคีย์อย่างน้อย 1 ค่าตรงกับค่าบัตรประจำตัวที่ปลอดภัยอย่างน้อย 1 ค่าในโทเค็นTag::USER_SECURE_ID
  • คีย์มี Tag::USER_AUTH_TYPE ที่ตรงกับประเภทการตรวจสอบสิทธิ์ในโทเค็น

  หากไม่เป็นไปตามเงื่อนไขเหล่านี้ วิธีการจะแสดงผลเป็น ErrorCode::KEY_USER_NOT_AUTHENTICATED

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

คีย์ RSA

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

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

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

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

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

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

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

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

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

• มี Tag::USER_SECURE_IDs อย่างน้อย 1 รายการ
• ไม่มี Tag::AUTH_TIMEOUT

ในกรณีนี้ คีย์ต้องมีการให้สิทธิ์ต่อการดำเนินการ และเมธอดการอัปเดตจะได้รับ Tag::AUTH_TOKEN ในอาร์กิวเมนต์ inParams HMAC จะยืนยันว่าโทเค็นถูกต้องและมีรหัสผู้ใช้ที่ปลอดภัยที่ตรงกัน ตรงกับTag::USER_AUTH_TYPE ของคีย์ และมีแฮนเดิลการดำเนินการของการดำเนินการปัจจุบันในช่อง challenge หากไม่เป็นไปตามเงื่อนไขเหล่านี้ ให้แสดงผล ErrorCode::KEY_USER_NOT_AUTHENTICATED

ผู้โทรจะระบุโทเค็นการตรวจสอบสิทธิ์ในการโทรทุกครั้งไปยัง update และ finish การติดตั้งใช้งานต้องตรวจสอบโทเค็นเพียงครั้งเดียว

คีย์ RSA

สำหรับการดำเนินการลงนามและการยืนยันด้วย Digest::NONE วิธีนี้จะยอมรับการเซ็นชื่อหรือยืนยันทั้งบล็อกในการอัปเดตครั้งเดียว แต่จะบริโภคได้เพียงบางส่วนของบล็อกเท่านั้น อย่างไรก็ตาม หากผู้เรียกเลือกที่จะให้ข้อมูลในการอัปเดตหลายครั้ง วิธีการนี้จะยอมรับข้อมูลดังกล่าว หากผู้โทรระบุข้อมูลที่จะเซ็นมากกว่าที่ระบบใช้ได้ (ความยาวของข้อมูลเกินขนาดคีย์ RSA) ให้แสดงผลลัพธ์เป็น ErrorCode::INVALID_INPUT_LENGTH

คีย์ ECDSA

สำหรับการดำเนินการลงนามและการยืนยันด้วย Digest::NONE วิธีนี้จะยอมรับการเซ็นชื่อหรือยืนยันทั้งบล็อกในการอัปเดตครั้งเดียว วิธีการนี้ใช้เพียงบางส่วนของบล็อกไม่ได้

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

คีย์ AES

โหมด AES GCM รองรับข้อมูลการตรวจสอบสิทธิ์ที่เกี่ยวข้อง ซึ่งระบุผ่านแท็ก Tag::ASSOCIATED_DATA ในอาร์กิวเมนต์ inParams คุณสามารถระบุข้อมูลที่เชื่อมโยงในการเรียกซ้ำได้ (สำคัญในกรณีที่ข้อมูลมีขนาดใหญ่เกินกว่าที่จะส่งในบล็อกเดียว) แต่ต้องอยู่ก่อนข้อมูลที่เข้ารหัสหรือถอดรหัสเสมอ การเรียกใช้การอัปเดตสามารถรับทั้งข้อมูลที่เกี่ยวข้องและข้อมูลที่จะเข้ารหัส/ถอดรหัสได้ แต่การอัปเดตที่ตามมาจะรวมข้อมูลที่เกี่ยวข้องไม่ได้ หากผู้โทรระบุข้อมูลที่เชื่อมโยงกับการเรียกใช้การอัปเดตหลังจากการเรียกใช้ที่มีข้อมูลที่จะเข้ารหัส/ถอดรหัส ให้แสดงผล ErrorCode::INVALID_TAG

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

เสร็จสิ้น

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

ดำเนินการที่อยู่ระหว่างดำเนินการซึ่งเริ่มต้นด้วย begin ให้เสร็จสิ้น โดยประมวลผลข้อมูลทั้งหมดที่ยังไม่ได้ประมวลผลซึ่งได้จากอินสแตนซ์ update

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

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

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

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

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

• มี Tag::USER_SECURE_IDs อย่างน้อย 1 รายการ
• ไม่มี Tag::AUTH_TIMEOUT

ในกรณีนี้ คีย์ต้องมีการให้สิทธิ์ต่อการดำเนินการ และเมธอดการอัปเดตจะได้รับ Tag::AUTH_TOKEN ในอาร์กิวเมนต์ inParams HMAC จะยืนยันว่าโทเค็นถูกต้องและมีรหัสผู้ใช้ที่ปลอดภัยที่ตรงกัน ตรงกับ Tag::USER_AUTH_TYPE ของคีย์ และมีแฮนเดิลการดำเนินการของการดำเนินการปัจจุบันในช่อง challenge หากไม่เป็นไปตามเงื่อนไขเหล่านี้ ให้แสดงผล ErrorCode::KEY_USER_NOT_AUTHENTICATED

ผู้โทรจะระบุโทเค็นการตรวจสอบสิทธิ์ในการโทรทุกครั้งไปยัง update และ finish การติดตั้งใช้งานต้องตรวจสอบโทเค็นเพียงครั้งเดียว

คีย์ RSA

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

• PaddingMode::NONE. สําหรับการดำเนินการลงนามและการเข้ารหัสแบบไม่เติมค่า ในกรณีที่ข้อมูลที่ให้ไว้สั้นกว่าคีย์ ระบบจะเติมค่า 0 ทางด้านซ้ายก่อนลงนาม/เข้ารหัส หากข้อมูลมีความยาวเท่ากับคีย์แต่มีจำนวนมากกว่า ให้แสดงผล ErrorCode::INVALID_ARGUMENT สําหรับการดำเนินการยืนยันและการถอดรหัส ข้อมูลต้องยาวเท่ากับคีย์ หรือไม่เช่นนั้น ให้แสดงผล ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. สําหรับการดำเนินการกับลายเซ็นที่มีการเติม PSS เกลือ PSS จะมีขนาดเท่ากับข้อมูลสรุปข้อความและสร้างขึ้นแบบสุ่ม ระบบจะใช้ข้อมูลสรุปที่ระบุด้วย Tag::DIGEST ใน inputParams ใน begin เป็นอัลกอริทึมข้อมูลสรุป PSS และเป็นอัลกอริทึมข้อมูลสรุป MGF1
• PaddingMode::RSA_OAEP. ระบบจะใช้ข้อมูลสรุปที่ระบุด้วย Tag::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 แนะนำให้เพิ่มบล็อกการเติมอีก 1 บล็อกหากข้อมูลเป็นจำนวนที่คูณกับความยาวของบล็อก
• BlockMode::GCM. ในระหว่างการเข้ารหัส หลังจากประมวลผลข้อความธรรมดาทั้งหมดแล้ว ให้คํานวณแท็ก (Tag::MAC_LENGTH ไบต์) และเพิ่มต่อท้ายข้อความที่เข้ารหัสที่แสดง ในระหว่างการถอดรหัส ให้ประมวลผลไบต์ Tag::MAC_LENGTH สุดท้ายเป็นแท็ก หากการยืนยันแท็กไม่สำเร็จ ให้กลับไปที่ ErrorCode::VERIFICATION_FAILED

ล้มเลิก

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

ยกเลิกการดำเนินการที่กำลังดำเนินอยู่ หลังจากการเรียกให้หยุดกลางคันแล้ว ให้แสดงผล ErrorCode::INVALID_OPERATION_HANDLE สำหรับการใช้ตัวแฮนเดิลการดำเนินการที่ระบุในภายหลังด้วย update, finish หรือ abort

get_supported_algorithms

เวอร์ชัน: 1

แสดงรายการอัลกอริทึมที่การติดตั้งใช้งานฮาร์ดแวร์ Keymaster รองรับ การติดตั้งใช้งานซอฟต์แวร์จะแสดงผลรายการว่าง ส่วนการติดตั้งใช้งานแบบผสมจะแสดงผลรายการที่มีเฉพาะอัลกอริทึมที่ฮาร์ดแวร์รองรับ

การติดตั้งใช้งาน Keymaster 1 รองรับ RSA, EC, AES และ HMAC

get_supported_block_modes

เวอร์ชัน: 1

แสดงรายการโหมดบล็อก AES ที่การติดตั้งใช้งานฮาร์ดแวร์ Keymaster รองรับสำหรับอัลกอริทึมและวัตถุประสงค์ที่ระบุ

สำหรับ RSA, EC และ HMAC ซึ่งไม่ใช่การเข้ารหัสบล็อก เมธอดจะแสดงผลเป็นรายการว่างสำหรับวัตถุประสงค์ที่ถูกต้องทั้งหมด วัตถุประสงค์ที่ไม่ถูกต้องควรทําให้เมธอดแสดงผล ErrorCode::INVALID_PURPOSE

การติดตั้งใช้งาน Keymaster 1 รองรับ ECB, CBC, CTR และ GCM สําหรับการเข้ารหัสและถอดรหัส AES

get_supported_padding_modes

เวอร์ชัน: 1

แสดงรายการโหมดการเติมที่รองรับโดยการใช้งานฮาร์ดแวร์ Keymaster สำหรับอัลกอริทึมและวัตถุประสงค์ที่ระบุ

HMAC และ EC ไม่มีแนวคิดเรื่องการเติม ดังนั้นเมธอดจะแสดงผลลิสต์ว่างสำหรับวัตถุประสงค์ที่ถูกต้องทั้งหมด วัตถุประสงค์ที่ไม่ถูกต้องจะทำให้เมธอดแสดงผล ErrorCode::INVALID_PURPOSE

สำหรับ RSA การติดตั้งใช้งาน Keymaster 1 รองรับการดำเนินการต่อไปนี้

• การเข้ารหัส การถอดรหัส การเซ็นชื่อ และการยืนยันแบบไม่เพิ่มค่าใดๆ สําหรับการเข้ารหัสและการรับรองที่ไม่เพิ่มการเติม หากข้อความสั้นกว่าค่าโมดูลสาธารณะ การใช้งานจะต้องเติม 0 ไว้ข้างหน้า สำหรับการถอดรหัสและการยืนยันแบบไม่เพิ่มการเติมความยาวของอินพุตต้องตรงกับขนาดของค่าโมดูลัสสาธารณะ
• โหมดการเติมข้อมูลการเข้ารหัสและการลงนาม PKCS#1 v1.5
• PSS ที่มีความยาวเกลือขั้นต่ำ 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 และรองรับการนําเข้าข้อมูลคีย์ AES และ HMAC แบบ RAW

get_supported_export_formats

เวอร์ชัน: 1

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

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

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

Keymaster 0

ฟังก์ชันต่อไปนี้เป็นของคีย์มาสเตอร์ 0 เวอร์ชันเดิม ข้อมูลเหล่านี้อยู่ในโครงสร้าง keymaster1_device_t ของ Keymaster 1 อย่างไรก็ตาม ใน Keymaster 1.0 ไม่ได้ติดตั้งใช้งานและตั้งค่าตัวชี้ฟังก์ชันเป็น NULL

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

Keymaster 1

ฟังก์ชันต่อไปนี้เป็นส่วนหนึ่งของคําจํากัดความของ Keymaster 1 แต่ถูกนําออกใน Keymaster 2 พร้อมกับฟังก์ชัน Keymaster 0 ที่ระบุไว้ข้างต้น

• get_supported_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_supported_export_formats

Keymaster 2

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

• configure