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

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

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

หลักเกณฑ์ต่อไปนี้ใช้กับฟังก์ชันทั้งหมดใน API

พารามิเตอร์เคอร์เซอร์อินพุต

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

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

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

ตั้งแต่ Keymaster 3 เป็นต้นไปจะไม่มีพารามิเตอร์เคอร์เซอร์ ระบบจะส่งพารามิเตอร์ทั้งหมด โดยการอ้างอิงค่าหรือ Const

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

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

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

ตั้งแต่ Keymaster 3 เป็นต้นไปจะไม่มีพารามิเตอร์เคอร์เซอร์ พารามิเตอร์ทั้งหมดจะส่งผ่านตามค่าหรือการอ้างอิง const

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

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

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

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

ฟังก์ชัน

getHardwareFeatures

เวอร์ชัน: 3

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

  • 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 เนื่องจากข้อมูลนี้มีอยู่ในไฟล์พร็อพเพอร์ตี้ของระบบ และการใช้งานของผู้ผลิตจะอ่านไฟล์เหล่านั้นระหว่างการเริ่มต้น

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

หากการติดตั้งใช้งาน Keymaster อยู่ในฮาร์ดแวร์ที่มีความปลอดภัย และค่าเวอร์ชันระบบปฏิบัติการและระดับแพตช์ที่ระบุไม่ตรงกับค่าที่บูตโหลดเดอร์ระบุไว้ในฮาร์ดแวร์ที่มีความปลอดภัย (หรือหากบูตโหลดเดอร์ไม่ได้ระบุค่า) วิธีการนี้จะแสดงผลเป็น KM_ERROR_INVALID_ARGUMENT และวิธีการอื่นๆ ทั้งหมดจะแสดงผลเป็น KM_ERROR_KEYMASTER_NOT_CONFIGURED ต่อไป

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

เพิ่มRngEntropy

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

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

เพิ่มข้อมูลความผันผวนของผู้โทรลงในพูลที่ใช้โดยการติดตั้งใช้งาน Keymaster 1 เพื่อใช้สร้างตัวเลขสุ่ม สําหรับคีย์, IV และอื่นๆ

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

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

คีย์สร้าง

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

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

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

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

คีย์ RSA

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

  • Tag::KEY_SIZE ระบุขนาดของโมดูลัสสาธารณะในหน่วยบิต หากไม่ระบุ เมธอดจะแสดง ErrorCode::UNSUPPORTED_KEY_SIZE ค่าที่รองรับคือ 1024, 2048, 3072 และ 4096 ค่าที่แนะนำคือขนาดคีย์ทั้งหมดที่หารด้วย 8 ได้
  • Tag::RSA_PUBLIC_EXPONENT ระบุค่าตัวคูณสาธารณะของ RSA หากไม่ระบุ เมธอดจะแสดงผล ErrorCode::INVALID_ARGUMENT ค่าที่รองรับคือ 3 และ 65537 ค่าที่แนะนำคือค่าจำนวนเฉพาะทั้งหมดสูงสุด 2^64

พารามิเตอร์ต่อไปนี้ไม่จำเป็นต่อการสร้างคีย์ RSA แต่การสร้างคีย์ RSA โดยไม่มีพารามิเตอร์เหล่านี้จะทำให้คีย์ใช้งานไม่ได้ อย่างไรก็ตาม ฟังก์ชัน generateKey จะไม่แสดงผลข้อผิดพลาดหากไม่ใส่พารามิเตอร์เหล่านี้

  • Tag::PURPOSE ระบุวัตถุประสงค์ที่อนุญาต คีย์ RSA ต้องรองรับวัตถุประสงค์ทั้งหมดในชุดค่าผสมใดก็ได้
  • Tag::DIGEST ระบุอัลกอริทึมสำหรับไดเจสต์ที่ใช้กับคีย์ใหม่ได้ การติดตั้งใช้งานที่ไม่รองรับอัลกอริทึมข้อมูลสรุปทั้งหมดต้องยอมรับคําขอสร้างคีย์ที่มีข้อมูลสรุปที่ไม่รองรับ ควรใส่ข้อมูลสรุปที่ไม่รองรับไว้ในรายการ "บังคับใช้โดยซอฟต์แวร์" ในลักษณะคีย์ที่แสดงผล เนื่องจากคีย์ดังกล่าวใช้ได้กับข้อมูลสรุปอื่นๆ แต่การสรุปข้อมูลจะดำเนินการในซอฟต์แวร์ จากนั้นระบบจะเรียกใช้ฮาร์ดแวร์เพื่อดำเนินการกับ Digest::NONE
  • Tag::PADDING ระบุโหมดการเติมที่ใช้กับคีย์ใหม่ได้ การใช้งานที่ไม่รองรับอัลกอริทึมข้อมูลสรุปทั้งหมดต้องใส่ PaddingMode::RSA_PSS และ PaddingMode::RSA_OAEP ในรายการลักษณะสำคัญของคีย์ที่บังคับใช้โดยซอฟต์แวร์ หากระบุอัลกอริทึมข้อมูลสรุปที่ไม่รองรับ

