chrome.enterprise.platformKeys

Важно: этот API работает только на ChromeOS .

Описание

Используйте API chrome.enterprise.platformKeys для создания ключей и установки сертификатов для этих ключей. Сертификаты будут управляться платформой и могут использоваться для аутентификации TLS, доступа к сети или для других расширений через chrome.platformKeys.

Разрешения

enterprise.platformKeys

Доступность

Только ChromeOS Требуется политика

Примечание. Этот API предназначен только для расширений, предварительно установленных политикой .

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

Типичное использование этого API для регистрации сертификата клиента состоит из следующих шагов:

• Получите все доступные токены, используя Enterprise.platformKeys.getTokens .

• Найдите токен с id , равным "user" . Используйте этот токен впоследствии.

• Создайте пару ключей, используя generateKey Token (определенный в SubtleCrypto). Это вернет дескриптор ключа.

• Экспортируйте открытый ключ с помощью метода exportKey Token (определенного в SubtleCrypto).

• Создайте подпись данных запроса на сертификацию, используя метод sign Token (определенный в SubtleCrypto).

• Заполните запрос на сертификацию и отправьте его в центр сертификации.

• Если сертификат получен, импортируйте его с помощью Enterprise.platformKeys.importCertificate.

Вот пример, показывающий основное взаимодействие API, за исключением создания и отправки запроса на сертификацию:

function getUserToken(callback) {
  chrome.enterprise.platformKeys.getTokens(function(tokens) {
    for (var i = 0; i < tokens.length; i++) {
      if (tokens[i].id == "user") {
        callback(tokens[i]);
        return;
      }
    }
    callback(undefined);
  });
}

