chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

Описание

Используйте этот API, чтобы предоставить платформе доступ к сертификатам, которые можно использовать для аутентификации TLS.

Разрешения

certificateProvider

Доступность

Chrome 46 и более поздних версий Только ChromeOS

Использование

Обычно этот API используется для предоставления сертификатов клиента ChromeOS следующим образом:

  • Расширение регистрируется для событий onCertificatesUpdateRequested и onSignatureRequested.
  • Расширение вызывает setCertificates, чтобы предоставить исходный список сертификатов после инициализации.
  • Расширение отслеживает изменения в списке доступных сертификатов и вызывает setCertificates, чтобы уведомить браузер о каждом таком изменении.
  • Во время подтверждения TLS браузер получает запрос сертификата клиента. С помощью события onCertificatesUpdateRequested браузер запрашивает у расширения отчет обо всех сертификатах, которые оно предоставляет в данный момент.
  • Расширение сообщает о доступных сертификатах с помощью метода setCertificates.
  • Браузер сопоставляет все доступные сертификаты с запросом сертификата клиента от удаленного хоста. Совпадения показываются пользователю в диалоговом окне выбора.
  • Пользователь может выбрать сертификат и подтвердить или отменить аутентификацию.

Диалоговое окно выбора сертификата

  • Если пользователь отменит аутентификацию или ни один сертификат не будет соответствовать запросу, аутентификация клиента TLS будет прервана.
  • Если пользователь подтверждает аутентификацию с помощью сертификата, предоставленного расширением, браузер запрашивает у расширения подпись данных, чтобы продолжить подтверждение TLS. Запрос отправляется как событие onSignatureRequested.
  • Это событие содержит входные данные, объявляет, какой алгоритм должен использоваться для создания подписи, и ссылается на один из сертификатов, о которых сообщило расширение. Расширение должно создать подпись для указанных данных, используя закрытый ключ, связанный с сертификатом, на который указывает ссылка. Для создания подписи может потребоваться добавить DigestInfo и заполнить результат перед фактическим подписанием.
  • Расширение отправляет подпись обратно в браузер с помощью метода reportSignature. Если подпись не удалось рассчитать, метод должен быть вызван без подписи.
  • Если подпись предоставлена, браузер завершает подтверждение TLS.

Фактическая последовательность шагов может отличаться. Например, пользователю не будет предложено выбрать сертификат, если используется корпоративное правило для автоматического выбора сертификата (см. AutoSelectCertificateForUrls и Правила Chrome для пользователей).

В расширении это может выглядеть примерно так:

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 not 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);

Типы

Algorithm

Chrome 86 и более поздних версий.

Типы поддерживаемых алгоритмов криптографической подписи.

Перечисление

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Указывает на алгоритм подписи RSASSA PKCS#1 v1.5 с хешированием MD5-SHA-1. Расширение не должно добавлять префикс DigestInfo, а только заполнение PKCS#1. Этот алгоритм устарел и не будет запрашиваться в Chrome начиная с версии 109.

"RSASSA_PKCS1_v1_5_SHA1"
Указывает алгоритм подписи RSASSA PKCS#1 v1.5 с хеш-функцией SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Указывает алгоритм подписи RSASSA PKCS#1 v1.5 с хеш-функцией SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Указывает на алгоритм подписи RSASSA PKCS#1 v1.5 с хеш-функцией SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Указывает алгоритм подписи RSASSA PKCS#1 v1.5 с хеш-функцией SHA-512.

"RSASSA_PSS_SHA256"
Указывает алгоритм подписи RSASSA PSS с хеш-функцией SHA-256, функцией генерации маски MGF1 и солью того же размера, что и хеш.

"RSASSA_PSS_SHA384"
Указывает на алгоритм подписи RSASSA PSS с хеш-функцией SHA-384, функцией генерации маски MGF1 и солью того же размера, что и хеш.

"RSASSA_PSS_SHA512"
Указывает на алгоритм подписи RSASSA PSS с хеш-функцией SHA-512, функцией генерации маски MGF1 и солью того же размера, что и хеш.

CertificateInfo

Свойства

  • сертификат

    ArrayBuffer

    Должен быть в кодировке DER сертификата X.509. В настоящее время поддерживаются только сертификаты ключей RSA.

  • supportedHashes

    Hash[]

    Должно быть установлено для всех хешей, поддерживаемых для этого сертификата. Расширение будет запрашивать подписи только для дайджестов, рассчитанных с помощью одного из этих хеш-алгоритмов. в порядке убывания предпочтительности.

CertificatesUpdateRequest

Chrome 86 и более поздних версий.

Свойства

  • certificatesRequestId

    число

    Идентификатор запроса, который будет передан в setCertificates.

