chrome.certificateProvider

Описание

Используйте этот 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 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);

Типы

Algorithm

Chrome 86+

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

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

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

"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

    Хэш []

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

CertificatesUpdateRequest

Chrome 86+

Характеристики

  • certificatesRequestId

    число

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

ClientCertificateInfo

Chrome 86+

Характеристики

  • цепочка сертификатов

    ArrayBuffer[]

    В качестве первого элемента массива необходимо указать DER-кодировку клиентского сертификата X.509.

    В него должен входить ровно один сертификат.

  • поддерживаемые алгоритмы

    Алгоритм []

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

Error

Chrome 86+

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

Ценить

"ОБЩАЯ_ОШИБКА"

Hash

Устарело. Заменено на Algorithm .

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

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

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

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

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

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

PinRequestErrorType

Chrome 57+

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

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

"INVALID_PIN"
Указывает, что PIN-код недействителен.

"INVALID_PUK"
Указывает, что PUK-код недействителен.

"ПРЕВЫШЕНО МАКСИМАЛЬНОЕ КОЛИЧЕСТВО ПОПЫТОК"
Указывает на то, что превышено максимальное количество попыток.

"НЕИЗВЕСТНАЯ ОШИБКА"
Указывает, что ошибка не может быть представлена ​​указанными выше типами.

PinRequestType

Chrome 57+

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

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

"ПРИКОЛОТЬ"
Указывает, что запрашиваемый код является PIN-кодом.

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

PinResponseDetails

Chrome 57+

Характеристики

  • пользовательский ввод

    строка необязательный

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

ReportSignatureDetails

Chrome 86+

Характеристики

  • ошибка

    "ОБЩАЯ_ОШИБКА"
    необязательный

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

  • signRequestId

    число

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

  • подпись

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

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

RequestPinDetails

Chrome 57+

Характеристики

  • попыткиОсталось

    число необязательно

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

  • errorType

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

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

  • requestType

    PinRequestType ( необязательный параметр)

    Тип запрашиваемого кода. По умолчанию — PIN-код.

  • signRequestId

    число

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

SetCertificatesDetails

Chrome 86+

Характеристики

  • certificatesRequestId

    число необязательно

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

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

    Информация о клиентском сертификате []

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

  • ошибка

    "ОБЩАЯ_ОШИБКА"
    необязательный

    Ошибка, возникшая при извлечении сертификатов (если таковая имелась). Информация об этой ошибке будет отображена пользователю при необходимости.

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 перестанет ожидать этого вызова через некоторое время и ответит ошибкой тайм-аута, когда эта функция будет вызвана.

Параметры

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

requestPin()

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

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

Параметры

  • подробности

    RequestPinDetails

    Содержит подробную информацию о запрошенном диалоге.

  • перезвонить

    функция необязательна

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

    (details?: PinResponseDetails) => void

Возвраты

  • Promise< PinResponseDetails | undefined>

    Chrome 96+

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

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setCertificates()

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

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

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

Параметры

  • подробности

    SetCertificatesDetails

    Укажите сертификаты, которые необходимо установить. Недействительные сертификаты будут проигнорированы.

  • перезвонить

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает промис, который разрешается по завершении операции.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

stopPinRequest()

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

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

Параметры

  • подробности

    StopPinRequestDetails

    Содержит подробную информацию о причине остановки обработки запроса.

  • перезвонить

    функция необязательна

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

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onCertificatesRequested

Chrome 47+ ≤ MV2 Устарело с Chrome 86
 
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Вместо этого используйте onCertificatesUpdateRequested .

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

Параметры

  • перезвонить

    функция

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

    (reportCallback: function) => void

    • reportCallback

      функция

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

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

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

        CertificateInfo []

      • перезвонить

        функция

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

        (rejectedCertificates: ArrayBuffer[]) => void

        • отклоненные сертификаты

          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 .

Параметры

onSignDigestRequested

≤ MV2 Устарело с Chrome 86
 
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Вместо этого используйте onSignatureRequested .

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

Параметры

  • перезвонить

    функция

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

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

    • запрос

      SignRequest

    • reportCallback

      функция

      Chrome 47+

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

      (signature?: ArrayBuffer) => void

      • подпись

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