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

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

แนวทางปฏิบัติทั่วไป

แนวทางต่อไปนี้ใช้กับฟังก์ชันทั้งหมดใน API

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

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

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

หากพารามิเตอร์อินพุตที่ต้องการเป็น NULL เมธอดของ Keymaster ควรส่งคืน ErrorCode::UNEXPECTED_NULL_POINTER

เริ่มต้นใน Keymaster 3 ไม่มีพารามิเตอร์ตัวชี้ พารามิเตอร์ทั้งหมดถูกส่งผ่านโดยค่าหรือการอ้างอิง const

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

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

เช่นเดียวกับพารามิเตอร์ตัวชี้อินพุต พารามิเตอร์ตัวชี้เอาต์พุตที่ไม่ได้ใช้อาจเป็น NULL หากเมธอดจำเป็นต้องส่งคืนข้อมูลในพารามิเตอร์เอาต์พุตที่พบว่าเป็น NULL ก็ควรส่งคืน ErrorCode::OUTPUT_PARAMETER_NULL

เริ่มต้นใน Keymaster 3 ไม่มีพารามิเตอร์ตัวชี้ พารามิเตอร์ทั้งหมดถูกส่งผ่านโดยค่าหรือการอ้างอิง const

การใช้ API ในทางที่ผิด

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

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

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

ฟังก์ชั่น

getHardwareFeatures

เวอร์ชัน : 3

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

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

addRngEntropy

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

ฟังก์ชั่นนี้ถูกนำมาใช้ใน Keymaster 1 เป็น add_rng_entropy และเปลี่ยนชื่อใน Keymaster 3

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

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

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

สร้างคีย์

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

ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น generate_key และเปลี่ยนชื่อใน Keymaster 3

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

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

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

แท็ก::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:

• แท็ก::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 หากแท็กเหล่านี้รวมอยู่ในพารามิเตอร์คีย์ แท็กเหล่านี้จะถูกลบออกจากคุณลักษณะที่ส่งคืน ดังนั้นจึงไม่สามารถค้นหาค่าได้โดยการตรวจสอบคีย์บล็อบที่ส่งคืน อย่างไรก็ตาม พวกมันถูกผูกไว้กับ key blob แบบเข้ารหัส ดังนั้นถ้าไม่ได้ระบุค่าที่ถูกต้องเมื่อใช้คีย์ การใช้งานจะล้มเหลว ในทำนองเดียวกัน Tag::ROOT_OF_TRUST ถูกผูกไว้กับคีย์แบบเข้ารหัส แต่ไม่สามารถระบุได้ระหว่างการสร้างหรือนำเข้าคีย์ และจะไม่ส่งคืน

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

ความต้านทานย้อนกลับ

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

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

getKeyCharacteristics

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

ฟังก์ชั่นนี้ถูกนำมาใช้ใน Keymaster 1 เป็น get_key_characteristics และเปลี่ยนชื่อใน Keymaster 3

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

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

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

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

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

importKey

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

ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น import_key และเปลี่ยนชื่อใน Keymaster 3

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

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

คีย์ส่งออก

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

ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น export_key และเปลี่ยนชื่อใน Keymaster 3

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

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

deleteKey

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

ฟังก์ชั่นนี้ถูกนำมาใช้ใน Keymaster 1 เป็น delete_key และเปลี่ยนชื่อใน Keymaster 3

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

deleteAllKeys

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

ฟังก์ชั่นนี้ถูกนำมาใช้ใน Keymaster 1 เป็น delete_all_keys และเปลี่ยนชื่อใน Keymaster 3

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

destroyAttestationIds

เวอร์ชัน : 3

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

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

เริ่ม

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

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

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

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

การบังคับใช้การอนุญาต

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

