chrome.certificateProvider

Opis

Ten interfejs API umożliwia ujawnianie certyfikatów platformie, która może ich używać do uwierzytelniania TLS.

Uprawnienia

certificateProvider

Dostępność

Chrome 46 i nowsze wersje tylko ChromeOS

Pojęcia i zastosowanie

Typowe zastosowanie tego interfejsu API do udostępniania certyfikatów klienta w ChromeOS:

  • Rozszerzenie rejestruje zdarzenia onCertificatesUpdateRequested i onSignatureRequested.
  • 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.
Okno wyboru certyfikatu
Okno wyboru certyfikatu.
  • 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

Chrome 86 i nowsze wersje

Typy obsługiwanych algorytmów podpisu kryptograficznego.

Enum

"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

Chrome 86 i nowsze wersje

Właściwości

  • certificatesRequestId

    Liczba

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

ClientCertificateInfo

Chrome 86 i nowsze wersje

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

Chrome 86 i nowsze wersje

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

Wartość

Hash

Rola wycofana. Zastąpione przez Algorithm.

Enum

"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

Chrome 57 i nowsze wersje

Typy błędów, które mogą zostać przedstawione użytkownikowi za pomocą funkcji requestPin.

Enum

"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

Chrome 57 i nowsze wersje

Typ kodu, którego żąda rozszerzenie za pomocą funkcji requestPin.

Enum

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

"PUK"
Określa wymagany kod PUK.

PinResponseDetails

Chrome 57 i nowsze wersje

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

Chrome 86 i nowsze wersje

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

Chrome 57 i nowsze wersje

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

Chrome 86 i nowsze wersje

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

    ClientCertificateInfo[]

    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

Chrome 86 i nowsze wersje

Właściwości

  • algorytm

    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

    Hash

    Odnosi się do algorytmu szyfrowania użytego do utworzenia funkcji digest.

  • signRequestId

    Liczba

    Chrome 57 i nowsze wersje

    Unikalny identyfikator rozszerzenia, który ma być używany do wywołania metody, która go wymaga, np. requestPin.

StopPinRequestDetails

Chrome 57 i nowsze wersje

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()

Obietnica Chrome w wersji 86 lub nowszej 
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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 96 i nowsze wersje

    Obietnice 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()

Obietnica Chrome w wersji 57 lub nowszej 
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

Akcje powrotne

  • Promise<PinResponseDetails|undefined>

    Chrome 96 i nowsze wersje

    Obietnice 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()

Obietnica Chrome w wersji 86 lub nowszej 
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

  • Certyfikaty do ustawienia. Nieprawidłowe certyfikaty będą ignorowane.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 96 i nowsze wersje

    Obietnice 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()

Obietnica Chrome w wersji 57 lub nowszej 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Zatrzymuje żądanie przypięcia wysyłane przez funkcję requestPin.

Parametry

  • szczegóły

    StopPinRequestDetails

    Zawiera szczegółowe informacje o przyczynie zatrzymania przepływu żądań.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 96 i nowsze wersje

    Obietnice 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 47 i nowsze &leq; MV2 Wycofane od Chrome 86
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

        CertificateInfo[]

      • wywołanie zwrotne

        funkcja

        Parametr callback wygląda tak: 

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          TablicaBuffer[]

onCertificatesUpdateRequested

Chrome 86 i nowsze wersje 
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

onSignatureRequested

Chrome 86 i nowsze wersje 
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

onSignDigestRequested

&leq; MV2 Wycofane od Chrome 86
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ś

      SignRequest

    • reportCallback

      funkcja

      Chrome 47 i nowsze wersje

      Parametr reportCallback wygląda tak: 

      (signature?: ArrayBuffer)=>void

      • podpis

        Tablica SlateBuffer opcjonalna