chrome.certificateProvider

Important: Cette API fonctionne uniquement sur ChromeOS.

Description

Utilisez cette API pour exposer des certificats à la plate-forme qui peut les utiliser pour les authentifications TLS.

Autorisations

certificateProvider

Disponibilité

Chrome (version 46 ou ultérieure) ChromeOS uniquement

Utilisation

Voici une utilisation type de cette API pour exposer des certificats client sur ChromeOS:

• L'extension s'enregistre pour les événements onCertificatesUpdateRequested et onSignatureRequested.
• L'extension appelle setCertificates pour fournir la liste initiale des certificats après l'initialisation.
• L'extension surveille les modifications apportées à la liste des certificats disponibles et appelle setCertificates pour avertir le navigateur de chaque modification.
• Lors d'un handshake TLS, le navigateur reçoit une demande de certificat client. Avec un événement onCertificatesUpdateRequested, le navigateur demande à l'extension de signaler tous les certificats qu'il fournit actuellement.
• L'extension renvoie les certificats actuellement disponibles à l'aide de la méthode setCertificates.
• Le navigateur met en correspondance tous les certificats disponibles avec la demande de certificat client de l'hôte distant. Les correspondances sont présentées à l'utilisateur dans une boîte de dialogue de sélection.
• L'utilisateur peut sélectionner un certificat et ainsi approuver l'authentification ou annuler l'authentification.

• Si l'utilisateur annule l'authentification ou si aucun certificat ne correspond à la requête, l'authentification du client TLS est annulée.
• Sinon, si l'utilisateur approuve l'authentification avec un certificat fourni par cette extension, le navigateur demande à l'extension de signer les données pour poursuivre le handshake TLS. La requête est envoyée en tant qu'événement onSignatureRequested.
• Cet événement contient des données d'entrée, déclare l'algorithme à utiliser pour générer la signature et fait référence à l'un des certificats signalés par cette extension. L'extension doit créer une signature pour les données fournies à l'aide de la clé privée associée au certificat référencé. Pour créer la signature, vous devrez peut-être ajouter un préfixe DigestInfo et ajouter une marge intérieure au résultat avant la signature effective.
• L'extension renvoie la signature au navigateur à l'aide de la méthode reportSignature. Si la signature n'a pas pu être calculée, la méthode doit être appelée sans signature.
• Si la signature a été fournie, le navigateur termine le handshake TLS.

La séquence réelle des étapes peut être différente. Par exemple, l'utilisateur n'est pas invité à sélectionner un certificat si la règle d'entreprise permettant de sélectionner automatiquement un certificat est utilisée (voir AutoSelectCertificateForUrls et Règles Chrome pour les utilisateurs).

Dans l'extension, l'extrait de code ci-dessous peut être semblable à celui-ci:

function collectAvailableCertificates() {
  // Return all certificates that this Extension can currently provide.
  // For example:
  return [{
    certificateChain: [new Uint8Array(...)],
    supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
  }];
}

// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
  chrome.certificateProvider.setCertificates({
    clientCertificates: collectAvailableCertificates()
  });
}

function handleCertificatesUpdateRequest(request) {
  // Report the currently available certificates as a response to the request
  // event. This is important for supporting the case when the Extension is
  // unable to detect the changes proactively.
  chrome.certificateProvider.setCertificates({
    certificatesRequestId: request.certificatesRequestId,
    clientCertificates: collectAvailableCertificates()
  });
}

// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}

// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}

