chrome.enterprise.platformKeys

Description

Utilisez l'API chrome.enterprise.platformKeys pour générer des clés et installer des certificats pour ces clés. Les certificats seront gérés par la plate-forme et pourront être utilisés pour l'authentification TLS, l'accès au réseau ou par toute autre extension via chrome.platformKeys.

Autorisations

enterprise.platformKeys

Garantie de disponibilité

ChromeOS uniquement Règle obligatoire

Concepts et utilisation

En général, cette API permet d'enregistrer un certificat client comme suit:

  • Obtenez tous les jetons disponibles en utilisant enterprise.platformKeys.getTokens().

  • Trouvez le jeton avec id égal à "user". Utilisez ce jeton ensuite.

  • Générez une paire de clés à l'aide de la méthode generateKey() Token (définie dans SubtleCrypto). Le handle est renvoyé à la clé.

  • Exportez la clé publique à l'aide de la méthode exportKey() Token (définie dans SubtleCrypto).

  • Créez la signature des données de la demande de certification à l'aide de la méthode du jeton sign() (définie dans SubtleCrypto).

  • Complétez la demande de certification et envoyez-la à l'autorité de certification.

  • Si un certificat est reçu, importez-le à l'aide de [enterprise.platformKeys.importCertificate()`[3]

Voici un exemple illustrant les principales interactions avec l'API, hormis la création et l'envoi de la demande de certification:

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

Types

Algorithm

Chrome 110 et versions ultérieures

Type de clé à générer.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 et versions ultérieures

Propriétés

  • challenge

    ArrayBuffer

    Question d'authentification émise par l'API Verified Access Web.

  • registerKey

    RegisterKeyOptions facultatif

    Si cette clé est présente, elle est enregistrée avec le jeton scope spécifié. La clé peut ensuite être associée à un certificat et utilisée comme n'importe quelle autre clé de signature. Les appels ultérieurs de cette fonction généreront une nouvelle clé d'entreprise dans le scope spécifié.

  • champ d'application

    Scope (Portée)

    La clé d'entreprise à contester.

RegisterKeyOptions

Chrome 110 et versions ultérieures

Propriétés

  • algorithm

    Algorithme

    Algorithme que la clé enregistrée doit utiliser.

Scope

Chrome 110 et versions ultérieures

Permet d'utiliser la clé utilisateur de l'entreprise ou la clé de machine de l'entreprise.

Enum

"MACHINE"

Token

Propriétés

  • id

    chaîne

    Identifie ce Token de manière unique.

    Les ID statiques correspondent à "user" et "system", faisant respectivement référence au jeton matériel propre à l'utilisateur de la plate-forme et au jeton matériel du système. Tout autre jeton (avec d'autres identifiants) peut être renvoyé par enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 et versions ultérieures

    Met en œuvre l'interface SubtleCrypto de WebCrypto. Les opérations de chiffrement, y compris la génération de clés, sont basées sur un logiciel. La protection des clés, et donc la mise en œuvre de la propriété non extensible, sont effectuées dans un logiciel. Les clés sont donc moins protégées que les clés intégrées au matériel.

    Seules les clés RSASSA-PKCS1-V1_5 non extensibles dont l'modulusLength est inférieur à 2 048 peuvent être générées. Chaque clé peut être utilisée une seule fois pour signer des données.

    Les clés générées sur un Token spécifique ne peuvent pas être utilisées avec d'autres jetons ni avec window.crypto.subtle. De même, les objets Key créés avec window.crypto.subtle ne peuvent pas être utilisés avec cette interface.

  • subtleCrypto

    SubtleCrypto

    Met en œuvre l'interface SubtleCrypto de WebCrypto. Les opérations de chiffrement, y compris la génération de clés, sont intégrées au matériel.

    Seules les clés RSASSA-PKCS1-V1_5 non extensibles avec modulusLength jusqu'à 2048 et les clés ECDSA avec namedCurve P-256 peuvent être générées. Chaque clé peut être utilisée une seule fois pour signer des données.

    Les clés générées sur un Token spécifique ne peuvent pas être utilisées avec d'autres jetons ni avec window.crypto.subtle. De même, les objets Key créés avec window.crypto.subtle ne peuvent pas être utilisés avec cette interface.

