browser.enterprise.platformKeys

API นี้ใช้ได้กับส่วนขยายที่ติดตั้งโดยนโยบายเท่านั้น

สำคัญ: API นี้ใช้ได้ใน ChromeOS เท่านั้น

คำอธิบาย

ใช้ chrome.enterprise.platformKeys API เพื่อสร้างคีย์และติดตั้งใบรับรองสำหรับคีย์เหล่านี้ แพลตฟอร์มจะจัดการใบรับรองและสามารถใช้สำหรับการตรวจสอบสิทธิ์ TLS, การเข้าถึงเครือข่าย หรือโดยส่วนขยายอื่นๆ ผ่าน chrome.platformKeys

สิทธิ์

enterprise.platformKeys

ความพร้อมใช้งาน

ChromeOS เท่านั้น ต้องใช้นโยบาย

แนวคิดและการใช้งาน

การใช้งาน API นี้โดยทั่วไปเพื่อลงทะเบียนใบรับรองไคลเอ็นต์จะเป็นไปตามขั้นตอนต่อไปนี้

• รับโทเค็นทั้งหมดที่มีโดยใช้ enterprise.platformKeys.getTokens()

• ค้นหาโทเค็นที่มี id เท่ากับ "user" ใช้โทเค็นนี้ในภายหลัง

• สร้างคู่คีย์โดยใช้วิธีการ generateKey() Token (กำหนดไว้ใน SubtleCrypto) การดำเนินการนี้จะแสดงแฮนเดิลของคีย์

• ส่งออกคีย์สาธารณะโดยใช้เมธอด exportKey() Token (กำหนดไว้ใน SubtleCrypto)

• สร้างลายเซ็นของข้อมูลคำขอการรับรองโดยใช้เมธอด sign() Token (กำหนดไว้ใน SubtleCrypto)

• กรอกคำขอการรับรองให้เสร็จสมบูรณ์และส่งไปยังหน่วยงานที่ให้การรับรอง

