browser.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 oleh ekstensi lain 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 selanjutnya.

  • Buat pasangan kunci menggunakan metode Token generateKey() (ditentukan di SubtleCrypto). Tindakan ini akan menampilkan handle 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).

  • Lengkapi permintaan sertifikasi dan kirimkan ke otoritas sertifikasi.

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

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

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

Jenis

Algorithm

Chrome 110+ browser.* sejak Chrome 148

Jenis kunci yang akan dibuat.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+ browser.* sejak Chrome 148

Properti

  • tantangan

    ArrayBuffer

    Verifikasi yang dikeluarkan oleh Verified Access Web API.

  • registerKey

    RegisterKeyOptions opsional

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

  • cakupan

    Cakupan

    Kunci Enterprise yang akan diverifikasi.

RegisterKeyOptions

Chrome 110+ browser.* sejak Chrome 148

Properti

  • algoritme

    Algoritma

    Algoritma yang harus digunakan kunci terdaftar.

Scope

Chrome 110+ browser.* sejak Chrome 148

Apakah akan menggunakan Kunci Pengguna Enterprise atau Kunci Perangkat Enterprise.

Enum

"USER"

"MACHINE"

Token

Properti

  • id

    string

    Secara unik mengidentifikasi Token ini.

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+ browser.* sejak Chrome 148

    Mengimplementasikan antarmuka SubtleCrypto WebCrypto. Operasi kriptografis, termasuk pembuatan kunci, didukung oleh software. Perlindungan kunci, dan dengan demikian penerapan properti yang tidak dapat diekstrak, dilakukan dalam software, sehingga kunci kurang terlindungi dibandingkan kunci yang didukung hardware.

    Hanya kunci yang tidak dapat diekstrak yang dapat dibuat. Satu-satunya jenis kunci yang didukung adalah RSASSA-PKCS1-V1_5 dengan modulusLength hingga 2048. Setiap kunci hanya dapat digunakan untuk menandatangani data maksimal satu kali, kecuali jika ekstensi telah masuk daftar yang diizinkan melalui kebijakan KeyPermissions, yang dalam hal ini kunci dapat digunakan tanpa batas waktu.

    Kunci yang dibuat di Token tertentu tidak dapat digunakan dengan Token lain, dan 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 kriptografis, termasuk pembuatan kunci, didukung hardware.

    Hanya kunci yang tidak dapat diekstrak yang dapat dibuat. Jenis kunci yang didukung adalah RSASSA-PKCS1-V1_5 dengan modulusLength hingga 2048 dan ECDSA dengan namedCurve P-256. Setiap kunci dapat digunakan untuk menandatangani data maksimal satu kali, kecuali jika ekstensi telah masuk daftar yang diizinkan oleh kebijakan KeyPermissions, yang dalam hal ini kunci dapat digunakan tanpa batas waktu.

    Kunci yang dibuat di Token tertentu tidak dapat digunakan dengan Token lain, dan 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+ browser.* sejak Chrome 148 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

Mirip dengan challengeMachineKey dan challengeUserKey, tetapi memungkinkan penentuan algoritma kunci terdaftar. Menantang Kunci Mesin Enterprise yang didukung hardware dan memunculkan respons sebagai bagian dari protokol pengesahan jarak jauh. Hanya berguna di ChromeOS dan bersama dengan Verified Access Web API yang mengeluarkan tantangan dan memverifikasi respons.

Verifikasi yang berhasil oleh Verified Access Web API adalah sinyal kuat bahwa perangkat saat ini adalah perangkat ChromeOS yang sah, perangkat saat ini dikelola oleh domain yang ditentukan selama verifikasi, pengguna yang saat ini login dikelola oleh domain yang ditentukan selama verifikasi, dan status perangkat saat ini mematuhi kebijakan perangkat perusahaan. Misalnya, kebijakan dapat menentukan bahwa perangkat tidak boleh dalam mode developer. Setiap identitas perangkat yang dikeluarkan oleh verifikasi terikat erat dengan hardware perangkat saat ini. Jika Cakupan "user" ditentukan, identitas juga akan terikat erat dengan pengguna yang saat ini login.

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