Méthodes

challengeKey()

Chrome 110 et versions ultérieures 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

Semblable à challengeMachineKey et challengeUserKey, mais permet de spécifier l'algorithme d'une clé enregistrée. Conteste une clé de machine d'entreprise intégrée au matériel et émet la réponse dans le cadre d'un protocole d'attestation à distance. Utile uniquement sur Chrome OS et en conjonction avec l'API Verified Access Web qui émet des questions d'authentification et vérifie les réponses.

La validation par l'API Verified Access Web constitue un indicateur clair de l'état actuel de l'appareil : il s'agit d'un appareil Chrome OS légitime. Par exemple, une règle peut spécifier que l'appareil ne doit pas être en mode développeur. Toute identité d'appareil émise par la validation est étroitement liée au matériel de l'appareil actuel. Si le champ d'application "user" est spécifié, l'identité est également liée de manière fortement liée à l'utilisateur actuellement connecté.

Cette fonction est très limitée et échouera si l'appareil actuel n'est pas géré, si l'utilisateur actuel n'est pas géré ou si cette opération n'a pas été explicitement activée pour l'appelant par les règles d'entreprise relatives aux appareils. La clé mise en cause ne se trouve pas dans le jeton "system" ni "user", et n'est accessible par aucune autre API.

Paramètres

  • Objet contenant les champs définis dans ChallengeKeyOptions.

  • rappel

    function

    Le paramètre callback se présente comme suit : 

    (response: ArrayBuffer)=>void

    • réponse

      ArrayBuffer

      La réponse à la question d'authentification.

challengeMachineKey()

Chrome 50 ou version ultérieure Obsolète depuis Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

Utilisez challengeKey à la place.

Conteste une clé de machine d'entreprise intégrée au matériel et émet la réponse dans le cadre d'un protocole d'attestation à distance. Utile uniquement sur Chrome OS et en conjonction avec l'API Verified Access Web qui émet des questions d'authentification et vérifie les réponses. Une validation réussie par l'API Verified Access Web constitue un signal fort de tous les éléments suivants: * L'appareil actuel est un appareil Chrome OS légitime. * L'appareil actuel est géré par le domaine spécifié lors de la validation. * L'utilisateur actuellement connecté est géré par le domaine spécifié lors de la validation. * L'état actuel de l'appareil est conforme aux règles relatives aux appareils de l'entreprise. Par exemple, une règle peut spécifier que l'appareil ne doit pas être en mode développeur. * Toute identité d'appareil émise par la validation est étroitement liée au matériel de l'appareil actuel. Cette fonction est très limitée et échouera si l'appareil actuel n'est pas géré, si l'utilisateur actuel n'est pas géré ou si cette opération n'a pas été explicitement activée pour l'appelant par les règles d'entreprise relatives aux appareils. La clé de machine d'entreprise ne se trouve pas dans le jeton "system" et n'est accessible par aucune autre API.

Paramètres

  • challenge

    ArrayBuffer

    Question d'authentification émise par l'API Verified Access Web.

  • registerKey

    Booléen facultatif

    Chrome 59 ou version ultérieure

    Si elle est définie, la clé de machine d'entreprise actuelle est enregistrée avec le jeton "system" et renonce au rôle de clé de machine d'entreprise. La clé peut ensuite être associée à un certificat et utilisée comme n'importe quelle autre clé de signature. Il s'agit d'une clé RSA 2 048 bits. Les appels ultérieurs de cette fonction généreront une nouvelle clé de machine d'entreprise.

  • rappel

    function

    Le paramètre callback se présente comme suit : 

    (response: ArrayBuffer)=>void

    • réponse

      ArrayBuffer

      La réponse à la question d'authentification.

challengeUserKey()

Chrome 50 ou version ultérieure Obsolète depuis Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

Utilisez challengeKey à la place.

