chrome.certificateProvider

Описание

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

Разрешения

certificateProvider

Доступность

Только ChromeOS 46+

Концепции и использование

Типичное использование этого 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

Хром 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

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

  • поддерживаемые хэши

    Хэш []

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

CertificatesUpdateRequest

Хром 86+

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

  • CertificatesRequestId

    число

    Идентификатор запроса для передачи в setCertificates .

ClientCertificateInfo

Хром 86+

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

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

    ArrayBuffer[]

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

    Должен быть представлен только один сертификат.

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

    Алгоритм []

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

Error

Хром 86+

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

Ценить

"GENERAL_ERROR"

Hash

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

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

"MD5_SHA1"
Определяет алгоритмы хеширования MD5 и SHA1.

"SHA1"
Задает алгоритм хеширования SHA1.

"ША256"
Определяет алгоритм хеширования SHA256.

"SHA384"
Задает алгоритм хеширования SHA384.

"SHA512"
Определяет алгоритм хеширования SHA512.

PinRequestErrorType

Хром 57+

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

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

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

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

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

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

PinRequestType

Хром 57+

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

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

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

"ПУК"
Указывает, что запрошенный код — это PUK.

PinResponseDetails

Хром 57+

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

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

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

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

ReportSignatureDetails

Хром 86+

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

  • ошибка

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

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

  • signRequestId

    число

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

  • подпись

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

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

RequestPinDetails

Хром 57+

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

  • попыткиЛевые

    номер необязательно

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

  • errorType

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

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

  • requestType

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

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

  • signRequestId

    число

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

SetCertificatesDetails

Хром 86+

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

  • CertificatesRequestId

    номер необязательно

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

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

    ClientCertificateInfo []

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

  • ошибка

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

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

SignatureRequest

Хром 86+

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

  • алгоритм

    Алгоритм

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

  • сертификат

    ArrayBuffer

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

  • вход

    ArrayBuffer

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

  • signRequestId

    число

    Идентификатор запроса для передачи в reportSignature .

SignRequest

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

  • сертификат

    ArrayBuffer

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

  • дайджест

    ArrayBuffer

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

  • хэш

    Хэш

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

  • signRequestId

    число

    Хром 57+

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

StopPinRequestDetails

Хром 57+

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

  • errorType

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

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

  • signRequestId

    число

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

Методы

reportSignature()

Хром 86+
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

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

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

Параметры

Возврат

  • Обещание<void>

    Хром 96+

requestPin()

Хром 57+
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

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

Параметры

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

    ЗапросPinDetails

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

Возврат

setCertificates()

Хром 86+
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

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

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

Параметры

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

    SetCertificatesDetails

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

Возврат

  • Обещание<void>

    Хром 96+

stopPinRequest()

Хром 57+
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

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

Параметры

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

    StopPinRequestDetails

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

Возврат

  • Обещание<void>

    Хром 96+

События

onCertificatesUpdateRequested

Хром 86+
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

Параметры

onSignatureRequested

Хром 86+
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

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

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

Параметры