ClientCertificateInfo

Chrome 86 и более поздних версий.

Свойства

  • certificateChain

    ArrayBuffer[]

    Первым элементом массива должна быть кодировка DER сертификата клиента X.509.

    В нем должен быть только один сертификат.

  • supportedAlgorithms

    Algorithm[]

    Все алгоритмы, поддерживаемые для этого сертификата. Расширение будет запрашивать подписи только с использованием одного из этих алгоритмов.

Error

Chrome 86 и более поздних версий.

Типы ошибок, о которых может сообщать расширение.

Значение

"GENERAL_ERROR"

Hash

Устаревший метод. Заменено на Algorithm.

Перечисление

"MD5_SHA1"
Указывает на алгоритмы хеширования MD5 и SHA1.

"SHA1"
Указывает на алгоритм хеширования SHA1.

"SHA256"
Указывает на алгоритм хеширования SHA256.

"SHA384"
Указывает на алгоритм хеширования SHA384.

"SHA512"
Указывает на алгоритм хеширования SHA512.

PinRequestErrorType

Chrome 57 и более поздних версий;

Типы ошибок, которые могут быть показаны пользователю функцией requestPin.

Перечисление

INVALID_PIN
PIN-код недействителен.

INVALID_PUK
PUK-код недействителен.

"MAX_ATTEMPTS_EXCEEDED"
Превышено максимальное количество попыток.

"UNKNOWN_ERROR"
Ошибка не относится ни к одному из перечисленных выше типов.

PinRequestType

Chrome 57 и более поздних версий;

Тип кода, запрашиваемого расширением с помощью функции requestPin.

Перечисление

"PIN"
Указывает, что запрашиваемый код является PIN-кодом.

PUK
Указывает, что запрашиваемый код – это PUK-код.

PinResponseDetails

Chrome 57 и более поздних версий;

Свойства

  • userInput

    Строка (необязательно)

    Код, предоставленный пользователем. Если пользователь закрыл диалоговое окно или произошла другая ошибка, поле остается пустым.

ReportSignatureDetails

Chrome 86 и более поздних версий.

Свойства

  • ошибка

    "GENERAL_ERROR"
     необязательно

    Ошибка, возникшая при создании подписи (если есть).

  • signRequestId

    число

    Идентификатор запроса, полученный через событие onSignatureRequested.

  • подпись

    ArrayBuffer (необязательно)

    Подпись, если она была успешно сгенерирована.

RequestPinDetails

Chrome 57 и более поздних версий;

Свойства

  • attemptsLeft

    number (необязательно)

    Количество оставшихся попыток. Это необходимо, чтобы любой интерфейс мог показывать эту информацию пользователю. Chrome не должен применять это ограничение. Вместо этого расширение должно вызывать stopPinRequest с errorType = MAX_ATTEMPTS_EXCEEDED, когда количество запросов PIN-кода превышено.

  • errorType

    PinRequestErrorType необязательный

    Шаблон ошибки, который показывается пользователю. Это значение следует задавать, если предыдущий запрос не был выполнен, чтобы сообщить пользователю о причине ошибки.

  • requestType

    PinRequestType необязательный

    Тип запрошенного кода. По умолчанию используется PIN-код.

  • signRequestId

    число

    Идентификатор, присвоенный Chrome в SignRequest.

SetCertificatesDetails

Chrome 86 и более поздних версий.

Свойства

  • certificatesRequestId

    number (необязательно)

    При вызове в ответ на onCertificatesUpdateRequested должен содержать полученное значение certificatesRequestId. В противном случае значение не задается.

  • clientCertificates

    ClientCertificateInfo[]

    Список доступных сертификатов клиента.

  • ошибка

    "GENERAL_ERROR"
     необязательно

    Ошибка, возникшая при извлечении сертификатов (если есть). Это сообщение об ошибке будет показываться пользователю в соответствующих случаях.

SignatureRequest

Chrome 86 и более поздних версий.

Свойства

  • алгоритм

    Алгоритм

    Алгоритм подписи, который будет использоваться.

  • сертификат

    ArrayBuffer

    Кодировка DER сертификата X.509. Расширение должно подписать input с помощью связанного закрытого ключа.

  • ввод

    ArrayBuffer

    Данные, которые нужно подписать. Обратите внимание, что данные не хешируются.

  • signRequestId

    число

    Идентификатор запроса, который будет передан в reportSignature.

SignRequest

Свойства

  • сертификат

    ArrayBuffer

    Кодировка DER сертификата X.509. Расширение должно подписать digest с помощью связанного закрытого ключа.

  • дайджест

    ArrayBuffer

    Дайджест, который нужно подписать.

  • хешировать

    Хеширование

    Алгоритм хеширования, который использовался для создания digest.

  • signRequestId

    число

    Chrome 57 и более поздних версий;

    Уникальный идентификатор, который будет использоваться расширением, если ему потребуется вызвать метод, требующий такого идентификатора, например requestPin.