• หากได้รับใบรับรอง ให้นำเข้าโดยใช้ [enterprise.platformKeys.importCertificate()`[3]

ต่อไปนี้เป็นตัวอย่างที่แสดงการโต้ตอบ API หลัก ยกเว้นการสร้างและการส่งคำขอการรับรอง

function getUserToken(callback) {
  browser.enterprise.platformKeys.getTokens(function(tokens) {
    for (var i = 0; i < tokens.length; i++) {
      if (tokens[i].id == "user") {
        callback(tokens[i]);
        return;
      }
    }
    callback(undefined);
  });
}

function generateAndSign(userToken) {
  var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
  var algorithm = {
    name: "RSASSA-PKCS1-v1_5",
    // RsaHashedKeyGenParams
    modulusLength: 2048,
    publicExponent:
        new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
    hash: {
      name: "SHA-256",
    }
  };
  var cachedKeyPair;
  userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
    .then(function(keyPair) {
            cachedKeyPair = keyPair;
            return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);
          },
          console.log.bind(console))
    .then(function(publicKeySpki) {
            // Build the Certification Request using the public key.
            return userToken.subtleCrypto.sign(
                {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
          },
          console.log.bind(console))
    .then(function(signature) {
              // Complete the Certification Request with |signature|.
              // Send out the request to the CA, calling back
              // onClientCertificateReceived.
          },
          console.log.bind(console));
}

function onClientCertificateReceived(userToken, certificate) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

ประเภท

Algorithm

Chrome 110 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

ประเภทคีย์ที่จะสร้าง

ค่าแจกแจง

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

• ชาเลนจ์

  ArrayBuffer

  คำถามที่ส่งโดย Verified Access Web API

• registerKey

  RegisterKeyOptions ไม่บังคับ

  หากมี ให้ลงทะเบียนคีย์ที่ถูกตรวจสอบด้วยโทเค็นของ scope ที่ระบุ จากนั้นคุณจะเชื่อมโยงคีย์กับใบรับรองและใช้คีย์ดังกล่าวได้เหมือนกับคีย์ Signing อื่นๆ การเรียกใช้ฟังก์ชันนี้ในครั้งต่อๆ ไปจะสร้างคีย์ Enterprise ใหม่ใน scope ที่ระบุ

• ขอบเขต

  ขอบเขต

  คีย์ Enterprise ที่จะทดสอบ

RegisterKeyOptions

Chrome 110 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

• อัลกอริทึม

  อัลกอริทึม

  อัลกอริทึมที่คีย์ที่ลงทะเบียนควรใช้

Scope

Chrome 110 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

เลือกว่าจะใช้ Enterprise User Key หรือ Enterprise Machine Key

ค่าแจกแจง

"USER"

"MACHINE"

Token

พร็อพเพอร์ตี้

• id

  สตริง

  ระบุ Token นี้แบบไม่ซ้ำ

  รหัสแบบคงที่คือ "user" และ "system" ซึ่งหมายถึงโทเค็นฮาร์ดแวร์เฉพาะผู้ใช้ของแพลตฟอร์มและโทเค็นฮาร์ดแวร์ทั้งระบบตามลำดับ enterprise.platformKeys.getTokens อาจแสดงผลโทเค็นอื่นๆ (ที่มีตัวระบุอื่นๆ)

• softwareBackedSubtleCrypto

  SubtleCrypto

  Chrome 97 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

  สร้างได้เฉพาะคีย์ที่แยกไม่ได้เท่านั้น ประเภทคีย์ที่รองรับมีเพียง RSASSA-PKCS1-V1_5 ที่มี modulusLength สูงสุด 2048 คีย์แต่ละรายการใช้สำหรับการรับรองข้อมูลได้สูงสุด 1 ครั้ง เว้นแต่ว่าส่วนขยายจะอยู่ในรายการที่อนุญาตผ่านนโยบาย KeyPermissions ซึ่งในกรณีนี้จะใช้คีย์ได้ไม่จำกัด

  คีย์ที่สร้างใน Token หนึ่งๆ จะใช้กับโทเค็นอื่นไม่ได้ และจะใช้กับ window.crypto.subtle ไม่ได้เช่นกัน ในทำนองเดียวกัน ออบเจ็กต์ Key ที่สร้างด้วย window.crypto.subtle จะใช้กับอินเทอร์เฟซนี้ไม่ได้

• subtleCrypto

  SubtleCrypto

  ใช้อินเทอร์เฟซ SubtleCrypto ของ WebCrypto การดำเนินการเข้ารหัส รวมถึงการสร้างคีย์ จะได้รับการสนับสนุนโดยฮาร์ดแวร์

  สร้างได้เฉพาะคีย์ที่แยกไม่ได้เท่านั้น ประเภทคีย์ที่รองรับคือ RSASSA-PKCS1-V1_5 ที่มี modulusLength สูงสุด 2048 และ ECDSA ที่มี namedCurve P-256 คีย์แต่ละรายการจะใช้สำหรับการลงนามข้อมูลได้ไม่เกิน 1 ครั้ง เว้นแต่ว่าส่วนขยายจะอยู่ในรายการที่อนุญาตโดยนโยบาย KeyPermissions ซึ่งในกรณีนี้จะใช้คีย์ได้ไม่จำกัด

  คีย์ที่สร้างใน Token หนึ่งๆ จะใช้กับโทเค็นอื่นไม่ได้ และจะใช้กับ window.crypto.subtle ไม่ได้เช่นกัน ในทำนองเดียวกัน ออบเจ็กต์ Key ที่สร้างด้วย window.crypto.subtle จะใช้กับอินเทอร์เฟซนี้ไม่ได้

เมธอด

challengeKey()

Chrome 110 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

คล้ายกับ challengeMachineKey และ challengeUserKey แต่ช่วยให้ระบุอัลกอริทึมของคีย์ที่ลงทะเบียนได้ ตรวจสอบคีย์เครื่องขององค์กรที่อิงฮาร์ดแวร์และส่งการตอบกลับเป็นส่วนหนึ่งของโปรโตคอลการรับรองระยะไกล มีประโยชน์เฉพาะใน ChromeOS และเมื่อใช้ร่วมกับ Verified Access Web API ซึ่งทั้งส่งคำถามและยืนยันคำตอบ

การยืนยันที่สำเร็จโดย Verified Access Web API เป็นสัญญาณที่ชัดเจนว่าอุปกรณ์ปัจจุบันเป็นอุปกรณ์ ChromeOS ที่ถูกต้องตามกฎหมาย อุปกรณ์ปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน ผู้ใช้ที่ลงชื่อเข้าใช้ในปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน และสถานะอุปกรณ์ปัจจุบันเป็นไปตามนโยบายด้านอุปกรณ์ขององค์กร เช่น นโยบายอาจระบุว่าอุปกรณ์ต้องไม่อยู่ในโหมดนักพัฒนาซอฟต์แวร์ ข้อมูลประจำตัวของอุปกรณ์ที่ได้จากการยืนยันจะเชื่อมโยงกับฮาร์ดแวร์ของอุปกรณ์ปัจจุบันอย่างแน่นหนา หากระบุขอบเขต "user" ข้อมูลประจำตัวจะเชื่อมโยงกับผู้ใช้ที่ลงชื่อเข้าใช้อยู่ในปัจจุบันอย่างแน่นหนาด้วย

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

พารามิเตอร์

• ตัวเลือก

  ChallengeKeyOptions

  ออบเจ็กต์ที่มีช่องที่กำหนดไว้ใน ChallengeKeyOptions

การคืนสินค้า

• Promise<ArrayBuffer>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วยการตอบกลับการตรวจสอบสิทธิ์

challengeMachineKey()

Chrome 50 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148 เลิกใช้งานตั้งแต่ Chrome 110

browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

โปรดใช้ challengeKey แทน

ตรวจสอบคีย์เครื่องขององค์กรที่อิงฮาร์ดแวร์และแสดงการตอบกลับเป็นส่วนหนึ่งของโปรโตคอลการรับรองระยะไกล มีประโยชน์เฉพาะใน ChromeOS และเมื่อใช้ร่วมกับ Verified Access Web API ซึ่งทั้งส่งคำถามและยืนยันคำตอบ การยืนยันที่สำเร็จโดย Verified Access Web API เป็นสัญญาณที่ชัดเจนว่า * อุปกรณ์ปัจจุบันเป็นอุปกรณ์ ChromeOS ที่ถูกต้อง * อุปกรณ์ปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน * ผู้ใช้ที่ลงชื่อเข้าใช้อยู่ในปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน * สถานะปัจจุบันของอุปกรณ์เป็นไปตามนโยบายด้านอุปกรณ์ขององค์กร เช่น นโยบายอาจระบุว่าอุปกรณ์ต้องไม่อยู่ในโหมดนักพัฒนาซอฟต์แวร์ * ข้อมูลประจำตัวของอุปกรณ์ที่ได้จากการยืนยันจะเชื่อมโยงกับฮาร์ดแวร์ของอุปกรณ์ปัจจุบันอย่างแน่นหนา ฟังก์ชันนี้ถูกจำกัดอย่างเข้มงวดและจะดำเนินการไม่สำเร็จหากอุปกรณ์ปัจจุบันไม่มีการจัดการ ผู้ใช้ปัจจุบันไม่มีการจัดการ หรือหากนโยบายด้านอุปกรณ์ขององค์กรไม่ได้เปิดใช้การดำเนินการนี้อย่างชัดแจ้งสำหรับผู้เรียกใช้ คีย์เครื่องขององค์กรไม่ได้อยู่ในโทเค็น "system" และ API อื่นๆ ไม่สามารถเข้าถึงได้

พารามิเตอร์

• ชาเลนจ์

  ArrayBuffer

  คำถามที่ส่งโดย Verified Access Web API

• registerKey

  บูลีน ไม่บังคับ

  Chrome 59 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  หากตั้งค่าไว้ คีย์เครื่องขององค์กรปัจจุบันจะลงทะเบียนด้วยโทเค็น "system" และสละบทบาทคีย์เครื่องขององค์กร จากนั้นคุณจะเชื่อมโยงคีย์กับใบรับรองและใช้คีย์ดังกล่าวได้เหมือนกับคีย์ Signing อื่นๆ คีย์นี้เป็น RSA 2048 บิต จากนั้นการเรียกใช้ฟังก์ชันนี้ในครั้งต่อๆ ไปจะสร้างคีย์เครื่องขององค์กรใหม่

การคืนสินค้า

• Promise<ArrayBuffer>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วยการตอบกลับการตรวจสอบสิทธิ์

challengeUserKey()

Chrome 50 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148 เลิกใช้งานตั้งแต่ Chrome 110

browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

โปรดใช้ challengeKey แทน

ตรวจสอบคีย์ผู้ใช้ระดับองค์กรที่อิงฮาร์ดแวร์และส่งการตอบกลับเป็นส่วนหนึ่งของโปรโตคอลการรับรองระยะไกล มีประโยชน์เฉพาะใน ChromeOS และเมื่อใช้ร่วมกับ Verified Access Web API ซึ่งทั้งส่งคำถามและยืนยันคำตอบ การยืนยันที่สำเร็จโดย Verified Access Web API เป็นสัญญาณที่ชัดเจนว่า * อุปกรณ์ปัจจุบันเป็นอุปกรณ์ ChromeOS ที่ถูกต้อง * อุปกรณ์ปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน * ผู้ใช้ที่ลงชื่อเข้าใช้อยู่ในปัจจุบันได้รับการจัดการโดยโดเมนที่ระบุในระหว่างการยืนยัน * สถานะปัจจุบันของอุปกรณ์เป็นไปตามนโยบายผู้ใช้ระดับองค์กร เช่น นโยบายอาจระบุว่าอุปกรณ์ต้องไม่อยู่ในโหมดนักพัฒนาซอฟต์แวร์ * คีย์สาธารณะที่ได้จากการยืนยันจะเชื่อมโยงกับฮาร์ดแวร์ของอุปกรณ์ปัจจุบันและผู้ใช้ที่ลงชื่อเข้าใช้ในปัจจุบันอย่างแน่นหนา ฟังก์ชันนี้ถูกจำกัดอย่างเข้มงวดและจะดำเนินการไม่สำเร็จหากอุปกรณ์ปัจจุบันไม่มีการจัดการ ผู้ใช้ปัจจุบันไม่มีการจัดการ หรือหากนโยบายผู้ใช้ระดับองค์กรไม่ได้เปิดใช้การดำเนินการนี้อย่างชัดแจ้งสำหรับผู้โทร คีย์ผู้ใช้ระดับองค์กรไม่ได้อยู่ในโทเค็น "user" และ API อื่นๆ จะเข้าถึงไม่ได้

พารามิเตอร์

• ชาเลนจ์

  ArrayBuffer

  คำถามที่ส่งโดย Verified Access Web API

• registerKey

  บูลีน

  หากตั้งค่าไว้ ระบบจะลงทะเบียนคีย์ผู้ใช้ระดับองค์กรปัจจุบันด้วยโทเค็น "user" และสละบทบาทคีย์ผู้ใช้ระดับองค์กร จากนั้นคุณจะเชื่อมโยงคีย์กับใบรับรองและใช้คีย์ดังกล่าวได้เหมือนกับคีย์ Signing อื่นๆ คีย์นี้เป็น RSA 2048 บิต การเรียกใช้ฟังก์ชันนี้ในครั้งต่อๆ ไปจะสร้างคีย์ผู้ใช้ระดับองค์กรใหม่

การคืนสินค้า

• Promise<ArrayBuffer>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วยการตอบกลับการตรวจสอบสิทธิ์

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

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

พารามิเตอร์

• tokenId

  สตริง

  รหัสของโทเค็นที่แสดงผลโดย getTokens

การคืนสินค้า

• Promise<ArrayBuffer[]>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะแก้ไขด้วยรายการใบรับรองที่ใช้ได้

getTokens()

browser.enterprise.platformKeys.getTokens(): Promise<Token[]>

แสดงผลโทเค็นที่ใช้ได้ ในเซสชันของผู้ใช้ทั่วไป รายการจะมีโทเค็นของผู้ใช้ที่มี id "user" เสมอ หากมีโทเค็น TPM ทั่วทั้งระบบ รายการที่แสดงผลจะมีโทเค็นทั่วทั้งระบบที่มี id "system" ด้วย โทเค็นทั้งระบบจะเหมือนกันทั้งหมดสำหรับทุกเซสชันในอุปกรณ์นี้ (อุปกรณ์ในความหมาย เช่น Chromebook)

การคืนสินค้า

• Promise<Token[]>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  เรียกใช้โดย getTokens พร้อมรายการโทเค็นที่ใช้ได้

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

พารามิเตอร์

• tokenId

  สตริง

  รหัสของโทเค็นที่แสดงผลโดย getTokens

• ใบรับรอง

  ArrayBuffer

  การเข้ารหัส DER ของใบรับรอง X.509

การคืนสินค้า

• Promise<void>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขเมื่อการดำเนินการนี้เสร็จสิ้น

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

พารามิเตอร์

• tokenId

  สตริง

  รหัสของโทเค็นที่แสดงผลโดย getTokens

• ใบรับรอง

  ArrayBuffer

  การเข้ารหัส DER ของใบรับรอง X.509

การคืนสินค้า

• Promise<void>

  Chrome 131 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขเมื่อการดำเนินการนี้เสร็จสิ้น