клиентская библиотека Аттестация Azure для JavaScript версии 1.0.0

Статья
04/05/2023

Служба Microsoft Аттестация Azure (MAA) — это единое решение для удаленной проверки надежности платформы и целостности двоичных файлов, работающих внутри нее. Служба поддерживает аттестацию платформ, поддерживаемых доверенными платформенными модулями (TPM), а также возможность подтверждения состояния доверенных сред выполнения (TEEs), таких как анклавы Intel(tm) Software Guard Extensions (SGX) и анклавы безопасности на основе виртуализации (VBS).

Аттестация — это процесс, демонстрирующий, что экземпляры двоичных файлов ПО правильно созданы на доверенной платформе. Удаленные проверяющие стороны могут удостовериться в том, что на доверенном оборудовании работает только соответствующее программное обеспечение. Аттестация Azure — это одновременно служба, ориентированная на клиентов, и инфраструктура для аттестации.

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

Аттестация Azure получает от вычислительных сущностей свидетельства, преобразует их в наборы утверждений, проверяет их на соответствие настраиваемым политикам и предоставляет криптографические подтверждения для приложений на основе утверждений (например, для проверяющих сторон или центров аудита).

Более полное представление о библиотеках Azure см. в выпуске typescript пакета sdk azure.

ПРИМЕЧАНИЕ. Это предварительная версия пакета SDK для службы Microsoft Аттестация Azure. Она предоставляет все необходимые функциональные возможности для доступа к службе Аттестация Azure, она должна считаться "как есть" и может быть изменена в будущем, что может нарушить совместимость с предыдущими версиями.

Основные ссылки:

Начало работы

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

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

Предварительные требования

Подписка Azure
Существующий экземпляр Аттестация Azure или можно использовать общий поставщик, доступный в каждом регионе Azure. Если вам нужно создать экземпляр службы Аттестация Azure, можно использовать портал Azure или Azure CLI.

Установите пакет @azure/attestation.

Установите клиентскую библиотеку Microsoft Аттестация Azure для JavaScript с помощью NPM:

npm install @azure/attestation

Аутентификация клиента

Чтобы взаимодействовать со службой Microsoft Аттестация Azure, необходимо создать экземпляр класса Клиент аттестации или Клиент администрирования аттестации. Вам потребуется URL-адрес экземпляра аттестации, который будет либо URI аттестации, отображаемый на портале, либо будет одним из общих поставщиков аттестации. Вам также потребуются учетные данные клиента для использования клиента администрирования аттестации attestTpm или вызова API. Учетные данные клиента требуют (идентификатор клиента, секрет клиента, идентификатор клиента) для создания экземпляра объекта клиента.

В этом разделе по началу работы мы будем выполнять проверку подлинности с помощью секретных учетных данных клиента через поставщика DefaultAzureCredential , но предлагаем дополнительные механизмы проверки подлинности с помощью пакета @azure/identity . Чтобы установить пакет @azure/identity, выполните следующие действия.

npm install @azure/identity

Создание и получение учетных данных

Используйте приведенный ниже фрагмент кода Azure CLI , чтобы создать или получить учетные данные секрета клиента.

Создайте субъект-службу и настройте для нее доступ к ресурсам Azure:

az ad sp create-for-rbac -n <your-application-name> --skip-assignment

Выходные данные:

{
  "appId": "generated-app-ID",
  "displayName": "dummy-app-name",
  "name": "http://dummy-app-name",
  "password": "random-password",
  "tenant": "tenant-ID"
}

Запишите objectId субъекта-службы.
```
az ad sp show --id <appId> --query objectId
```
Выходные данные:
```
"<your-service-principal-object-id>"
```
Используйте указанные выше учетные данные, чтобы задать переменные среды AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (пароль) и AZURE_TENANT_ID (клиент). В следующем примере показано, как это сделать в PowerShell:

    $Env:AZURE_CLIENT_ID="generated-app-ID"
    $Env:AZURE_CLIENT_SECRET="random-password"
    $Env:AZURE_TENANT_ID="tenant-ID"

Дополнительные сведения об API удостоверений Azure и их использовании см. в статье Клиентская библиотека удостоверений Azure.

Основные понятия