• แท็ก::PURPOSE : วัตถุประสงค์ที่ระบุในการเรียก begin() ต้องตรงกับหนึ่งในวัตถุประสงค์ในการให้สิทธิ์คีย์ เว้นแต่การดำเนินการที่ร้องขอเป็นการดำเนินการคีย์สาธารณะ หากวัตถุประสงค์ที่ระบุไม่ตรงกัน และการดำเนินการไม่ใช่การดำเนินการคีย์สาธารณะ begin จะส่งกลับ ErrorCode::UNSUPPORTED_PURPOSE การทำงานของคีย์สาธารณะคือการเข้ารหัสหรือการดำเนินการตรวจสอบที่ไม่สมมาตร
• แท็ก::ACTIVE_DATETIME สามารถบังคับใช้ได้ก็ต่อเมื่อแหล่งเวลา UTC ที่เชื่อถือได้พร้อมใช้งาน หากวันที่และเวลาปัจจุบันอยู่ก่อนค่าแท็ก เมธอดจะส่งกลับ ErrorCode::KEY_NOT_YET_VALID
• แท็ก::ORIGINATION_EXPIRE_DATETIME สามารถบังคับใช้ได้ก็ต่อเมื่อแหล่งเวลา UTC ที่เชื่อถือได้พร้อมใช้งาน หากวันที่และเวลาปัจจุบันช้ากว่าค่าแท็กและวัตถุประสงค์คือ KeyPurpose::ENCRYPT หรือ KeyPurpose::SIGN เมธอดจะส่งกลับ ErrorCode::KEY_EXPIRED
• แท็ก::USAGE_EXPIRE_DATETIME สามารถบังคับใช้ได้ก็ต่อเมื่อแหล่งเวลา UTC ที่เชื่อถือได้พร้อมใช้งาน หากวันที่และเวลาปัจจุบันช้ากว่าค่าแท็กและวัตถุประสงค์คือ KeyPurpose::DECRYPT หรือ 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 ถูกบังคับใช้โดยวิธีนี้ก็ต่อเมื่อคีย์นั้นมี Tag::AUTH_TIMEOUT ด้วย หากคีย์มีทั้งคู่ เมธอดนี้ต้องได้รับ Tag::AUTH_TOKEN ที่ถูกต้องใน inParams เพื่อให้โทเค็นการตรวจสอบความถูกต้องถูกต้อง สิ่งต่อไปนี้ทั้งหมดจะต้องเป็นจริง:
  • ฟิลด์ HMAC ตรวจสอบอย่างถูกต้อง
  • ค่า Tag::USER_SECURE_ID อย่างน้อยหนึ่งค่าจากคีย์ตรงกับค่า ID ที่ปลอดภัยอย่างน้อยหนึ่งค่าในโทเค็น
  • คีย์มี Tag::USER_AUTH_TYPE ที่ตรงกับประเภทการตรวจสอบสิทธิ์ในโทเค็น

  หากไม่ตรงตามเงื่อนไขใดๆ เมธอดจะส่งกลับ ErrorCode::KEY_USER_NOT_AUTHENTICATED

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

คีย์ RSA

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

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

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

ด้วยข้อยกเว้นของ PaddingMode::NONE โหมดการเติม RSA ทั้งหมดจะใช้ได้เฉพาะกับวัตถุประสงค์บางอย่างเท่านั้น โดยเฉพาะ PaddingMode::RSA_PKCS1_1_5_SIGN และ PaddingMode::RSA_PSS รองรับเฉพาะการลงชื่อและการตรวจสอบ ขณะที่ PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT และ PaddingMode::RSA_OAEP รองรับเฉพาะการเข้ารหัสและถอดรหัสเท่านั้น เมธอดส่งคืน ErrorCode::UNSUPPORTED_PADDING_MODE หากโหมดที่ระบุไม่รองรับวัตถุประสงค์ที่ระบุ

มีการโต้ตอบที่สำคัญบางอย่างระหว่างโหมดการเติมและการย่อย:

