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 ที่จะทดสอบ

RegisterKeyOptions

Chrome 110 ขึ้นไป

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

  • อัลกอริทึม

    อัลกอริทึม

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

Scope

Chrome 110 ขึ้นไป

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

ค่าแจกแจง

"USER"

"MACHINE"

Token

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

  • id

    สตริง

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 ขึ้นไป

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

    สร้างได้เฉพาะคีย์ที่แยกไม่ได้ ประเภทคีย์ที่รองรับคือ RSASSA-PKCS1-V1_5 และ RSA-OAEP (ใน Chrome เวอร์ชัน 135 ขึ้นไป) ที่มี modulusLength สูงสุด 2048 คีย์ RSASSA-PKCS1-V1_5 แต่ละรายการใช้ลงนามข้อมูลได้สูงสุด 1 ครั้ง เว้นแต่จะมีการอนุญาตพิเศษส่วนขยายผ่านนโยบาย KeyPermissions ในกรณีนี้จะใช้คีย์ได้ไม่จำกัด คีย์ RSA-OAEP ได้รับการรองรับตั้งแต่ Chrome เวอร์ชัน 135 และส่วนขยายที่อยู่ในรายการที่อนุญาตผ่านนโยบายเดียวกันนั้นสามารถใช้คีย์ดังกล่าวเพื่อยกเลิกการห่อคีย์อื่นๆ ได้

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

  • subtleCrypto

    SubtleCrypto

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

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

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

เมธอด

challengeKey()

Chrome 110 ขึ้นไป 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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

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

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

พารามิเตอร์

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

  • Promise<ArrayBuffer>

    Chrome 131 ขึ้นไป

challengeMachineKey()

Chrome 50 ขึ้นไป เลิกใช้งานตั้งแต่ Chrome 110
chrome.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 ขึ้นไป

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

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

  • Promise<ArrayBuffer>

    Chrome 131 ขึ้นไป

challengeUserKey()

Chrome 50 ขึ้นไป เลิกใช้งานตั้งแต่ Chrome 110
chrome.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" และสละบทบาทคีย์ผู้ใช้ระดับองค์กร จากนั้นคุณจะเชื่อมโยงคีย์กับใบรับรองและใช้คีย์ดังกล่าวได้เหมือนกับคีย์การลงนามอื่นๆ คีย์นี้เป็น RSA 2048 บิต การเรียกใช้ฟังก์ชันนี้ในครั้งต่อๆ ไปจะสร้างคีย์ผู้ใช้ Enterprise ใหม่

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

  • Promise<ArrayBuffer>

    Chrome 131 ขึ้นไป

getCertificates()

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

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

พารามิเตอร์

  • tokenId

    สตริง

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

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

  • Promise<ArrayBuffer[]>

    Chrome 131 ขึ้นไป

getTokens()

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

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

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

  • Promise<Token[]>

    Chrome 131 ขึ้นไป

importCertificate()

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

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

พารามิเตอร์

  • tokenId

    สตริง

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

  • ใบรับรอง

    ArrayBuffer

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

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

  • Promise<void>

    Chrome 131 ขึ้นไป

removeCertificate()

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

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

พารามิเตอร์

  • tokenId

    สตริง

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

  • ใบรับรอง

    ArrayBuffer

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

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

  • Promise<void>

    Chrome 131 ขึ้นไป