หน้านี้ให้รายละเอียดเพื่อช่วยเหลือผู้ใช้งาน Keymaster Hardware Abstraction Layers (HAL) โดยครอบคลุมแต่ละฟังก์ชันใน API และเวอร์ชันของ Keymaster ที่ฟังก์ชันพร้อมใช้งานและอธิบายการใช้งานเริ่มต้น สำหรับแท็ก โปรดดูที่หน้า แท็กคีย์มาสเตอร์
แนวทางการดำเนินงานทั่วไป
แนวทางต่อไปนี้ใช้กับฟังก์ชันทั้งหมดใน API
ป้อนพารามิเตอร์ตัวชี้
เวอร์ชัน : 1, 2
พารามิเตอร์ตัวชี้อินพุตที่ไม่ได้ใช้สำหรับการโทรที่กำหนดอาจเป็น NULL
ผู้โทรไม่จำเป็นต้องระบุตัวยึดตำแหน่ง ตัวอย่างเช่น คีย์บางประเภทและโหมดอาจไม่ใช้ค่าใดๆ จากอาร์กิวเมนต์ inParams
เพื่อ เริ่มต้น ดังนั้นผู้เรียกอาจตั้งค่า inParams
เป็น NULL
หรือจัดเตรียมชุดพารามิเตอร์ว่าง ผู้เรียกยังสามารถจัดเตรียมพารามิเตอร์ที่ไม่ได้ใช้ และวิธีการ Keymaster ไม่ควรแสดงข้อผิดพลาด
หากพารามิเตอร์อินพุตที่ต้องการเป็น NULL วิธีการคีย์มาสเตอร์ควรส่งคืน ErrorCode::UNEXPECTED_NULL_POINTER
เริ่มต้นใน Keymaster 3 จะไม่มีพารามิเตอร์ตัวชี้ พารามิเตอร์ทั้งหมดถูกส่งผ่านโดยค่าหรือการอ้างอิง const
พารามิเตอร์ตัวชี้เอาต์พุต
เวอร์ชัน : 1, 2
เช่นเดียวกับพารามิเตอร์ตัวชี้อินพุต พารามิเตอร์ตัวชี้เอาต์พุตที่ไม่ได้ใช้อาจเป็น NULL
หากเมธอดจำเป็นต้องส่งคืนข้อมูลในพารามิเตอร์เอาต์พุตที่พบว่าเป็น NULL
ก็ควรส่งคืน ErrorCode::OUTPUT_PARAMETER_NULL
เริ่มต้นใน Keymaster 3 จะไม่มีพารามิเตอร์ตัวชี้ พารามิเตอร์ทั้งหมดถูกส่งผ่านโดยค่าหรือการอ้างอิง const
การใช้ API ในทางที่ผิด
เวอร์ชัน : 1, 2, 3
มีหลายวิธีที่ผู้โทรสามารถส่งคำขอที่ไม่สมเหตุสมผลหรือโง่เขลาแต่ไม่ผิดทางเทคนิค การใช้งานคีย์มาสเตอร์ไม่จำเป็นต้องล้มเหลวในกรณีเช่นนี้หรือออกการวินิจฉัย การใช้คีย์ที่เล็กเกินไป ข้อมูลจำเพาะของพารามิเตอร์อินพุตที่ไม่เกี่ยวข้อง การใช้ IV หรือ nonces ซ้ำ การสร้างคีย์โดยไม่มีวัตถุประสงค์ (จึงไม่มีประโยชน์) และอื่นๆ ที่คล้ายกัน ไม่ควรได้รับการวินิจฉัยโดยการใช้งาน การละเว้นพารามิเตอร์ที่จำเป็น ข้อมูลจำเพาะของพารามิเตอร์ที่จำเป็นที่ไม่ถูกต้อง และข้อผิดพลาดที่คล้ายกันจะต้องได้รับการวินิจฉัย
เป็นความรับผิดชอบของแอป เฟรมเวิร์ก และที่เก็บคีย์ Android เพื่อให้แน่ใจว่าการเรียกโมดูล Keymaster นั้นสมเหตุสมผลและมีประโยชน์
ฟังก์ชั่น
รับคุณสมบัติฮาร์ดแวร์
เวอร์ชั่น : 3
เมธอด getHardwareFeatures
ใหม่จะเปิดเผยคุณลักษณะที่สำคัญบางประการของฮาร์ดแวร์ที่มีการรักษาความปลอดภัยพื้นฐานให้กับลูกค้า เมธอดนี้ไม่รับอาร์กิวเมนต์และส่งกลับค่าสี่ค่า บูลีนทั้งหมด:
-
isSecure
เป็นtrue
หากคีย์ถูกจัดเก็บไว้ในฮาร์ดแวร์ที่ปลอดภัย (TEE ฯลฯ) และไม่เคยปล่อยทิ้งไว้ -
supportsEllipticCurve
เป็นtrue
หากฮาร์ดแวร์รองรับการเข้ารหัส Elliptic Curve ด้วยเส้นโค้ง 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 เนื่องจากข้อมูลนี้มีอยู่ในไฟล์คุณสมบัติของระบบ และการใช้งานของผู้ผลิตจะอ่านไฟล์เหล่านั้นระหว่างการเริ่มต้นระบบ
กำหนดค่าคีย์มาสเตอร์ วิธีการนี้จะเรียกหนึ่งครั้งหลังจากเปิดอุปกรณ์และก่อนใช้งาน ใช้เพื่อจัดเตรียม KM_TAG_OS_VERSION และ KM_TAG_OS_PATCHLEVEL ให้กับคีย์มาสเตอร์ จนกว่าจะมีการเรียกเมธอดนี้ เมธอดอื่นๆ ทั้งหมดจะส่งคืน KM_ERROR_KEYMASTER_NOT_CONFIGURED
ค่าที่ระบุโดยวิธีนี้ได้รับการยอมรับโดยคีย์มาสเตอร์เพียงครั้งเดียวต่อการบูตเท่านั้น การโทรครั้งต่อไปจะส่งคืน KM_ERROR_OK
แต่ไม่ทำอะไรเลย
หากการใช้งานคีย์มาสเตอร์อยู่ในฮาร์ดแวร์ที่ปลอดภัยและเวอร์ชันของระบบปฏิบัติการและค่าระดับแพตช์ที่ระบุไม่ตรงกับค่าที่บูตโหลดเดอร์มอบให้กับฮาร์ดแวร์ที่ปลอดภัย (หรือหากบูตโหลดเดอร์ไม่ได้ระบุค่า) ดังนั้นเมธอดนี้จะส่งคืน 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 ฯลฯ
การใช้งานคีย์มาสเตอร์จำเป็นต้องผสมเอนโทรปีที่ให้มาลงในพูลอย่างปลอดภัย ซึ่งจะต้องมีเอนโทรปีที่สร้างขึ้นภายในจากตัวสร้างตัวเลขสุ่มของฮาร์ดแวร์ด้วย การผสมควรได้รับการจัดการเพื่อให้ผู้โจมตีที่สามารถควบคุมบิตที่ให้มาด้วย addRngEntropy
หรือบิตที่สร้างโดยฮาร์ดแวร์ได้อย่างสมบูรณ์ แต่ไม่ใช่ทั้งสองอย่าง ไม่มีข้อได้เปรียบที่ไม่อาจละเลยในการทำนายบิตที่สร้างจากพูลเอนโทรปี
การใช้งานคีย์มาสเตอร์ที่พยายามประมาณค่าเอนโทรปีในพูลภายในจะถือว่าข้อมูลที่จัดทำโดย addRngEntropy
ไม่มีเอนโทรปี การใช้งานคีย์มาสเตอร์อาจส่งคืน ErrorCode::INVALID_INPUT_LENGTH
หากได้รับข้อมูลมากกว่า 2 KiB ในการโทรครั้งเดียว
สร้างคีย์
เวอร์ชัน : 1, 2, 3
ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น generate_key
และเปลี่ยนชื่อใน Keymaster 3
สร้างคีย์การเข้ารหัสลับใหม่ โดยระบุการอนุญาตที่เกี่ยวข้อง ซึ่งผูกไว้กับคีย์อย่างถาวร การใช้งานคีย์มาสเตอร์ทำให้ไม่สามารถใช้คีย์ในลักษณะที่ไม่สอดคล้องกับการอนุญาตที่ระบุ ณ เวลาที่สร้างได้ ในส่วนของการอนุญาตที่ฮาร์ดแวร์ที่ปลอดภัยไม่สามารถบังคับใช้ได้ ภาระหน้าที่ของฮาร์ดแวร์ที่ปลอดภัยนั้นจำกัดอยู่เพียงเพื่อให้แน่ใจว่าการอนุญาตที่ไม่สามารถบังคับใช้ได้ที่เกี่ยวข้องกับคีย์นั้นไม่สามารถแก้ไขได้ ดังนั้นการเรียก getKeyCharacteristics ทุกครั้งจะส่งกลับค่าดั้งเดิม นอกจากนี้ คุณลักษณะที่ส่งคืนโดย generateKey
จะจัดสรรการอนุญาตอย่างถูกต้องระหว่างรายการที่บังคับใช้ฮาร์ดแวร์และรายการที่บังคับใช้ซอฟต์แวร์ ดู getKeyCharacteristics สำหรับรายละเอียดเพิ่มเติม
พารามิเตอร์ที่ให้ไว้สำหรับ generateKey
ขึ้นอยู่กับประเภทของคีย์ที่ถูกสร้างขึ้น ส่วนนี้จะสรุปแท็กที่จำเป็นและเป็นทางเลือกสำหรับคีย์แต่ละประเภท Tag::ALGORITHM จำเป็นเสมอเพื่อระบุประเภท
คีย์อาร์เอสเอ
จำเป็นต้องใช้พารามิเตอร์ต่อไปนี้เพื่อสร้างคีย์ 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::วัตถุประสงค์ ระบุวัตถุประสงค์ที่ได้รับอนุญาต วัตถุประสงค์ทั้งหมดต้องได้รับการสนับสนุนสำหรับคีย์ RSA ไม่ว่าจะใช้ร่วมกันอย่างไร
- แท็ก::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 ตามลำดับ
Tag::DIGEST ยังจำเป็นสำหรับคีย์ ECDSA ที่มีประโยชน์ แต่ไม่จำเป็นสำหรับการสร้าง
คีย์เออีเอส
ต้องใช้ แท็ก::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 ถูกผูกไว้กับคีย์แบบเข้ารหัส แต่อาจไม่สามารถระบุได้ในระหว่างการสร้างหรือนำเข้าคีย์ และจะไม่มีการส่งคืน
นอกเหนือจากแท็กที่ให้มา trustlet ยังเพิ่ม Tag::ORIGIN ด้วยค่า KeyOrigin::GENERATED
และหากคีย์นั้นต้านทานการย้อนกลับ
ความต้านทานการย้อนกลับ
การต้านทานการย้อนกลับหมายความว่าเมื่อคีย์ถูกลบด้วย DeleteKey หรือ DeleteAllKeys ฮาร์ดแวร์ที่ปลอดภัยจะรับประกันว่าจะไม่สามารถใช้งานได้อีกต่อไป การใช้งานที่ไม่มีการต้านทานการย้อนกลับมักจะส่งคืนวัสดุคีย์ที่สร้างขึ้นหรือนำเข้าไปยังผู้เรียกในรูปแบบคีย์บล็อบ ซึ่งเป็นแบบฟอร์มที่เข้ารหัสและรับรองความถูกต้อง เมื่อที่เก็บคีย์ลบคีย์บล็อบ คีย์จะหายไป แต่ผู้โจมตีที่เคยจัดการเพื่อดึงข้อมูลคีย์อาจกู้คืนไปยังอุปกรณ์ได้
คีย์สามารถต้านทานการย้อนกลับได้หากฮาร์ดแวร์ที่ปลอดภัยรับประกันว่าคีย์ที่ถูกลบไปแล้วไม่สามารถกู้คืนได้ในภายหลัง โดยทั่วไปจะทำได้โดยการจัดเก็บข้อมูลเมตาที่สำคัญเพิ่มเติมไว้ในตำแหน่งที่เชื่อถือได้ซึ่งผู้โจมตีไม่สามารถจัดการได้ บนอุปกรณ์เคลื่อนที่ กลไกที่ใช้สำหรับสิ่งนี้มักจะเป็น Replay Protected Memory Blocks (RPMB) เนื่องจากจำนวนคีย์ที่อาจสร้างขึ้นนั้นไม่มีขอบเขตเป็นหลัก และพื้นที่เก็บข้อมูลที่เชื่อถือได้ที่ใช้สำหรับการต้านทานการย้อนกลับอาจมีขนาดจำกัด วิธีการนี้จึงต้องประสบความสำเร็จแม้ว่าจะไม่สามารถจัดเตรียมการต้านทานการย้อนกลับสำหรับคีย์ใหม่ได้ก็ตาม ในกรณีดังกล่าว ไม่ควรเพิ่ม Tag::ROLLBACK_RESISTANT ให้กับคุณลักษณะที่สำคัญ
รับลักษณะเฉพาะของคีย์
เวอร์ชัน : 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 ด้วยอัลกอริธึมการแยกย่อยที่ฮาร์ดแวร์ที่ปลอดภัยไม่รองรับ
- Tag::USER_SECURE_ID และ Tag::USER_AUTH_TYPE บังคับใช้ด้วยฮาร์ดแวร์เฉพาะในกรณีที่มีการบังคับใช้การตรวจสอบสิทธิ์ผู้ใช้ด้วยฮาร์ดแวร์ เพื่อให้บรรลุเป้าหมายนี้ Keymaster trustlet และ trustlet การรับรองความถูกต้องที่เกี่ยวข้องจะต้องปลอดภัยและแบ่งปันคีย์ HMAC ลับที่ใช้ในการลงนามและตรวจสอบโทเค็นการตรวจสอบสิทธิ์ ดูหน้า การรับรองความถูกต้อง สำหรับรายละเอียด
- แท็ก::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME และแท็ก Tag::USAGE_EXPIRE_DATETIME จำเป็นต้องเข้าถึงนาฬิกาแขวนที่ถูกต้องซึ่งตรวจสอบได้ ฮาร์ดแวร์ที่ปลอดภัยส่วนใหญ่จะเข้าถึงได้เฉพาะข้อมูลเวลาที่ได้รับจากระบบปฏิบัติการที่ไม่ปลอดภัยเท่านั้น ซึ่งหมายความว่าแท็กนั้นบังคับใช้โดยซอฟต์แวร์
- Tag::ORIGIN อยู่ในรายการฮาร์ดแวร์สำหรับคีย์ที่เชื่อมโยงกับฮาร์ดแวร์เสมอ การมีอยู่ในรายการนั้นเป็นวิธีที่เลเยอร์ที่สูงกว่ากำหนดว่าคีย์ได้รับการสนับสนุนด้วยฮาร์ดแวร์
นำเข้าคีย์
เวอร์ชัน : 1, 2, 3
ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น import_key
และเปลี่ยนชื่อใน Keymaster 3
นำเข้าเนื้อหาสำคัญไปยังฮาร์ดแวร์ Keymaster พารามิเตอร์คำจำกัดความคีย์และคุณลักษณะเอาต์พุตได้รับการจัดการเหมือนกับ generateKey
โดยมีข้อยกเว้นต่อไปนี้:
- Tag::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
ลบคีย์
เวอร์ชัน : 1, 2, 3
ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น delete_key
และเปลี่ยนชื่อใน Keymaster 3
ลบคีย์ที่ให้มา วิธีการนี้เป็นทางเลือก และใช้ได้เฉพาะกับโมดูล Keymaster ที่มีความต้านทานการย้อนกลับเท่านั้น
ลบAllKeys
เวอร์ชัน : 1, 2, 3
ฟังก์ชันนี้ถูกนำมาใช้ใน Keymaster 1 เป็น delete_all_keys
และเปลี่ยนชื่อใน Keymaster 3
ลบคีย์ทั้งหมด วิธีการนี้เป็นทางเลือก และใช้ได้เฉพาะกับโมดูล Keymaster ที่มีความต้านทานการย้อนกลับเท่านั้น
ทำลายรหัสรับรอง
เวอร์ชั่น : 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 รายการ เหลือ 1 รายการสำหรับ 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 จะได้รับอนุญาตให้ดำเนินการได้สำเร็จ แม้ว่าจะไม่เป็นไปตามข้อกำหนดในการอนุญาตก็ตาม
- Tag::วัตถุประสงค์ : วัตถุประสงค์ที่ระบุในการเรียก
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
- 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 ด้วย หากคีย์มีทั้งสองอย่าง วิธีการนี้จะต้องได้รับ Tag::AUTH_TOKEN ที่ถูกต้องใน
inParams
เพื่อให้โทเค็นการตรวจสอบความถูกต้องถูกต้อง ต้องเป็นไปตามเงื่อนไขทั้งหมดต่อไปนี้:- ช่อง HMAC ตรวจสอบอย่างถูกต้อง
- ค่า Tag::USER_SECURE_ID อย่างน้อยหนึ่งค่าจากคีย์ตรงกับค่า ID ที่ปลอดภัยอย่างน้อยหนึ่งค่าในโทเค็น
- คีย์มี Tag::USER_AUTH_TYPE ที่ตรงกับประเภทการรับรองความถูกต้องในโทเค็น
หากไม่ตรงตามเงื่อนไขใดๆ เหล่านี้ วิธีการจะส่งกลับ
ErrorCode::KEY_USER_NOT_AUTHENTICATED
- Tag::CALLER_NONCE อนุญาตให้ผู้เรียกระบุ nonce หรือเวกเตอร์การเริ่มต้น (IV) ถ้าคีย์ไม่มีแท็กนี้ แต่ผู้เรียกระบุ Tag::NONCE สำหรับเมธอดนี้
ErrorCode::CALLER_NONCE_PROHIBITED
จะถูกส่งกลับ - Tag::BOOTLOADER_ONLY ระบุว่าเฉพาะ bootloader เท่านั้นที่สามารถใช้คีย์ได้ หากเรียกใช้เมธอดนี้ด้วยคีย์สำหรับบูตโหลดเดอร์เท่านั้นหลังจากที่บูตโหลดเดอร์ดำเนินการเสร็จสิ้นแล้ว ก็จะส่งกลับ
ErrorCode::INVALID_KEY_BLOB
คีย์อาร์เอสเอ
การดำเนินการคีย์ 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 padding ทั้งหมดจะใช้ได้กับวัตถุประสงค์บางอย่างเท่านั้น โดยเฉพาะอย่างยิ่ง 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
แทน0x00 || 0x01 || PS || 0x00 || M
โดยที่ M คือข้อความที่ให้มา และ PS คือสตริงการเติม ขนาดของคีย์ RSA จะต้องมีขนาดใหญ่กว่าข้อความอย่างน้อย 11 ไบต์ มิฉะนั้นเมธอดจะส่งกลับErrorCode::INVALID_INPUT_LENGTH
-
PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT
การเติมไม่จำเป็นต้องมีการแยกย่อย -
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 ระบุโหมดการเติมหนึ่งโหมดใน inParams
หากไม่ได้ระบุหรือระบุมากกว่าหนึ่งครั้ง วิธีการจะส่งกลับ ErrorCode::UNSUPPORTED_PADDING_MODE
การดำเนินการคีย์ส่วนตัว ( KeyPurpose::SIGN
) จำเป็นต้องมีการอนุญาตการแยกย่อยและการเติม ซึ่งหมายความว่าการอนุญาตคีย์จำเป็นต้องมีค่าที่ระบุ ถ้าไม่เช่นนั้น ให้ส่งคืน ErrorCode::INCOMPATIBLE_DIGEST
การดำเนินการคีย์สาธารณะ ( KeyPurpose::VERIFY
) ได้รับอนุญาตโดยมีการแยกย่อยหรือขยายโดยไม่ได้รับอนุญาต
คีย์เออีเอส
การดำเนินการคีย์ AES ระบุโหมดบล็อกหนึ่งโหมดและโหมดการขยายหนึ่งโหมดใน inParams
หากค่าใดค่าหนึ่งไม่ได้ระบุหรือระบุมากกว่าหนึ่งครั้ง ให้ส่งคืน 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 ไบต์ nonce ของ 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
จัดเตรียมข้อมูลเพื่อประมวลผลในการดำเนินการต่อเนื่องที่เริ่มต้นด้วย beginning การดำเนินการถูกระบุโดยพารามิเตอร์ operationHandle
เพื่อให้มีความยืดหยุ่นมากขึ้นในการจัดการบัฟเฟอร์ การใช้งานวิธีนี้จึงมีตัวเลือกในการใช้ข้อมูลน้อยกว่าที่ให้ไว้ ผู้โทรมีหน้าที่รับผิดชอบในการวนซ้ำเพื่อป้อนข้อมูลที่เหลือในการโทรครั้งต่อไป จำนวนอินพุตที่ใช้จะถูกส่งกลับในพารามิเตอร์ inputConsumed
การใช้งานจะใช้อย่างน้อยหนึ่งไบต์เสมอ เว้นแต่การดำเนินการจะไม่สามารถยอมรับได้อีกต่อไป หากมีการระบุมากกว่าศูนย์ไบต์และใช้ไบต์เป็นศูนย์ ผู้เรียกจะพิจารณาว่านี่เป็นข้อผิดพลาดและยกเลิกการดำเนินการ
การใช้งานอาจเลือกจำนวนข้อมูลที่ส่งคืนอันเป็นผลมาจากการอัปเดต สิ่งนี้เกี่ยวข้องกับการดำเนินการเข้ารหัสและถอดรหัสเท่านั้น เนื่องจากการลงนามและการตรวจสอบยืนยันจะไม่ส่งคืนข้อมูลจนกว่า จะเสร็จสิ้น ส่งคืนข้อมูลโดยเร็วที่สุด แทนที่จะบัฟเฟอร์
การจัดการข้อผิดพลาด
ถ้าวิธีนี้ส่งกลับรหัสข้อผิดพลาดอื่นที่ไม่ใช่ ErrorCode::OK
การดำเนินการจะถูกยกเลิกและหมายเลขอ้างอิงการดำเนินการไม่ถูกต้อง การใช้หมายเลขอ้างอิงใด ๆ ในอนาคต ด้วยวิธีนี้ เสร็จสิ้น หรือ ยกเลิก จะส่งกลับ ErrorCode::INVALID_OPERATION_HANDLE
การบังคับใช้การอนุญาต
การบังคับใช้การอนุญาตคีย์จะดำเนินการเป็นหลักใน beginning ข้อยกเว้นประการหนึ่งคือกรณีที่คีย์มี:
- แท็ก::USER_SECURE_IDs อย่างน้อยหนึ่งรายการ และ
- ไม่มี แท็ก::AUTH_TIMEOUT
ในกรณีนี้ คีย์จำเป็นต้องได้รับอนุญาตต่อการดำเนินการ และวิธีการอัปเดตจะได้รับ Tag::AUTH_TOKEN ในอาร์กิวเมนต์ inParams
HMAC ตรวจสอบว่าโทเค็นถูกต้องและมี ID ผู้ใช้ที่ปลอดภัยที่ตรงกัน ตรงกับ Tag::USER_AUTH_TYPE ของคีย์ และมีตัวจัดการการดำเนินการของการดำเนินการปัจจุบันในช่องท้าทาย หากไม่ตรงตามเงื่อนไขเหล่านี้ ให้ส่งคืน ErrorCode::KEY_USER_NOT_AUTHENTICATED
ผู้เรียกจะให้โทเค็นการรับรองความถูกต้องแก่ทุกการโทรเพื่อ อัปเดต และ เสร็จสิ้น การใช้งานจำเป็นต้องตรวจสอบโทเค็นเพียงครั้งเดียวหากต้องการ
คีย์อาร์เอสเอ
สำหรับการลงนามและการดำเนินการตรวจสอบด้วย Digest::NONE
วิธีการนี้จะยอมรับบล็อกทั้งหมดที่จะลงนามหรือตรวจสอบในการอัปเดตครั้งเดียว ไม่อาจกินเพียงส่วนหนึ่งของบล็อก อย่างไรก็ตาม หากผู้เรียกเลือกที่จะให้ข้อมูลในการอัพเดตหลายครั้ง วิธีการนี้จะยอมรับข้อมูลดังกล่าว หากผู้เรียกให้ข้อมูลในการลงนามมากกว่าที่สามารถใช้ได้ (ความยาวของข้อมูลเกินขนาดคีย์ RSA) ให้ส่งคืน ErrorCode::INVALID_INPUT_LENGTH
คีย์ ECDSA
สำหรับการลงนามและการดำเนินการตรวจสอบด้วย Digest::NONE
วิธีการนี้จะยอมรับบล็อกทั้งหมดที่จะลงนามหรือตรวจสอบในการอัปเดตครั้งเดียว วิธีนี้อาจไม่ใช้เพียงส่วนหนึ่งของบล็อกเท่านั้น
อย่างไรก็ตาม หากผู้เรียกเลือกที่จะให้ข้อมูลในการอัพเดตหลายครั้ง วิธีการนี้จะยอมรับข้อมูลดังกล่าว หากผู้เรียกให้ข้อมูลในการลงนามมากกว่าที่สามารถใช้ได้ ข้อมูลจะถูกตัดทอนโดยไม่แจ้งให้ทราบ (สิ่งนี้แตกต่างจากการจัดการข้อมูลที่เกินมาในการดำเนินการ RSA ที่คล้ายกัน เหตุผลก็คือความเข้ากันได้กับไคลเอนต์รุ่นเก่า)
คีย์เออีเอส
โหมด AES GCM รองรับ "ข้อมูลการตรวจสอบสิทธิ์ที่เกี่ยวข้อง" ที่ให้มาผ่านแท็ก Tag::ASSOCIATED_DATA ในอาร์กิวเมนต์ inParams
ข้อมูลที่เกี่ยวข้องอาจถูกจัดเตรียมไว้ในการเรียกซ้ำๆ (สำคัญหากข้อมูลมีขนาดใหญ่เกินกว่าจะส่งในบล็อกเดียว) แต่จะต้องนำหน้าข้อมูลที่จะเข้ารหัสหรือถอดรหัสเสมอ การเรียกการอัปเดตอาจได้รับทั้งข้อมูลที่เกี่ยวข้องและข้อมูลเพื่อเข้ารหัส/ถอดรหัส แต่การอัปเดตในภายหลังอาจไม่รวมข้อมูลที่เกี่ยวข้อง หากผู้เรียกให้ข้อมูลที่เกี่ยวข้องแก่การโทรอัปเดตหลังการโทรที่มีข้อมูลที่จะเข้ารหัส/ถอดรหัส ให้ส่งคืน ErrorCode::INVALID_TAG
สำหรับการเข้ารหัส GCM แท็กจะถูกต่อท้ายข้อความไซเฟอร์ด้วย การเสร็จสิ้น ในระหว่างการถอดรหัส Tag::MAC_LENGTH
ไบต์สุดท้ายของข้อมูลที่ให้ไว้สำหรับการเรียกอัปเดตครั้งล่าสุดคือแท็ก เนื่องจากการเรียกใช้การ อัปเดต ที่ระบุไม่สามารถทราบได้ว่าเป็นการเรียกใช้ครั้งล่าสุดหรือไม่ จึงประมวลผลทั้งหมดยกเว้นความยาวแท็กและบัฟเฟอร์ข้อมูลแท็กที่เป็นไปได้ระหว่าง การเสร็จสิ้น
เสร็จ
เวอร์ชัน : 1, 2, 3
เสร็จสิ้นการดำเนินการต่อเนื่องที่เริ่มต้นด้วย start ประมวลผลข้อมูลที่ยังไม่ได้ประมวลผลทั้งหมดที่ได้รับจาก การอัปเดต
เมธอดนี้เป็นเมธอดสุดท้ายที่ถูกเรียกใช้ในการดำเนินการ ดังนั้นข้อมูลที่ประมวลผลทั้งหมดจึงถูกส่งกลับ
ไม่ว่าจะเสร็จสิ้นสำเร็จหรือส่งคืนข้อผิดพลาดวิธีนี้จะเสร็จสิ้นการดำเนินการและทำให้การจัดการการดำเนินการที่ให้ไว้นั้นไม่ถูกต้อง การใช้งานที่จับในอนาคตด้วยวิธีนี้หรือ อัปเดต หรือ ยกเลิก จะส่งคืน ErrorCode::INVALID_OPERATION_HANDLE
การลงนามในการดำเนินการส่งคืนลายเซ็นเป็นเอาต์พุต การดำเนินการตรวจสอบยอมรับลายเซ็นในพารามิเตอร์ signature
และส่งคืนไม่มีการส่งออก
การบังคับใช้กฎหมาย
การบังคับใช้การอนุญาตที่สำคัญจะดำเนินการเป็นหลักใน การเริ่มต้น ข้อยกเว้นหนึ่งคือกรณีที่คีย์มี:
- หนึ่ง แท็กหรือมากกว่า :: user_secure_ids และ
- ไม่มี แท็ก :: auth_timeout
ในกรณีนี้คีย์ต้องได้รับอนุญาตต่อการดำเนินการและวิธีการอัปเดตจะได้รับ แท็ก :: auth_token ในอาร์กิวเมนต์ inParams
HMAC ตรวจสอบว่าโทเค็นนั้นถูกต้องและมีรหัสผู้ใช้ที่ปลอดภัยที่ตรงกันตรงกับ แท็กของคีย์ :: user_auth_type และมีที่จับการดำเนินการของการดำเนินการปัจจุบันในฟิลด์ Challenge หากเงื่อนไขเหล่านี้ไม่เป็นไปตาม ErrorCode::KEY_USER_NOT_AUTHENTICATED
ผู้โทรมอบโทเค็นการรับรองความถูกต้องสำหรับการโทรทุกครั้งเพื่อ อัปเดต และ เสร็จสิ้น การใช้งานจำเป็นต้องมีการตรวจสอบโทเค็นเพียงครั้งเดียวหากต้องการ
คีย์อาร์เอสเอ
ข้อกำหนดเพิ่มเติมบางอย่างขึ้นอยู่กับโหมดการขยาย:
-
PaddingMode::NONE
สำหรับการดำเนินการลงนามและการเข้ารหัสที่ไม่ได้เพิ่มหากข้อมูลที่ให้นั้นสั้นกว่าคีย์ข้อมูลจะเป็นแบบไม่มีการเสริมทางด้านซ้ายก่อนการลงนาม/การเข้ารหัส หากข้อมูลมีความยาวเท่ากับคีย์ แต่มีขนาดใหญ่กว่าตัวเลขให้ส่งคืนErrorCode::INVALID_ARGUMENT
สำหรับการตรวจสอบและการถอดรหัสข้อมูลจะต้องตรงกับคีย์ มิฉะนั้นให้ส่งคืนErrorCode::INVALID_INPUT_LENGTH.
-
PaddingMode::RSA_PSS
สำหรับการดำเนินการลายเซ็น PSS-padded เกลือ PSS คือขนาดของการย่อยข้อความและสร้างแบบสุ่ม Digest ที่ระบุด้วย Tag :: Digest ในinputParams
บน เริ่มต้น ใช้เป็นอัลกอริทึม Digest PSS และเป็นอัลกอริทึม MGF1 Digest -
PaddingMode::RSA_OAEP
Digest ที่ระบุด้วย Tag :: Digest ในinputParams
บน เริ่มต้น ใช้เป็นอัลกอริทึม Digest OAEP และ SHA1 ใช้เป็นอัลกอริทึม MGF1 Digest
คีย์ ECDSA
หากข้อมูลที่ให้ไว้สำหรับการลงนามหรือการตรวจสอบที่ไม่ได้เพิ่มขึ้นนั้นยาวเกินไปให้ตัดทอน
คีย์ AES
เงื่อนไขเพิ่มเติมบางอย่างขึ้นอยู่กับโหมดบล็อก:
-
BlockMode::ECB
หรือBlockMode::CBC
หากการเติมผ้าเป็นPaddingMode::NONE
และความยาวของข้อมูลไม่ใช่ขนาดบล็อก AES หลายตัวให้ส่งคืนErrorCode::INVALID_INPUT_LENGTH
หากการตอบสนองคือPaddingMode::PKCS7
ให้เพิ่มข้อมูลตามข้อกำหนด PKCS#7 โปรดทราบว่า PKCS#7 แนะนำให้เพิ่มบล็อกการขยายเพิ่มเติมหากข้อมูลเป็นความยาวหลายบล็อก -
BlockMode::GCM
ในระหว่างการเข้ารหัสหลังจากประมวลผลข้อความธรรมดาทั้งหมดให้คำนวณแท็ก ( แท็ก :: mac_length bytes) และผนวกเข้ากับ ciphertext ที่ส่งคืน ในระหว่างการถอดรหัสให้ประมวลผล แท็กสุดท้าย :: mac_length ไบต์เป็นแท็ก หากการตรวจสอบแท็กล้มเหลวให้ส่งคืนErrorCode::VERIFICATION_FAILED
ยกเลิก
เวอร์ชัน : 1, 2, 3
ยกเลิกการดำเนินงานที่กำลังดำเนินการอยู่ หลังจากการเรียกให้ยกเลิกให้ส่งคืน ErrorCode::INVALID_OPERATION_HANDLE
สำหรับการใช้งานการดำเนินการที่ให้มาพร้อมกับ การอัปเดต เสร็จสิ้น หรือ ยกเลิก
get_supported_algorithms
เวอร์ชั่น : 1
ส่งคืนรายการอัลกอริทึมที่รองรับโดยการใช้งานฮาร์ดแวร์ Keymaster การใช้งานซอฟต์แวร์ส่งคืนรายการที่ว่างเปล่า การใช้งานแบบไฮบริดส่งคืนรายการที่มีเฉพาะอัลกอริทึมที่สนับสนุนโดยฮาร์ดแวร์
การใช้งาน Keymaster 1 รองรับ RSA, EC, AES และ HMAC
get_supported_block_modes
เวอร์ชั่น : 1
ส่งคืนรายการโหมดบล็อก AES ที่รองรับโดยการใช้งานฮาร์ดแวร์ Keymaster สำหรับอัลกอริทึมและวัตถุประสงค์ที่ระบุ
สำหรับ RSA, EC และ HMAC ซึ่งไม่ได้บล็อก Ciphers วิธีการส่งคืนรายการว่างเปล่าสำหรับวัตถุประสงค์ที่ถูกต้องทั้งหมด วัตถุประสงค์ที่ไม่ถูกต้องควรทำให้วิธีการส่งคืน 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 ที่มีความยาวเกลือขั้นต่ำ 20
- OAEP
สำหรับ AES ในโหมด ECB และ CBC การใช้งาน Keymaster 1 ไม่สนับสนุนการขยายช่องว่างและ PKCS#7-padding โหมด 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 ไม่รองรับการส่งออกคีย์ส่วนตัวหรือคีย์แบบอสมมาตร
ฟังก์ชั่นประวัติศาสตร์
Keymaster 0
ฟังก์ชั่นต่อไปนี้เป็นของคำจำกัดความ Keymaster 0 ต้นฉบับ พวกเขามีอยู่ใน Keymaster 1 struct keymaster1_device_t อย่างไรก็ตามใน Keymaster 1.0 พวกเขาไม่ได้ถูกนำไปใช้และพอยน์เตอร์ฟังก์ชั่นของพวกเขาถูกตั้งค่าเป็นโมฆะ
-
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