Opis
Użyj tego interfejsu API, aby udostępniać certyfikaty platformie, która może ich używać do uwierzytelniania TLS.
Uprawnienia
certificateProvider
Dostępność
Pojęcia i wykorzystanie
Typowe zastosowanie tego interfejsu API do udostępniania certyfikatów klienta w ChromeOS odbywa się w ten sposób:
- Rozszerzenie rejestruje się w przypadku zdarzeń
onCertificatesUpdateRequested
ionSignatureRequested
. - Rozszerzenie wywołuje
setCertificates()
, aby po zainicjowaniu wyświetlić wstępną listę certyfikatów. - Rozszerzenie monitoruje zmiany na liście dostępnych certyfikatów i wywołuje metodę
setCertificates()
, aby powiadamiać przeglądarkę o każdej takiej zmianie. - Podczas uzgadniania połączenia TLS przeglądarka odbiera żądanie certyfikatu klienta. W przypadku zdarzenia
onCertificatesUpdateRequested
przeglądarka prosi rozszerzenie o raportowanie wszystkich certyfikatów, które obecnie dostarcza. - Rozszerzenie wysyła raporty z informacjami o dostępnych obecnie certyfikatach przy użyciu metody
setCertificates()
. - Przeglądarka dopasowuje wszystkie dostępne certyfikaty do żądania certyfikatu klienta otrzymanego od hosta zdalnego. Pasujące wyniki zostaną wyświetlone użytkownikowi w oknie wyboru.
- Użytkownik może wybrać certyfikat, aby zatwierdzić uwierzytelnianie lub przerwać uwierzytelnianie.
![Okno wyboru certyfikatu](https://developer.chrome.com/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=9&hl=pl)
- Jeśli użytkownik przerwie uwierzytelnianie lub żaden certyfikat nie pasuje do żądania, uwierzytelnianie klienta TLS zostanie przerwane.
- W przeciwnym razie, jeśli użytkownik zatwierdzi uwierzytelnianie za pomocą certyfikatu dostarczonego przez to rozszerzenie, przeglądarka poprosi rozszerzenie o podpisanie danych w celu kontynuowania uzgadniania połączenia TLS. Żądanie jest wysyłane jako zdarzenie
onSignatureRequested
. - To zdarzenie zawiera dane wejściowe, deklaruje, który algorytm musi zostać użyty do wygenerowania podpisu, i odwołuje się do jednego z certyfikatów zgłoszonych przez to rozszerzenie. Rozszerzenie musi utworzyć podpis dla danych danych przy użyciu klucza prywatnego powiązanego z podanym certyfikatem. Utworzenie podpisu może wymagać umieszczenia na początku elementu DigestInfo i dopełnienia wyniku przed samym podpisem.
- Rozszerzenie wysyła podpis do przeglądarki przy użyciu metody
reportSignature()
. Jeśli nie udało się obliczyć podpisu, należy wywołać metodę bez podpisu. - Jeśli podpis został podany, przeglądarka uzgadnia połączenie TLS.
Rzeczywista sekwencja kroków może być inna. Na przykład użytkownik nie zostanie poproszony o wybranie certyfikatu, jeśli używana jest zasada przedsiębiorstwa, która automatycznie wybiera certyfikat (zobacz AutoSelectCertificateForUrls
i Zasady Chrome dotyczące użytkowników).
W rozszerzeniu może to wyglądać mniej więcej tak:
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);
Typy
Algorithm
Typy obsługiwanych algorytmów podpisu kryptograficznego.
Typ wyliczeniowy
"RSASSA_PKCS1_v1_5_MD5_SHA1"
Określa algorytm podpisu RSASSA PKCS#1 w wersji 1.5 z szyfrowaniem MD5-SHA-1. Rozszerzenie nie może zaczynać się przedrostkiem DigestInfo, a jedynie dodać dopełnienie PKCS#1. Ten algorytm został wycofany i od wersji 109 Chrome nie będzie nigdy żądać.
"RSASSA_PKCS1_v1_5_SHA1"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją szyfrowania SHA-1.
"RSASSA_PKCS1_v1_5_SHA256"
Określa algorytm podpisu RSASSA PKCS#1 w wersji 1.5 z funkcją szyfrowania SHA-256.
"RSASSA_PKCS1_v1_5_SHA384"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją szyfrowania SHA-384.
"RSASSA_PKCS1_v1_5_SHA512"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją szyfrowania SHA-512.
"RSASSA_PSS_SHA256"
Określa algorytm podpisu RSASSA PSS z funkcją szyfrowania SHA-256, funkcją generowania maski MGF1 i ciągiem zaburzającym o tym samym rozmiarze co hasz.
"RSASSA_PSS_SHA384"
Określa algorytm podpisu RSASSA PSS z funkcją szyfrowania SHA-384, funkcją generowania maski MGF1 i ciągiem zaburzającym o tym samym rozmiarze co hasz.
"RSASSA_PSS_SHA512"
Określa algorytm podpisu RSASSA PSS z funkcją szyfrowania SHA-512, funkcją generowania maski MGF1 i ciągiem zaburzającym o tym samym rozmiarze co hasz.
CertificateInfo
Właściwości
-
certyfikat
SlateBuffer
Musi to być kodowanie DER certyfikatu X.509. Obecnie obsługiwane są tylko certyfikaty kluczy RSA.
-
supportedHashes
Hasz[]
Wartość musi być ustawiona na wszystkie hasze obsługiwane przez ten certyfikat. To rozszerzenie będzie prosić o podpisy podsumowań obliczonych za pomocą jednego z tych algorytmów haszujących. Powinny być one uporządkowane w kolejności malejącej preferencji haszowania.
CertificatesUpdateRequest
Właściwości
-
certificatesRequestId
liczba
Identyfikator żądania przekazywany do
setCertificates
.
ClientCertificateInfo
Właściwości
-
certificateChain
ArrayBuffer[]
Tablica musi zawierać jako pierwszy element kodowanie DER certyfikatu klienta X.509.
Musi zawierać dokładnie 1 certyfikat.
-
supportedAlgorithms
Algorytm[]
Wszystkie algorytmy obsługiwane przez ten certyfikat. Rozszerzenie będzie prosić o podpisy tylko przy użyciu jednego z tych algorytmów.
Error
Rodzaje błędów, które może zgłosić rozszerzenie.
Wartość
"GENERAL_ERROR"
Hash
Rola wycofana. Zastąpiona przez: Algorithm
.
Typ wyliczeniowy
"MD5_SHA1"
Określa algorytmy haszowania MD5 i SHA1.
"SHA1"
Określa algorytm szyfrowania SHA1.
"SHA256"
Określa algorytm szyfrowania SHA256.
"SHA384"
Określa algorytm szyfrowania SHA384.
"SHA512"
Określa algorytm szyfrowania SHA512.
PinRequestErrorType
Typy błędów, które mogą być przedstawione użytkownikowi za pomocą funkcji requestPin.
Typ wyliczeniowy
"INVALID_PIN"
Określa nieprawidłowy kod PIN.
"INVALID_PUK"
Określa nieprawidłowy kod PUK.
"MAX_ATTEMPTS_EXCEEDED"
Określa przekroczoną maksymalną liczbę prób.
"UNKNOWN_ERROR"
Określa, że błędu nie można przedstawić za pomocą powyższych typów.
PinRequestType
Typ kodu, którego żąda rozszerzenie z funkcją requestPin.
Typ wyliczeniowy
"PIN"
Określa kod PIN, którego dotyczy żądanie.
"PUK"
Określa wymagany kod PUK.
PinResponseDetails
Właściwości
-
userInput
ciąg znaków opcjonalny
Kod podany przez użytkownika. Pole jest puste, jeśli użytkownik zamknął okno lub wystąpił inny błąd.
ReportSignatureDetails
Właściwości
-
błąd
"GENERAL_ERROR"
opcjonalnyPodczas generowania podpisu wystąpił błąd (jeśli taki istnieje).
-
signRequestId
liczba
Identyfikator żądania, który został odebrany przez zdarzenie
onSignatureRequested
. -
podpis
SlateBuffer opcjonalnie
Podpis (jeśli został wygenerowany).
RequestPinDetails
Właściwości
-
attemptsLeft
liczba opcjonalnie
Liczba pozostałych prób. Dzięki temu każdy interfejs użytkownika może przedstawić te informacje użytkownikowi. Chrome nie powinno tego wymuszać. Zamiast tego po przekroczeniu liczby żądań kodu PIN polecenie stopPinRequest powinno być wywoływane przez rozszerzenie z parametrem errorType = MAX_ATTEMPTS_EXCEEDED.
-
errorType
PinRequestErrorType optional
Szablon błędu wyświetlony użytkownikowi. Ten parametr należy ustawić, jeśli poprzednie żądanie zakończyło się niepowodzeniem, aby powiadomić użytkownika o przyczynie niepowodzenia.
-
requestType
Opcjonalny PinRequestType
Typ żądanego kodu. Wartość domyślna to kod PIN.
-
signRequestId
liczba
Identyfikator podany przez Chrome w żądaniu logowania.
SetCertificatesDetails
Właściwości
-
certificatesRequestId
liczba opcjonalnie
Jeśli ta metoda jest wywoływana w odpowiedzi na metodę
onCertificatesUpdateRequested
, powinna zawierać otrzymaną wartośćcertificatesRequestId
. W przeciwnym razie wartość nie powinna być ustawiona. -
clientCertificates
Lista obecnie dostępnych certyfikatów klienta.
-
błąd
"GENERAL_ERROR"
opcjonalnyPodczas wyodrębniania certyfikatów wystąpił błąd (jeśli takie istnieją). Ten błąd wyświetli się użytkownikowi w razie potrzeby.
SignatureRequest
Właściwości
-
algorytm
Algorytm podpisu do użycia.
-
certyfikat
SlateBuffer
Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisywać plik
input
przy użyciu powiązanego klucza prywatnego. -
dane wejściowe
SlateBuffer
Dane do podpisania. Pamiętaj, że dane nie są zaszyfrowane.
-
signRequestId
liczba
Identyfikator żądania przekazywany do
reportSignature
.
SignRequest
Właściwości
-
certyfikat
SlateBuffer
Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisywać plik
digest
przy użyciu powiązanego klucza prywatnego. -
skrót
SlateBuffer
Skrót, który musi być podpisany.
-
wyliczyć skrót
Odnosi się do algorytmu haszowania użytego do utworzenia
digest
. -
signRequestId
liczba
Chrome w wersji 57 lub nowszej .Unikalny identyfikator, którego rozszerzenie ma używać w razie potrzeby wywołania metody, która go wymaga, np. requestPin.
StopPinRequestDetails
Właściwości
-
errorType
PinRequestErrorType optional
Szablon błędu. Jeśli jest podany, jest wyświetlany użytkownikowi. Ma zawierać przyczynę zatrzymania przepływu, jeśli nastąpiło to przez błąd, np. MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
liczba
Identyfikator podany przez Chrome w żądaniu logowania.
Metody
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Powinno być wywoływane w odpowiedzi na onSignatureRequested
.
Rozszerzenie musi ostatecznie wywoływać tę funkcję w przypadku każdego zdarzenia onSignatureRequested
. po pewnym czasie implementacja interfejsu API przestanie czekać na to wywołanie i po wywołaniu tej funkcji wyświetli komunikat o błędzie przekroczenia limitu czasu.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Chrome w wersji 96 lub nowszej, .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Pyta użytkownika o kod PIN. Dozwolone jest tylko jedno bieżące żądanie. Żądania wysłane w trakcie wykonywania innego procesu są odrzucane. Obowiązkiem rozszerzenia jest spróbować ponownie później, gdy trwa inny proces.
Parametry
-
szczegóły
Zawiera szczegóły żądanego okna.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(details?: PinResponseDetails) => void
-
szczegóły
Opcjonalny PinResponseDetails
-
Zwroty
-
Promise<PinResponseDetails | niezdefiniowane>
Chrome w wersji 96 lub nowszej, .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Ustawia listę certyfikatów, które mają być używane w przeglądarce.
Rozszerzenie powinno wywoływać tę funkcję po zainicjowaniu i przy każdej zmianie zestawu obecnie dostępnych certyfikatów. Powinno też wywoływać tę funkcję w odpowiedzi na onCertificatesUpdateRequested
za każdym razem, gdy nadejdzie to zdarzenie.
Parametry
-
szczegóły
Certyfikaty do ustawienia. Nieprawidłowe certyfikaty są ignorowane.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Chrome w wersji 96 lub nowszej, .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Zatrzymuje żądanie pinezki rozpoczęte przez funkcję requestPin
.
Parametry
-
szczegóły
Zawiera szczegółowe informacje o przyczynie zatrzymania przepływu żądania.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Chrome w wersji 96 lub nowszej, .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Zamiast niego użyj onCertificatesUpdateRequested
.
To zdarzenie jest uruchamiane za każdym razem, gdy przeglądarka wysyła żądanie udostępnienia bieżącej listy certyfikatów udostępnionych przez to rozszerzenie. Rozszerzenie musi wywołać funkcję reportCallback
dokładnie raz z bieżącą listą certyfikatów.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(reportCallback: function) => void
-
reportCallback
funkcja
Parametr
reportCallback
wygląda tak:(certificates: CertificateInfo[], callback: function) => void
-
certyfikaty
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
To zdarzenie jest uruchamiane, gdy certyfikaty ustawione za pomocą setCertificates
są niewystarczające lub gdy przeglądarka zażąda aktualizacji informacji. Rozszerzenie musi wywołać metodę setCertificates
ze zaktualizowaną listą certyfikatów i otrzymaną wartością certificatesRequestId
.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: CertificatesUpdateRequest) => void
-
żądanie
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka musi podpisać wiadomość przy użyciu certyfikatu dostarczonego przez to rozszerzenie w setCertificates
.
Rozszerzenie musi podpisać dane wejściowe z request
odpowiednim algorytmem i kluczem prywatnym oraz zwrócić je, wywołując metodę reportSignature
z otrzymanym algorytmem signRequestId
.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: SignatureRequest) => void
-
żądanie
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Zamiast niego użyj onSignatureRequested
.
To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka musi podpisać wiadomość przy użyciu certyfikatu dostarczonego przez to rozszerzenie w odpowiedzi na zdarzenie onCertificatesRequested
. Rozszerzenie musi podpisać dane w usłudze request
odpowiednim algorytmem i kluczem prywatnym oraz zwrócić je, wywołując metodę reportCallback
. Funkcja reportCallback
musi zostać wywołana dokładnie raz.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: SignRequest, reportCallback: function) => void
-
żądanie
-
reportCallback
funkcja
Chrome w wersji 47 lub nowszej .Parametr
reportCallback
wygląda tak:(signature?: ArrayBuffer) => void
-
podpis
SlateBuffer opcjonalnie
-
-