chrome.enterprise.platformKeys

Opis

Użyj interfejsu chrome.enterprise.platformKeys API, aby wygenerować klucze i zainstalować certyfikaty dla tych kluczy. Certyfikaty będą zarządzane przez platformę i mogą być używane do uwierzytelniania TLS, dostępu do sieci lub przez inne rozszerzenia za pomocą interfejsu chrome.platformKeys.

Uprawnienia

enterprise.platformKeys

Dostępność

Tylko ChromeOS Wymaga zasad

Wykorzystanie

Typowe użycie tego interfejsu API do rejestracji certyfikatu klienta obejmuje te czynności:

  • Pobierz wszystkie dostępne tokeny za pomocą funkcji enterprise.platformKeys.getTokens.

  • Znajdź token, w którym id jest równe "user". Użyj tego tokena później.

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

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

  • Utwórz podpis danych żądania certyfikacji za pomocą metody sign Token (zdefiniowanej w SubtleCrypto).

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

  • Jeśli otrzymasz certyfikat, zaimportuj go za pomocą funkcji enterprise.platformKeys.importCertificate.

Oto przykład, który pokazuje główne interakcje z interfejsem API z wyjątkiem tworzenia i wysyłania żądania certyfikacji:

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 nowsza

Typ klucza do wygenerowania.

Typ wyliczeniowy

„RSA”

„ECDSA”

ChallengeKeyOptions

Chrome 110 lub nowsza

Właściwości

  • wyzwanie

    ArrayBuffer

    Wyzwanie wygenerowane przez interfejs Verified Access Web API.

  • registerKey

    RegisterKeyOptions opcjonalny

    Jeśli jest obecny, rejestruje klucz, który został poddany weryfikacji, za pomocą tokena określonego przez 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 będą generować nowy klucz Enterprise w określonym scope.

  • zakres

    Zakres

    Który klucz firmowy ma zostać użyty do uwierzytelniania.

RegisterKeyOptions

Chrome 110 lub nowsza

Właściwości

  • algorytm

    Algorytm

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

Scope

Chrome 110 lub nowsza

Czy używać klucza użytkownika Enterprise czy klucza urządzenia Enterprise.

Typ wyliczeniowy

„USER”

„MACHINE”

Token

Właściwości

  • id

    ciąg znaków

    Jednoznacznie identyfikuje ten Token.

    Identyfikatory statyczne to "user" i "system", które odnoszą się odpowiednio do tokena sprzętowego użytkownika platformy i tokena sprzętowego całego systemu. enterprise.platformKeys.getTokens może zwracać inne tokeny (z innymi identyfikatorami).

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 lub nowsza

    Implementuje interfejs SubtleCrypto WebCrypto. Operacje kryptograficzne, w tym generowanie kluczy, są obsługiwane przez oprogramowanie. Ochrona kluczy, a tym samym implementacja właściwości niewydobywalności, odbywa się w oprogramowaniu, więc klucze są mniej chronione niż klucze obsługiwane sprzętowo.

    Można generować tylko klucze, których nie można wyodrębnić. Obsługiwane typy kluczy to RSASSA-PKCS1-V1_5 i RSA-OAEP (w Chrome w wersji 135 lub nowszej) o długości modulusLength do 2048 bitów. Każdego klucza RSASSA-PKCS1-V1_5 można użyć do podpisywania danych co najwyżej raz, chyba że rozszerzenie znajduje się na liście dozwolonych w ramach zasady KeyPermissions. W takim przypadku klucza można używać bez ograniczeń. Klucze RSA-OAEP są obsługiwane od wersji Chrome 135 i mogą być używane przez rozszerzenia dodane do listy dozwolonych za pomocą tej samej zasady do rozpakowywania innych kluczy.

    Kluczy wygenerowanych na konkretnym urządzeniu Token nie można używać z żadnymi innymi tokenami ani z window.crypto.subtle. Podobnie obiekty Key utworzone za pomocą window.crypto.subtle nie mogą być używane z tym interfejsem.

  • subtleCrypto

    SubtleCrypto

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

    Można generować tylko klucze, których nie można wyodrębnić. Obsługiwane typy kluczy to RSASSA-PKCS1-V1_5 i RSA-OAEP (w Chrome w wersji 135 lub nowszej) z modulusLength maksymalnie 2048 bitami oraz ECDSA z namedCurve P-256. Każdy klucz RSASSA-PKCS1-V1_5 i ECDSA może być używany do podpisywania danych co najwyżej raz, chyba że rozszerzenie znajduje się na liście dozwolonych w ramach zasady KeyPermissions. W takim przypadku klucz może być używany bezterminowo. Klucze RSA-OAEP są obsługiwane od wersji Chrome 135 i mogą być używane przez rozszerzenia dodane do listy dozwolonych za pomocą tej samej zasady do rozpakowywania innych kluczy.

    Kluczy wygenerowanych na konkretnym urządzeniu Token nie można używać z żadnymi innymi tokenami ani z window.crypto.subtle. Podobnie obiekty Key utworzone za pomocą window.crypto.subtle nie mogą być używane z tym interfejsem.