คีย์ ECDSA

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

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

คีย์ AES

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

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

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

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

คีย์ HMAC

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

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

ลักษณะสำคัญ

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

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

Tag::ROLLBACK_RESISTANT

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

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

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

getKeyCharacteristics

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

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

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

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

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

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

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

คีย์นำเข้า

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

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

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

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

exportKey

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

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

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

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

deleteKey

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

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

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

deleteAllKeys

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

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

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

destroyAttestationIds

เวอร์ชัน: 3

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

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

begin

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

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

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

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

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

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

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

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

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

คีย์ RSA

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

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

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

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

การโต้ตอบที่สําคัญระหว่างโหมดการเติมและข้อมูลสรุปมีดังนี้

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

คีย์ EC

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

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

คีย์ AES

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

หากโหมดบล็อกคือ BlockMode::GCM inParams จะระบุ Tag::MAC_LENGTH และค่าที่ระบุคือผลคูณของ 8 ที่ไม่มากกว่า 128 หรือน้อยกว่าค่าของ Tag::MIN_MAC_LENGTH ในการให้สิทธิ์คีย์ สำหรับความยาว MAC ที่มากกว่า 128 หรือไม่ใช่ค่าพหุคูณของ 8 ให้แสดงผล ErrorCode::UNSUPPORTED_MAC_LENGTH สำหรับค่าที่น้อยกว่าความยาวขั้นต่ำของคีย์ ระบบจะแสดงผล ErrorCode::INVALID_MAC_LENGTH

หากโหมดบล็อกคือ BlockMode::GCM หรือ BlockMode::CTR โหมดระยะห่างจากขอบที่ระบุต้องเป็น PaddingMode::NONE สำหรับ BlockMode::ECB หรือ BlockMode::CBC โหมดอาจเป็นPaddingMode::NONE หรือ PaddingMode::PKCS7 หากโหมดการเติมไม่ตรงตามเงื่อนไขเหล่านี้ ให้แสดงผล ErrorCode::INCOMPATIBLE_PADDING_MODE

หากโหมดบล็อกคือ BlockMode::CBC, BlockMode::CTR หรือ BlockMode::GCM คุณจะต้องมีเวกเตอร์การเริ่มต้นหรือ Nonce ในกรณีส่วนใหญ่ ผู้เรียกไม่ควรระบุ IV หรือ Nonce ในกรณีนี้ การใช้งาน Keymaster จะสร้าง IV หรือ Nonce แบบสุ่มและแสดงผลพร้อมTag::NONCE ใน outParams CBC และ CTR IV มีขนาด 16 ไบต์ ข้อมูลที่ไม่ซ้ำกันของ GCM มีความยาว 12 ไบต์ หากการให้สิทธิ์คีย์มี Tag::CALLER_NONCE ผู้เรียกจะให้ IV หรือ Nonce กับ Tag::NONCE ใน inParams ได้ หากระบุ Nonce เมื่อTag::CALLER_NONCEไม่ได้รับอนุญาต ให้แสดงผล ErrorCode::CALLER_NONCE_PROHIBITED หากไม่ได้ระบุ Nonce เมื่อ Tag::CALLER_NONCE ได้รับสิทธิ์ ให้สร้าง IV/nonce แบบสุ่ม

คีย์ HMAC

การดำเนินการคีย์ HMAC ระบุ Tag::MAC_LENGTH ใน inParams ค่าที่ระบุต้องเป็นแบบ 8 เท่าซึ่งไม่มากกว่าความยาวของข้อมูลสรุปหรือน้อยกว่าค่าของ Tag::MIN_MAC_LENGTH ในการให้สิทธิ์คีย์ สำหรับความยาว MAC ที่มากกว่าความยาวของข้อมูลสรุปหรือไม่ใช่จำนวนที่หารด้วย 8 ได้ ระบบจะแสดงผล ErrorCode::UNSUPPORTED_MAC_LENGTH สำหรับค่าที่น้อยกว่าความยาวขั้นต่ำของคีย์ ให้แสดงผล ErrorCode::INVALID_MAC_LENGTH

