chrome.enterprise.platformKeys

Описание

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

Разрешения

enterprise.platformKeys

Доступность

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

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

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

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

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

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

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

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

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

  • Если сертификат получен, импортируйте его с помощью [ enterprise.platformKeys.importCertificate() `[3]

Вот пример, показывающий основное взаимодействие 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.

Параметры

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

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

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

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

    (response: ArrayBuffer) => void

    • ответ

      МассивБуфер

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

Возврат

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

    Хром 131+

    Промисы поддерживаются в Манифесте 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+

    Промисы поддерживаются в Манифесте 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+

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

getCertificates()

Обещать
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

Параметры

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

    нить

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

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

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

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

    (certificates: ArrayBuffer[]) => void

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

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

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

Возврат

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

    Хром 131+

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

getTokens()

Обещать
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

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

Параметры

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

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

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

    (tokens: Token[]) => void

    • жетоны

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

Возврат

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

    Хром 131+

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

importCertificate()

Обещать
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

Параметры

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

    нить

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

  • сертификат

    МассивБуфер

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

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

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

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

    () => void

Возврат

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

    Хром 131+

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

removeCertificate()

Обещать
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

Параметры

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

    нить

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

  • сертификат

    МассивБуфер

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

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

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

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

    () => void

Возврат

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

    Хром 131+

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