chrome.enterprise.platformKeys

Opis

Użyj interfejsu API chrome.enterprise.platformKeys, aby wygenerować klucze i zainstalować certyfikaty dla tych kluczy. Certyfikatami będzie zarządzać platforma. Można ich używać do uwierzytelniania TLS, dostępu do sieci lub przez inne rozszerzenie za pomocą interfejsu chrome.platformKeys.

Uprawnienia

enterprise.platformKeys

Dostępność

Tylko w ChromeOS Wymaga ustawienia zasad

Pojęcia i zastosowanie

Typowe użycie tego interfejsu API do rejestracji certyfikatu klienta:

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

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

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

  • Wyeksportuj klucz publiczny, używając metody exportKey() Token (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()`[3]

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

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome w wersji 110 lub nowszej

Właściwości

  • wyzwanie

    ArrayBuffer

    Wyzwanie wygenerowane przez interfejs Verified Access Web API.

  • registerKey

    RegisterKeyOptions opcjonalnie

    Jeśli klucz jest dostępny, rejestruje klucz z wyzwaniem za pomocą tokena scope. Klucz można następnie powiązać z certyfikatem i używać go 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 chcesz zakwestionować.

RegisterKeyOptions

Chrome w wersji 110 lub nowszej

Właściwości

  • algorytm

    Algorytm

    Którego algorytmu powinien używać zarejestrowany klucz.

Scope

Chrome w wersji 110 lub nowszej

Czy użyć klucza użytkownika Enterprise czy klucza maszynowego Enterprise.

Typ wyliczeniowy

"MACHINE"

Token

Właściwości

  • id

    ciąg znaków

    Jednoznacznie identyfikuje zasób Token.

    Identyfikatory statyczne to "user" i "system", które odnoszą się odpowiednio do tokena sprzętowego na poziomie użytkownika i domeny systemowej. enterprise.platformKeys.getTokens może zwrócić dowolne inne tokeny (z innymi identyfikatorami).

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome w wersji 97 lub nowszej

    Implementuje interfejs SubtleCrypto biblioteki WebCrypto. Operacje kryptograficzne, w tym generowanie kluczy, są obsługiwane przez oprogramowanie. 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 konkretnym elemencie 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 klucze RSASSA-PKCS1-V1_5 z modulusLength do 2048 i ECDSA z namedCurve P-256, które nie mogą być wyodrębniane. Każdego klucza można użyć do podpisywania danych najwyżej raz.

    Kluczy wygenerowanych na 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()

Obietnica Chrome w wersji 110 lub nowszej 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Podobnie jak 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. Jest przydatna tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który wysyła wyzwania i sprawdza 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 ChromeOS, jest 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. Tożsamość urządzenia emitowana przez weryfikację jest ściśle powiązana ze sprzętem bieżącego urządzenia. Jeśli jest określony zakres "user", tożsamość jest też ściśle powiązana z aktualnie zalogowanym użytkownikiem.

Ta funkcja jest bardzo ograniczona i nie zadziała, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub jeśli ta operacja nie została wyraźnie włączona dla wywołującego przez zasady urządzenia firmowego. 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 ChallengeKeyOptions.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Obietkwarzeczenie<ArrayBuffer>

    Oczekuje

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

challengeMachineKey()

Obietnica Chrome 50 lub nowszy Wycofane w Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

Zamiast tego użyj kolumny challengeKey.

Wyzwanie klucza maszynowego firmy obsługiwanego sprzętowo i emitowanie odpowiedzi w ramach protokołu zdalnego uwierzytelniania. Jest przydatna tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który wysyła wyzwania i sprawdza odpowiedzi. Pomyślna weryfikacja przez interfejs Verified Access Web API jest mocnym sygnałem o tym, że: * bieżące urządzenie jest prawidłowym urządzeniem z ChromeOS. * Bieżące urządzenie jest zarządzane przez domenę podaną podczas weryfikacji. * Zalogowanym użytkownikiem zarządza domena określona podczas weryfikacji. * Aktualny 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. Ta funkcja jest bardzo ograniczona i nie zadziała, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub jeśli ta operacja nie została wyraźnie włączona dla wywołującego przez zasady urządzenia firmowego. Klucz maszynowy dla firm 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 optional

    Parametr callback ma postać:

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Obietkwarzeczenie<ArrayBuffer>

    Oczekujący

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

challengeUserKey()

Obietnica Chrome 50 lub nowszy Wycofane w Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

Zamiast niego użyj challengeKey.

Wyzwanie klucza użytkownika Enterprise opartego na sprzęcie i wysyłanie odpowiedzi w ramach protokołu weryfikacji zdalnej. Jest przydatna tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który wysyła wyzwania i sprawdza odpowiedzi. Pomyślna weryfikacja przy użyciu interfejsu Verified Access Web API to wyraźny sygnał z tych źródeł: * Obecne urządzenie z ChromeOS to prawidłowe urządzenie. * 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 dla 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

    wartość logiczna

    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ć go jak każdego innego klucza podpisywania. Ten klucz jest kluczem RSA o długości 2048 bitów. Kolejne wywołania tej funkcji będą generować nowy klucz użytkownika firmowego.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback wygląda tak: 

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Obietkwarzeczenie<ArrayBuffer>

    Oczekujący

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getCertificates()

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

Zwraca listę wszystkich certyfikatów klienta dostępnych w danym tokenie. Może służyć do sprawdzania istnienia i terminu ważności certyfikatów klienta, które można wykorzystać do określonego uwierzytelniania.

Parametry

  • tokenId

    ciąg znaków

    Identyfikator tokena zwróconego przez getTokens.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (certificates: ArrayBuffer[]) => void

    • certyfikaty

      ArrayBuffer[]

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

Zwroty

  • Promise<ArrayBuffer[]>

    Oczekujący

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getTokens()

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

Zwraca dostępne tokeny. W sesji zwykłego użytkownika lista zawsze będzie zawierać token użytkownika z id "user". Jeśli dostępny jest token TPM dla całego systemu, zwrócona lista będzie zawierać również token dla całego systemu z wartością 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 optional

    Parametr callback wygląda tak: 

    (tokens: Token[]) => void

    • tokeny

      Token[]

      Lista dostępnych tokenów.

Zwroty

  • Obietnica<Token[]>

    Oczekujący

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

importCertificate()

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

Zaimportuj certificate do danego tokena, jeśli certyfikowany klucz jest już w nim przechowywany. Po pomyślnym przesłaniu żądania certyfikacji należy użyć tej funkcji, aby przechowywać uzyskany certyfikat i udostępniać go systemowi operacyjnemu oraz przeglądarce na potrzeby uwierzytelniania.

Parametry

  • tokenId

    ciąg znaków

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Oczekuje

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

removeCertificate()

Obietnica 
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. Należy go używać, aby zwolnić miejsce w sklepie z certyfikatami.

Parametry

  • tokenId

    ciąg znaków

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Oczekujący

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Obiet na obietnice zwraca ten sam typ, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.