chrome.certificateProvider

Opis

Używaj tego interfejsu API, aby udostępniać certyfikaty platformie, która może używać tych certyfikatów do uwierzytelniania TLS.

Uprawnienia

certificateProvider

Dostępność

Chrome 46 lub nowszy Tylko w ChromeOS

Pojęcia i zastosowanie

Typowe użycie tego interfejsu API do udostępnienia certyfikatów klienta w ChromeOS:

  • Rozszerzenie rejestruje zdarzenia onCertificatesUpdateRequested i onSignatureRequested.
  • Po zainicjowaniu rozszerzenie wywołuje funkcję setCertificates(), aby przekazać początkową listę certyfikatów.
  • Rozszerzenie monitoruje zmiany w liście dostępnych certyfikatów i wywołuje setCertificates(), aby powiadomić 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 aktualnie udostępnia.
  • Rozszerzenie zwraca aktualnie dostępne certyfikaty, używając metody setCertificates().
  • Przeglądarka porównuje wszystkie dostępne certyfikaty z żądaniem certyfikatu klienta z hosta zdalnego. Dopasowania są prezentowane użytkownikowi w oknie wyboru.
  • Użytkownik może wybrać certyfikat i zatwierdzić uwierzytelnianie lub przerwać proces uwierzytelniania.
Okno wyboru certyfikatu
Okno wyboru certyfikatu.
  • Jeśli użytkownik przerwie uwierzytelnianie lub żaden certyfikat nie pasuje do żądania, uwierzytelnianie klienta TLS zostanie przerwane.
  • Jeśli użytkownik zatwierdzi uwierzytelnianie za pomocą certyfikatu dostarczonego przez to rozszerzenie, przeglądarka poprosi je o podpisanie danych, aby kontynuować uzgadnianie TLS. Prośba jest wysyłana jako zdarzenie onSignatureRequested.
  • To zdarzenie zawiera dane wejściowe, deklaruje, który algorytm ma być użyty do wygenerowania podpisu, i odwołuje się do jednego z certyfikatów zgłoszonych przez to rozszerzenie. Rozszerzenie musi utworzyć podpis dla podanych danych, używając klucza prywatnego powiązanego z odwołanym certyfikatem. Utworzenie podpisu może wymagać dodania informacji DigestInfo i uzupełnienia wyniku przed faktycznym podpisaniem.
  • Rozszerzenie wysyła podpis z powrotem do przeglądarki za pomocą metody reportSignature(). Jeśli nie można obliczyć podpisu, metoda musi być wywoływana bez podpisu.
  • Jeśli podpis został podany, przeglądarka kończy uzgadnianie połączenia TLS.

Rzeczywista kolejność czynności może być inna. Na przykład użytkownik nie zostanie poproszony o wybranie certyfikatu, jeśli używana jest zasada firmy dotycząca automatycznego wybierania certyfikatu (patrz AutoSelectCertificateForUrls i Zasady Chrome dotyczące użytkowników).

W rozszerzeniu może to wyglądać 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

Chrome 86 lub nowszy

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 mieć prefiksu DigestInfo, ale musi zawierać tylko wypełnienie PKCS#1. Ten algorytm jest wycofany i od wersji 109 w Chrome nigdy nie będzie używany.

"RSASSA_PKCS1_v1_5_SHA1"
Określa algorytm podpisywania RSASSA PKCS#1 w wersji 1.5 z funkcją haszującą 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 w wersji 1.5 z funkcją haszującą SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Określa algorytm podpisywania RSASSA PKCS#1 w wersji 1.5 z funkcją haszującą SHA-512.

"RSASSA_PSS_SHA256"
Określa algorytm podpisu RSASSA PSS z funkcją szyfrowania SHA-256, funkcją generowania maski MGF1 i soli o tej samej wielkości co skrót.

"RSASSA_PSS_SHA384"
Określa algorytm podpisu RSASSA PSS z funkcją skrótu SHA-384, funkcją generowania maski MGF1 i solą o tej samej wielkości co skrót.

"RSASSA_PSS_SHA512"
Określa algorytm podpisu RSASSA PSS z funkcją szyfrowania SHA-512, funkcją generowania maski MGF1 i ciągiem zaburzającym o tej samej wielkości co skrót.

CertificateInfo

Właściwości

  • certyfikat

    ArrayBuffer

    Musi to być kodowanie DER certyfikatu X.509. Obecnie obsługiwane są tylko certyfikaty kluczy RSA.

  • supportedHashes

    Hash[]

    Musi być ustawiony na wszystkie hashe obsługiwane przez ten certyfikat. To rozszerzenie będzie prosić tylko o podpisy skrótów obliczanych za pomocą jednego z tych algorytmów haszowania. Powinny być one uporządkowane według malejącej preferencji haszowania.

