chrome.certificateProvider

Description

Utilise cette API pour divulguer les certificats sur la plate-forme qui peut les utiliser pour les authentifications TLS.

Autorisations

certificateProvider

Disponibilité

Chrome 46 et versions ultérieures ChromeOS uniquement

Concepts et utilisation

L'utilisation typique de cette API pour exposer les certificats client à ChromeOS suit les étapes suivantes :

  • L'extension s'inscrit aux é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 en informer le navigateur.
  • 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'elle fournit actuellement.
  • L'extension renvoie les certificats actuellement disponibles à l'aide de la méthode setCertificates().
  • Le navigateur fait correspondre tous les certificats disponibles à 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 ou annuler l'authentification.
Boîte de dialogue de sélection du certificat
Boîte de dialogue de sélection du certificat.
  • Si l'utilisateur annule l'authentification ou si aucun certificat ne correspond à la demande, 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 sous la forme d'un événement onSignatureRequested.
  • Cet événement contient des données d'entrée, indique 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é. La création de la signature peut nécessiter l'ajout d'un DigestInfo et le remplissage du résultat avant la signature proprement dite.
  • 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 effectue le handshake TLS.

La séquence réelle des étapes peut être différente. Par exemple, l'utilisateur ne sera 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, cela peut ressembler à l'extrait suivant :

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 et versions ultérieures

Types d'algorithmes de signature cryptographique acceptés.

É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 un remplissage 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 de masque MGF1 et le sel de 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 de masque MGF1 et le sel de 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 de masque MGF1 et le sel de 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

    Hash[]

    Doit être défini sur tous les hachages compatibles avec ce certificat. Cette extension ne demandera que les signatures des résumés calculés avec l'un de ces algorithmes de hachage. Ils doivent être classés par ordre décroissant de préférence de hachage.

CertificatesUpdateRequest

Chrome 86 et versions ultérieures

Propriétés

  • certificatesRequestId

    Total

    Identifiant de la requête à transmettre à setCertificates.

ClientCertificateInfo

Chrome 86 et versions ultérieures

Propriétés

  • certificateChain

    ArrayBuffer[]

    Le premier élément du tableau doit contenir l'encodage DER du certificat client X.509.

    Il doit inclure exactement un certificat.

  • supportedAlgorithms

    Algorithme[]

    Tous les algorithmes sont acceptés pour ce certificat. L'extension ne sera invitée à fournir des signatures qu'à l'aide de l'un de ces algorithmes.

Error

Chrome 86 et versions ultérieures

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 57 et versions ultérieures

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

Énumération

"INVALID_PIN"
Indique que le code est incorrect.

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

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

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

PinRequestType

Chrome 57 et versions ultérieures

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

Énumération

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

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

PinResponseDetails

Chrome 57 et versions ultérieures

Propriétés

  • userInput

    chaîne facultative

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

ReportSignatureDetails

Chrome 86 et versions ultérieures

Propriétés

  • erreur

    "GENERAL_ERROR"
     facultatif

    Erreur survenue lors de la génération de la signature, le cas échéant.

  • signRequestId

    Total

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

  • signature

    ArrayBuffer facultatif

    Signature, si elle a été générée.

RequestPinDetails

Chrome 57 et versions ultérieures

Propriétés

  • attemptsLeft

    number facultatif

    Nombre de tentatives restantes. Ces informations sont fournies pour que n'importe quelle UI puisse les présenter à l'utilisateur. Chrome n'est pas censé appliquer cette règle. L'extension doit plutôt appeler stopPinRequest avec errorType = MAX_ATTEMPTS_EXCEEDED lorsque le nombre de demandes de code est dépassé.

  • errorType

    PinRequestErrorType facultatif

    Modèle d'erreur affiché pour l'utilisateur. Ce paramètre doit être défini si la requête précédente a échoué, afin d'informer l'utilisateur de la raison de l'échec.

  • requestType

    PinRequestType facultatif

    Type de code demandé. La valeur par défaut est "Code".

  • signRequestId

    Total

    ID fourni par Chrome dans SignRequest.

SetCertificatesDetails

Chrome 86 et versions ultérieures

Propriétés

  • certificatesRequestId

    number facultatif

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

  • clientCertificates

    ClientCertificateInfo[]

    Liste des certificats clients actuellement disponibles.

  • erreur

    "GENERAL_ERROR"
     facultatif

    Erreur survenue lors de l'extraction des certificats, le cas échéant. Cette erreur sera présentée à l'utilisateur le cas échéant.

SignatureRequest

Chrome 86 et versions ultérieures

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

    Total

    Identifiant de la 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é qui doit être signé.

  • hash

    Hachage

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

  • signRequestId

    Total

    Chrome 57 et versions ultérieures

    ID unique à utiliser par l'extension si elle doit appeler une méthode qui le requiert, par exemple requestPin.

StopPinRequestDetails

Chrome 57 et versions ultérieures

Propriétés

  • errorType

    PinRequestErrorType facultatif

    Modèle d'erreur. Si elle est présente, elle est affichée à l'utilisateur. Doit contenir la raison de l'arrêt du flux si celui-ci est dû à une erreur, par exemple MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    Total

    ID fourni par Chrome dans SignRequest.

Méthodes

reportSignature()

Chrome 86 et versions ultérieures 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

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

L'extension doit finir par appeler cette fonction pour chaque événement onSignatureRequested. L'implémentation de l'API cessera d'attendre cet appel après un certain temps et répondra avec une erreur de délai d'attente lorsque cette fonction sera appelée.

Paramètres

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

requestPin()

Chrome 57 et versions ultérieures 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

Demande le code à l'utilisateur. Vous ne pouvez avoir qu'une seule demande en cours à la fois. Les requêtes émises pendant qu'un autre flux est en cours sont rejetées. Il incombe à l'extension de réessayer ultérieurement si un autre flux est en cours.

Paramètres

  • Contient des informations sur la boîte de dialogue demandée.

Renvoie

setCertificates()

Chrome 86 et versions ultérieures 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

Définit une liste de certificats à utiliser dans le navigateur.

L'extension doit appeler cette fonction après l'initialisation et à chaque modification de l'ensemble des 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

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

stopPinRequest()

Chrome 57 et versions ultérieures 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

Arrête la demande de code PIN lancée par la fonction requestPin.

Paramètres

Renvoie

  • Promise<void>

    Chrome 96 et versions ultérieures

Événements

onCertificatesUpdateRequested

Chrome 86 et versions ultérieures 
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 mise à jour des certificats et le certificatesRequestId reçu.

Paramètres

onSignatureRequested

Chrome 86 et versions ultérieures 
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 le signRequestId reçu.

Paramètres