chrome.certificateProvider

.

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ść

Chrome w wersji 46 lub nowszej, Tylko ChromeOS

Wykorzystanie

Typowe zastosowanie tego interfejsu API do udostępniania certyfikatów klienta w ChromeOS odbywa się w ten sposób:

  • Rozszerzenie rejestruje zdarzenia onCertificatesUpdateRequested i onSignatureRequested.
  • Rozszerzenie wywołuje po zainicjowaniu setCertificates, aby podać 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 zgłaszanie wszystkich aktualnie udostępnianych certyfikatów.
  • Rozszerzenie wysyła raporty z użyciem obecnie dostępnych certyfikatów 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

  • 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 (patrz 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

Chrome 86 i nowsze .

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

Chrome 86 i nowsze .

Właściwości

  • certificatesRequestId

    liczba

    Identyfikator żądania przekazywany do setCertificates.

ClientCertificateInfo

Chrome 86 i nowsze .

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

Chrome 86 i nowsze .

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

Chrome w wersji 57 lub nowszej .

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

Chrome w wersji 57 lub nowszej .

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

Chrome w wersji 57 lub nowszej .

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 .

Właściwości

  • błąd

    "GENERAL_ERROR"
     opcjonalny

    Podczas 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

Chrome w wersji 57 lub nowszej .

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

Chrome 86 i nowsze .

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

    ClientCertificateInfo[]

    Lista obecnie dostępnych certyfikatów klienta.

  • błąd

    "GENERAL_ERROR"
     opcjonalny

    Podczas wyodrębniania certyfikatów wystąpił błąd (jeśli takie istnieją). Ten błąd wyświetli się użytkownikowi w razie potrzeby.

SignatureRequest

Chrome 86 i nowsze .

Właściwości

  • algorytm

    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

    Hasz

    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

Chrome w wersji 57 lub nowszej .

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

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

requestPin()

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

Zwroty

  • Promise&lt;PinResponseDetails | niezdefiniowane>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

setCertificates()

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

  • 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 tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

stopPinRequest()

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

Zatrzymuje żądanie pinezki rozpoczęte przez funkcję requestPin.

Parametry

  • szczegóły

    StopPinRequestDetails

    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 tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onCertificatesRequested

Chrome w wersji 47 lub nowszej &amp;leq; MV2 Wycofane od Chrome 86
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

        CertificateInfo[]

      • wywołanie zwrotne

        funkcja

        Parametr callback wygląda tak: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

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

onSignatureRequested

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

onSignDigestRequested

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

      SignRequest

    • reportCallback

      funkcja

      Chrome w wersji 47 lub nowszej .

      Parametr reportCallback wygląda tak: 

      (signature?: ArrayBuffer) => void

      • podpis

        SlateBuffer opcjonalnie