chrome.enterprise.platformKeys

Opis

Użyj interfejsu API chrome.enterprise.platformKeys do generowania kluczy i instalowania certyfikatów dla tych kluczy. Certyfikaty będą zarządzane przez platformę i mogą być używane do uwierzytelniania TLS, dostępu do sieci lub za pomocą innego rozszerzenia za pomocą chrome.platformKeys.

Uprawnienia

enterprise.platformKeys

Dostępność

Tylko ChromeOS Wymaga zasady

Wykorzystanie

Typowe użycie tego interfejsu API do rejestracji certyfikatu klienta wygląda tak:

  • Uzyskaj wszystkie dostępne tokeny za pomocą klucza enterprise.platformKeys.getTokens.

  • Znajdź token z wartością id równą "user". Używaj go później.

  • Wygeneruj parę kluczy za pomocą metody tokena generateKey (zdefiniowanej w SubtleCrypto). Spowoduje to zwrócenie nicka do klucza.

  • Wyeksportuj klucz publiczny za pomocą metody tokena exportKey (zdefiniowanej w SubtleCrypto).

  • Utwórz podpis danych prośby o certyfikację za pomocą metody tokena sign (zdefiniowanej w SubtleCrypto).

  • Wypełnij wniosek o certyfikat i wyślij go do urzędu certyfikacji.

  • Jeśli certyfikat został odebrany, zaimportuj go przy użyciu enterprise.platformKeys.importCertificate

Oto przykład, który pokazuje główną interakcję interfejsu API z wyjątkiem tworzenia i wysyłania prośby o certyfikację:

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

Typy

Algorithm

Chrome 110 lub nowszy

Typ klucza do wygenerowania.

Typ wyliczeniowy

ChallengeKeyOptions

Chrome 110 lub nowszy

Właściwości

  • wyzwanie

    ArrayBuffer

    Wyzwanie wygenerowane przez interfejs Verified Access Web API.

  • registerKey

    RegisterKeyOptions (opcjonalny)

    Jeśli ten klucz jest dostępny, rejestruje testowany klucz za pomocą podanego tokena scope. Klucz można następnie powiązać z certyfikatem i używać tak samo jak każdego innego klucza podpisywania. Kolejne wywołania tej funkcji w określonym scope będą generować nowy klucz Enterprise.

  • zakres

    Zakres

    Który klucz Enterprise ma zakwestionować.

RegisterKeyOptions

Chrome 110 lub nowszy

Właściwości

  • algorytm

    Algorytm

    Algorytmu, którego powinien używać zarejestrowany klucz.

Scope

Chrome 110 lub nowszy

Określa, czy używany jest klucz użytkownika Enterprise czy klucz komputera firmowego.

Typ wyliczeniowy

Token

Właściwości

  • id

    string,

    Jednoznacznie identyfikuje zasób Token.

    Statyczne identyfikatory to "user" i "system". Odnoszą się one odpowiednio do tokena użytkownika platformy i tokena sprzętowego w całym systemie. Pozostałe tokeny (z innymi identyfikatorami) mogą zostać zwrócone przez enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 lub nowszy

    Implementuje interfejs SubtleCrypto interfejsu WebCrypto. Operacje kryptograficzne, w tym generowanie kluczy, są oparte na oprogramowaniu. Ochrona kluczy, a tym samym implementacja właściwości, której nie można wyodrębnić, odbywa się w oprogramowaniu, więc klucze są mniej chronione niż klucze obsługiwane sprzętowo.

    Można generować tylko niewyodrębnione klucze RSASSA-PKCS1-V1_5 o zakresie od modulusLength do 2048. Każdego klucza można użyć do podpisywania danych najwyżej raz.

    Kluczy wygenerowanych w określonym Token nie można używać z żadnymi innymi tokenami ani z window.crypto.subtle. Podobnie obiektów Key utworzonych za pomocą window.crypto.subtle nie można używać w tym interfejsie.

  • subtleCrypto

    SubtleCrypto

    Implementuje interfejs SubtleCrypto interfejsu WebCrypto. Operacje kryptograficzne, w tym generowanie kluczy, są obsługiwane sprzętowo.

    Można generować tylko niewyodrębnione klucze RSASSA-PKCS1-V1_5 o wartości modulusLength do 2048 i ECDSA z namedCurve P-256. Każdego klucza można użyć do podpisywania danych najwyżej raz.

    Kluczy wygenerowanych w określonym Token nie można używać z żadnymi innymi tokenami ani z window.crypto.subtle. Podobnie obiektów Key utworzonych za pomocą window.crypto.subtle nie można używać w tym interfejsie.

