chrome.enterprise.platformKeys

Deskripsi

Gunakan chrome.enterprise.platformKeys API untuk membuat kunci dan menginstal sertifikat untuk kunci ini. Sertifikat akan dikelola oleh platform dan dapat digunakan untuk autentikasi TLS, akses jaringan, atau dengan ekstensi lainnya melalui chrome.platformKeys.

Izin

enterprise.platformKeys

Ketersediaan

Khusus ChromeOS Memerlukan kebijakan

Konsep dan penggunaan

Penggunaan umum API ini untuk mendaftarkan sertifikat klien mengikuti langkah-langkah berikut:

  • Dapatkan semua token yang tersedia menggunakan enterprise.platformKeys.getTokens().

  • Temukan Token dengan id yang sama dengan "user". Gunakan Token ini secara berurutan.

  • Buat pasangan kunci menggunakan metode Token generateKey() (ditentukan di SubtleCrypto). Ini akan mengembalikan {i>handle<i} ke kunci.

  • Ekspor kunci publik menggunakan metode Token exportKey() (ditentukan di SubtleCrypto).

  • Buat tanda tangan data permintaan sertifikasi menggunakan metode Token sign() (ditentukan di SubtleCrypto).

  • Selesaikan permintaan sertifikasi dan kirimkan ke otoritas sertifikasi.

  • Jika sertifikat diterima, impor menggunakan [enterprise.platformKeys.importCertificate()`[3]

Berikut ini contoh yang menunjukkan interaksi API utama kecuali pembuatan dan pengiriman permintaan sertifikasi:

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);

Jenis

Algorithm

Chrome 110 dan yang lebih baru

Jenis kunci yang akan dibuat.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 dan yang lebih baru

Properti

  • tantangan

    ArrayBuffer

    Tantangan seperti yang ditampilkan oleh Verified Access Web API.

  • registerKey

    RegisterKeyOptions opsional

    Jika ada, daftarkan kunci verifikasi dengan token scope yang ditentukan. Kunci tersebut kemudian dapat dikaitkan dengan sertifikat dan digunakan seperti kunci penandatanganan lainnya. Panggilan berikutnya ke fungsi ini akan membuat Kunci Enterprise baru di scope yang ditentukan.

  • cakupan

    Cakupan

    Kunci Perusahaan mana yang akan ditantang.

RegisterKeyOptions

Chrome 110 dan yang lebih baru

Properti

  • algoritme

    Algoritma

    Algoritma mana yang harus digunakan oleh kunci terdaftar.

Scope

Chrome 110 dan yang lebih baru

Apakah akan menggunakan Kunci Pengguna Perusahaan atau Kunci Mesin Perusahaan.

Enum

"MACHINE"

Token

Properti

  • id

    string

    Secara unik mengidentifikasi Token ini.

    ID statis adalah "user" dan "system", yang mengacu pada token hardware khusus pengguna platform dan token hardware seluruh sistem. Token lainnya (dengan ID lain) dapat ditampilkan oleh enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 dan yang lebih baru

    Mengimplementasikan antarmuka SubtleCrypto WebCrypto. Operasi kriptografi, termasuk pembuatan kunci, didukung oleh software. Perlindungan kunci, sehingga implementasi properti yang tidak dapat diekstrak, dilakukan di software, sehingga kunci kurang terlindungi dibandingkan kunci yang didukung hardware.

    Hanya kunci RSASSA-PKCS1-V1_5 yang tidak dapat diekstrak dengan modulusLength hingga 2048 yang dapat dibuat. Setiap kunci dapat digunakan paling banyak untuk menandatangani data.

    Kunci yang dibuat pada Token tertentu tidak dapat digunakan dengan Token lain, dan juga tidak dapat digunakan dengan window.crypto.subtle. Demikian pula, objek Key yang dibuat dengan window.crypto.subtle tidak dapat digunakan dengan antarmuka ini.

  • subtleCrypto

    SubtleCrypto

    Mengimplementasikan antarmuka SubtleCrypto WebCrypto. Operasi kriptografi, termasuk pembuatan kunci, didukung oleh hardware.

    Hanya kunci RSASSA-PKCS1-V1_5 yang tidak dapat diekstrak dengan modulusLength hingga 2048 dan ECDSA dengan namedCurve P-256 yang dapat dibuat. Setiap kunci dapat digunakan paling banyak untuk menandatangani data.

    Kunci yang dibuat pada Token tertentu tidak dapat digunakan dengan Token lain, dan juga tidak dapat digunakan dengan window.crypto.subtle. Demikian pula, objek Key yang dibuat dengan window.crypto.subtle tidak dapat digunakan dengan antarmuka ini.

Metode

challengeKey()

Chrome 110 dan yang lebih baru 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

Serupa dengan challengeMachineKey dan challengeUserKey, tetapi memungkinkan penentuan algoritma kunci terdaftar. Melakukan tantangan Kunci Mesin Perusahaan yang didukung hardware dan memberikan respons sebagai bagian dari protokol pengesahan jarak jauh. Hanya berguna di Chrome OS dan bersama dengan Verified Access Web API yang memberikan tantangan dan memverifikasi respons.

Verifikasi yang berhasil oleh API Akses Terverifikasi merupakan sinyal kuat bahwa perangkat saat ini adalah perangkat Chrome OS yang sah, perangkat saat ini dikelola oleh domain yang ditentukan selama verifikasi, pengguna yang login saat ini dikelola oleh domain yang ditentukan selama verifikasi, dan status perangkat saat ini mematuhi kebijakan perangkat perusahaan. Misalnya, kebijakan dapat menentukan bahwa perangkat tidak boleh berada dalam mode developer. Identitas perangkat apa pun yang dikeluarkan oleh verifikasi terikat erat dengan hardware perangkat saat ini. Jika Cakupan "user" ditentukan, identitas juga terikat erat dengan pengguna yang sedang login.

Fungsi ini sangat dibatasi dan akan gagal jika perangkat saat ini tidak dikelola, pengguna saat ini tidak dikelola, atau jika operasi ini belum secara eksplisit diaktifkan untuk pemanggil oleh kebijakan perangkat perusahaan. Kunci yang ditantang tidak berada di token "system" atau "user" dan tidak dapat diakses oleh API lainnya.

Parameter

  • Objek yang berisi kolom yang ditentukan dalam ChallengeKeyOptions.

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (response: ArrayBuffer)=>void

    • respons

      ArrayBuffer

      Respons tantangan.

challengeMachineKey()

Chrome 50+ Tidak digunakan lagi sejak Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

Sebagai gantinya, gunakan challengeKey.

Melakukan tantangan Kunci Mesin Perusahaan yang didukung hardware dan memberikan respons sebagai bagian dari protokol pengesahan jarak jauh. Hanya berguna di Chrome OS dan bersama dengan Verified Access Web API yang memberikan tantangan dan memverifikasi respons. Verifikasi yang berhasil oleh Verified Access Web API adalah sinyal kuat dari semua hal berikut: * Perangkat saat ini adalah perangkat Chrome OS yang sah. * Perangkat saat ini dikelola oleh domain yang ditentukan selama verifikasi. * Pengguna yang sudah login saat ini dikelola oleh domain yang ditentukan selama verifikasi. * Status perangkat saat ini sesuai dengan kebijakan perangkat perusahaan. Misalnya, kebijakan dapat menentukan bahwa perangkat tidak boleh berada dalam mode developer. * Identitas perangkat apa pun yang dikeluarkan oleh verifikasi terikat erat dengan hardware perangkat saat ini. Fungsi ini sangat dibatasi dan akan gagal jika perangkat saat ini tidak dikelola, pengguna saat ini tidak dikelola, atau jika operasi ini belum secara eksplisit diaktifkan untuk pemanggil oleh kebijakan perangkat perusahaan. Kunci Mesin Perusahaan tidak berada dalam token "system" dan tidak dapat diakses oleh API lainnya.

Parameter

  • tantangan

    ArrayBuffer

    Tantangan seperti yang ditampilkan oleh Verified Access Web API.

  • registerKey

    boolean opsional

    Chrome 59+

    Jika ditetapkan, Kunci Mesin Perusahaan saat ini akan didaftarkan dengan token "system" dan melepaskan peran Kunci Mesin Perusahaan. Kunci tersebut kemudian dapat dikaitkan dengan sertifikat dan digunakan seperti kunci penandatanganan lainnya. Kunci ini adalah RSA 2048-bit. Panggilan berikutnya ke fungsi ini akan membuat Kunci Mesin Enterprise baru.

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (response: ArrayBuffer)=>void

    • respons

      ArrayBuffer

      Respons tantangan.

challengeUserKey()

Chrome 50+ Tidak digunakan lagi sejak Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

Sebagai gantinya, gunakan challengeKey.

Melakukan tantangan Kunci Pengguna Perusahaan yang didukung hardware dan memberikan respons sebagai bagian dari protokol pengesahan jarak jauh. Hanya berguna di Chrome OS dan bersama dengan Verified Access Web API yang memberikan tantangan dan memverifikasi respons. Verifikasi yang berhasil oleh Verified Access Web API adalah sinyal kuat dari semua hal berikut: * Perangkat saat ini adalah perangkat Chrome OS yang sah. * Perangkat saat ini dikelola oleh domain yang ditentukan selama verifikasi. * Pengguna yang sudah login saat ini dikelola oleh domain yang ditentukan selama verifikasi. * Status perangkat saat ini sesuai dengan kebijakan pengguna perusahaan. Misalnya, kebijakan dapat menentukan bahwa perangkat tidak boleh berada dalam mode developer. * Kunci publik yang dikeluarkan oleh verifikasi terikat erat dengan hardware perangkat saat ini dan dengan pengguna yang login saat ini. Fungsi ini sangat dibatasi dan akan gagal jika perangkat saat ini tidak dikelola, pengguna saat ini tidak dikelola, atau jika operasi ini belum secara eksplisit diaktifkan untuk pemanggil oleh kebijakan pengguna perusahaan. Kunci Pengguna Enterprise tidak berada dalam token "user" dan tidak dapat diakses oleh API lainnya.

Parameter

  • tantangan

    ArrayBuffer

    Tantangan seperti yang ditampilkan oleh Verified Access Web API.

  • registerKey

    boolean

    Jika ditetapkan, Kunci Pengguna Perusahaan saat ini akan didaftarkan dengan token "user" dan melepaskan peran Kunci Pengguna Perusahaan. Kunci tersebut kemudian dapat dikaitkan dengan sertifikat dan digunakan seperti kunci penandatanganan lainnya. Kunci ini adalah RSA 2048-bit. Panggilan berikutnya ke fungsi ini akan membuat Kunci Pengguna Enterprise baru.

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (response: ArrayBuffer)=>void

    • respons

      ArrayBuffer

      Respons tantangan.

getCertificates()

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

Menampilkan daftar semua sertifikat klien yang tersedia dari token yang diberikan. Dapat digunakan untuk memeriksa keberadaan dan kedaluwarsa sertifikat klien yang dapat digunakan untuk otentikasi tertentu.

Parameter

  • tokenId

    string

    ID Token yang ditampilkan oleh getTokens.

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (certificates: ArrayBuffer[])=>void

    • sertifikat

      ArrayBuffer[]

      Daftar sertifikat, masing-masing dalam encoding DER pada sertifikat X.509.

getTokens()

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

Menampilkan Token yang tersedia. Dalam sesi pengguna reguler, daftar akan selalu berisi token pengguna dengan id "user". Jika token TPM seluruh sistem tersedia, daftar yang ditampilkan juga akan berisi token seluruh sistem dengan id "system". Token seluruh sistem akan sama untuk semua sesi di perangkat ini (perangkat dalam artian misalnya Chromebook).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (tokens: Token[])=>void

    • token

      Token[]

      Daftar token yang tersedia.

importCertificate()

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

Mengimpor certificate ke token yang diberikan jika kunci tersertifikasi sudah disimpan dalam token ini. Setelah permintaan sertifikasi berhasil, fungsi ini harus digunakan untuk menyimpan sertifikat yang diperoleh dan menyediakannya untuk sistem operasi dan browser untuk autentikasi.

Parameter

  • tokenId

    string

    ID Token yang ditampilkan oleh getTokens.

  • sertifikat

    ArrayBuffer

    Encoding DER sertifikat X.509.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

removeCertificate()

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

Menghapus certificate dari token yang diberikan jika ada. Harus digunakan untuk menghapus sertifikat yang sudah tidak berlaku sehingga tidak dipertimbangkan selama otentikasi dan tidak mengacaukan pilihan sertifikat. Harus digunakan untuk penyimpanan gratis di penyimpanan sertifikat.

Parameter

  • tokenId

    string

    ID Token yang ditampilkan oleh getTokens.

  • sertifikat

    ArrayBuffer

    Encoding DER sertifikat X.509.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void