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

หน้านี้ให้รายละเอียดเพื่อช่วยเหลือผู้ใช้งาน 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 และหากคีย์นั้นต้านทานการย้อนกลับ

แท็ก::ROLLBACK_RESISTANT

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

การต้านทานการย้อนกลับหมายความว่าเมื่อคีย์ถูกลบด้วย 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 ข้อยกเว้นประการหนึ่งคือกรณีที่คีย์มี:

ในกรณีนี้ คีย์จำเป็นต้องได้รับอนุญาตต่อการดำเนินการ และวิธีการอัปเดตจะได้รับ 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 และส่งคืนไม่มีการส่งออก

การบังคับใช้กฎหมาย

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

ในกรณีนี้คีย์ต้องได้รับอนุญาตต่อการดำเนินการและวิธีการอัปเดตจะได้รับ แท็ก :: 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