• PaddingMode::NONE ระบุว่ามีการดำเนินการ RSA แบบ "ดิบ" หากลงนามหรือยืนยัน Digest::NONE จะถูกระบุสำหรับไดเจสต์ ไม่จำเป็นต้องมีไดเจสต์สำหรับการเข้ารหัสหรือถอดรหัสที่ไม่ได้แพ็ด
• PaddingMode::RSA_PKCS1_1_5_SIGN padding ต้องการไดเจสต์ ไดเจสต์อาจเป็น Digest::NONE ซึ่งในกรณีนี้ การใช้งาน Keymaster ไม่สามารถสร้างโครงสร้างลายเซ็น PKCS#1 v1.5 ที่เหมาะสมได้ เนื่องจากไม่สามารถเพิ่มโครงสร้าง DigestInfo ได้ การใช้งานจะสร้าง 0x00 || 0x01 || PS || 0x00 || M . แทน 0x00 || 0x01 || PS || 0x00 || M โดยที่ M คือข้อความที่ให้มา และ PS คือสตริงการเติม ขนาดของคีย์ RSA ต้องใหญ่กว่าข้อความอย่างน้อย 11 ไบต์ มิฉะนั้น เมธอดจะส่งกลับ ErrorCode::INVALID_INPUT_LENGTH
• PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding ไม่ต้องการไดเจสต์
• PaddingMode::RSA_PSS padding ต้องการไดเจสต์ ซึ่งอาจไม่ใช่ Digest::NONE หาก Digest::NONE เมธอดจะส่งกลับ ErrorCode::INCOMPATIBLE_DIGEST นอกจากนี้ ขนาดของคีย์ RSA ต้องมีอย่างน้อย 2 + D ไบต์ที่ใหญ่กว่าขนาดเอาต์พุตของไดเจสต์ โดยที่ D คือขนาดของไดเจสต์ หน่วยเป็นไบต์ มิฉะนั้นเมธอดจะส่งคืน ErrorCode::INCOMPATIBLE_DIGEST ขนาดเกลือคือ D.
• PaddingMode::RSA_OAEP padding ต้องการไดเจสต์ ซึ่งอาจไม่ใช่ Digest::NONE หาก Digest::NONE เมธอดจะส่งกลับ ErrorCode::INCOMPATIBLE_DIGEST

คีย์ EC

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

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

คีย์ AES

การทำงานของคีย์ AES จะระบุโหมดบล็อกหนึ่งโหมดและโหมดการเติมหนึ่งโหมดใน inParams หากค่าใดค่าหนึ่งไม่ได้ระบุหรือระบุมากกว่าหนึ่งครั้ง ให้ส่งคืน ErrorCode::UNSUPPORTED_BLOCK_MODE หรือ ErrorCode::UNSUPPORTED_PADDING_MODE โหมดที่ระบุต้องได้รับอนุญาตจากคีย์ มิฉะนั้น เมธอดจะส่งกลับ ErrorCode::INCOMPATIBLE_BLOCK_MODE 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 nonce คือ 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

ให้ข้อมูลเพื่อดำเนินการในการดำเนินการต่อเนื่องโดยเริ่มจาก จุดเริ่มต้น การดำเนินการถูกระบุโดยพารามิเตอร์ operationHandle

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

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

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

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

การบังคับใช้การอนุญาต

การบังคับใช้การอนุญาตหลักจะดำเนินการใน เบื้องต้น ข้อยกเว้นประการหนึ่งคือกรณีที่คีย์มี:

• แท็ก::USER_SECURE_IDs หนึ่งรายการขึ้นไป และ
• ไม่มี แท็ก::AUTH_TIMEOUT

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

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

คีย์ RSA

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

คีย์ ECDSA

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

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

คีย์ AES

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

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

เสร็จ

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

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

• One or more Tag::USER_SECURE_IDs , and
• Does not have a Tag::AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

• PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
• PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

• BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
• BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

• Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
• PKCS#1 v1.5 encryption and signing padding modes
• PSS with a minimum salt length of 20
• OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

• configure