chrome.enterprise.platformKeys

Descripción

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

Permisos

enterprise.platformKeys

Disponibilidad

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 con id igual a "user". Luego, usa este token.

  • Genera un par de claves con el método de token generateKey() (definido en SubtleCrypto). Esto devolverá el controlador a 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]

A continuación, te mostramos un ejemplo en el que se muestra la interacción principal de la API, excepto la compilació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 que se generará.

Enum

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 desafiada con el token de scope especificado. De este modo, se puede asociar la clave a un certificado y usarse como cualquier otra clave de firma. Las llamadas posteriores a esta función generarán una clave empresarial nueva en el scope especificado.

  • permiso

    Alcance

    A qué clave empresarial desafiar.

RegisterKeyOptions

Chrome 110 y versiones posteriores

Propiedades

  • algoritmo

    Algorithm

    El algoritmo que 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

Token

Propiedades

  • id

    cadena

    Identifica este Token de forma inequívoca.

    Los IDs estáticos son "user" y "system", que hacen referencia al token de hardware específico del usuario de la plataforma y al token de hardware para todo el sistema, respectivamente. enterprise.platformKeys.getTokens puede 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, se respaldan 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 claves guardadas en hardware.

    Solo se pueden generar claves RSASSA-PKCS1-V1_5 no extraíbles con modulusLength 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 con window.crypto.subtle. De la misma manera, 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, se respaldan en 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. De la misma manera, los objetos Key creados con window.crypto.subtle no se pueden usar con esta interfaz.

Métodos

challengeKey()

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

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 en conjunto con la API web de Verified Access, que genera desafíos y verifica respuestas.

La verificación correcta por parte de la API web de Verified Access Web es un indicador claro de que el dispositivo actual es un dispositivo con Chrome OS legítimo, que administra el dispositivo actual mediante el dominio especificado durante la verificación, que administra el usuario que accedió a su cuenta el dominio especificado durante la verificación y que 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 de dispositivo que emita la verificación estará estrechamente vinculada al hardware del dispositivo actual. Si se especifica el permiso "user", la identidad también se vincula estrechamente al usuario que accedió.

Esta función está altamente 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 no se puede acceder a ella mediante ninguna otra API.

Parámetros

  • Objeto que contiene los campos definidos en ChallengeKeyOptions

  • callback

    la función

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

    (response: ArrayBuffer)=>void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

challengeMachineKey()

Chrome 50 y versiones posteriores Obsoleta 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 en conjunto con la API web de Verified Access, que genera desafíos y verifica respuestas. Una verificación correcta por parte de la API web de Verified Access Web es un indicador claro de todo lo siguiente: * El dispositivo actual es un dispositivo legítimo del ChromeOS. * El dominio especificado durante la verificación administra el dispositivo actual. * El dominio especificado durante la verificación administra al usuario que accedió con su cuenta. * 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 que emita la verificación estará estrechamente vinculada al hardware del dispositivo actual. Esta función está altamente 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 de máquina empresarial no reside en el token "system" y no se puede acceder a ella mediante ninguna otra API.

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 configura, la clave de máquina empresarial actual se registra con el token "system" y renuncia al rol de clave de máquina empresarial. De este modo, se puede asociar la clave a 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

    la función

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

    (response: ArrayBuffer)=>void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

challengeUserKey()

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

En su lugar, usa challengeKey.

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

Parámetros

  • desafío

    ArrayBuffer

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

  • registerKey

    boolean

    Si se configura, la clave de usuario empresarial actual se registra con el token "user" y renuncia al rol de la clave de usuario empresarial. De este modo, se puede asociar la clave a 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 clave de usuario empresarial nueva.

  • callback

    la función

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

    (response: ArrayBuffer)=>void

    • respuesta

      ArrayBuffer

      La respuesta del desafío.

getCertificates()

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

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

Parámetros

  • tokenId

    cadena

    El ID de un token que muestra getTokens.

  • callback

    la función

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

    (certificates: ArrayBuffer[])=>void

    • certificates

      ArrayBuffer[]

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

getTokens()

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 a todo el sistema con id "system". El token de todo el sistema será el mismo para todas las sesiones en este dispositivo (p.ej., una Chromebook).

Parámetros

  • callback

    la función

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

    (tokens: Token[])=>void

    • tokens

      Token

      La lista de tokens disponibles.

importCertificate()

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 se aprueba la solicitud de certificación, esta función se debe usar para almacenar el certificado obtenido y ponerlo a disposición del sistema operativo y del navegador para su autenticación.

Parámetros

  • tokenId

    cadena

    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

removeCertificate()

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

Quita certificate del token dado, si está presente. Debe usarse para quitar certificados obsoletos para que no se consideren durante la autenticación y no desordenen la elección de certificados. Debe usarse para liberar almacenamiento en el almacén de certificados.

Parámetros

  • tokenId

    cadena

    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