Существует четыре основных семейства функциональных возможностей, предоставляемых в этой предварительной версии пакета SDK:

Аттестация анклавов SGX и TPM.
MAA обнаружение и проверка сертификата подписи маркера аттестации.
Управление политикой аттестации.
Управление сертификатами управления политиками аттестации (да, управление политиками).

Служба Microsoft Аттестация Azure работает в двух отдельных режимах: "Изолированный" и "AAD". Если служба работает в режиме "Изолированный", клиент должен предоставить дополнительные сведения, помимо учетных данных проверки подлинности, чтобы убедиться, что он имеет право изменять состояние экземпляра аттестации.

Наконец, каждый регион, в котором доступна служба Microsoft Аттестация Azure, поддерживает "общий" экземпляр, который можно использовать для подтверждения анклавов SGX, для которых требуется только проверка на соответствие базовым показателям Azure (к общему поставщику не применяются политики). Аттестация доверенного платформенного модуля недоступна в общем поставщике. Хотя общий экземпляр требует проверки подлинности AAD, он не имеет политик RBAC. Любой клиент с допустимым маркером носителя AAD может подтвердить использование общего экземпляра.

Аттестация

Аттестация SGX или TPM — это процесс проверки доказательств, собранных из доверенной среды выполнения, чтобы убедиться, что они соответствуют как базовым показателям Azure для этой среды, так и политикам, определенным клиентом, применяемым к этой среде.

Обнаружение и проверка сертификата для подписи маркера службы аттестации

Одной из основных операционных гарантий службы Аттестация Azure является то, что служба работает "в оперативном режиме за пределы TCB". Другими словами, оператор Майкрософт не может изменить работу службы или повредить данные, отправленные от клиента. Чтобы обеспечить эту гарантию, ядро службы аттестации выполняется в анклаве Intel(tm) SGX.

Чтобы клиенты могли убедиться, что операции действительно выполнялись в анклаве, большинство ответов от службы аттестации кодируются в веб-маркере JSON, который подписывается ключом, удерживаемым в анклаве службы аттестации.

Этот маркер будет подписан сертификатом подписи, выданным службой MAA для указанного экземпляра.

Если экземпляр службы MAA работает в регионе, где служба выполняется в анклаве SGX, сертификат, выданный сервером, можно проверить с помощью API oe_verify_attestation_certificate.

Объект AttestationResponse содержит два основных атрибута: token и value. Атрибут token содержит полный маркер, возвращенный службой аттестации value , а атрибут содержит текст ответа json Web Token.

Управление политикой

К каждому экземпляру службы аттестации применяется политика, которая определяет дополнительные критерии, определенные клиентом.

Дополнительные сведения о политиках аттестации см. в статье Политика аттестации.

Управление сертификатами управления политиками

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

Изолированный режим и режим AAD

Каждый экземпляр службы Microsoft Аттестация Azure работает в режиме AAD или изолированном режиме. Если экземпляр MAA работает в режиме AAD, это означает, что клиент, создавший экземпляр аттестации, разрешает Azure Active Directory и политикам управления доступом на основе ролей Azure проверять доступ к экземпляру аттестации.

Тип аттестации

Служба Microsoft Аттестация Azure поддерживает аттестацию различных типов доказательств в зависимости от среды. В настоящее время MAA поддерживает следующие доверенные среды выполнения:

OpenEnclave — процессор Intel(tm), выполняющий код в анклаве SGX, где доказательства аттестации были собраны с помощью OpenEnclave oe_get_report или oe_get_evidence API.
SgxEnclave — процессор Intel(tm), выполняющий код в анклаве SGX, где доказательства аттестации были собраны с помощью пакета SDK intel SGX.
Tpm — среда безопасности на основе виртуализации, в которой доверенный платформенный модуль процессора используется для предоставления подтверждения аттестации.

Данные среды выполнения и данные Inittime

RuntimeData — это данные, которые представлены логике создания предложения Intel SGX Quote или oe_get_report/oe_get_evidence API. Если вызывающий API аттестации предоставил runtime_data атрибут, служба Аттестация Azure проверит, что первые 32 байт report_data поля в отчете SGX Quote/OE Report/OE Evidence соответствуют хэшу runtime_dataSHA256 объекта .