Metody

challengeKey()

Chrome 110 lub nowszy 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

Podobny do challengeMachineKey i challengeUserKey, ale umożliwia określenie algorytmu zarejestrowanego klucza. Testuje test zabezpieczający użycie klucza Enterprise Machine Key i wysyła odpowiedź w ramach protokołu zdalnego poświadczania. Przydatny tylko w Chrome OS oraz w połączeniu z interfejsem Verified Access Web API, który powoduje problemy i weryfikuje odpowiedzi.

Pomyślna weryfikacja przy użyciu interfejsu Verified Access Web API to wyraźny sygnał, że bieżące urządzenie jest prawidłowym urządzeniem z Chrome OS, jest ono zarządzane przez domenę podaną podczas weryfikacji, aktualnie zalogowany użytkownik jest zarządzany przez domenę podaną podczas weryfikacji, a bieżący stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń firmowych. Na przykład zasada może określać, że urządzenie nie może działać w trybie programisty. Każda tożsamość urządzenia wygenerowana w ramach weryfikacji jest ściśle powiązana ze sprzętem aktualnie używanego urządzenia. Jeśli jest określony zakres "user", tożsamość jest też ściśle powiązana z obecnie zalogowanym użytkownikiem.

Ta funkcja ma duże ograniczenia i nie będzie działać, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub ta operacja nie została bezpośrednio włączona dla wywołującego przez firmowe zasady dotyczące urządzeń. Testowany klucz nie znajduje się w tokenie "system" ani "user" i nie jest dostępny dla żadnego innego interfejsu API.

Parametry

  • Obiekt zawierający pola zdefiniowane w narzędziu ChallengeKeyOptions.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

challengeMachineKey()

Chrome w wersji 50 lub nowszej Wycofany od Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

Zamiast niego użyj challengeKey.

Testuje test zabezpieczający użycie klucza Enterprise Machine Key i wysyła odpowiedź w ramach protokołu zdalnego poświadczania. Przydatny tylko w Chrome OS oraz w połączeniu z interfejsem Verified Access Web API, który powoduje problemy i weryfikuje odpowiedzi. Pomyślna weryfikacja przy użyciu interfejsu Verified Access Web API to ważny sygnał, aby: * Używane obecnie urządzenie z Chrome OS ma prawidłowe działanie. * Bieżące urządzenie jest zarządzane przez domenę podaną podczas weryfikacji. * Zalogowanym użytkownikiem zarządza domena określona podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń w firmie. Na przykład zasada może określać, że urządzenie nie może działać w trybie programisty. * Każda tożsamość urządzenia wygenerowana w ramach weryfikacji jest ściśle powiązana ze sprzętem aktualnie używanego urządzenia. Ta funkcja ma duże ograniczenia i nie będzie działać, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub ta operacja nie została bezpośrednio włączona dla wywołującego przez firmowe zasady dotyczące urządzeń. Firmowy klucz maszyny nie znajduje się w tokenie "system" i nie jest dostępny dla żadnego innego interfejsu API.

Parametry

  • wyzwanie

    ArrayBuffer

    Wyzwanie wygenerowane przez interfejs Verified Access Web API.

  • registerKey

    Wartość logiczna opcjonalna

    Chrome w wersji 59 lub nowszej

    Jeśli jest ustawiony, bieżący Enterprise Machine Key jest zarejestrowany przy użyciu tokena "system" i rezygnuje z roli Enterprise Machine Key. Klucz można następnie powiązać z certyfikatem i używać tak samo jak każdego innego klucza podpisywania. Jest to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji będą generować nowy klucz maszyny wirtualnej.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

