browser.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 podrán usar para la autenticación de TLS, el acceso a la red o con otras extensiones a través de chrome.platformKeys.

Permisos

enterprise.platformKeys

Disponibilidad

Solo en 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 con id igual a "user". Usa este token posteriormente.

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

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

  • 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 compilación y el envío de la solicitud de certificación:

function getUserToken(callback) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

Tipos

Algorithm

Chrome 110 y versiones posteriores browser.* desde Chrome 148

Es el tipo de clave que se generará.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 y versiones posteriores browser.* desde Chrome 148

Propiedades

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Acceso verificado.

  • registerKey

    RegisterKeyOptions opcional

    Si está presente, registra la clave de desafío con el token del scope especificado. Luego, la clave se puede asociar con un certificado y usarse 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 verificar.

RegisterKeyOptions

Chrome 110 y versiones posteriores browser.* desde Chrome 148

Propiedades

  • algoritmo

    Algorithm

    Es el algoritmo que debe usar la clave registrada.

Scope

Chrome 110 y versiones posteriores browser.* desde Chrome 148

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 inequívoca este Token.

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 y versiones posteriores browser.* desde Chrome 148

    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 realizan en el software, por lo que las claves están menos protegidas que las claves guardadas en hardware.

    Solo se pueden generar claves no extraíbles. El único tipo de clave admitido es RSASSA-PKCS1-V1_5 con modulusLength de hasta 2048. Cada clave se puede usar para firmar datos como máximo una vez, a menos que la extensión se incluya en la lista de entidades permitidas a través de la política KeyPermissions, en cuyo caso la clave se puede usar de forma indefinida.

    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.

  • 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 no extraíbles. Los tipos de claves compatibles son RSASSA-PKCS1-V1_5 con modulusLength de hasta 2048 y ECDSA con namedCurve P-256. Cada clave se puede usar para firmar datos como máximo una vez, a menos que la extensión esté incluida en la lista de entidades permitidas de la política KeyPermissions, en cuyo caso la clave se puede usar de forma indefinida.

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

Chrome 110 y versiones posteriores browser.* desde Chrome 148 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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 web de Acceso verificado, que emite desafíos y verifica respuestas.

Una verificación exitosa por parte de la API web de Acceso verificado es un indicador sólido de que el dispositivo actual es un dispositivo ChromeOS legítimo, que el dominio especificado durante la verificación administra el dispositivo actual, que el dominio especificado durante la verificación administra el usuario que accedió actualmente y que 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 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 se vincula de forma estrecha al usuario que accedió actualmente.

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

Parámetros

Muestra

  • Promise<ArrayBuffer>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con la respuesta del desafío.

challengeMachineKey()

Chrome 50 y versiones posteriores browser.* desde Chrome 148 Obsoleto desde Chrome 110
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

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 web de Acceso verificado, que emite desafíos y verifica respuestas. Una verificación correcta por parte de la API web de Acceso verificado es un indicador sólido de todo lo siguiente: * El dispositivo actual es un dispositivo ChromeOS legítimo. * El dispositivo actual está administrado por el dominio especificado durante la verificación. * El usuario que accedió actualmente se administra con el dominio especificado durante la verificación. 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. Esta función está muy restringida y fallará si el dispositivo actual no está administrado, el usuario actual no está administrado o si esta operación no se habilitó de forma explícita para el emisor por la política de dispositivos empresariales. La clave de máquina empresarial no reside en el token de "system" y ninguna otra API puede acceder a ella.

Parámetros

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Acceso verificado.

  • registerKey

    booleano opcional

    Chrome 59 y versiones posteriores browser.* desde Chrome 148

    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.

Muestra

  • Promise<ArrayBuffer>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con la respuesta del desafío.

challengeUserKey()

Chrome 50 y versiones posteriores browser.* desde Chrome 148 Obsoleto desde Chrome 110
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

En su lugar, usa challengeKey.

Desafía 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 junto con la API web de Acceso verificado, que emite desafíos y verifica respuestas. Una verificación correcta por parte de la API web de Acceso verificado es un indicador sólido de todo lo siguiente: * El dispositivo actual es un dispositivo ChromeOS legítimo. * El dispositivo actual está administrado por el dominio especificado durante la verificación. * El usuario que accedió actualmente se administra con 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 que emite la verificación está estrechamente vinculada al hardware del dispositivo actual y al usuario que accedió en ese momento. Esta función está muy restringida y fallará si el dispositivo actual no está administrado, el usuario actual no está administrado o si esta operación no se habilitó de forma explícita para el emisor por la política de usuario empresarial. La clave de usuario empresarial no reside en el token de "user" y no se puede acceder a ella a través de ninguna otra API.

Parámetros

  • desafío

    ArrayBuffer

    Un desafío emitido por la API web de Acceso verificado.

  • registerKey

    booleano

    Si se establece, la clave de usuario empresarial actual se registra con el token de "user" y se 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.

Muestra

  • Promise<ArrayBuffer>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con la respuesta del desafío.

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

Devuelve la lista de todos los certificados de cliente disponibles del token determinado. Se puede usar para verificar la existencia y el vencimiento de los certificados de cliente que se pueden usar para una autenticación determinada.

Parámetros

  • tokenId

    string

    Es el ID de un token que devuelve getTokens.

Muestra

  • Promise<ArrayBuffer[]>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con la lista de los certificados disponibles.

getTokens()

browser.enterprise.platformKeys.getTokens(): Promise<Token[]>

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

Muestra

  • Promise<Token[]>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    getTokens lo invoca con la lista de tokens disponibles.

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

Importa certificate al token determinado si la clave certificada ya está almacenada en este token. Después de una solicitud de certificación exitosa, esta función se debe usar para almacenar el certificado obtenido y ponerlo a disposición del sistema operativo y el navegador para la autenticación.

Parámetros

  • tokenId

    string

    Es el ID de un token que devuelve getTokens.

  • certificado

    ArrayBuffer

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

Muestra

  • Promise<void>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando finaliza esta operación.

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

Quita certificate del token determinado si está presente. Se debe usar para quitar los certificados obsoletos, de modo que no se consideren durante la autenticación y no saturen la elección de certificados. Debe usarse para liberar espacio en el almacén de certificados.

Parámetros

  • tokenId

    string

    Es el ID de un token que devuelve getTokens.

  • certificado

    ArrayBuffer

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

Muestra

  • Promise<void>

    Chrome 131 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando finaliza esta operación.