Description
Utilisez cette API pour exposer des certificats à la plate-forme qui peut les utiliser pour les authentifications TLS.
Autorisations
certificateProvider
Garantie de disponibilité
Concepts et utilisation
En général, cette API est utilisée pour exposer des certificats clients à ChromeOS. Pour ce faire, procédez comme suit:
- L'extension s'enregistre pour les événements
onCertificatesUpdateRequested
etonSignatureRequested
. - 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 informer le navigateur de toute modification de ce type. - 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. - L'extension génère un rapport avec les certificats actuellement disponibles, à l'aide de la méthode
setCertificates()
. - Le navigateur établit une correspondance entre tous les certificats disponibles et la demande de certificat client envoyée par 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](https://developer.chrome.com/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=9&hl=fr)
- 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 afin de 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 données à l'aide de la clé privée associée au certificat référencé. La création de la signature peut nécessiter de faire précéder un DigestInfo d'un élément DigestInfo et d'ajouter une marge intérieure au 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.
L'ordre réel des étapes peut être différent. 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, 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
Types d'algorithmes de signature cryptographique compatibles.
Enum
"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 un préfixe DigestInfo, mais uniquement ajouter 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 PSS RSASSA avec la fonction de hachage SHA-256, la fonction de génération de masques MGF1 et le salage de la même taille que le hachage.
"RSASSA_PSS_SHA384"
Spécifie l'algorithme de signature PSS RSASSA avec la fonction de hachage SHA-384, la fonction de génération de masques MGF1 et le salage de la même taille que le hachage.
"RSASSA_PSS_SHA512"
Spécifie l'algorithme de signature PSS RSASSA avec la fonction de hachage SHA-512, la fonction de génération de masques 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 des condensés calculés avec l'un de ces algorithmes de hachage. Cette valeur doit être classée par ordre décroissant de préférence de hachage.
CertificatesUpdateRequest
Propriétés
-
certificatesRequestId
Nombre
Identifiant de requête à transmettre à
setCertificates
.
ClientCertificateInfo
Propriétés
-
certificateChain
ArrayBuffer[]
Le premier élément du tableau doit contenir l'encodage DER du certificat client X.509.
Un seul certificat doit être inclus.
-
supportedAlgorithms
Tous les algorithmes compatibles avec ce certificat. L'extension ne demandera des signatures qu'à l'aide de l'un de ces algorithmes.
Error
Types d'erreurs que l'extension peut signaler.
Valeur
"GENERAL_ERROR"
Hash
Obsolète. Remplacé par Algorithm
.
Enum
"MD5_SHA1"
Indique 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
Types d'erreurs qui peuvent être présentés à l'utilisateur via la fonction requestPin.
Enum
"INVALID_PIN"
Indique que le code n'est pas valide.
"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
Type de code demandé par l'extension avec la fonction requestPin.
Enum
"PIN"
Indique que le code demandé est un code.
"PUK"
Indique que le code demandé est une clé PUK.
PinResponseDetails
Propriétés
-
userInput
string facultatif
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
Propriétés
-
error
facultatif
Une erreur s'est produite lors de la génération de la signature, le cas échéant.
-
signRequestId
Nombre
Identifiant de la requête reçu via l'événement
onSignatureRequested
. -
signature
ArrayBuffer facultatif
La signature, si elle a été correctement générée.
RequestPinDetails
Propriétés
-
attemptsLeft
numéro facultatif
Nombre de tentatives restantes. Cela permet à n'importe quelle interface utilisateur de présenter ces informations à l'utilisateur. Chrome n'est pas censé appliquer cette règle. La méthode stopPinRequest doit être appelée par l'extension avec le type d'erreur MAX_ATTEMPTS_EXCEEDED lorsque le nombre de requêtes de code d'accès est dépassé.
-
errorType
PinRequestErrorType facultatif
Modèle d'erreur présenté à l'utilisateur. Il doit être défini en cas d'échec de la requête précédente, afin d'informer l'utilisateur du motif de l'échec.
-
requestType
PinRequestType facultatif
Type de code demandé. La valeur par défaut est "Code".
-
signRequestId
Nombre
ID fourni par Chrome dans SignRequest.
SetCertificatesDetails
Propriétés
-
certificatesRequestId
numéro facultatif
Lorsqu'elle est appelée en réponse à
onCertificatesUpdateRequested
, elle doit contenir la valeurcertificatesRequestId
reçue. Sinon, elle ne doit pas être définie. -
clientCertificates
Liste des certificats client actuellement disponibles.
-
error
facultatif
Erreur qui s'est produite lors de l'extraction des certificats, le cas échéant. Cette erreur sera présentée à l'utilisateur si nécessaire.
SignatureRequest
Propriétés
-
algorithm
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é à signer.
-
hash
Fait référence à l'algorithme de hachage utilisé pour créer
digest
. -
signRequestId
Nombre
Chrome 57 et versions ultérieuresIdentifiant unique que l'extension doit utiliser si elle doit appeler une méthode qui l'exige, par exemple requestPin.
StopPinRequestDetails
Propriétés
-
errorType
PinRequestErrorType facultatif
Modèle d'erreur S'il est présent, l'utilisateur peut le voir. Destiné à contenir le motif de l'arrêt du flux si celui-ci est causé par une erreur, par exemple MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
Nombre
ID fourni par Chrome dans SignRequest.
Méthodes
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Doit être appelé en réponse à onSignatureRequested
.
À terme, l'extension doit appeler cette fonction pour chaque événement onSignatureRequested
. L'implémentation de l'API cesse d'attendre cet appel au bout d'un certain temps et renvoie une erreur de délai avant expiration lorsque cette fonction est appelée.
Paramètres
-
détails
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Demande le code PIN à l'utilisateur. Une seule demande en cours à la fois est autorisée. Les requêtes émises lorsqu'un autre flux est en cours sont refusées. Il incombe à l'extension de réessayer plus tard si un autre flux est en cours.
Paramètres
-
détails
Contient les détails sur la boîte de dialogue demandée.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(details?: PinResponseDetails) => void
-
détails
PinResponseDetails facultatif
-
Renvoie
-
Promise<PinResponseDetails | undefined>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
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 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
Certificats à définir. Les certificats non valides seront ignorés.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Arrête la demande d'épinglage lancée par la fonction requestPin
.
Paramètres
-
détails
Contient les détails sur le motif de l'arrêt du flux de requêtes.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onCertificatesRequested
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 de certificats fournis par cette extension. L'extension doit appeler reportCallback
une seule fois avec la liste actuelle de certificats.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(reportCallback: function) => void
-
reportCallback
function
Le paramètre
reportCallback
se présente comme suit :(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
rappel
function
Le paramètre
callback
se présente comme suit :(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
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 à jour. L'extension doit appeler setCertificates
avec la liste à jour de certificats et le certificatesRequestId
reçu.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
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
function
Le paramètre
callback
se présente comme suit :(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
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
function
Le paramètre
callback
se présente comme suit :(request: SignRequest, reportCallback: function) => void
-
request
-
reportCallback
function
Chrome 47 ou version ultérieureLe paramètre
reportCallback
se présente comme suit :(signature?: ArrayBuffer) => void
-
signature
ArrayBuffer facultatif
-
-