chrome.enterprise.platformKeys

Opis

Do generowania kluczy i instalowania certyfikatów dla tych kluczy używaj interfejsu API chrome.enterprise.platformKeys. Certyfikaty będą zarządzane przez platformę i można ich używać 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

Pojęcia i zastosowanie

Typowe zastosowanie tego interfejsu API do rejestracji certyfikatu klienta przebiega w następujący sposób:

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

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

  • Wygeneruj parę kluczy, korzystając z metody tokena generateKey() (zdefiniowanej w SubtleCrypto). Spowoduje to zwrócenie nicku do klucza.

  • Wyeksportuj klucz publiczny, korzystając z metody exportKey() Token (zdefiniowanej w SubtleCrypto).

  • Utwórz podpis danych wniosku o certyfikację, korzystając z metody sign() Token (zdefiniowanej w SubtleCrypto).

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

  • Po otrzymaniu certyfikatu zaimportuj go za pomocą atrybutu [enterprise.platformKeys.importCertificate()`[3]

Oto przykład, który przedstawia 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 i nowsze wersje

Typ klucza do wygenerowania.

Enum

ChallengeKeyOptions

Chrome 110 i nowsze wersje

Właściwości

  • wyzwanie

    ArrayBuffer

    Wyzwanie generowane przez interfejs Verified Access Web API.

  • registerKey

    Opcjonalny RegisterKeyOptions

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

  • zakres

    Zakres

    Który klucz Enterprise należy zakwestionować.

RegisterKeyOptions

Chrome 110 i nowsze wersje

Właściwości

  • algorytm

    Algorytm

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

Scope

Chrome 110 i nowsze wersje

Określa, czy używany jest klucz użytkownika Enterprise, czy Enterprise Machine Key.

Enum

Token

Właściwości

  • id

    string,

    Jednoznacznie identyfikuje zasób Token.

    Identyfikatory statyczne to odpowiednio "user" i "system". Odwołują się one odpowiednio do specyficznych dla użytkownika platformy i do całego systemu tokena sprzętowego. Wszystkie inne tokeny (z innymi identyfikatorami) mogą zostać zwrócone przez enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 i nowsze wersje

    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órych nie można wyodrębnić, odbywa się w oprogramowaniu, dzięki czemu klucze są mniej chronione niż klucze sprzętowe.

    Można wygenerować tylko niewyodrębnione klucze RSASSA-PKCS1-V1_5 z modulusLength do 2048. Każdego klucza możesz używać do podpisywania danych najwyżej raz.

    Kluczy wygenerowanych na określonym urządzeniu Token nie można używać z żadnym innym tokenem ani z window.crypto.subtle. Również obiekty Key utworzone za pomocą window.crypto.subtle nie mogą być używane w tym interfejsie.

  • subtleCrypto

    SubtleCrypto

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

    Można wygenerować tylko niewyodrębnione klucze RSASSA-PKCS1-V1_5 z modulusLength do 2048 oraz ECDSA z namedCurve P-256. Każdego klucza możesz używać do podpisywania danych najwyżej raz.

    Kluczy wygenerowanych na określonym urządzeniu Token nie można używać z żadnym innym tokenem ani z window.crypto.subtle. Również obiekty Key utworzone za pomocą window.crypto.subtle nie mogą być używane w tym interfejsie.

Metody

challengeKey()

Chrome 110 i nowsze wersje 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

Podobnie jak challengeMachineKey i challengeUserKey, ale umożliwia określenie algorytmu zarejestrowanego klucza. kwestionuje oparty na sprzętowym kluczu Enterprise Machine Key i wysyła odpowiedź w ramach protokołu poświadczania zdalnego. Ta opcja jest przydatna tylko w systemie operacyjnym Chrome oraz w połączeniu z interfejsem internetowym Verified Access API, który zarówno wyświetla testy, jak i weryfikuje odpowiedzi.

Pomyślna weryfikacja przez interfejs internetowy interfejsu Verified Access API to wyraźny sygnał, że urządzenie jest prawidłowym urządzeniem z Chrome OS, bieżącym urządzeniem zarządza domena określona podczas weryfikacji, bieżącym zalogowanym użytkownikiem jest domena wskazana podczas weryfikacji, a bieżący stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń firmowych. Zasady mogą na przykład określać, że urządzenie nie może być w trybie programisty. Każda tożsamość urządzenia widoczna w ramach weryfikacji jest ściśle powiązana ze sprzętem danego urządzenia. Jeśli określono zakres "user", tożsamość jest też ściśle powiązana z obecnym zalogowanym użytkownikiem.

Ta funkcja jest bardzo ograniczona i nie powiedzie się, 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 elementu 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 ChallengeKeyOptions.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (response: ArrayBuffer)=>void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

challengeMachineKey()

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

Użyj w zamian challengeKey.

kwestionuje oparty na sprzętowym kluczu Enterprise Machine Key i wysyła odpowiedź w ramach protokołu poświadczania zdalnego. Ta opcja jest przydatna tylko w systemie operacyjnym Chrome oraz w połączeniu z interfejsem internetowym Verified Access API, który zarówno wyświetla testy, jak i weryfikuje odpowiedzi. Pomyślna weryfikacja przez interfejs internetowy Verified Access API to wyraźny sygnał, że: * Posiadane urządzenie to prawidłowe urządzenie z Chrome OS. * Bieżące urządzenie jest zarządzane przez domenę podaną podczas weryfikacji. * Obecnie zalogowany użytkownik jest zarządzany przez domenę podaną podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami dotyczącymi urządzeń w firmie. Zasady mogą na przykład określać, że urządzenie nie może być w trybie programisty. * Wszelka tożsamość urządzenia widoczna w ramach weryfikacji jest ściśle powiązana ze sprzętem danego urządzenia. Ta funkcja jest bardzo ograniczona i nie powiedzie się, 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 elementu wywołującego przez firmowe zasady dotyczące urządzeń. Klucz Enterprise Machine Key nie znajduje się w tokenie "system" i nie jest dostępny dla żadnego innego interfejsu API.

Parametry

  • wyzwanie

    ArrayBuffer

    Wyzwanie generowane przez interfejs Verified Access Web API.

  • registerKey

    wartość logiczna opcjonalna

    Chrome w wersji 59 i nowszych

    Jeśli jest ustawiony, bieżący klucz komputera Enterprise jest rejestrowany za pomocą tokena "system" i zrzeka się roli klucza komputera przedsiębiorstwa. Klucz ten można powiązać z certyfikatem i używać jak każdego innego klucza podpisywania. Jest to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji będą powodować wygenerowanie nowego klucza komputera Enterprise.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (response: ArrayBuffer)=>void

    • odpowiedź

      ArrayBuffer

      Odpowiedź na wyzwanie.

challengeUserKey()

Chrome 50 i nowszy Wycofane od Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

Użyj w zamian challengeKey.

kwestionuje oparty na sprzętowym kluczu użytkownika Enterprise klucz użytkownika i wysyła odpowiedź w ramach protokołu poświadczania zdalnego. Ta opcja jest przydatna tylko w systemie operacyjnym Chrome oraz w połączeniu z interfejsem internetowym Verified Access API, który zarówno wyświetla testy, jak i weryfikuje odpowiedzi. Pomyślna weryfikacja przez interfejs internetowy Verified Access API to wyraźny sygnał, że: * Posiadane urządzenie to prawidłowe urządzenie z Chrome OS. * Bieżące urządzenie jest zarządzane przez domenę podaną podczas weryfikacji. * Obecnie zalogowany użytkownik jest zarządzany przez domenę podaną podczas weryfikacji. * Obecny stan urządzenia jest zgodny z zasadami dotyczącymi użytkowników firmowych. Zasady mogą na przykład określać, że urządzenie nie może być w trybie programisty. * Klucz publiczny wygenerowany podczas weryfikacji jest ściśle powiązany ze sprzętem obecnego urządzenia i z aktualnie zalogowanym użytkownikiem. Ta funkcja jest bardzo ograniczona i nie powiedzie się, jeśli bieżące urządzenie nie jest zarządzane, bieżący użytkownik nie jest zarządzany lub ta operacja nie została jawnie włączona dla elementu wywołującego za pomocą zasad dotyczących 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 generowane przez interfejs Verified Access Web API.

  • registerKey

    boolean

    Jeśli jest ustawiony, bieżący klucz użytkownika Enterprise jest rejestrowany za pomocą tokena "user" i zwalnia rolę klucza Enterprise użytkownika. Klucz ten można powiązać z certyfikatem i używać jak każdego innego klucza podpisywania. Jest to 2048-bitowy klucz RSA. Kolejne wywołania tej funkcji będą powodować wygenerowanie nowego klucza użytkownika Enterprise.

  • 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 w danym tokenie. Może służyć do sprawdzania, czy certyfikaty klienta nadają się do określonego uwierzytelniania i czy istnieją i czy nie wygasają.

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 zwykłej sesji użytkownika lista zawsze zawiera token użytkownika z id "user". Jeśli dostępny jest token TPM stosowany w całym systemie, zwrócona lista będzie zawierać też token dla całego systemu z id "system". Token dla całego systemu będzie taki sam dla wszystkich sesji na tym urządzeniu (urządzenie w rozumieniu, np. Chromebook).

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ż zapisany w tym tokenie. Po pozytywnym rozpatrzeniu wniosku o certyfikację należy użyć tej funkcji do zapisania uzyskanego certyfikatu oraz udostępnienia go systemowi operacyjnemu i przeglądarce w celu uwierzytelnienia.

Parametry

  • tokenId

    string,

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

removeCertificate()

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

Usuwa certificate z danego tokena, jeśli występuje. Służy do usuwania przestarzałych certyfikatów, aby nie zostały uwzględnione podczas uwierzytelniania i nie zaśmiecały wyboru certyfikatów. Powinno być używane do zwolnienia miejsca w magazynie certyfikatów.

Parametry

  • tokenId

    string,

    Identyfikator tokena zwrócony przez getTokens.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void