CertificatesUpdateRequest

Chrome 86 lub nowszy

Właściwości

  • certificatesRequestId

    liczba

    Identyfikator żądania przekazywany do setCertificates.

ClientCertificateInfo

Chrome 86 lub nowszy

Właściwości

  • certificateChain

    ArrayBuffer[]

    Pierwszym elementem tablicy musi być kodowanie DER certyfikatu klienta X.509.

    Musi on zawierać dokładnie 1 certyfikat.

  • supportedAlgorithms

    Algorytm[]

    Wszystkie algorytmy obsługiwane przez ten certyfikat. Rozszerzenie będzie prosić o podpis tylko za pomocą jednego z tych algorytmów.

Error

Chrome 86 lub nowszy

Typy błędów, które może zgłaszać rozszerzenie.

Wartość

"GENERAL_ERROR"

Hash

Rola wycofana. Zastąpiony przez Algorithm.

Typ wyliczeniowy

"MD5_SHA1"
Określa algorytmy MD5 i SHA1.

„SHA1”
Określa algorytm haszowania SHA1.

"SHA256"
Określa algorytm haszowania SHA256.

„SHA384”
Określa algorytm haszowania SHA384.

„SHA512”
Określa algorytm haszowania SHA512.

PinRequestErrorType

Chrome 57 lub nowszy

Typy błędów, które mogą być wyświetlane użytkownikowi za pomocą funkcji requestPin.

Typ wyliczeniowy

"INVALID_PIN"
Określa, że kod PIN jest nieprawidłowy.

"INVALID_PUK"
Określa, że kod PUK jest nieprawidłowy.

"MAX_ATTEMPTS_EXCEEDED"
Określa, że została przekroczona maksymalna liczba prób.

"UNKNOWN_ERROR"
Określa, że błąd nie może być reprezentowany przez żadne z wymienionych powyżej typów.

PinRequestType

Chrome 57 lub nowszy

Typ kodu żądanego przez rozszerzenie za pomocą funkcji requestPin.

Typ wyliczeniowy

"PIN"
Określa, że żądany kod to kod PIN.

„PUK”
Określa, że żądany kod to kod PUK.

PinResponseDetails

Chrome 57 lub nowszy

Właściwości

  • userInput

    ciąg znaków opcjonalny

    Kod podany przez użytkownika. Pusty, jeśli użytkownik zamknął okno lub wystąpił inny błąd.

ReportSignatureDetails

Chrome 86 lub nowszy

Właściwości

  • błąd

    "GENERAL_ERROR"
     opcjonalnie

    Błąd, który wystąpił podczas generowania podpisu (jeśli wystąpił).

  • signRequestId

    liczba

    Identyfikator żądania otrzymany za pomocą zdarzenia onSignatureRequested.

  • podpis

    ArrayBuffer opcjonalny

    podpis, jeśli został wygenerowany;

RequestPinDetails

Chrome 57 lub nowszy

Właściwości

  • attemptsLeft

    number opcjonalny

    Liczba prób, które można jeszcze wykonać. Jest to konieczne, aby interfejs użytkownika mógł wyświetlić te informacje. Chrome nie ma na celu egzekwowania tej zasady. Gdy liczba żądań przypięcia przekroczy dopuszczalną wartość, rozszerzenie powinno wywołać metodę stopPinRequest z argumentem errorType = MAX_ATTEMPTS_EXCEEDED.

  • errorType

    PinRequestErrorType opcjonalnie

    Szablon błędu wyświetlany użytkownikowi. Należy go ustawić, jeśli poprzednie żądanie zakończyło się niepowodzeniem, aby powiadomić użytkownika o przyczynie niepowodzenia.

  • requestType

    PinRequestType opcjonalny

    Typ kodu. Domyślnie jest to kod PIN.

  • signRequestId

    liczba

    Identyfikator podany przez Chrome w SignRequest.

SetCertificatesDetails

Chrome 86 lub nowszy

Właściwości

  • certificatesRequestId

    number opcjonalny

    Gdy jest wywoływany w odpowiedzi na onCertificatesUpdateRequested, powinien zawierać otrzymaną wartość certificatesRequestId. W przeciwnym razie nie należy go ustawiać.

  • clientCertificates

    ClientCertificateInfo[]

    Lista aktualnie dostępnych certyfikatów klienta.

  • błąd

    "GENERAL_ERROR"
     opcjonalnie

    Błąd, który wystąpił podczas wyodrębniania certyfikatów (jeśli wystąpił). W odpowiednich przypadkach błąd ten będzie wyświetlany użytkownikowi.

SignatureRequest

Chrome 86 lub nowszy

