chrome.certificateProvider

Opis

Użyj tego interfejsu API, aby udostępnić platformie certyfikaty, które mogą być używane do uwierzytelniania TLS.

Uprawnienia

certificateProvider

Dostępność

Chrome 46 lub nowszy Tylko ChromeOS

Wykorzystanie

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

  • Rozszerzenie rejestruje zdarzenia onCertificatesUpdateRequested i onSignatureRequested.
  • Po zainicjowaniu rozszerzenie wywołuje funkcję setCertificates, aby podać 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 przesyła z powrotem informacje o obecnie dostępnych certyfikatach 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ć uwierzytelnianie lub je przerwać.

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 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 za pomocą klucza prywatnego powiązanego z odwołującym się do niego certyfikatem. Utworzenie podpisu może wymagać dodania przedrostka DigestInfo i wypełnienia wyniku przed podpisaniem.
  • Rozszerzenie odsyła podpis do przeglądarki za pomocą metody reportSignature. Jeśli nie można obliczyć podpisu, metodę należy wywołać 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 będzie proszony o wybranie certyfikatu, jeśli używana jest zasada przedsiębiorstwa dotycząca automatycznego wybierania certyfikatu (patrz AutoSelectCertificateForUrls i zasady Chrome dla 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() {
  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 w wersji 86 lub nowszej

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 funkcją mieszającą 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ż nigdy używany przez Chrome.

"RSASSA_PKCS1_v1_5_SHA1"
Określa algorytm podpisu RSASSA PKCS#1 v1.5 z funkcją haszowania 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ą haszowania SHA-384.

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

„RSASSA_PSS_SHA256”
Określa algorytm podpisu RSASSA PSS z funkcją skrótu SHA-256, funkcją generowania maski MGF1 i solą o rozmiarze takim samym jak skrót.

„RSASSA_PSS_SHA384”
Określa algorytm podpisu RSASSA PSS z funkcją skrótu SHA-384, funkcją generowania maski MGF1 i solą o rozmiarze takim samym jak skrót.

„RSASSA_PSS_SHA512”
Określa algorytm podpisu RSASSA PSS z funkcją haszowania SHA-512, funkcją generowania maski MGF1 i ciągiem zaburzającym 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ć ustawiona na wszystkie skróty obsługiwane w przypadku tego certyfikatu. To rozszerzenie będzie wymagać podpisów skrótów obliczonych za pomocą jednego z tych algorytmów haszujących. Powinny być one podane w kolejności malejącej preferencji haszowania.

CertificatesUpdateRequest

Chrome w wersji 86 lub nowszej

Właściwości

  • certificatesRequestId

    liczba

    Identyfikator żądania do przekazania do setCertificates.

ClientCertificateInfo

Chrome w wersji 86 lub nowszej

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

    Algorithm[]

    Wszystkie algorytmy obsługiwane w przypadku tego certyfikatu. Rozszerzenie będzie proszone o podpisywanie tylko za pomocą jednego z tych algorytmów.

Error

Chrome w wersji 86 lub nowszej

Rodzaje 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 haszowania 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 w wersji 57 lub nowszej

Rodzaje 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”
Oznacza, że kod PUK jest nieprawidłowy.

„MAX_ATTEMPTS_EXCEEDED”
Określa, że przekroczono maksymalną liczbę prób.

„UNKNOWN_ERROR”
Oznacza, że błędu nie można przedstawić za pomocą powyższych typów.

PinRequestType

Chrome w wersji 57 lub nowszej

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

Typ wyliczeniowy

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

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

PinResponseDetails

Chrome w wersji 57 lub nowszej

Właściwości

  • userInput

    string opcjonalny

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

ReportSignatureDetails

Chrome w wersji 86 lub nowszej

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, który został otrzymany za pomocą zdarzenia onSignatureRequested.

  • podpis

    ArrayBuffer opcjonalny

    Podpis, jeśli został wygenerowany.

RequestPinDetails

Chrome w wersji 57 lub nowszej

Właściwości

  • attemptsLeft

    number opcjonalny

    Liczba pozostałych prób. Jest to udostępniane, aby każdy interfejs mógł przedstawić te informacje użytkownikowi. Chrome nie powinien tego wymuszać. Zamiast tego rozszerzenie powinno wywołać stopPinRequest z wartością errorType = MAX_ATTEMPTS_EXCEEDED, gdy liczba żądań kodu PIN zostanie przekroczona.

  • errorType

    PinRequestErrorType opcjonalny

    Szablon błędu wyświetlany użytkownikowi. Należy ustawić tę wartość, jeśli poprzednia prośba nie powiodła się, aby powiadomić użytkownika o przyczynie niepowodzenia.

  • requestType

    PinRequestType opcjonalny

    Typ kodu, o który prosisz. Domyślnie jest to PIN.

  • signRequestId

    liczba

    Identyfikator nadany przez Chrome w SignRequest.

SetCertificatesDetails

Chrome w wersji 86 lub nowszej

Właściwości

  • certificatesRequestId

    number opcjonalny

    W przypadku wywołania w odpowiedzi na onCertificatesUpdateRequested powinien zawierać otrzymaną wartość certificatesRequestId. W przeciwnym razie powinna być nieustawiona.

  • clientCertificates

    ClientCertificateInfo[]

    Lista obecnie 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ł). Ten błąd będzie wyświetlany użytkownikowi w odpowiednich sytuacjach.

SignatureRequest

Chrome w wersji 86 lub nowszej

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.

  • dane wejściowe

    ArrayBuffer

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

  • signRequestId

    liczba

    Identyfikator żądania do przekazania 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

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

  • signRequestId

    liczba

    Chrome w wersji 57 lub nowszej

    Unikalny identyfikator, którego rozszerzenie może użyć, jeśli będzie musiało wywołać metodę, która go wymaga, np. requestPin.

StopPinRequestDetails

Chrome w wersji 57 lub nowszej

Właściwości

  • errorType

    PinRequestErrorType opcjonalny

    Szablon błędu. Jeśli jest obecny, jest wyświetlany użytkownikowi. Zawiera przyczynę zatrzymania przepływu, jeśli została spowodowana przez błąd, np. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    liczba

    Identyfikator nadany przez Chrome w SignRequest.

Metody

reportSignature()

Promise Chrome 86 i nowsze wersje 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
): Promise<void>

