chrome.enterprise.platformKeys

คำอธิบาย

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

สิทธิ์

enterprise.platformKeys

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

ChromeOS เท่านั้น ต้องมีนโยบาย

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

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

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

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

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

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

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

  • กรอกคำขอการรับรองและส่งไปยังหน่วยงานที่รับรอง

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

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

function getUserToken(callback) {
  chrome.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) {
  chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

ประเภท

Algorithm

Chrome 110 ขึ้นไป

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

ค่าแจกแจง

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 ขึ้นไป

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

  • ชาเลนจ์

    ArrayBuffer

    ความท้าทายที่เกิดจาก Verified Access Web API

  • registerKey

    RegisterKeyOptions ไม่บังคับ

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

  • ขอบเขต

    ขอบเขต

    Enterprise Key ที่จะทดสอบ

RegisterKeyOptions

Chrome 110 ขึ้นไป

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

  • อัลกอริทึม

    อัลกอริทึม

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

Scope

Chrome 110 ขึ้นไป

จะใช้คีย์ผู้ใช้ของ Enterprise หรือคีย์เครื่องขององค์กร

ค่าแจกแจง

Token

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

  • id

    string

    ระบุ Token นี้โดยไม่ซ้ำกัน

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 ขึ้นไป

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

    สามารถสร้างได้เฉพาะคีย์ RSASSA-PKCS1-V1_5 ที่ดึงข้อมูลไม่ได้ซึ่งมี modulusLength สูงสุด 2048 เท่านั้น แต่ละคีย์ใช้ในการลงนามข้อมูลได้สูงสุด 1 ครั้ง

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

  • subtleCrypto

    SubtleCrypto

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

    สร้างได้เฉพาะคีย์ RSASSA-PKCS1-V1_5 ที่ดึงข้อมูลไม่ได้ซึ่งมี modulusLength สูงสุด 2048 และ ECDSA ที่มี namedCurve P-256 ได้เท่านั้น แต่ละคีย์ใช้ในการลงนามข้อมูลได้สูงสุด 1 ครั้ง

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

วิธีการ

challengeKey()

Chrome 110 ขึ้นไป 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

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

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

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

พารามิเตอร์

  • ตัวเลือก

    ChallengeKeyOptions

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

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (response: ArrayBuffer) => void

    • การตอบกลับ

      ArrayBuffer

      การตอบคำถาม

challengeMachineKey()

Chrome 50 ขึ้นไป เลิกใช้งานตั้งแต่ Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

โปรดใช้ challengeKey แทน

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

พารามิเตอร์

  • ชาเลนจ์

    ArrayBuffer

    ความท้าทายที่เกิดจาก Verified Access Web API

  • registerKey

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

    Chrome 59 ขึ้นไป

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

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (response: ArrayBuffer) => void

    • การตอบกลับ

      ArrayBuffer

      การตอบคำถาม

challengeUserKey()

Chrome 50 ขึ้นไป เลิกใช้งานตั้งแต่ Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

โปรดใช้ challengeKey แทน

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

พารามิเตอร์

  • ชาเลนจ์

    ArrayBuffer

    ความท้าทายที่เกิดจาก Verified Access Web API

  • registerKey

    boolean

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

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (response: ArrayBuffer) => void

    • การตอบกลับ

      ArrayBuffer

      การตอบคำถาม

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback: function,
)

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

พารามิเตอร์

  • tokenId

    string

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

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (certificates: ArrayBuffer[]) => void

    • ใบรับรอง

      อาร์เรย์บัฟเฟอร์[]

      รายการใบรับรอง โดยแต่ละใบรับรองมีการเข้ารหัส DER ของใบรับรอง X.509

getTokens()

chrome.enterprise.platformKeys.getTokens(
  callback: function,
)

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (tokens: Token[]) => void

    • โทเค็น

      โทเค็น[]

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

importCertificate()

chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

พารามิเตอร์

  • tokenId

    string

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

  • ใบรับรอง

    ArrayBuffer

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

  • Callback

    ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    () => void

removeCertificate()

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

พารามิเตอร์

  • tokenId

    string

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

  • ใบรับรอง

    ArrayBuffer

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

  • Callback

    ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    () => void