Описание
Используйте chrome.enterprise.platformKeys API, чтобы генерировать ключи и устанавливать для них сертификаты. Сертификаты будут управляться платформой и могут использоваться для аутентификации TLS, доступа к сети или другими расширениями через chrome.platformKeys.
Разрешения
enterprise.platformKeysДоступность
Основные понятия и использование
Обычно этот API используется для регистрации сертификата клиента следующим образом:
Получите все доступные токены с помощью
enterprise.platformKeys.getTokens().Найдите токен, у которого значение
idравно"user". Используйте этот токен в дальнейшем.Сгенерируйте пару ключей с помощью метода
generateKey()Token (определен в SubtleCrypto). Будет возвращен дескриптор ключа.Экспортируйте открытый ключ с помощью метода
exportKey()Token (определенного в SubtleCrypto).Создайте подпись данных запроса на сертификацию с помощью метода
sign()Token (определенного в SubtleCrypto).Заполните запрос на сертификат и отправьте его в центр сертификации.
Если сертификат получен, импортируйте его с помощью [
enterprise.platformKeys.importCertificate()`[3]
Ниже приведен пример, в котором показано основное взаимодействие с API, за исключением создания и отправки запроса на сертификацию.
function getUserToken(callback) {
browser.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) {
browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}
getUserToken(generateAndSign);
Типы
Algorithm
Тип ключа, который нужно сгенерировать.
Перечисление
"RSA"
ECDSA
ChallengeKeyOptions
Свойства
-
челлендж
ArrayBuffer
Запрос, отправленный веб-API подтвержденного доступа.
-
registerKey
RegisterKeyOptions необязательный
Если ключ есть, регистрирует его с помощью токена
scope. Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Последующие вызовы этой функции будут генерировать новый корпоративный ключ в указанномscope. -
область действия
Какой корпоративный ключ использовать для дополнительной аутентификации.
RegisterKeyOptions
Свойства
-
алгоритм
Алгоритм, который должен использовать зарегистрированный ключ.
Scope
Использовать ли ключ корпоративного пользователя или ключ корпоративного устройства.
Перечисление
"USER"
"MACHINE"
Token
Свойства
-
id
string
Уникальный идентификатор
Token.Статические идентификаторы –
"user"и"system", которые относятся к пользовательскому и системному аппаратным токенам платформы соответственно. Другие токены (с другими идентификаторами) могут быть возвращены методомenterprise.platformKeys.getTokens. -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 и более поздних версий browser.* начиная с Chrome 148Реализует интерфейс SubtleCrypto WebCrypto. Криптографические операции, включая создание ключей, выполняются программно. Защита ключей и, следовательно, реализация свойства неизвлекаемости выполняются в программном обеспечении, поэтому ключи менее защищены, чем ключи с аппаратной защитой.
Можно генерировать только неизвлекаемые ключи. Поддерживается только тип ключа RSASSA-PKCS1-V1_5 с
modulusLengthдо 2048. Каждый ключ можно использовать для подписания данных не более одного раза, если только расширение не добавлено в белый список с помощью правила KeyPermissions. В этом случае ключ можно использовать неограниченное количество раз.Ключи, сгенерированные на определенном
Token, нельзя использовать с другими токенами или сwindow.crypto.subtle. ОбъектыKey, созданные с помощьюwindow.crypto.subtle, также нельзя использовать с этим интерфейсом. -
subtleCrypto
SubtleCrypto
Реализует интерфейс SubtleCrypto WebCrypto. Криптографические операции, включая создание ключей, выполняются на аппаратном уровне.
Можно генерировать только неизвлекаемые ключи. Поддерживаются следующие типы ключей: RSASSA-PKCS1-V1_5 с
modulusLengthдо 2048 и ECDSA сnamedCurveP-256. Каждый ключ можно использовать для подписи данных не более одного раза, если расширение не добавлено в белый список с помощью правила KeyPermissions. В этом случае ключ можно использовать неограниченное количество раз.Ключи, сгенерированные на определенном
Token, нельзя использовать с другими токенами или сwindow.crypto.subtle. ОбъектыKey, созданные с помощьюwindow.crypto.subtle, также нельзя использовать с этим интерфейсом.
Методы
challengeKey()
browser.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
): Promise<ArrayBuffer>
Аналогично challengeMachineKey и challengeUserKey, но позволяет указать алгоритм зарегистрированного ключа. Запрашивает корпоративный ключ устройства с аппаратной защитой и передает ответ в рамках протокола удаленной аттестации. Это правило работает только в ChromeOS и в сочетании с Verified Access Web API, который отправляет запросы и проверяет ответы.
Успешная проверка с помощью Verified Access Web API – это надежный сигнал о том, что текущее устройство является легитимным устройством с ChromeOS, управляется доменом, указанным во время проверки, текущий вошедший в систему пользователь управляется доменом, указанным во время проверки, и текущее состояние устройства соответствует корпоративным правилам для устройств. Например, в правиле может быть указано, что устройство не должно находиться в режиме разработчика. Любой идентификатор устройства, полученный в результате проверки, тесно связан с аппаратным обеспечением текущего устройства. Если указана область действия "user", идентификационные данные также тесно связаны с текущим пользователем, выполнившим вход.
Эта функция строго ограничена и не будет работать, если текущее устройство или пользователь не управляются или если эта операция не была явно включена для вызывающего абонента правилами для корпоративных устройств. Проверяемый ключ не находится в токене "system" или "user" и недоступен для других API.
Параметры
-
Параметры
Объект, содержащий поля, определенные в
ChallengeKeyOptions.
Возвраты
-
Promise<ArrayBuffer>
Chrome 131+ browser.* начиная с Chrome 148Возвращает объект Promise, который распознается и выдает ответ на вызов.
challengeMachineKey()
browser.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
): Promise<ArrayBuffer>
Используйте вместо него challengeKey.
Запрашивает корпоративный ключ устройства с аппаратной защитой и передает ответ в рамках протокола удаленной аттестации. Это правило работает только в ChromeOS и в сочетании с Verified Access Web API, который отправляет запросы и проверяет ответы. Успешная проверка с помощью Verified Access Web API – это надежный сигнал того, что: * Текущее устройство является подлинным устройством с ChromeOS. * Текущее устройство управляется доменом, указанным во время проверки. * Текущий пользователь, выполнивший вход, управляется доменом, указанным во время проверки. * Текущее состояние устройства соответствует корпоративным правилам для устройств. Например, в правиле может быть указано, что устройство не должно находиться в режиме разработчика. * Любой идентификатор устройства, полученный в результате проверки, тесно связан с аппаратным обеспечением текущего устройства. Эта функция строго ограничена и не будет работать, если текущее устройство или пользователь не управляются или если эта операция не была явно включена для вызывающего абонента правилами для корпоративных устройств. Ключ Enterprise Machine Key не хранится в токене "system" и недоступен для других API.
Параметры
-
челлендж
ArrayBuffer
Запрос, отправленный веб-API подтвержденного доступа.
-
registerKey
Логическое значение (необязательно)
Chrome 59 и более поздних версий browser.* начиная с Chrome 148Если правило настроено, текущий ключ корпоративного устройства регистрируется с помощью токена
"system"и перестает выполнять свою роль. Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Это ключ RSA размером 2048 бит. При последующих вызовах этой функции будет генерироваться новый ключ Enterprise Machine Key.
Возвраты
-
Promise<ArrayBuffer>
Chrome 131+ browser.* начиная с Chrome 148Возвращает объект Promise, который распознается и выдает ответ на вызов.
challengeUserKey()
browser.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
): Promise<ArrayBuffer>
Используйте вместо него challengeKey.
Запрашивает аппаратный корпоративный ключ пользователя и передает ответ в рамках протокола удаленной аттестации. Это правило работает только в ChromeOS и в сочетании с Verified Access Web API, который отправляет запросы и проверяет ответы. Успешная проверка с помощью Verified Access Web API – это надежный сигнал того, что: * Текущее устройство является подлинным устройством с ChromeOS. * Текущее устройство управляется доменом, указанным во время проверки. * Текущий пользователь, выполнивший вход, управляется доменом, указанным во время проверки. * Текущее состояние устройства соответствует правилам для корпоративных пользователей. Например, в правиле может быть указано, что устройство не должно находиться в режиме разработчика. * Открытый ключ, полученный в результате проверки, тесно связан с аппаратным обеспечением текущего устройства и текущим пользователем, выполнившим вход. Эта функция имеет строгие ограничения и не будет работать, если текущее устройство или пользователь не управляются или если эта операция не была явно включена для вызывающего абонента корпоративными правилами для пользователей. Ключ корпоративного пользователя не хранится в токене "user" и недоступен для других API.
Параметры
-
челлендж
ArrayBuffer
Запрос, отправленный веб-API подтвержденного доступа.
-
registerKey
Логическое значение
Если правило настроено, текущий ключ корпоративного пользователя регистрируется с токеном
"user"и перестает выполнять роль ключа корпоративного пользователя. Затем ключ можно связать с сертификатом и использовать как любой другой ключ подписи. Это ключ RSA размером 2048 бит. При последующих вызовах этой функции будет генерироваться новый ключ корпоративного пользователя.
Возвраты
-
Promise<ArrayBuffer>
Chrome 131+ browser.* начиная с Chrome 148Возвращает объект Promise, который распознается и выдает ответ на вызов.
getCertificates()
browser.enterprise.platformKeys.getCertificates(
tokenId: string,
): Promise<ArrayBuffer[]>
Возвращает список всех сертификатов клиента, доступных для указанного токена. Позволяет проверить наличие и срок действия сертификатов клиента, которые можно использовать для определенной аутентификации.
Параметры
-
tokenId
string
Идентификатор токена, возвращенный
getTokens.
Возвраты
-
Promise<ArrayBuffer[]>
Chrome 131+ browser.* начиная с Chrome 148Возвращает объект Promise, который преобразуется в список доступных сертификатов.
getTokens()
browser.enterprise.platformKeys.getTokens(): Promise<Token[]>
Возвращает доступные токены. В сеансе обычного пользователя список всегда будет содержать токен пользователя с id "user". Если доступен токен TPM на уровне системы, возвращенный список также будет содержать токен на уровне системы с id "system". Токен на уровне системы будет одинаковым для всех сеансов на этом устройстве (например, Chromebook).
Возвраты
-
Promise<Token[]>
Chrome 131+ browser.* начиная с Chrome 148Вызывается
getTokensсо списком доступных токенов.
importCertificate()
browser.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
): Promise<void>
Импортирует certificate в указанный токен, если сертифицированный ключ уже хранится в этом токене. После успешного запроса сертификата эта функция должна использоваться для хранения полученного сертификата и предоставления его операционной системе и браузеру для аутентификации.
Параметры
-
tokenId
string
Идентификатор токена, возвращенный
getTokens. -
сертификат
ArrayBuffer
Кодировка DER сертификата X.509.
Возвраты
-
Promise<void>
Chrome 131+ browser.* начиная с Chrome 148Возвращает Promise, который разрешается по завершении этой операции.
removeCertificate()
browser.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
): Promise<void>
Удаляет certificate из заданного токена, если он присутствует. Используйте его, чтобы удалить устаревшие сертификаты, которые не должны учитываться при аутентификации и загромождать список выбора сертификатов. Используется для освобождения места в хранилище сертификатов.
Параметры
-
tokenId
string
Идентификатор токена, возвращенный
getTokens. -
сертификат
ArrayBuffer
Кодировка DER сертификата X.509.
Возвраты
-
Promise<void>
Chrome 131+ browser.* начиная с Chrome 148Возвращает Promise, который разрешается по завершении этой операции.