Powinna być wywoływana w odpowiedzi na onSignatureRequested.

Rozszerzenie musi ostatecznie wywołać tę funkcję dla każdego zdarzenia onSignatureRequested. Po pewnym czasie implementacja interfejsu API przestanie czekać na to wywołanie i gdy ta funkcja zostanie wywołana, odpowie błędem przekroczenia limitu czasu.

Parametry

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

requestPin()

Promise Chrome 57 lub nowszy 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
): Promise<PinResponseDetails | undefined>

Prosi użytkownika o podanie kodu PIN. Dozwolona jest tylko 1 trwająca prośba naraz. Żądania wysyłane podczas trwania innego procesu są odrzucane. Jeśli trwa inny proces, rozszerzenie musi spróbować ponownie później.

Parametry

Zwroty

  • Promise<PinResponseDetails | undefined>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

setCertificates()

Promise Chrome 86 i nowsze wersje 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): 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 obecnie dostępnych certyfikatów. Rozszerzenie powinno też wywoływać tę funkcję w odpowiedzi na onCertificatesUpdateRequested za każdym razem, gdy to zdarzenie zostanie odebrane.

Parametry

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

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

stopPinRequest()

Promise Chrome 57 lub nowszy 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
): Promise<void>

Zatrzymuje żądanie kodu PIN rozpoczęte przez funkcję requestPin.

Parametry

  • szczegóły

    StopPinRequestDetails

    Zawiera szczegóły dotyczące przyczyny przerwania przepływu żądań.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onCertificatesRequested

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

Zamiast niej używaj kolumny onCertificatesUpdateRequested.

To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka wysyła żądanie bieżącej listy certyfikatów dostarczanych przez to rozszerzenie. Rozszerzenie musi wywołać funkcję reportCallback dokładnie raz z bieżącą listą certyfikatów.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (reportCallback: function) => void

    • reportCallback

      funkcja

      Parametr reportCallback wygląda tak:

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

      • certyfikaty

        CertificateInfo[]

      • callback

        funkcja

        Parametr callback wygląda tak:

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome w wersji 86 lub nowszej 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

Parametry

onSignatureRequested

Chrome w wersji 86 lub nowszej 
chrome.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ą interfejsu setCertificates.

Rozszerzenie musi podpisać dane wejściowe z request za pomocą odpowiedniego algorytmu i klucza prywatnego oraz zwrócić je, wywołując funkcję reportSignature z otrzymanym parametrem signRequestId.

Parametry

onSignDigestRequested

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

Zamiast niej używaj 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 za pomocą odpowiedniego algorytmu i klucza prywatnego oraz zwrócić je, wywołując reportCallback. Metoda reportCallback musi zostać wywołana dokładnie raz.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • żądanie

      SignRequest

    • reportCallback

      funkcja

      Chrome 47 lub nowsza

      Parametr reportCallback wygląda tak:

      (signature?: ArrayBuffer) => void

      • podpis

        ArrayBuffer opcjonalny