challengeUserKey()

Chrome w wersji 50 lub nowszej Wycofany od Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

Zamiast niego użyj challengeKey.

Testuje wspierany sprzętowo klucz użytkownika Enterprise i wysyła odpowiedź w ramach protokołu zdalnego poświadczania. Przydatny tylko w Chrome OS oraz w połączeniu z interfejsem Verified Access Web API, który powoduje problemy i weryfikuje odpowiedzi. Pomyślna weryfikacja przy użyciu interfejsu Verified Access Web API to ważny sygnał, aby: * Używane obecnie urządzenie z Chrome OS ma prawidłowe działanie. * Bieżące urządzenie jest zarządzane przez domenę podaną podczas weryfikacji. * Zalogowanym użytkownikiem zarządza domena określona podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami dotyczącymi użytkowników firmowych. Na przykład zasada może określać, że urządzenie nie może działać w trybie programisty. * Klucz publiczny wygenerowany w ramach weryfikacji jest ściśle powiązany ze sprzętem bieżącego urządzenia i aktualnie zalogowanym użytkownikiem. Ta funkcja ma duże ograniczenia i nie będzie działać, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub ta operacja nie została wyraźnie włączona dla wywołującego przez zasady dotyczące użytkowników firmowych. Klucz użytkownika Enterprise nie znajduje się w tokenie "user" i nie jest dostępny dla żadnego innego interfejsu API.

Parametry

  • wyzwanie

    ArrayBuffer

    Wyzwanie wygenerowane przez interfejs Verified Access Web API.

  • registerKey

    boolean

    Jeśli jest ustawiony, bieżący klucz użytkownika Enterprise jest zarejestrowany przy użyciu tokena "user" i znika rolę klucza użytkownika firmowego. Klucz można następnie powiązać z certyfikatem i używać tak samo jak każdego innego klucza podpisywania. Jest to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji będą generować nowy klucz użytkownika firmowego.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

getCertificates()

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

Zwraca listę wszystkich certyfikatów klienta dostępnych z podanego tokena. Pozwala sprawdzać ważność certyfikatów klienta odpowiednich do określonego uwierzytelniania.

Parametry

  • tokenId

    string,

    Identyfikator tokena zwrócony przez getTokens.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (certificates: ArrayBuffer[]) => void

    • certyfikaty

      tablicaBuffer[]

      Lista certyfikatów, każdy w kodowaniu DER certyfikatu X.509.

getTokens()

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

Zwraca dostępne tokeny. W sesji zwykłego użytkownika lista będzie zawsze zawierać token użytkownika z identyfikatorem id "user". Jeśli dostępny jest token TPM dla całego systemu, zwrócona lista będzie też zawierać token systemu z id "system". Token dla całego systemu będzie taki sam dla wszystkich sesji na tym urządzeniu (w rozumieniu np. na Chromebooku).

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (tokens: Token[]) => void

    • tokeny

      Token[]

      Lista dostępnych tokenów.

importCertificate()

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

Importuje certificate do danego tokena, jeśli certyfikowany klucz jest już w nim przechowywany. Po udanej prośbie o certyfikację należy używać tej funkcji do przechowywania uzyskanego certyfikatu i udostępniania go systemowi operacyjnemu oraz przeglądarce na potrzeby uwierzytelniania.

Parametry

  • tokenId

    string,

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

removeCertificate()

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

Usuwa element certificate z danego tokena, jeśli jest dostępny. Służy do usuwania przestarzałych certyfikatów, aby nie były brane pod uwagę podczas uwierzytelniania i nie zaśmiecały wybranego certyfikatu. Powinien być używany do zwalniania miejsca na dane w magazynie certyfikatów.

Parametry

  • tokenId

    string,

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void