Данные InitTime — это данные, которые используются для настройки аттестации анклава SGX.

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

Дополнительные понятия

Создание экземпляра клиента

Создает экземпляр клиента аттестации по универсальному коду ресурса (URI endpoint), используя учетные данные Azure по умолчанию (DefaultAzureCredential).

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Если вы не вызываете attestTpm API, вам не нужно предоставлять учетные данные для доступа к клиенту аттестации. Это означает, что клиент можно создать просто с помощью:

const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

Создает экземпляр клиента администрирования аттестации по адресу URI endpoint.

Обратите внимание, что клиенту администрирования требуются учетные данные Azure.

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

  // Retrieve the SGX policy from the specified attestation instance.
  const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

Получение политики аттестации

Метод getPolicy извлекает политику аттестации из службы. Политики аттестации экземплярируются по каждому типу аттестации, AttestationType параметр определяет тип извлекаемого экземпляра.

const policyResult = await adminClient.getPolicy(attestationType);

// The text policy document is available in the `policyResult.body`
// property.

// The actual attestation token returned by the MAA service is available
// in `policyResult.token`.

Настройка политики аттестации для указанного типа аттестации

Если экземпляр службы аттестации работает в изолированном режиме, API set_policy должен предоставить сертификат подписи (и закрытый ключ), который можно использовать для проверки того, что вызывающий объект имеет право изменять политику в экземпляре аттестации. Если экземпляр службы работает в режиме AAD, то сертификат подписи и ключ являются необязательными.

Если экземпляр службы работает в режиме AAD, вызов setPolicy выполняется должным образом:

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Attestation Policy>`;

// Set the new attestation policy. Set the policy as an unsecured policy.
const setPolicyResult = await client.setPolicy(KnownAttestationType.SgxEnclave, newPolicy);

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

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Policy Document>`;

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = <Retrieve isolated mode private key from storage>
const certificate = <Retrieve certificate associated with that private key>

const setPolicyResult = await client.setPolicy(
  KnownAttestationType.OpenEnclave,
  newPolicy,
  {
    privateKey: privateKey,
    certificate: certificate
  }
);

Под заголовком API setPolicy создают веб-токен JSON , содержащийся в документе certificate политики, и подписывается с privateKey помощью , который затем отправляется в службу аттестации.

Если клиент хочет убедиться, что документ политики аттестации не был изменен до того, как документ политики был получен анклавом службы аттестации, он может использовать свойства, возвращенные в объекте PolicyResult , который можно использовать для проверки того, что служба получила документ политики:

policySigner — если вызов setPolicy включал certificate, это значение будет сертификатом, предоставленным во время setPolicy вызова. Если пользователь, подписывающий политику, не задан, это значение будет иметь значение NULL.
policyTokenHash — это хэш веб-подписи JSON , отправляемой в службу для API setPolicy.

Чтобы проверить хэш, клиенты могут создать маркер политики аттестации (вспомогательный класс, представляющий маркер, используемый для установки политики аттестации) и проверить хэш, созданный из этого маркера:

const expectedPolicy = createAttestationPolicyToken(
  `<Policy Document>`,
  privateKey,
  certificate);

// Use your favorite SHA256 hash generator function to create a hash of the
// stringized JWS.
const expectedHash = generateSha256Hash(expectedPolicy.serialize());

// The hash returned in expectedHash should match the value in
// `setResult.body.policyTokenHash`.

Аттестация SGX и Open Анклава

Используйте метод для attestSgxEnclave аттестации анклава SGX.

Одной из основных проблем, с которыми сталкиваются клиенты при взаимодействии с зашифрованными средами, является обеспечение безопасного взаимодействия с кодом, выполняемым в среде ("код анклава").

Одним из решений этой проблемы является то, что называется "Выпуск безопасного ключа", который является шаблоном, обеспечивающим безопасный обмен данными с кодом анклава.

Для реализации шаблона "Выпуск безопасного ключа" код анклава создает эфемерный асимметричный ключ. Затем он сериализует открытую часть ключа в определенном формате (возможно, веб-ключ JSON, PEM или другой формат сериализации).