Właściwości

  • algorytm

    Algorytm

    Algorytm podpisu do użycia.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisywać input przy użyciu powiązanego klucza prywatnego.

  • dane wejściowe

    ArrayBuffer

    Data podpisania. Pamiętaj, że dane nie są zaszyfrowane.

  • signRequestId

    liczba

    Identyfikator żądania przekazywany do reportSignature.

SignRequest

Właściwości

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisywać digest przy użyciu powiązanego klucza prywatnego.

  • skrót

    ArrayBuffer

    Digest, który musi być podpisany.

  • wyliczyć skrót

    Hash

    Odnosi się do algorytmu haszowania użytego do utworzenia digest.

  • signRequestId

    liczba

    Chrome 57 lub nowszy

    Unikalny identyfikator, którego ma używać rozszerzenie, jeśli musi wywołać metodę, która go wymaga, np. requestPin.

StopPinRequestDetails

Chrome 57 lub nowszy

Właściwości

  • errorType

    PinRequestErrorType opcjonalnie

    Szablon błędu. Jeśli jest obecny, wyświetla się użytkownikowi. Zawiera powód zatrzymania przepływu, jeśli spowodował go błąd, np. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    liczba

    Identyfikator podany przez Chrome w SignRequest.

Metody

reportSignature()

Obietnice Chrome 86 i nowsze wersje 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Należy go wywołać w odpowiedzi na onSignatureRequested.

Rozszerzenie musi wywołać tę funkcję w przypadku każdego zdarzenia onSignatureRequested. Po pewnym czasie implementacja interfejsu API przestanie oczekiwać na to wywołanie i w odpowiedzi na nie wyświetli błąd przekroczenia limitu czasu.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 96+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

requestPin()

Obietnice Chrome 57 lub nowszy 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Wymaga podania przez użytkownika kodu PIN. Dozwolona jest tylko 1 trwająca prośba naraz. Prośby wysłane podczas wykonywania innego procesu są odrzucane. Jeśli trwa inny proces, rozszerzenie musi spróbować ponownie później.

Parametry

Zwroty

  • Promise<PinResponseDetails | undefined>

    Chrome 96+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

setCertificates()

Obietnice Chrome 86 i nowsze wersje 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Ustawia listę certyfikatów do użycia w przeglądarce.

Rozszerzenie powinno wywoływać tę funkcję po inicjalizacji i przy każdej zmianie w zestawie aktualnie dostępnych certyfikatów. Rozszerzenie powinno też wywoływać tę funkcję w odpowiedzi na zdarzenie onCertificatesUpdateRequested za każdym razem, gdy zostanie ono odebrane.

Parametry

  • Certyfikaty do ustawienia. Nieprawidłowe certyfikaty są ignorowane.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 96+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

stopPinRequest()

Obietnice Chrome 57 lub nowszy 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Zatrzymuje żądanie przypięcia rozpoczęte przez funkcję requestPin.

Parametry

  • szczegóły

    StopPinRequestDetails

    Zawiera szczegóły dotyczące powodu zatrzymania procesu przesyłania żądania.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 96+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onCertificatesRequested

Chrome 47 i nowsze &leq; MV2 Wycofane w Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Zamiast tego użyj kolumny onCertificatesUpdateRequested.

To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka żąda bieżącej listy certyfikatów dostarczonych 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 ma postać:

    (reportCallback: function) => void

    • reportCallback

      funkcja

      Parametr reportCallback ma postać:

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

      • certyfikaty

        CertificateInfo[]

      • wywołanie zwrotne

        funkcja

        Parametr callback ma postać:

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 lub nowszy 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

To zdarzenie jest wywoływane, gdy certyfikaty ustawione za pomocą setCertificates są niewystarczające lub przeglądarka prosi o zaktualizowanie informacji. Rozszerzenie musi wywołać setCertificates z aktualizowaną listą certyfikatów i otrzymanym certificatesRequestId.

Parametry

onSignatureRequested

Chrome 86 lub nowszy 
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 za pomocą 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 signRequestId.

Parametry

onSignDigestRequested

&leq; MV2 Wycofane w Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Zamiast tego użyj kolumny onSignatureRequested.

To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka musi podpisać wiadomość za pomocą certyfikatu dostarczonego przez to rozszerzenie w odpowiedzi na zdarzenie onCertificatesRequested. Rozszerzenie musi podpisać dane w request, używając odpowiedniego algorytmu i klucza prywatnego, a potem zwrócić je, wywołując funkcję reportCallback. Metoda reportCallback musi zostać wywołana dokładnie raz.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

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

    • żądanie

      SignRequest

    • reportCallback

      funkcja

      Chrome 47 lub nowszy

      Parametr reportCallback ma postać:

      (signature?: ArrayBuffer) => void

      • podpis

        ArrayBuffer opcjonalny