Parameter

Hasil

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang di-resolve dengan respons verifikasi.

challengeMachineKey()

Chrome 50+ browser.* sejak Chrome 148 Tidak digunakan lagi sejak Chrome 110
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

Sebagai gantinya, gunakan challengeKey.

Menantang Kunci Mesin Enterprise yang didukung hardware dan memunculkan respons sebagai bagian dari protokol pengesahan jarak jauh. Hanya berguna di ChromeOS dan bersama dengan Verified Access Web API yang mengeluarkan tantangan dan memverifikasi respons. Verifikasi yang berhasil oleh Verified Access Web API adalah sinyal kuat dari semua hal berikut: * Perangkat saat ini adalah perangkat ChromeOS yang sah. * Perangkat saat ini dikelola oleh domain yang ditentukan selama verifikasi. * Pengguna yang saat ini login dikelola oleh domain yang ditentukan selama verifikasi. * Status perangkat saat ini mematuhi kebijakan perangkat perusahaan. Misalnya, kebijakan dapat menentukan bahwa perangkat tidak boleh dalam mode developer. * Setiap identitas perangkat 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 diaktifkan secara eksplisit untuk pemanggil oleh kebijakan perangkat perusahaan. Kunci Mesin Enterprise tidak berada di token "system" dan tidak dapat diakses oleh API lain.

Parameter

  • tantangan

    ArrayBuffer

    Verifikasi yang dikeluarkan oleh Verified Access Web API.

  • registerKey

    boolean opsional

    Chrome 59+ browser.* sejak Chrome 148

    Jika disetel, Kunci Perangkat Enterprise saat ini akan didaftarkan dengan token "system" dan melepaskan peran Kunci Perangkat Enterprise. 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 menghasilkan Kunci Perangkat Enterprise baru.

Hasil

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang di-resolve dengan respons verifikasi.

challengeUserKey()

Chrome 50+ browser.* sejak Chrome 148 Tidak digunakan lagi sejak Chrome 110
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

Sebagai gantinya, gunakan challengeKey.

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

Parameter

  • tantangan

    ArrayBuffer

    Verifikasi yang dikeluarkan oleh Verified Access Web API.

  • registerKey

    boolean

    Jika disetel, Kunci Pengguna versi bisnis saat ini akan didaftarkan dengan token "user" dan melepaskan peran Kunci Pengguna versi bisnis. 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 menghasilkan Kunci Pengguna Enterprise baru.

Hasil

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang di-resolve dengan respons verifikasi.

getCertificates()

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

Menampilkan daftar semua sertifikat klien yang tersedia dari token yang diberikan. Dapat digunakan untuk memeriksa keberadaan dan masa berlaku sertifikat klien yang dapat digunakan untuk autentikasi tertentu.

Parameter

  • tokenId

    string

    ID Token yang ditampilkan oleh getTokens.

Hasil

  • Promise<ArrayBuffer[]>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang di-resolve dengan daftar sertifikat yang tersedia.

getTokens()

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

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

Hasil

  • Promise<Token[]>

    Chrome 131+ browser.* sejak Chrome 148

    Dipanggil oleh getTokens dengan daftar Token yang tersedia.

importCertificate()

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

Mengimpor certificate ke token yang diberikan jika kunci bersertifikat 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 dari sertifikat X.509.

Hasil

  • Promise<void>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang akan di-resolve saat operasi ini selesai.

removeCertificate()

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

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

Parameter

  • tokenId

    string

    ID Token yang ditampilkan oleh getTokens.

  • sertifikat

    ArrayBuffer

    Encoding DER dari sertifikat X.509.

Hasil

  • Promise<void>

    Chrome 131+ browser.* sejak Chrome 148

    Menampilkan Promise yang akan di-resolve saat operasi ini selesai.