Затем код анклава вычисляет значение SHA256 открытого ключа и передает его в качестве входных данных в код, который создает цитату SGX (для OpenEnclave это будет oe_get_evidence или oe_get_report).

Затем клиент отправляет цитату SGX и сериализованный ключ в службу аттестации. Служба аттестации проверит предложение и убедится, что хэш ключа присутствует в расценке, и выдаст токен аттестации.

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

В этом примере показан один распространенный шаблон вызова службы аттестации для получения маркера аттестации, связанного с запросом.

В этом примере предполагается, что у вас есть объект AttestationClient , для которого настроен универсальный код ресурса (URI) аттестации для конечной точки. Также предполагается, что у вас есть отчет OpenEnclave (report), созданный в анклаве SGX, который вы подтверждаете, и "Данные среды выполнения" (binaryRuntimeData), на который ссылается цитата SGX.

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeData: binaryRuntimeData
});

Также возможно, что объект , отправленный binaryRuntimeData в службу аттестации, должен интерпретироваться как данные JSON. В этом случае клиент должен указать runTimeJson в вызове API аттестации:

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeJson: binaryRuntimeData
});

Аналогичным образом, если вы используете пакет SDK Intel для создания "quote", вы можете проверить цитату, используя:

const attestationResult = await client.attestSgxEnclave(quote, {
  runTimeData: binaryRuntimeData
});

Дополнительные сведения о том, как выполнить проверку маркера аттестации, можно найти в примере аттестации службы MAA.

Получение сертификатов маркеров

Используйте getSigningCertificates для получения сертификатов, которые можно использовать для проверки маркера, возвращенного службой аттестации. Обратите внимание, что этот вызов создает клиент с учетными данными Azure, который не требуется при вызове attestSgxEnclave API или .attestOpenEnclave

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

const attestationSigners = await client.getAttestationSigners();

console.log(`There are ${attestationSigners.length} signers`);

Устранение неполадок

Большинство операций службы аттестации будут вызывать исключения, определенные в Azure Core. API службы аттестации будут вызывать исключение при сбое RestError с полезными кодами ошибок. Многие из этих ошибок можно исправить.

try {
  await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
  console.log(`Exception thrown for invalid request: ${error.message}`);
}

Ведение журнала

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средства ведения журнала.

Дополнительные сведения об устранении неполадок для службы MAA см. здесь.

Дальнейшие действия

Дополнительные сведения о службе Microsoft Аттестация Azure см. на странице документации.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на сайте лицензионного соглашения с участником.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в вопросах и ответах по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.

Дополнительные сведения о создании, тестировании и участии в этих библиотеках см. в CONTRIBUTING.md .

Отзывы

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

Пакет SDK Microsoft Azure для JavaScript

Просмотры

Поделиться через

клиентская библиотека Аттестация Azure для JavaScript версии 1.0.0

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Установите пакет @azure/attestation.

Аутентификация клиента

Создание и получение учетных данных

Основные понятия

Аттестация

Обнаружение и проверка сертификата для подписи маркера службы аттестации

Управление политикой

Управление сертификатами управления политиками

Изолированный режим и режим AAD

Тип аттестации

Данные среды выполнения и данные Inittime

Дополнительные понятия

Примеры

Создание экземпляра клиента

Получение политики аттестации

Настройка политики аттестации для указанного типа аттестации

Аттестация SGX и Open Анклава

Получение сертификатов маркеров

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Отзывы

Дополнительные ресурсы

Поделиться через

клиентская библиотека Аттестация Azure для JavaScript версии 1.0.0

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Установите пакет @azure/attestation.

Аутентификация клиента

Создание и получение учетных данных

Основные понятия

Аттестация

Обнаружение и проверка сертификата для подписи маркера службы аттестации

Управление политикой

Управление сертификатами управления политиками

Изолированный режим и режим AAD

Тип аттестации

Данные среды выполнения и данные Inittime

Дополнительные понятия

Примеры

Создание экземпляра клиента

Получение политики аттестации

Настройка политики аттестации для указанного типа аттестации

Аттестация SGX и Open Анклава

Получение сертификатов маркеров

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Отзывы

Связанные проекты

Дополнительные ресурсы