อัปเดต

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

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

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

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

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

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

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

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

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

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

คีย์ RSA

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

คีย์ ECDSA

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

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

คีย์ AES

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

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

เสร็จสิ้น

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

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

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

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

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

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

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

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

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

คีย์ RSA

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

  • PaddingMode::NONE. สําหรับการดำเนินการลงนามและการเข้ารหัสแบบไม่เติมค่า ในกรณีที่ข้อมูลที่ให้ไว้สั้นกว่าคีย์ ระบบจะเติมค่า 0 ทางด้านซ้ายก่อนลงนาม/เข้ารหัส หากข้อมูลมีความยาวเท่ากับคีย์แต่เป็นตัวเลขขนาดใหญ่ ให้แสดงผล ErrorCode::INVALID_ARGUMENT สําหรับการดำเนินการยืนยันและการถอดรหัส ข้อมูลต้องยาวเท่ากับคีย์ หรือไม่เช่นนั้น ให้แสดงผล ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS สำหรับการดำเนินการลายเซ็นที่เพิ่ม PSS นั้น Salt ของ PSS คือขนาดของไดเจสต์ข้อความและสร้างขึ้นแบบสุ่ม ระบบจะใช้ข้อมูลสรุปที่ระบุด้วย Tag::DIGEST ใน inputParams ใน begin เป็นอัลกอริทึมข้อมูลสรุป PSS และเป็นอัลกอริทึมข้อมูลสรุป MGF1
  • PaddingMode::RSA_OAEP. ระบบจะใช้ข้อมูลสรุปที่ระบุด้วย Tag::DIGEST ใน inputParams ในส่วน begin เป็นอัลกอริทึมข้อมูลสรุป OAEP และจะใช้ SHA1 เป็นอัลกอริทึมข้อมูลสรุป MGF1

คีย์ ECDSA

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

คีย์ AES

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

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

ล้มเลิก

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

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

อัลกอริทึม get_supported_

เวอร์ชัน: 1

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

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

get_supported_block_modes

เวอร์ชัน: 1

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

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

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

get_supported_padding_modes

เวอร์ชัน: 1

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

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

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

  • การเข้ารหัส การถอดรหัส การรับรอง และการยืนยันแบบไม่เพิ่มค่าให้กับบิต สำหรับการเข้ารหัสและการลงชื่อแบบไม่ต้องเข้ารหัส ถ้าข้อความสั้นกว่าโมดูลัสสาธารณะ การใช้งานจะต้องใส่เลข 0 ค้างไว้ สำหรับการถอดรหัสและการตรวจสอบแบบไม่เพิ่มความยาว ความยาวของอินพุตต้องตรงกับขนาดโมดูลัสสาธารณะ
  • โหมดการเติมข้อมูลการเข้ารหัสและการลงนาม PKCS#1 v1.5
  • PSS ที่มีความยาวเกลือขั้นต่ำ 20
  • OAEP

สำหรับ AES ในโหมด ECB และ CBC การใช้งาน Keymaster 1 จะไม่รองรับการเติมค่าและ PKCS#7 โหมด CTR และ GCM รองรับเฉพาะการไม่เพิ่มค่าใดๆ

get_supported_digests

เวอร์ชัน: 1

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

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

การติดตั้งใช้งาน Keymaster 1 สามารถใช้ชุดย่อยของข้อมูลสรุปที่กําหนดไว้ การใช้งานจะใช้ SHA-256 และสามารถระบุ MD5, SHA1, SHA-224, SHA-256, SHA384 และ SHA512 (ชุดข้อมูลสรุปที่กําหนดไว้ทั้งหมด)

get_supported_import_formats

เวอร์ชัน: 1

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

การติดตั้งใช้งาน Keymaster 1 รองรับรูปแบบ PKCS#8 (ไม่มีการปกป้องด้วยรหัสผ่าน) สำหรับการนําเข้าคู่คีย์ RSA และ EC และรองรับการนําเข้าข้อมูลคีย์ AES และ HMAC แบบ RAW

get_supported_export_formats

เวอร์ชัน: 1

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

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

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

Keymaster 0

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

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

Keymaster 1

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

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

Keymaster 2

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

  • configure