Metody

challengeKey()

Promise Chrome 110 lub nowszy 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

Podobne do challengeMachineKey i challengeUserKey, ale umożliwia określenie algorytmu zarejestrowanego klucza. Wyzwanie dla klucza urządzenia firmowego opartego na sprzęcie i emitowanie odpowiedzi w ramach protokołu zdalnego potwierdzania. Przydatne tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który zarówno wysyła wyzwania, jak i weryfikuje odpowiedzi.

Pomyślna weryfikacja przez interfejs Verified Access Web API jest silnym sygnałem, że bieżące urządzenie jest legalnym urządzeniem z ChromeOS, jest zarządzane przez domenę określoną podczas weryfikacji, bieżący zalogowany użytkownik jest zarządzany przez domenę określoną podczas weryfikacji, a bieżący stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń firmowych. Na przykład zasady mogą określać, że urządzenie nie może działać w trybie programisty. Każda tożsamość urządzenia wygenerowana przez weryfikację jest ściśle powiązana ze sprzętem bieżącego urządzenia. Jeśli określono "user" Scope, tożsamość jest też ściśle powiązana z aktualnie zalogowanym użytkownikiem.

Ta funkcja jest bardzo ograniczona i nie będzie działać, jeśli bieżące urządzenie lub użytkownik nie są zarządzani albo jeśli ta operacja nie została wyraźnie włączona dla wywołującego przez zasady dotyczące urządzeń firmowych. Klucz poddany weryfikacji 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.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Promise<ArrayBuffer>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

challengeMachineKey()

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

Zamiast niej używaj kolumny challengeKey.

Wyzwanie dla klucza urządzenia firmowego opartego na sprzęcie i emitowanie odpowiedzi w ramach protokołu zdalnego potwierdzania. Przydatne tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który zarówno wysyła wyzwania, jak i weryfikuje odpowiedzi. Pomyślna weryfikacja przez interfejs Verified Access Web API jest silnym sygnałem, że: * bieżące urządzenie jest legalnym urządzeniem z ChromeOS; * Bieżącym urządzeniem zarządza domena określona podczas weryfikacji. * Bieżący zalogowany użytkownik jest zarządzany przez domenę określoną podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń w firmie. Na przykład zasady mogą określać, że urządzenie nie może działać w trybie programisty. * Każdy identyfikator urządzenia wygenerowany przez weryfikację jest ściśle powiązany ze sprzętem bieżącego urządzenia. Ta funkcja jest bardzo ograniczona i nie będzie działać, jeśli bieżące urządzenie lub użytkownik nie są zarządzani albo jeśli ta operacja nie została wyraźnie włączona dla wywołującego przez zasady dotyczące urządzeń firmowych. Klucz urządzenia Enterprise 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 59 lub nowsza

    Jeśli ta opcja jest ustawiona, bieżący klucz urządzenia w firmie jest rejestrowany za pomocą tokena "system" i traci rolę klucza urządzenia w firmie. Klucz można następnie powiązać z certyfikatem i używać go jak każdego innego klucza podpisywania. Ten klucz to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji spowodują wygenerowanie nowego klucza maszyny Enterprise.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Promise<ArrayBuffer>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