Conteste une clé utilisateur d'entreprise intégrée au matériel et émet la réponse dans le cadre d'un protocole d'attestation à distance. Utile uniquement sur Chrome OS et en conjonction avec l'API Verified Access Web qui émet des questions d'authentification et vérifie les réponses. Une validation réussie par l'API Verified Access Web constitue un signal fort de tous les éléments suivants: * L'appareil actuel est un appareil Chrome OS légitime. * L'appareil actuel est géré par le domaine spécifié lors de la validation. * L'utilisateur actuellement connecté est géré par le domaine spécifié lors de la validation. * L'état actuel de l'appareil est conforme aux règles relatives aux utilisateurs de l'entreprise. Par exemple, une règle peut spécifier que l'appareil ne doit pas être en mode développeur. * La clé publique émise par la validation est étroitement liée au matériel de l'appareil actuel et à l'utilisateur actuellement connecté. Cette fonction est très limitée et échouera si l'appareil actuel n'est pas géré, si l'utilisateur actuel n'est pas géré ou si cette opération n'a pas été explicitement activée pour l'appelant par les règles relatives aux utilisateurs de l'entreprise. La clé utilisateur de l'entreprise ne se trouve pas dans le jeton "user" et n'est accessible par aucune autre API.

Paramètres

  • challenge

    ArrayBuffer

    Question d'authentification émise par l'API Verified Access Web.

  • registerKey

    boolean

    Si cette valeur est définie, la clé utilisateur de l'entreprise actuelle est enregistrée avec le jeton "user" et renonce au rôle de clé utilisateur de l'entreprise. La clé peut ensuite être associée à un certificat et utilisée comme n'importe quelle autre clé de signature. Il s'agit d'une clé RSA 2 048 bits. Les appels ultérieurs de cette fonction généreront une nouvelle clé utilisateur d'entreprise.

  • rappel

    function

    Le paramètre callback se présente comme suit : 

    (response: ArrayBuffer)=>void

    • réponse

      ArrayBuffer

      La réponse à la question d'authentification.

getCertificates()

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

Renvoie la liste de tous les certificats client disponibles à partir du jeton donné. Permet de vérifier l'existence et l'expiration de certificats clients utilisables pour une certaine authentification.

Paramètres

  • tokenId

    chaîne

    Identifiant d'un jeton renvoyé par getTokens.

  • rappel

    function

    Le paramètre callback se présente comme suit : 

    (certificates: ArrayBuffer[])=>void

    • certificates

      ArrayBuffer[]

      Liste des certificats, chacun avec encodage DER d'un certificat X.509.

getTokens()

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

Renvoie les jetons disponibles. Dans une session utilisateur standard, la liste contiendra toujours le jeton de l'utilisateur avec id "user". Si un jeton TPM à l'échelle du système est disponible, la liste renvoyée contient également le jeton à l'échelle du système avec id "system". Le jeton au niveau du système sera le même pour toutes les sessions sur cet appareil (appareil au sens de celui-ci, par exemple).

Paramètres

  • rappel

    function

    Le paramètre callback se présente comme suit : 

    (tokens: Token[])=>void

    • Jetons

      Jeton[]

      Liste des jetons disponibles.

importCertificate()

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

Importe certificate dans le jeton donné si la clé certifiée y est déjà stockée. Après une demande de certification réussie, cette fonction doit être utilisée pour stocker le certificat obtenu et le mettre à la disposition du système d'exploitation et du navigateur pour l'authentification.

Paramètres

  • tokenId

    chaîne

    Identifiant d'un jeton renvoyé par getTokens.

  • certificat

    ArrayBuffer

    Encodage DER d'un certificat X.509.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    ()=>void

removeCertificate()

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

Supprime certificate du jeton donné, le cas échéant. Ce paramètre doit être utilisé pour supprimer les certificats obsolètes afin qu'ils ne soient pas pris en compte lors de l'authentification et n'encombrent pas le choix des certificats. À utiliser pour libérer de l'espace de stockage dans le magasin de certificats.

Paramètres

  • tokenId

    chaîne

    Identifiant d'un jeton renvoyé par getTokens.

  • certificat

    ArrayBuffer

    Encodage DER d'un certificat X.509.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    ()=>void