function handleSignatureRequest(request) {
  // Look up the handle to the private key of |request.certificate|.
  const key = getPrivateKeyHandle(request.certificate);
  if (!key) {
    // Handle if the key isn't available.
    console.error('Key for requested certificate no available.');

    // Abort the request by reporting the error to the API.
    chrome.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  chrome.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

Types

Algorithm

Chrome 86 ou version ultérieure

Types d'algorithmes de signature cryptographique compatibles.

Énumération

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Spécifie l'algorithme de signature RSASSA PKCS#1 v1.5 avec le hachage MD5-SHA-1. L'extension ne doit pas ajouter de préfixe DigestInfo, mais uniquement une marge intérieure PKCS#1. Cet algorithme est obsolète et ne sera plus demandé par Chrome à partir de la version 109.

"RSASSA_PKCS1_v1_5_SHA1"
Spécifie l'algorithme de signature RSASSA PKCS#1 v1.5 avec la fonction de hachage SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Spécifie l'algorithme de signature RSASSA PKCS#1 v1.5 avec la fonction de hachage SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Spécifie l'algorithme de signature RSASSA PKCS#1 v1.5 avec la fonction de hachage SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Spécifie l'algorithme de signature RSASSA PKCS#1 v1.5 avec la fonction de hachage SHA-512.

"RSASSA_PSS_SHA256"
Spécifie l'algorithme de signature RSASSA PSS avec la fonction de hachage SHA-256, la fonction de génération du masque MGF1 et le salage de la même taille que le hachage.

"RSASSA_PSS_SHA384"
Spécifie l'algorithme de signature RSASSA PSS avec la fonction de hachage SHA-384, la fonction de génération du masque MGF1 et le salage de la même taille que le hachage.

"RSASSA_PSS_SHA512"
Spécifie l'algorithme de signature RSASSA PSS avec la fonction de hachage SHA-512, la fonction de génération du masque MGF1 et le salage de la même taille que le hachage.

CertificateInfo

Propriétés

• certificat

  ArrayBuffer

  Doit correspondre à l'encodage DER d'un certificat X.509. Actuellement, seuls les certificats de clés RSA sont acceptés.

• supportedHashes

  Hachage[]

  Doit être défini sur tous les hachages compatibles avec ce certificat. Cette extension ne sera demandée que pour les signatures de condensés calculés avec l'un de ces algorithmes de hachage. Ces valeurs devraient être classées par ordre décroissant de préférence de hachage.

CertificatesUpdateRequest

Chrome 86 ou version ultérieure

Propriétés

• certificatesRequestId

  Nombre

  Identifiant de requête à transmettre à setCertificates.

ClientCertificateInfo

Chrome 86 ou version ultérieure

Propriétés

• certificateChain

  ArrayBuffer[]

  Le tableau doit contenir le codage DER du certificat client X.509 en tant que premier élément.

  Celui-ci doit inclure exactement un certificat.

• supportedAlgorithms

  Algorithme[]

  Tous les algorithmes compatibles avec ce certificat. L'extension ne demandera des signatures qu'à l'aide de l'un de ces algorithmes.

Error

Chrome 86 ou version ultérieure

Types d'erreurs que l'extension peut signaler.

Valeur

"GENERAL_ERROR"

Hash

Obsolète. Remplacé par Algorithm.

Énumération

"MD5_SHA1"
Spécifie les algorithmes de hachage MD5 et SHA1.

"SHA1"
Spécifie l'algorithme de hachage SHA1.

"SHA256"
Spécifie l'algorithme de hachage SHA256.

"SHA384"
Spécifie l'algorithme de hachage SHA384.

"SHA512"
Spécifie l'algorithme de hachage SHA512.

PinRequestErrorType

Chrome (version 57 ou ultérieure)

Types d'erreurs qui peuvent être présentés à l'utilisateur via la fonction requestPin.

Énumération

"INVALID_PIN"
Spécifie que le code n'est pas valide.

"INVALID_PUK"
Spécifie que la clé PUK n'est pas valide.

"MAX_ATTEMPTS_EXCEEDED"
Indique que le nombre maximal de tentatives a été dépassé.

"UNKNOWN_ERROR"
Spécifie que l'erreur ne peut pas être représentée par les types ci-dessus.

PinRequestType

Chrome (version 57 ou ultérieure)

Type de code demandé par l'extension avec la fonction requestPin.

Énumération

"PIN"
Indique que le code demandé est un code.

"PUK"
Indique que le code demandé est une clé PUK.

PinResponseDetails

Chrome (version 57 ou ultérieure)

Propriétés

• userInput

  chaîne facultatif

  Code fourni par l'utilisateur. Ce champ est vide si l'utilisateur a fermé la boîte de dialogue ou si une autre erreur s'est produite.

ReportSignatureDetails

Chrome 86 ou version ultérieure

Propriétés

• erreur

  "GENERAL_ERROR"
   facultatif

  Une erreur s'est produite lors de la génération de la signature, le cas échéant.

• signRequestId

  Nombre

  Identifiant de requête reçu via l'événement onSignatureRequested.

• signature

  ArrayBuffer facultatif

  La signature, si elle a bien été générée.

RequestPinDetails

Chrome (version 57 ou ultérieure)

Propriétés

• attemptsLeft

  numéro facultatif

  Nombre de tentatives restantes. Ils sont fournis afin que n'importe quelle interface utilisateur puisse présenter ces informations à l'utilisateur. Chrome n'est pas censé appliquer cette règle. À la place, l'extension doit appeler stopPinRequest avec la valeur MAX_ATTEMPTS_EXCEEDED lorsque le nombre de demandes d'épinglage est dépassé.

• errorType

  PinRequestErrorType optional

  Modèle d'erreur présenté à l'utilisateur. Ce paramètre doit être défini si la requête précédente a échoué, afin d'en informer l'utilisateur.

• requestType

  PinRequestType facultatif

  Type de code demandé. Le code par défaut est le code.

• signRequestId

  Nombre

  ID fourni par Chrome dans SignRequest.

SetCertificatesDetails

Chrome 86 ou version ultérieure

Propriétés

• certificatesRequestId

  numéro facultatif

  Lorsqu'il est appelé en réponse à onCertificatesUpdateRequested, doit contenir la valeur certificatesRequestId reçue. Sinon, ne doit pas être défini.

• clientCertificates

  ClientCertificateInfo[]

  Liste des certificats client actuellement disponibles.

• erreur

  "GENERAL_ERROR"
   facultatif

  Une erreur s'est produite lors de l'extraction des certificats, le cas échéant. Cette erreur sera signalée à l'utilisateur le cas échéant.

SignatureRequest

Chrome 86 ou version ultérieure

Propriétés

• algorithm

  Algorithme

  Algorithme de signature à utiliser.

• certificat

  ArrayBuffer

  Encodage DER d'un certificat X.509. L'extension doit signer input à l'aide de la clé privée associée.

• entrée

  ArrayBuffer

  Données à signer. Notez que les données ne sont pas hachées.

• signRequestId

  Nombre

  Identifiant de requête à transmettre à reportSignature.

SignRequest

Propriétés

• certificat

  ArrayBuffer

  Encodage DER d'un certificat X.509. L'extension doit signer digest à l'aide de la clé privée associée.

• condensé

  ArrayBuffer

  Condensé devant être signé.

• hash

  Hachage

  Fait référence à l'algorithme de hachage utilisé pour créer digest.

• signRequestId

  Nombre

  Chrome (version 57 ou ultérieure)

  Identifiant unique que l'extension doit utiliser si elle doit appeler une méthode qui l'exige, par exemple requestPin.

StopPinRequestDetails

Chrome (version 57 ou ultérieure)

Propriétés

• errorType

  PinRequestErrorType optional

  Modèle d'erreur. S'il est présent, l'utilisateur peut le voir. Destiné à contenir la raison de l'arrêt du flux s'il a été causé par une erreur, par exemple MAX_ATTEMPTS_EXCEEDED

• signRequestId

  Nombre

  ID fourni par Chrome dans SignRequest.

Méthodes

reportSignature()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 86 ou version ultérieure

chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Doit être appelé en réponse à onSignatureRequested.

L'extension doit à terme appeler cette fonction pour chaque événement onSignatureRequested. l'implémentation de l'API cessera d'attendre cet appel au bout d'un certain temps et renverra une erreur de délai d'inactivité lorsque cette fonction sera appelée.

Paramètres

• détails

  ReportSignatureDetails

• rappel

  function facultatif

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

  () => void

Renvoie

• Promesse<void>

  Chrome 96 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

requestPin()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome (version 57 ou ultérieure)

chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Demande le code à l'utilisateur. Une seule demande en cours à la fois est autorisée. Les requêtes émises pendant qu'un autre flux est en cours sont refusées. Il appartient à l'extension de réessayer plus tard si un autre flux est en cours.

Paramètres

• détails

  RequestPinDetails

  Contient les détails de la boîte de dialogue demandée.

• rappel

  function facultatif

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

  (details?: PinResponseDetails) => void

  • détails

    PinResponseDetails facultatif

Renvoie

• Promise&lt;PinResponseDetails | indéfini>

  Chrome 96 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setCertificates()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 86 ou version ultérieure

chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Définit la liste des certificats à utiliser dans le navigateur.

L'extension doit appeler cette fonction après l'initialisation et à chaque modification de l'ensemble de certificats actuellement disponibles. L'extension doit également appeler cette fonction en réponse à onCertificatesUpdateRequested chaque fois que cet événement est reçu.

Paramètres

• détails

  SetCertificatesDetails

  Certificats à définir. Les certificats non valides seront ignorés.

• rappel

  function facultatif

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

  () => void

Renvoie

• Promesse<void>

  Chrome 96 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

stopPinRequest()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome (version 57 ou ultérieure)

chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Arrête la demande de code d'accès démarrée par la fonction requestPin.

Paramètres

• détails

  StopPinRequestDetails

  Contient les détails sur la raison de l'arrêt du flux de requête.

• rappel

  function facultatif

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

  () => void

Renvoie

• Promesse<void>

  Chrome 96 ou version ultérieure

  Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onCertificatesRequested

Chrome (version 47 ou ultérieure) &amp;leq; MV2 Obsolète depuis Chrome 86

chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Utilisez onCertificatesUpdateRequested à la place.

Cet événement se déclenche chaque fois que le navigateur demande la liste actuelle des certificats fournis par cette extension. L'extension doit appeler reportCallback une seule fois avec la liste actuelle des certificats.

Paramètres

• rappel

  fonction

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

  (reportCallback: function) => void

  • reportCallback

    fonction

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

    (certificates: CertificateInfo[], callback: function) => void

    • certificats

      CertificateInfo[]

    • rappel

      fonction

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

      (rejectedCertificates: ArrayBuffer[]) => void

      • rejectedCertificates

        ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 ou version ultérieure

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Cet événement se déclenche si les certificats définis via setCertificates sont insuffisants ou si le navigateur demande des informations mises à jour. L'extension doit appeler setCertificates avec la liste des certificats mise à jour et le certificatesRequestId reçu.

Paramètres

• rappel

  fonction

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

  (request: CertificatesUpdateRequest) => void

  • request

    CertificatesUpdateRequest

onSignatureRequested

Chrome 86 ou version ultérieure

chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Cet événement se déclenche chaque fois que le navigateur doit signer un message à l'aide d'un certificat fourni par cette extension via setCertificates.

L'extension doit signer les données d'entrée de request à l'aide de l'algorithme et de la clé privée appropriés, puis les renvoyer en appelant reportSignature avec la signRequestId reçue.

Paramètres

• rappel

  fonction

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

  (request: SignatureRequest) => void

  • request

    SignatureRequest

onSignDigestRequested

<ph type="x-smartling-placeholder"></ph> &amp;leq; MV2 Obsolète depuis Chrome 86

chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Utilisez onSignatureRequested à la place.

Cet événement se déclenche chaque fois que le navigateur doit signer un message à l'aide d'un certificat fourni par cette extension en réponse à un événement onCertificatesRequested. L'extension doit signer les données dans request à l'aide de l'algorithme et de la clé privée appropriés, puis les renvoyer en appelant reportCallback. reportCallback doit être appelé exactement une fois.

Paramètres

• rappel

  fonction

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

  (request: SignRequest, reportCallback: function) => void

  • request

    SignRequest

  • reportCallback

    fonction

    Chrome (version 47 ou ultérieure)

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

    (signature?: ArrayBuffer) => void

    • signature

      ArrayBuffer facultatif