chrome.enterprise.platformKeys

Descripción

Usa la API de chrome.enterprise.platformKeys para generar claves y, luego, instalar certificados para ellas. La plataforma administrará los certificados, que se pueden usar para la autenticación TLS, el acceso a la red o cualquier otra extensión a través de chrome.platformKeys.

Permisos

enterprise.platformKeys

Disponibilidad

Solo para ChromeOS Requiere una política

Conceptos y uso

El uso típico de esta API para inscribir un certificado de cliente sigue estos pasos:

  • Obtén todos los tokens disponibles con enterprise.platformKeys.getTokens().

  • Busca el token cuyo id sea igual a "user". Usa este token más adelante.

  • Genera un par de claves con el método del token generateKey() (definido en SubtleCrypto). Esto mostrará el control de la clave.

  • Exporta la clave pública con el método de token exportKey() (definido en SubtleCrypto).

  • Crea la firma de los datos de la solicitud de certificación con el método de token sign() (definido en SubtleCrypto).

  • Completa la solicitud de certificación y envíala a la autoridad certificadora.

  • Si se recibe un certificado, impórtalo con [enterprise.platformKeys.importCertificate()`[3]

Este es un ejemplo que muestra la interacción principal de la API, excepto la creación y el envío de la solicitud de certificación:

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

Tipos

Algorithm

Chrome 110 y versiones posteriores

Tipo de clave para generar.

Enum

"ECDSA"

ChallengeKeyOptions

Chrome 110 y versiones posteriores

Propiedades

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Verified Access.

  • registerKey

    RegisterKeyOptions opcional

    Si está presente, registra la clave desaprobada con el token de scope especificado. Luego, la clave se puede asociar con un certificado y se puede usar como cualquier otra clave de firma. Las llamadas posteriores a esta función generarán una nueva clave empresarial en el scope especificado.

  • alcance

    Alcance

    Qué clave empresarial se debe impugnar.

RegisterKeyOptions

Chrome 110 y versiones posteriores

Propiedades

  • algoritmo

    Algorithm

    Indica qué algoritmo debe usar la clave registrada.

Scope

Chrome 110 y versiones posteriores

Indica si se debe usar la clave de usuario empresarial o la clave de máquina empresarial.

Enum

"USER"

"MACHINE"

Token

Propiedades

  • id

    string

    Identifica de forma única este Token.

    Los IDs estáticos son "user" y "system", que se refieren al token de hardware específico del usuario de la plataforma y al token de hardware del sistema, respectivamente. enterprise.platformKeys.getTokens podría mostrar cualquier otro token (con otros identificadores).

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 y versiones posteriores

    Implementa la interfaz SubtleCrypto de WebCrypto. Las operaciones criptográficas, incluida la generación de claves, están respaldadas por software. La protección de las claves y, por lo tanto, la implementación de la propiedad no extraíble se realiza en software, por lo que las claves están menos protegidas que las guardadas en hardware.

    Solo se pueden generar claves RSASSA-PKCS1-V1_5 no extraíbles con modulusLength de hasta 2048. Cada clave se puede usar para firmar datos como máximo una vez.

    Las claves generadas en un Token específico no se pueden usar con ningún otro token ni se pueden usar con window.crypto.subtle. Del mismo modo, los objetos Key creados con window.crypto.subtle no se pueden usar con esta interfaz.

  • subtleCrypto

    SubtleCrypto

    Implementa la interfaz SubtleCrypto de WebCrypto. Las operaciones criptográficas, incluida la generación de claves, están respaldadas por hardware.

    Solo se pueden generar claves RSASSA-PKCS1-V1_5 no extraíbles con modulusLength hasta 2048 y ECDSA con namedCurve P-256. Cada clave se puede usar para firmar datos como máximo una vez.

    Las claves generadas en un Token específico no se pueden usar con ningún otro token ni con window.crypto.subtle. Del mismo modo, los objetos Key creados con window.crypto.subtle no se pueden usar con esta interfaz.

Métodos

challengeKey()

Promesa Chrome 110 y versiones posteriores 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Es similar a challengeMachineKey y challengeUserKey, pero permite especificar el algoritmo de una clave registrada. Desafía una clave de máquina empresarial respaldada por hardware y emite la respuesta como parte de un protocolo de certificación remota. Solo es útil en ChromeOS y junto con la API de Verified Access Web, que genera desafíos y verifica las respuestas.

Una verificación exitosa por parte de la API de Verified Access Web es un indicador claro de que el dispositivo actual es un dispositivo ChromeOS legítimo, el dispositivo actual es administrado por el dominio especificado durante la verificación, el dominio especificado durante la verificación administra al usuario actual que accedió y el estado actual del dispositivo cumple con la política de dispositivo empresarial. Por ejemplo, una política puede especificar que el dispositivo no debe estar en modo de desarrollador. Cualquier identidad del dispositivo que emita la verificación está estrechamente vinculada al hardware del dispositivo actual. Si se especifica el permiso "user", la identidad también está estrechamente vinculada al usuario que accedió actualmente.

Esta función está muy restringida y fallará si el dispositivo actual no está administrado, no se administra al usuario actual o si la política de dispositivo empresarial no habilitó explícitamente esta operación para el emisor. La clave desafiada no reside en el token "system" ni "user", y ninguna otra API puede acceder a ella.

Parámetros

  • Objeto que contiene los campos definidos en ChallengeKeyOptions

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (response: ArrayBuffer) => void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

Muestra

  • Promise<ArrayBuffer>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

challengeMachineKey()

Promesa Chrome 50 y versiones posteriores Obsoleto desde Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

En su lugar, usa challengeKey.

Desafía una clave de máquina empresarial respaldada por hardware y emite la respuesta como parte de un protocolo de certificación remota. Solo es útil en ChromeOS y junto con la API de Verified Access Web, que genera desafíos y verifica las respuestas. Una verificación correcta de la API web de Verified Access es un indicador sólido de lo siguiente: * El dispositivo actual es un dispositivo ChromeOS legítimo. * El dispositivo actual es administrado por el dominio especificado durante la verificación. * El usuario que accedió actualmente está administrado por el dominio especificado durante la verificación. * El estado actual del dispositivo cumple con la política de dispositivos empresariales. Por ejemplo, una política puede especificar que el dispositivo no debe estar en modo de desarrollador. * Cualquier identidad de dispositivo emitida por la verificación está estrechamente vinculada al hardware del dispositivo actual. Esta función tiene muchas restricciones y fallará si el dispositivo actual no está administrado, si el usuario actual no está administrado o si la política de dispositivos empresariales no habilitó esta operación de forma explícita para el llamador. La clave de máquina empresarial no reside en el token "system" y ninguna otra API puede acceder a ella.

Parámetros

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Verified Access.

  • registerKey

    booleano opcional

    Chrome 59 y versiones posteriores

    Si se establece, la clave de máquina empresarial actual se registra con el token "system" y renuncia al rol de clave de máquina empresarial. Luego, la clave se puede asociar con un certificado y usarse como cualquier otra clave de firma. Esta clave es RSA de 2,048 bits. Las llamadas posteriores a esta función generarán una nueva clave de máquina empresarial.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (response: ArrayBuffer) => void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

Muestra

  • Promise<ArrayBuffer>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

challengeUserKey()

Promesa Chrome 50 y versiones posteriores Obsoleto desde Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

En su lugar, usa challengeKey.

Desafía una clave de usuario empresarial guardada en hardware y emite la respuesta como parte de un protocolo de certificación remota. Solo es útil en ChromeOS y junto con la API de Verified Access Web, que genera desafíos y verifica las respuestas. Una verificación correcta de la API web de Verified Access es un indicador sólido de lo siguiente: * El dispositivo actual es un dispositivo ChromeOS legítimo. * El dominio especificado durante la verificación administra el dispositivo actual. * El usuario que accedió actualmente está administrado por el dominio especificado durante la verificación. * El estado actual del dispositivo cumple con la política de usuarios empresariales. Por ejemplo, una política puede especificar que el dispositivo no debe estar en modo de desarrollador. * La clave pública emitida por la verificación está estrechamente vinculada al hardware del dispositivo actual y al usuario que accedió a su cuenta. Esta función tiene muchas restricciones y fallará si el dispositivo actual no está administrado, si el usuario actual no está administrado o si la política de usuario empresarial no habilitó explícitamente esta operación para el llamador. La clave de usuario empresarial no reside en el token "user" y ninguna otra API puede acceder a ella.

Parámetros

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Verified Access.

  • registerKey

    boolean

    Si se establece, la clave de usuario empresarial actual se registra con el token "user" y renuncia al rol de clave de usuario empresarial. Luego, la clave se puede asociar con un certificado y usarse como cualquier otra clave de firma. Esta clave es RSA de 2,048 bits. Las llamadas posteriores a esta función generarán una nueva clave de usuario empresarial.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (response: ArrayBuffer) => void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

Muestra

  • Promise<ArrayBuffer>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getCertificates()

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

Muestra la lista de todos los certificados de cliente disponibles a partir del token determinado. Se puede utilizar para comprobar la existencia y el vencimiento de certificados de cliente que se puedan utilizar para una autenticación determinada.

Parámetros

  • tokenId

    string

    Es el ID de un token que muestra getTokens.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (certificates: ArrayBuffer[]) => void

    • certificados

      ArrayBuffer[]

      Lista de certificados, cada uno con codificación DER de un certificado X.509.

Muestra

  • Promise<ArrayBuffer[]>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getTokens()

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

Devuelve los tokens disponibles. En la sesión de un usuario normal, la lista siempre contendrá el token del usuario con id "user". Si hay disponible un token TPM para todo el sistema, la lista que se muestra también contendrá el token para todo el sistema con id "system". El token del sistema será el mismo para todas las sesiones en este dispositivo (dispositivo en el sentido de, p. ej., una Chromebook).

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (tokens: Token[]) => void

    • tokens

      Token[]

      La lista de tokens disponibles.

Muestra

  • Promesa<Token[]>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

importCertificate()

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

Importa certificate al token determinado si la clave certificada ya está almacenada en este token. Si la solicitud de certificación se realiza correctamente, esta función debe utilizarse para almacenar el certificado obtenido y ponerlo a disposición del sistema operativo y del navegador con fines de autenticación.

Parámetros

  • tokenId

    string

    El ID de un token que muestra getTokens.

  • certificado

    ArrayBuffer

    La codificación DER de un certificado X.509.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Pendiente

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

removeCertificate()

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

Quita certificate del token determinado si está presente. Se debe usar para quitar los certificados obsoletos, de modo que no se tengan en cuenta durante la autenticación y no desordenen la elección del certificado. Se debe usar para liberar almacenamiento en el almacén de certificados.

Parámetros

  • tokenId

    string

    El ID de un token que muestra getTokens.

  • certificado

    ArrayBuffer

    La codificación DER de un certificado X.509.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Pendiente

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.