challengeUserKey()

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

Zamiast niej używaj kolumny challengeKey.

Wyzwanie dla klucza użytkownika Enterprise opartego na sprzęcie i przesyłanie odpowiedzi w ramach protokołu zdalnego potwierdzania. Przydatne tylko w ChromeOS i w połączeniu z interfejsem Verified Access Web API, który zarówno wysyła wyzwania, jak i weryfikuje odpowiedzi. Pomyślna weryfikacja przez interfejs Verified Access Web API jest silnym sygnałem, że: * bieżące urządzenie jest legalnym urządzeniem z ChromeOS; * Bieżącym urządzeniem zarządza domena określona podczas weryfikacji. * Bieżący zalogowany użytkownik jest zarządzany przez domenę określoną podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami użytkownika firmowego. Na przykład zasady mogą określać, że urządzenie nie może działać w trybie programisty. * Klucz publiczny wygenerowany przez weryfikację jest ściśle powiązany ze sprzętem bieżącego urządzenia i z aktualnie zalogowanym użytkownikiem. Ta funkcja jest bardzo ograniczona 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 jeśli ta operacja nie została wyraźnie włączona dla wywołującego przez zasady użytkownika firmowego. Klucz użytkownika Enterprise nie znajduje się w "user" tokenie 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 ta opcja jest ustawiona, bieżący klucz użytkownika firmowego jest rejestrowany za pomocą tokena "user" i traci 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 to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji będą generować nowy klucz użytkownika Enterprise.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (response: ArrayBuffer) => void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

Zwroty

  • Promise<ArrayBuffer>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getCertificates()

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

Zwraca listę wszystkich certyfikatów klienta dostępnych w danym tokenie. Może służyć do sprawdzania, czy istnieją certyfikaty klienta, które można wykorzystać do określonego uwierzytelniania, oraz czy nie wygasły.

Parametry

  • tokenId

    ciąg znaków

    Identyfikator tokena zwrócony przez getTokens.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (certificates: ArrayBuffer[]) => void

    • certyfikaty

      ArrayBuffer[]

      Lista certyfikatów, z których każdy jest certyfikatem X.509 zakodowanym w formacie DER.

Zwroty

  • Promise<ArrayBuffer[]>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getTokens()

Obietnica 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

Zwraca dostępne tokeny. W sesji zwykłego użytkownika lista zawsze będzie zawierać token użytkownika z wartością id "user". Jeśli dostępny jest token TPM obejmujący cały system, zwrócona lista będzie zawierać również token obejmujący cały system z wartością id "system". Token obejmujący cały system będzie taki sam we wszystkich sesjach na tym urządzeniu (urządzenie w sensie np. Chromebooka).

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (tokens: Token[]) => void

    • tokeny

      Token[]

      Lista dostępnych tokenów.

Zwroty

  • Promise<Token[]>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

importCertificate()

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

Importuje certificate do danego tokena, jeśli certyfikowany klucz jest już w nim zapisany. Po pomyślnym przesłaniu prośby o certyfikat należy użyć tej funkcji, aby zapisać uzyskany certyfikat i udostępnić 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.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

removeCertificate()

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

Usuwa znak certificate z podanego tokena, jeśli występuje. Należy go używać do usuwania przestarzałych certyfikatów, aby nie były brane pod uwagę podczas uwierzytelniania i nie zaśmiecały wyboru certyfikatów. Należy go używać do zwalniania miejsca w magazynie certyfikatów.

Parametry

  • tokenId

    ciąg znaków

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 131 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.