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

Pojęcia i zastosowanie

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

  • Rozszerzenie rejestruje się w przypadku zdarzeń 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 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
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. 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 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 zobaczy prośby o wybranie certyfikatu, jeśli używana jest zasada przedsiębiorstwa dotycząca automatycznego wybierania certyfikatu (patrz 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() {
  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()

Chrome w wersji 86 lub nowszej 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): 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

requestPin()

Chrome w wersji 57 lub nowszej 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): 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

setCertificates()

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

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

stopPinRequest()

Chrome w wersji 57 lub nowszej 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): 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ń.

Zwroty

  • Promise<void>

    Chrome w wersji 96 lub nowszej

Wydarzenia

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