StopPinRequestDetails

Chrome 57 и более поздних версий;

Свойства

  • errorType

    PinRequestErrorType необязательный

    Шаблон ошибки. Если он указан, то показывается пользователю. Указывает причину остановки процесса, если она была вызвана ошибкой, например MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    число

    Идентификатор, присвоенный Chrome в SignRequest.

Методы

reportSignature()

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

Должен вызываться в ответ на onSignatureRequested.

Расширение должно в конечном итоге вызвать эту функцию для каждого события onSignatureRequested. Реализация API перестанет ожидать этого вызова через некоторое время и ответит ошибкой тайм-аута при вызове этой функции.

Параметры

  • подробные сведения

    ReportSignatureDetails

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 96 и более поздних версий;

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

requestPin()

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

Запрашивает PIN-код у пользователя. Одновременно может выполняться только один запрос. Запросы, отправленные во время выполнения другого процесса, отклоняются. Если в данный момент выполняется другой процесс, расширение должно повторить попытку позже.

Параметры

  • подробные сведения

    RequestPinDetails

    Содержит сведения о запрошенном диалоговом окне.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (details?: PinResponseDetails) => void

Возвраты

  • Promise<PinResponseDetails | undefined>

    Chrome 96 и более поздних версий;

    Возвращает объект Promise, который распознается, когда пользователь вводит PIN-код. Отклоняет запрос с ошибкой, если он не был выполнен успешно (например, пользователь отменил показ диалогового окна или показ был запрещен).

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setCertificates()

Promise Chrome 86+ 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): Promise<void>

Позволяет задать список сертификатов для использования в браузере.

Расширение должно вызывать эту функцию после инициализации и при каждом изменении в наборе доступных сертификатов. Расширение также должно вызывать эту функцию в ответ на onCertificatesUpdateRequested каждый раз, когда получает это событие.

Параметры

  • подробные сведения

    SetCertificatesDetails

    Сертификаты, которые нужно установить. Недействительные сертификаты будут игнорироваться.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 96 и более поздних версий;

    Возвращает объект Promise, который распознается после завершения.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

stopPinRequest()

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

Останавливает запрос PIN-кода, запущенный функцией requestPin.

Параметры

  • подробные сведения

    StopPinRequestDetails

    Содержит сведения о причине остановки потока запросов.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 96 и более поздних версий;

    Возвращает объект Promise, который распознается, когда запрос на закрытие диалогового окна PIN-кода выполнен.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onCertificatesRequested

Chrome 47 и более поздние версии &leq; MV2 Поддержка прекращена в Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Используйте вместо него onCertificatesUpdateRequested.

Это событие активируется каждый раз, когда браузер запрашивает текущий список сертификатов, предоставленных этим расширением. Расширение должно вызвать reportCallback ровно один раз с текущим списком сертификатов.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (reportCallback: function) => void

    • reportCallback

      function

      Параметр reportCallback выглядит следующим образом: 

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

      • сертификаты

        CertificateInfo[]

      • обратный вызов

        function

        Параметр callback выглядит следующим образом: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 и более поздних версий. 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Это событие активируется, если сертификатов, заданных с помощью setCertificates, недостаточно или браузер запрашивает обновленную информацию. Расширение должно вызвать setCertificates с обновленным списком сертификатов и полученным certificatesRequestId.

Параметры

onSignatureRequested

Chrome 86 и более поздних версий. 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Это событие активируется каждый раз, когда браузеру нужно подписать сообщение с помощью сертификата, предоставленного этим расширением через setCertificates.

Расширение должно подписать входные данные из request, используя подходящий алгоритм и закрытый ключ, и вернуть их, вызвав reportSignature с полученным signRequestId.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (request: SignatureRequest) => void

onSignDigestRequested

&leq; MV2 Устарело начиная с Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Используйте вместо него onSignatureRequested.

Это событие активируется каждый раз, когда браузеру нужно подписать сообщение с помощью сертификата, предоставленного этим расширением в ответ на событие onCertificatesRequested. Расширение должно подписать данные в request, используя подходящий алгоритм и закрытый ключ, и вернуть их, вызвав reportCallback. Метод reportCallback должен вызываться только один раз.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • запрос

      SignRequest

    • reportCallback

      function

      Chrome 47 и более поздних версий;

      Параметр reportCallback выглядит следующим образом: 

      (signature?: ArrayBuffer) => void

      • подпись

        ArrayBuffer (необязательно)