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

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

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

  • сертификат

    МассивБуфер

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

  • поддерживается Хэши

    Хэш []

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

CertificatesUpdateRequest

Хром 86+

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

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

    число

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

ClientCertificateInfo

Хром 86+

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

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

    МассивБуфер[]

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

    Он должен включать ровно один сертификат.

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

    Алгоритм []

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

Error

Хром 86+

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

Ценить

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

Hash

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

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

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

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

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

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

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

PinRequestErrorType

Хром 57+

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

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

"ИНВАЛИД_ПИН"
Указывает, что PIN-код недействителен.

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

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

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

PinRequestType

Хром 57+

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

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

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

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

PinResponseDetails

Хром 57+

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

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

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

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

ReportSignatureDetails

Хром 86+

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

  • ошибка

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

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

  • SignRequestId

    число

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

  • подпись

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

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

RequestPinDetails

Хром 57+

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

  • попыткислева

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

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

  • тип ошибки

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

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

  • тип запроса

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

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

  • SignRequestId

    число

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

SetCertificatesDetails

Хром 86+

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

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

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

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

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

    Клиентсертификатеинфо []

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

  • ошибка

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

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

SignatureRequest

Хром 86+

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

  • алгоритм

    Алгоритм

    Используемый алгоритм подписи.

  • сертификат

    МассивБуфер

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

  • вход

    МассивБуфер

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

  • SignRequestId

    число

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

SignRequest

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

  • сертификат

    МассивБуфер

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

  • переваривать

    МассивБуфер

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

  • хэш

    Хэш

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

  • SignRequestId

    число

    Хром 57+

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

StopPinRequestDetails

Хром 57+

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

  • тип ошибки

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

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

  • SignRequestId

    число

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

Методы

reportSignature()

Обещание Chrome 86+
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

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

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

Параметры

Возврат

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

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

requestPin()

Обещание Chrome 57+
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

Параметры

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

    ЗапросPinDetails

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

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

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

    Параметр callback выглядит так: 

    (details?: PinResponseDetails) => void

Возврат

  • Обещание< PinResponseDetails | не определено>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

setCertificates()

Обещание Chrome 86+
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

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

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

Параметры

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

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

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

    Параметр callback выглядит так: 

    () => void

Возврат

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

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

stopPinRequest()

Обещание Chrome 57+
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

Параметры

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

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

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

    Параметр callback выглядит так: 

    () => void

Возврат

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

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onCertificatesUpdateRequested

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

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

Параметры

onSignatureRequested

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

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

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

Параметры