browser.certificateProvider

Opis

Użyj tego interfejsu API, aby udostępnić certyfikaty platformie, która może ich używać do uwierzytelniania TLS.

Uprawnienia

certificateProvider

Dostępność

Chrome 46 lub nowsza browser.* od Chrome 148 Tylko ChromeOS

Pojęcia i użycie

Typowe użycie tego interfejsu API do udostępniania certyfikatów klienta w ChromeOS obejmuje te kroki:

  • Rozszerzenie rejestruje zdarzenia onCertificatesUpdateRequested i onSignatureRequested.
  • Rozszerzenie wywołuje setCertificates(), aby po inicjalizacji udostępnić początkową listę certyfikatów.
  • Rozszerzenie monitoruje zmiany na liście dostępnych certyfikatów i wywołuje funkcję 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 obecnie udostępnia.
  • Rozszerzenie zgłasza obecnie dostępne certyfikaty za pomocą metody setCertificates().
  • Przeglądarka dopasowuje wszystkie dostępne certyfikaty do żądania certyfikatu klienta z hosta zdalnego. Dopasowania są wyświetlane użytkownikowi w oknie wyboru.
  • Użytkownik może wybrać certyfikat i w ten sposób zatwierdzić lub przerwać uwierzytelnianie.
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 rozszerzenie o podpisanie danych, aby kontynuować uzgadnianie połączenia TLS. Żądanie jest wysyłane jako zdarzenie onSignatureRequested.
  • To zdarzenie zawiera dane wejściowe, deklaruje algorytm, który ma 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 podanych danych przy użyciu klucza prywatnego powiązanego z przywoływanym certyfikatem. Utworzenie podpisu może wymagać dodania DigestInfo i uzupełnienia wyniku przed podpisaniem.
  • Rozszerzenie odsyła podpis do przeglądarki za pomocą metody reportSignature(). Jeśli nie udało się obliczyć podpisu, metodę należy wywołać bez podpisu.
  • Jeśli podpis został podany, przeglądarka kończy uzgadnianie połączenia TLS.

Rzeczywista kolejność kroków może być inna. Użytkownik nie zostanie na przykład poproszony o wybranie certyfikatu, jeśli używana jest zasada przedsiębiorstwa dotycząca automatycznego wybierania certyfikatu (zobacz AutoSelectCertificateForUrls i Zasady Chrome dotyczące użytkowników).