function generateAndSign(userToken) {
  var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
  var algorithm = {
    name: "RSASSA-PKCS1-v1_5",
    // RsaHashedKeyGenParams
    modulusLength: 2048,
    publicExponent:
        new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
    hash: {
      name: "SHA-256",
    }
  };
  var cachedKeyPair;
  userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
    .then(function(keyPair) {
            cachedKeyPair = keyPair;
            return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);
          },
          console.log.bind(console))
    .then(function(publicKeySpki) {
            // Build the Certification Request using the public key.
            return userToken.subtleCrypto.sign(
                {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
          },
          console.log.bind(console))
    .then(function(signature) {
              // Complete the Certification Request with |signature|.
              // Send out the request to the CA, calling back
              // onClientCertificateReceived.
          },
          console.log.bind(console));
}

function onClientCertificateReceived(userToken, certificate) {
  chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

Типы

Algorithm

Хром 110+

Тип генерируемого ключа.

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

"РСА"

"ЭКДСА"

ChallengeKeyOptions

Хром 110+

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

• испытание

  МассивБуфер

  Запрос, отправленный веб-API проверенного доступа.

• РегистрацияКлюч

  РегистрКейОпционс необязательно

  Если он присутствует, регистрирует вызываемый ключ с помощью токена указанной scope . Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Последующие вызовы этой функции будут генерировать новый корпоративный ключ в указанной scope .

• объем

  Объем

  Какой корпоративный ключ бросить вызов.

RegisterKeyOptions

Хром 110+

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

• алгоритм

  Алгоритм

  Какой алгоритм должен использовать зарегистрированный ключ.

Scope

Хром 110+

Использовать ли ключ корпоративного пользователя или ключ корпоративного компьютера.

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

"ПОЛЬЗОВАТЕЛЬ"

"МАШИНА"

Token

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

• идентификатор

  нить

  Уникально идентифицирует этот Token .

  Статические идентификаторы — это "user" и "system" , относящиеся к пользовательскому и общесистемному аппаратному токену платформы соответственно. Любые другие токены (с другими идентификаторами) могут быть возвращены enterprise.platformKeys.getTokens .

• программное обеспечениеBackedSubtleCrypto

  SubtleCrypto

  Хром 97+

  Реализует интерфейс SubtleCrypto WebCrypto. Криптографические операции, включая генерацию ключей, поддерживаются программным обеспечением. Защита ключей и, следовательно, реализация неизвлекаемого свойства осуществляется программно, поэтому ключи менее защищены, чем ключи с аппаратной поддержкой.

  Могут быть сгенерированы только неизвлекаемые ключи. Поддерживаемые типы ключей: RSASSA-PKCS1-V1_5 и RSA-OAEP с modulusLength до 2048. Каждый ключ RSASSA-PKCS1-V1_5 можно использовать для подписи данных не более одного раза, если только расширение не внесено в список разрешенных с помощью политики KeyPermissions , и в этом случае ключ можно использовать неограниченное время. Ключи RSA-OAEP могут использоваться расширениями, включенными в разрешенный список той же политики, для развертывания других ключей.

  Ключи, сгенерированные для определенного Token , нельзя использовать ни с какими другими токенами, а также с window.crypto.subtle . Аналогичным образом, объекты Key , созданные с помощью window.crypto.subtle не могут использоваться с этим интерфейсом.

• тонкийКрипто

  SubtleCrypto

  Реализует интерфейс SubtleCrypto WebCrypto. Криптографические операции, включая генерацию ключей, поддерживаются аппаратно.

  Могут быть сгенерированы только неизвлекаемые ключи. Поддерживаемые типы ключей: RSASSA-PKCS1-V1_5 и RSA-OAEP с modulusLength до 2048 и ECDSA с namedCurve P-256. Каждый ключ RSASSA-PKCS1-V1_5 и ECDSA можно использовать для подписи данных не более одного раза, если только расширение не внесено в список разрешенных с помощью политики KeyPermissions , и в этом случае ключ можно использовать бесконечно. Ключи RSA-OAEP могут использоваться расширениями, включенными в разрешенный список той же политики, для развертывания других ключей.

  Ключи, сгенерированные для определенного Token , нельзя использовать ни с какими другими токенами, а также с window.crypto.subtle . Аналогичным образом, объекты Key , созданные с помощью window.crypto.subtle не могут использоваться с этим интерфейсом.

Методы

challengeKey()

Обещание Chrome 110+

chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Аналогичен challengeMachineKey и challengeUserKey , но позволяет указать алгоритм зарегистрированного ключа. Вызывает аппаратный ключ Enterprise Machine Key и отправляет ответ как часть протокола удаленной аттестации. Полезно только в ChromeOS и в сочетании с веб-API проверенного доступа, который одновременно отправляет запросы и проверяет ответы.

Успешная проверка с помощью веб-API Verified Access является убедительным сигналом того, что текущее устройство является законным устройством ChromeOS, текущее устройство управляется доменом, указанным во время проверки, текущий пользователь, вошедший в систему, управляется доменом, указанным во время проверки. и текущее состояние устройства соответствует корпоративной политике устройств. Например, политика может указывать, что устройство не должно находиться в режиме разработчика. Любой идентификатор устройства, полученный при проверке, тесно связан с аппаратным обеспечением текущего устройства. Если указана область "user" , удостоверение также тесно привязано к текущему вошедшему в систему пользователю.

Эта функция строго ограничена и завершится сбоем, если текущее устройство не управляется, текущий пользователь не управляется или если эта операция не была явно включена для вызывающего объекта политикой устройств предприятия. Запрашиваемый ключ не находится в "system" или "user" токене и недоступен для любого другого API.

Параметры

• параметры

  Параметры ChallengeKey

  Объект, содержащий поля, определенные в ChallengeKeyOptions .

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

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

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

  (response: ArrayBuffer) => void

  • ответ

    МассивБуфер

    Ответ на вызов.

Возврат

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

  Хром 131+

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

challengeMachineKey()

Promise Chrome 50+ устарел с версии Chrome 110

chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

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

Вызывает аппаратный ключ Enterprise Machine Key и отправляет ответ как часть протокола удаленной аттестации. Полезно только в ChromeOS и в сочетании с веб-API проверенного доступа, который одновременно отправляет запросы и проверяет ответы. Успешная проверка с помощью веб-API Verified Access является убедительным сигналом всего следующего: * Текущее устройство является законным устройством ChromeOS. * Текущее устройство управляется доменом, указанным при проверке. * Текущий вошедший в систему пользователь управляется доменом, указанным при проверке. * Текущее состояние устройства соответствует корпоративной политике устройств. Например, политика может указывать, что устройство не должно находиться в режиме разработчика. * Любой идентификатор устройства, полученный при проверке, тесно связан с аппаратным обеспечением текущего устройства. Эта функция строго ограничена и завершится сбоем, если текущее устройство не управляется, текущий пользователь не управляется или если эта операция не была явно включена для вызывающего объекта политикой устройств предприятия. Ключ предприятия не находится в "system" токене и недоступен для любого другого API.

Параметры

• испытание

  МассивБуфер

  Запрос, отправленный веб-API проверенного доступа.

• РегистрацияКлюч

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

  Хром 59+

  Если этот параметр установлен, текущий ключ корпоративного компьютера регистрируется с помощью "system" токена и отказывается от роли ключа корпоративного компьютера. Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Этот ключ — 2048-битный RSA. Последующие вызовы этой функции будут генерировать новый ключ предприятия.

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

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

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

  (response: ArrayBuffer) => void

  • ответ

    МассивБуфер

    Ответ на вызов.

Возврат

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

  Хром 131+

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

challengeUserKey()

Promise Chrome 50+ устарел с версии Chrome 110

chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

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

Вызывает аппаратный ключ корпоративного пользователя и отправляет ответ как часть протокола удаленной аттестации. Полезно только в ChromeOS и в сочетании с веб-API проверенного доступа, который одновременно отправляет запросы и проверяет ответы. Успешная проверка с помощью веб-API Verified Access является убедительным сигналом всего следующего: * Текущее устройство является законным устройством ChromeOS. * Текущее устройство управляется доменом, указанным при проверке. * Текущий вошедший в систему пользователь управляется доменом, указанным при проверке. * Текущее состояние устройства соответствует политике корпоративных пользователей. Например, политика может указывать, что устройство не должно находиться в режиме разработчика. * Открытый ключ, полученный при проверке, тесно привязан к оборудованию текущего устройства и текущему вошедшему в систему пользователю. Эта функция строго ограничена и завершится сбоем, если текущее устройство не управляется, текущий пользователь не управляется или если эта операция не была явно включена для вызывающей стороны в соответствии с корпоративной пользовательской политикой. Ключ корпоративного пользователя не находится в токене "user" и недоступен для любого другого API.

Параметры

• испытание

  МассивБуфер

  Запрос, отправленный веб-API проверенного доступа.

• РегистрацияКлюч

  логическое значение

  Если этот параметр установлен, текущий ключ корпоративного пользователя регистрируется с токеном "user" и отказывается от роли корпоративного ключа пользователя. Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Этот ключ — 2048-битный RSA. Последующие вызовы этой функции будут генерировать новый ключ корпоративного пользователя.

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

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

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

  (response: ArrayBuffer) => void

  • ответ

    МассивБуфер

    Ответ на вызов.

Возврат

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

  Хром 131+

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

getCertificates()

Обещать

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

Параметры

• идентификатор токена

  нить

  Идентификатор токена, возвращаемый getTokens .

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

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

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

  (certificates: ArrayBuffer[]) => void

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

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

    Список сертификатов, каждый в кодировке DER сертификата X.509.

Возврат

• Обещание<ArrayBuffer[]>

  Хром 131+

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

getTokens()

Обещать

chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

Возвращает доступные токены. В сеансе обычного пользователя список всегда будет содержать токен пользователя с id "user" . Если доступен общесистемный токен TPM, возвращаемый список также будет содержать общесистемный токен с id "system" . Общесистемный токен будет одинаковым для всех сеансов на этом устройстве (например, устройстве Chromebook).

Параметры

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

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

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

  (tokens: Token[]) => void

  • жетоны

    Токен []

    Список доступных токенов.

Возврат

• Обещание< Токен []>

  Хром 131+

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

importCertificate()

Обещать

chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

Параметры

• идентификатор токена

  нить

  Идентификатор токена, возвращаемый getTokens .

• сертификат

  МассивБуфер

  Кодировка DER сертификата X.509.

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

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

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

  () => void

Возврат

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

  Хром 131+

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

removeCertificate()

Обещать

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

Удаляет certificate из данного токена, если он присутствует. Следует использовать для удаления устаревших сертификатов, чтобы они не учитывались при аутентификации и не загромождали выбор сертификата. Следует использовать для освобождения места в хранилище сертификатов.

Параметры

• идентификатор токена

  нить

  Идентификатор токена, возвращаемый getTokens .

• сертификат

  МассивБуфер

  Кодировка DER сертификата X.509.

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

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

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

  () => void

Возврат

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

  Хром 131+

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