Opis
Ten interfejs API umożliwia ujawnianie certyfikatów platformie, która może ich używać do uwierzytelniania TLS.
Uprawnienia
certificateProvider
Dostępność
Pojęcia i zastosowanie
Typowe zastosowanie tego interfejsu API do udostępniania certyfikatów klienta w ChromeOS:
- Rozszerzenie rejestruje zdarzenia
onCertificatesUpdateRequested
ionSignatureRequested
. - Rozszerzenie wywołuje
setCertificates()
, aby podać początkową listę certyfikatów po zainicjowaniu. - Rozszerzenie monitoruje zmiany na liście dostępnych certyfikatów i wywołania
setCertificates()
, aby powiadamiać przeglądarkę o każdej takiej zmianie. - Podczas uzgadniania połączenia TLS przeglądarka otrzymuje żądanie certyfikatu klienta. W przypadku zdarzenia
onCertificatesUpdateRequested
przeglądarka prosi rozszerzenie o zgłoszenie wszystkich certyfikatów, które obecnie udostępnia. - Rozszerzenie przesyła raport z dostępnymi aktualnie certyfikatami za pomocą metody
setCertificates()
. - Przeglądarka dopasowuje wszystkie dostępne certyfikaty do żądania certyfikatu klienta otrzymanego od hosta zdalnego. Dopasowania są wyświetlane użytkownikowi w oknie wyboru.
- Użytkownik może wybrać certyfikat, a tym samym zatwierdzić uwierzytelnianie lub przerwać uwierzytelnianie.
- 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 przy użyciu certyfikatu dostarczonego przez to rozszerzenie, przeglądarka poprosi rozszerzenie o podpisanie danych, aby kontynuować uzgadnianie połączenia TLS. Prośba jest wysyłana jako zdarzenie
onSignatureRequested
. - To zdarzenie zawiera dane wejściowe, określa algorytm, którego należy użyć do wygenerowania podpisu, i odwołuje się do jednego z certyfikatów zgłoszonych przez to rozszerzenie. Rozszerzenie musi utworzyć podpis dla określonych danych za pomocą klucza prywatnego powiązanego z przywoływanym certyfikatem. Utworzenie podpisu może wymagać poprzedzania informacji DigestInfo i dopełnienia wyniku przed faktycznym podpisaniem.
- Rozszerzenie odsyła podpis do przeglądarki przy użyciu metody
reportSignature()
. Jeśli nie można obliczyć podpisu, metoda musi zostać wywołana bez podpisu. - Jeśli podpis został podany, przeglądarka kończy uzgadnianie połączenia 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 dotycząca automatycznego wyboru certyfikatu (zobacz AutoSelectCertificateForUrls
i Zasady Chrome dotyczące użytkowników).
W rozszerzeniu może to wyglądać podobnie do tego:
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 v1.5 z szyfrowaniem MD5-SHA-1. Rozszerzenie nie może poprzedzać prefiksu DigestInfo, a jedynie dopełnienie PKCS#1. Ten algorytm został wycofany i od wersji 109 Chrome nigdy nie będzie go żądał.
"RSASSA_PKCS1_v1_5_SHA1"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją skrótu SHA-1.
"RSASSA_PKCS1_v1_5_SHA256"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją haszującą 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ą haszującą SHA-512.
"RSASSA_PSS_SHA256"
Określa algorytm podpisu RSASSA PSS za pomocą funkcji szyfrowania SHA-256, funkcji generowania maski MGF1 i ciągu zaburzającego o takim samym rozmiarze jak hasz.
"RSASSA_PSS_SHA384"
Określa algorytm podpisu RSASSA PSS za pomocą funkcji haszującej SHA-384, funkcji generowania maski MGF1 i ciągu zaburzającego o takim samym rozmiarze jak hasz.
"RSASSA_PSS_SHA512"
Określa algorytm podpisu RSASSA PSS za pomocą funkcji szyfrowania SHA-512, funkcji generowania maski MGF1 i ciągu zaburzającego o takim samym rozmiarze jak hasz.
CertificateInfo
Właściwości
-
certyfikat
ArrayBuffer
Musi być kodowaniem DER certyfikatu X.509. Obecnie obsługiwane są tylko certyfikaty kluczy RSA.
-
supportedHashes
Hash[]
Należy ustawić wszystkie wartości hash obsługiwane przez ten certyfikat. To rozszerzenie będzie prosić tylko o podpisy skrótów obliczonych za pomocą jednego z tych algorytmów haszowania. Należy to zrobić zgodnie ze malejącymi preferencjami haszowania.
CertificatesUpdateRequest
Właściwości
-
certificatesRequestId
Liczba
Identyfikator żądania, który ma zostać przekazany do
setCertificates
.
ClientCertificateInfo
Właściwości
-
certificateChain
TablicaBuffer[]
Pierwszym elementem tablicy musi być 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łaszać rozszerzenie.
Wartość
Hash
Rola wycofana. Zastąpione przez Algorithm
.
Typ wyliczeniowy
"MD5_SHA1"
Określa algorytmy szyfrowania 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ą zostać przedstawione użytkownikowi za pomocą funkcji requestPin.
Typ wyliczeniowy
"INVALID_PIN"
Określa nieprawidłowy kod PIN.
"TRUE_PUK"
Określa nieprawidłowy kod PUK.
"MAX_ATTEMPTS_EXCEEDED"
Określa maksymalną liczbę prób.
"UNKNOWN_ERROR"
Wskazuje, że powyższe typy błędu nie mogą wystąpić.
PinRequestType
Typ kodu, którego żąda rozszerzenie za pomocą funkcji requestPin.
Typ wyliczeniowy
"PIN"
Określa, że wymagany kod jest kodem PIN.
"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
-
error
opcjonalny
Podczas generowania podpisu wystąpił błąd (jeśli wystąpił).
-
signRequestId
Liczba
Identyfikator żądania otrzymany za pomocą zdarzenia
onSignatureRequested
. -
podpis
Tablica SlateBuffer opcjonalna
Podpis, jeśli został wygenerowany.
RequestPinDetails
Właściwości
-
attemptsLeft
Liczba opcjonalnie
Liczba pozostałych prób. Dane są przekazywane, dzięki czemu każdy interfejs użytkownika może przedstawić te informacje użytkownikowi. Chrome nie powinien tego egzekwować. Zamiast tego po przekroczeniu liczby żądań przypięcia narzędzie stopPinRequest powinno być wywoływane przez rozszerzenie z parametrem errorType = MAX_ATTEMPTS_EXCEEDED.
-
errorType
PinRequestErrorType opcjonalny
Szablon błędu wyświetlany użytkownikowi. Ten parametr należy ustawić, aby powiadamiać użytkownika o przyczynie niepowodzenia, jeśli poprzednie żądanie zakończyło się niepowodzeniem.
-
requestType
PinRequestType opcjonalny
Typ żądanego kodu. Domyślna wartość to PIN.
-
signRequestId
Liczba
Identyfikator podany przez Chrome w SignRequest.
SetCertificatesDetails
Właściwości
-
certificatesRequestId
Liczba opcjonalnie
Wywołane w odpowiedzi na metodę
onCertificatesUpdateRequested
powinno zawierać odebraną wartośćcertificatesRequestId
. W przeciwnym razie zasada nie powinna być ustawiona. -
clientCertificates
Lista obecnie dostępnych certyfikatów klienta.
-
error
opcjonalny
Podczas wyodrębniania certyfikatów (jeśli wystąpiły) wystąpił błąd. Ten błąd zostanie w razie potrzeby wyświetlony użytkownikowi.
SignatureRequest
Właściwości
-
algorytm
Algorytm podpisu, który ma zostać użyty.
-
certyfikat
ArrayBuffer
Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisać identyfikator
input
przy użyciu powiązanego klucza prywatnego. -
dane wejściowe
ArrayBuffer
Dane do podpisania. Pamiętaj, że dane nie są zaszyfrowane.
-
signRequestId
Liczba
Identyfikator żądania, który ma zostać przekazany do
reportSignature
.
SignRequest
Właściwości
-
certyfikat
ArrayBuffer
Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisać identyfikator
digest
przy użyciu powiązanego klucza prywatnego. -
skrót
ArrayBuffer
Podsumowanie, które należy podpisać.
-
wyliczyć skrót
Odnosi się do algorytmu szyfrowania użytego do utworzenia funkcji
digest
. -
signRequestId
Liczba
Chrome 57 i nowsze wersjeUnikalny identyfikator rozszerzenia, który ma być używany do wywołania metody, która go wymaga, np. requestPin.
StopPinRequestDetails
Właściwości
-
errorType
PinRequestErrorType opcjonalny
Szablon błędu. Jeśli istnieje, jest wyświetlana użytkownikowi. Zawiera przyczynę zatrzymania procesu, jeśli był on spowodowany błędem, np. MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
Liczba
Identyfikator podany przez Chrome w SignRequest.
Metody
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Powinna być wywoływana jako odpowiedź na żądanie onSignatureRequested
.
Rozszerzenie musi w końcu wywoływać tę funkcję przy każdym zdarzeniu onSignatureRequested
. Implementacja interfejsu API po pewnym czasie przestanie czekać na to wywołanie i pokaże komunikat o błędzie przekroczenia limitu czasu.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Pyta użytkownika o podanie kodu PIN. Jednocześnie może być aktywne tylko 1 trwałe żądanie. Żądania wysłane w trakcie innego procesu są odrzucane. Jeśli trwa inny proces, należy spróbować ponownie później.
Parametry
-
szczegóły
Zawiera szczegółowe informacje o żądanym oknie.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(details?: PinResponseDetails) => void
-
szczegóły
Opcjonalny PinResponseDetails
-
Zwroty
-
Promise<PinResponseDetails | undefined>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Ustawia listę certyfikatów do użycia w przeglądarce.
Rozszerzenie powinno wywoływać tę funkcję po zainicjowaniu i przy każdej zmianie w zestawie aktualnie dostępnych certyfikatów. Rozszerzenie powinno też wywoływać tę funkcję w odpowiedzi na metodę onCertificatesUpdateRequested
przy każdym otrzymaniu tego zdarzenia.
Parametry
-
szczegóły
Certyfikaty do ustawienia. Nieprawidłowe certyfikaty będą ignorowane.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Zatrzymuje żądanie przypięcia wysyłane przez funkcję requestPin
.
Parametry
-
szczegóły
Zawiera szczegółowe informacje o przyczynie zatrzymania przepływu żądań.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Użyj w zamian onCertificatesUpdateRequested
.
To zdarzenie jest uruchamiane za każdym razem, gdy przeglądarka żąda bieżącej listy certyfikatów dostarczanych przez to rozszerzenie. Rozszerzenie musi wywołać metodę reportCallback
dokładnie raz z aktualną 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
TablicaBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
To zdarzenie jest wywoływane, gdy certyfikaty ustawione za pomocą setCertificates
są niewystarczające lub przeglądarka żąda aktualizacji informacji. Rozszerzenie musi wywołać metodę setCertificates
z aktualną listą certyfikatów i otrzymanym certificatesRequestId
.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: CertificatesUpdateRequest) => void
-
Poproś
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
To zdarzenie jest uruchamiane za każdym razem, gdy przeglądarka musi podpisać wiadomość przy użyciu certyfikatu dostarczonego przez to rozszerzenie przez setCertificates
.
Rozszerzenie musi podpisać dane wejściowe z request
za pomocą odpowiedniego algorytmu i klucza prywatnego, a następnie zwrócić je, wywołując reportSignature
z otrzymanym identyfikatorem signRequestId
.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: SignatureRequest) => void
-
Poproś
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Użyj w zamian onSignatureRequested
.
To zdarzenie jest uruchamiane 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
za pomocą odpowiedniego algorytmu i klucza prywatnego oraz zwrócić je, wywołując reportCallback
. Pole reportCallback
należy wywołać dokładnie raz.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(request: SignRequest, reportCallback: function) => void
-
Poproś
-
reportCallback
funkcja
Chrome 47 i nowsze wersjeParametr
reportCallback
wygląda tak:(signature?: ArrayBuffer) => void
-
podpis
Tablica SlateBuffer opcjonalna
-
-