W rozszerzeniu może to wyglądać podobnie do tego fragmentu kodu:

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() {
  browser.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.
  browser.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.
    browser.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  browser.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

browser.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
browser.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

Typy

Algorithm

Chrome 86 lub nowsza browser.* od Chrome 148

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 haszowaniem MD5-SHA-1. Rozszerzenie nie może dodawać prefiksu DigestInfo, a jedynie dopełnienie PKCS#1. Ten algorytm jest wycofany i od wersji 109 nie będzie już używany przez Chrome.

"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ą skrótu SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją skrótu SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją skrótu SHA-512.

"RSASSA_PSS_SHA256"
Określa algorytm podpisu RSASSA PSS z funkcją skrótu SHA-256, funkcją generowania maski MGF1 i solą o tym samym rozmiarze 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 tym samym rozmiarze co skrót.

"RSASSA_PSS_SHA512"
Określa algorytm podpisu RSASSA PSS z funkcją skrótu SHA-512, funkcją generowania maski MGF1 i solą o tym samym rozmiarze 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 hasze obsługiwane przez ten certyfikat. To rozszerzenie będzie proszone o podpisy skrótów obliczonych za pomocą jednego z tych algorytmów szyfrowania. Kolejność powinna być zgodna z malejącą preferencją haszowania.

CertificatesUpdateRequest

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

  • certificatesRequestId

    liczba

    Identyfikator żądania, który ma zostać przekazany do setCertificates.

ClientCertificateInfo

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

  • certificateChain

    ArrayBuffer[]

    Tablica musi zawierać kodowanie DER certyfikatu klienta X.509 jako pierwszy element.

    Musi zawierać dokładnie 1 certyfikat.

  • supportedAlgorithms

    Algorithm[]

    Wszystkie algorytmy obsługiwane w przypadku tego certyfikatu. Rozszerzenie będzie proszone o podpisy tylko przy użyciu jednego z tych algorytmów.

Error

Chrome 86 lub nowsza browser.* od Chrome 148

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

Wartość

"GENERAL_ERROR"

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 haszowania SHA384.

"SHA512"
Określa algorytm haszowania SHA512.

PinRequestErrorType

Chrome 57 lub nowsza browser.* od Chrome 148

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

Typ wyliczeniowy

"INVALID_PIN"
Wskazuje, że kod PIN jest nieprawidłowy.

"INVALID_PUK"
Wskazuje, że kod PUK jest nieprawidłowy.

"MAX_ATTEMPTS_EXCEEDED"
Wskazuje, że przekroczono maksymalną liczbę prób.

"UNKNOWN_ERROR"
Wskazuje, że błąd nie może być reprezentowany przez powyższe typy.

PinRequestType

Chrome 57 lub nowsza browser.* od Chrome 148

Typ kodu, o który prosi rozszerzenie za pomocą funkcji requestPin.

Typ wyliczeniowy

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

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

PinResponseDetails

Chrome 57 lub nowsza browser.* od Chrome 148

Właściwości

  • userInput

    ciąg znaków opcjonalny

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

ReportSignatureDetails

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

  • błąd

    "GENERAL_ERROR"
     opcjonalny

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

  • signRequestId

    liczba

    Identyfikator żądania, który został odebrany w ramach zdarzenia onSignatureRequested.

  • podpis

    ArrayBuffer opcjonalny

    Podpis, jeśli został wygenerowany.

RequestPinDetails

Chrome 57 lub nowsza browser.* od Chrome 148

Właściwości

  • attemptsLeft

    number optional

    Liczba pozostałych prób. Dzięki temu każdy interfejs może wyświetlać te informacje użytkownikowi. Chrome nie powinien tego wymuszać. Zamiast tego rozszerzenie powinno wywołać stopPinRequest z błędem errorType = MAX_ATTEMPTS_EXCEEDED, gdy liczba żądań kodu PIN zostanie przekroczona.

  • errorType

    PinRequestErrorType opcjonalne

    Szablon błędu wyświetlany użytkownikowi. Należy to ustawić, jeśli poprzednie żądanie nie powiodło się, aby powiadomić użytkownika o przyczynie niepowodzenia.

  • requestType

    PinRequestType opcjonalny

    Typ kodu, o który poproszono. Domyślna metoda to kod PIN.

  • signRequestId

    liczba

    Identyfikator podany przez Chrome w SignRequest.

SetCertificatesDetails

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

  • certificatesRequestId

    number optional

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

  • clientCertificates

    ClientCertificateInfo[]

    Lista obecnie dostępnych certyfikatów klienta.

  • błąd

    "GENERAL_ERROR"
     opcjonalny

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

SignatureRequest

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

  • algorytm

    Algorytm

    Algorytm podpisu, który ma być używany.

  • certyfikat

    ArrayBuffer

    Kodowanie DER certyfikatu X.509. Rozszerzenie musi podpisać input za pomocą powiązanego klucza prywatnego.

  • wprowadzanie danych

    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ć digest za pomocą powiązanego klucza prywatnego.

  • skrót

    ArrayBuffer

    Skrót, który musi zostać podpisany.

  • hash

    Hash

    Odnosi się do algorytmu haszującego, który został użyty do utworzenia digest.

  • signRequestId

    liczba

    Chrome 57 lub nowsza browser.* od Chrome 148

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

StopPinRequestDetails

Chrome 57 lub nowsza browser.* od Chrome 148

Właściwości

  • errorType

    PinRequestErrorType opcjonalne

    Szablon błędu. Jeśli jest obecny, jest wyświetlany użytkownikowi. Powinien zawierać przyczynę zatrzymania przepływu, jeśli było ono spowodowane błędem, np. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    liczba

    Identyfikator podany przez Chrome w SignRequest.

Metody

reportSignature()

Chrome 86 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

Powinno być wywoływane w odpowiedzi na onSignatureRequested.

Rozszerzenie musi ostatecznie wywołać tę funkcję dla każdego zdarzenia onSignatureRequested. Implementacja interfejsu API po pewnym czasie przestanie czekać na to wywołanie i po wywołaniu tej funkcji zwróci błąd przekroczenia limitu czasu.

Parametry

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

requestPin()

Chrome 57 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

Prosi użytkownika o kod PIN. Dozwolona jest tylko jedna prośba naraz. Żądania wysłane podczas trwania innego przepływu są odrzucane. Jeśli trwa inny proces, rozszerzenie powinno spróbować ponownie później.

Parametry

Zwroty

  • Promise<PinResponseDetails | undefined>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Zwraca obiekt Promise, który jest rozwiązywany, gdy użytkownik poda kod PIN. Zwraca błąd, jeśli żądanie okna nie powiedzie się (np. okno zostało anulowane przez użytkownika lub nie można go wyświetlić).

setCertificates()

Chrome 86 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

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 onCertificatesUpdateRequested za każdym razem, gdy otrzyma to zdarzenie.

Parametry

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Zwraca obietnicę, która jest spełniana po zakończeniu.

stopPinRequest()

Chrome 57 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

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

Parametry

  • szczegóły

    StopPinRequestDetails

    Zawiera szczegółowe informacje o przyczynie zatrzymania procesu żądania.

Zwroty

  • thought Promise<void>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Zwraca obietnicę, która jest spełniana po zakończeniu żądania zamknięcia okna PIN.

Wydarzenia

onCertificatesUpdateRequested

Chrome 86 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

To zdarzenie jest wywoływane, jeśli certyfikaty ustawione za pomocą setCertificates są niewystarczające lub przeglądarka żąda zaktualizowanych informacji. Rozszerzenie musi wywołać setCertificates ze zaktualizowaną listą certyfikatów i otrzymanym certificatesRequestId.

Parametry

onSignatureRequested

Chrome 86 lub nowsza browser.* od Chrome 148 
browser.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka musi podpisać wiadomość za pomocą certyfikatu dostarczonego przez to rozszerzenie za pomocą setCertificates.

Rozszerzenie musi podpisać dane wejściowe z request, używając odpowiedniego algorytmu i klucza prywatnego, i zwrócić je, wywołując reportSignature z otrzymanym signRequestId.

Parametry