Compartilhar via

Atestado do Azure biblioteca de clientes para JavaScript – versão 1.0.0

  • Artigo

O serviço do MAA (Microsoft Atestado do Azure) é uma solução unificada para verificar remotamente a confiabilidade de uma plataforma e a integridade dos binários em execução dentro dele. O serviço dá suporte ao atestado das plataformas apoiadas por TPMs (Trusted Platform Modules) juntamente com a capacidade de atestar o estado dos TEEs (Ambientes de Execução Confiável), como enclaves intel(tm) SGX (Extensões de Proteção de Software) e enclaves de VBS (Segurança Baseada em Virtualização).

O atestado é um processo usado para demonstrar que os binários de software foram instanciados corretamente em uma plataforma confiável. Em seguida, as partes confiáveis remotas podem ter a confiança de que apenas esse software pretendido está sendo executado no hardware confiável. O Atestado do Azure é um serviço unificado voltado ao cliente e uma estrutura para o atestado.

O Atestado do Azure permite paradigmas de segurança de ponta, como a Computação confidencial do Azure e a proteção de borda inteligente. Os clientes estão solicitando a capacidade de verificar de maneira independente a localização de um computador, a postura de uma VM (máquina virtual) nesse computador e o ambiente no qual os enclaves estão em execução nessa VM. O Atestado do Azure capacitará essas e muitas solicitações de clientes adicionais.

O Atestado do Azure recebe evidências de entidades de computação, transforma-as em um conjunto de declarações, valida-as em relação às políticas configuráveis e produz provas de criptografia para aplicativos baseados em declarações (por exemplo, partes confiáveis e autoridades de auditoria).

Para obter uma exibição mais completa das bibliotecas do Azure, confira a versão do typescript do sdk do Azure.

OBSERVAÇÃO: este é um SDK de versão prévia para o serviço microsoft Atestado do Azure. Ele fornece toda a funcionalidade essencial para acessar o serviço Atestado do Azure, ele deve ser considerado "no estado em que se encontra" e está sujeito a alterações no futuro que podem interromper a compatibilidade com versões anteriores.

Links principais:

Introdução

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Uma Instância de Atestado do Azure existente ou você pode usar o "provedor compartilhado" disponível em cada região do Azure. Se você precisar criar uma instância de serviço Atestado do Azure, poderá usar o Portal do Azure ou a CLI do Azure.

Instalar o pacote @azure/attestation

Instale a biblioteca de clientes do Microsoft Atestado do Azure para JavaScript com o NPM:

npm install @azure/attestation

Autenticar o cliente

Para interagir com o serviço microsoft Atestado do Azure, você precisará criar uma instância da classe Cliente de Atestado ou Cliente de Administração de Atestado. Você precisa de uma URL de instância de atestado, que será o "URI atestado" mostrado no portal ou será um dos provedores de atestado compartilhados. Você também precisará de credenciais de cliente para usar o Cliente de Administração de Atestado ou chamar a attestTpm API. As credenciais do cliente exigem (id do cliente, segredo do cliente, ID do locatário) para instanciar um objeto de cliente.

Nesta seção de introdução, autenticaremos usando credenciais de segredo do cliente por meio do provedor DefaultAzureCredential , mas oferecemos mais mecanismos de autenticação por meio do pacote de @azure/identidade . Para instalar o @azure/identity pacote:

npm install @azure/identity

Criar/Obter credenciais

Use o snippet da CLI do Azure abaixo para criar/obter credenciais de segredo do cliente.

  • Crie uma entidade de serviço e configure seu acesso aos recursos do Azure:

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

    Saída:

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

  • Anote a objectId da entidade de serviço

    az ad sp show --id <appId> --query objectId

    Saída:

    "<your-service-principal-object-id>"

  • Use as credenciais retornadas acima para definir variáveis de ambiente AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (senha) e AZURE_TENANT_ID (locatário). O exemplo a seguir mostra uma maneira de fazer isso no PowerShell:

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

Para obter mais informações sobre as APIs de Identidade do Azure e como usá-las, consulte Biblioteca de clientes do Azure Identity

Principais conceitos

Há quatro famílias principais de funcionalidades fornecidas nesta versão prévia do SDK:

O serviço microsoft Atestado do Azure é executado em dois modos separados: "Isolado" e "AAD". Quando o serviço está em execução no modo "Isolado", o cliente precisa fornecer informações adicionais além de suas credenciais de autenticação para verificar se está autorizado a modificar o estado de uma instância de atestado.

Por fim, cada região na qual o serviço de Atestado do Azure da Microsoft está disponível dá suporte a uma instância "compartilhada", que pode ser usada para atestar enclaves SGX que só precisam de verificação na linha de base do azure (não há políticas aplicadas ao provedor compartilhado). O atestado do TPM não está disponível no provedor compartilhado. Embora a instância compartilhada exija autenticação do AAD, ela não tem nenhuma política RBAC – qualquer cliente com um token de portador do AAD válido pode atestar o uso da instância compartilhada.

Atestado

O atestado SGX ou TPM é o processo de validação de evidências coletadas de um ambiente de execução confiável para garantir que ele atenda à linha de base do Azure para esse ambiente e às políticas definidas pelo cliente aplicadas a esse ambiente.

Descoberta e validação de certificado de autenticação de token de serviço de atestado

Uma das principais garantias operacionais do Serviço de Atestado do Azure é que o serviço opera "operacionalmente fora do TCB". Em outras palavras, não há como um operador da Microsoft adulterar a operação do serviço ou corromper os dados enviados do cliente. Para garantir essa garantia, o núcleo do serviço de atestado é executado em um enclave Intel(tm) SGX.

Para permitir que os clientes verifiquem se as operações foram realmente executadas dentro do enclave, a maioria das respostas do Serviço de Atestado é codificada em um Token Web JSON, que é assinado por uma chave mantida no enclave do serviço de atestado.

Esse token será assinado por um certificado de autenticação emitido pelo serviço MAA para a instância especificada.

Se a instância de serviço MAA estiver em execução em uma região em que o serviço é executado em um enclave SGX, o certificado emitido pelo servidor poderá ser verificado usando a API oe_verify_attestation_certificate.

O AttestationResponse objeto contém dois atributos principais: token e value. O token atributo contém o token completo retornado pelo serviço de atestado, o value atributo contém o corpo da resposta do Token Web JSON.

Gerenciamento de política

Cada instância de serviço de atestado tem uma política aplicada a ela que define critérios adicionais definidos pelo cliente.

Para obter mais informações sobre políticas de atestado, consulte Política de atestado

Gerenciamento de certificados do Gerenciamento de Políticas

Quando uma instância de atestado estiver em execução no modo "Isolado", o cliente que criou a instância terá fornecido um certificado de gerenciamento de política no momento em que a instância for criada. Todas as operações de modificação de política exigem que o cliente assine os dados da política com um dos certificados de gerenciamento de política existentes. As APIs de Gerenciamento de Certificados de Gerenciamento de Políticas permitem que os clientes "roll" os certificados de gerenciamento de política.

Modo Isolado e Modo AAD

Cada instância de serviço do Microsoft Atestado do Azure opera no modo "AAD" ou no modo "Isolado". Quando uma instância do MAA está operando no modo do AAD, isso significa que o cliente que criou a instância de atestado permite que as políticas de controle de acesso baseado em função do Azure e do Azure Active Directory verifiquem o acesso à instância de atestado.

AttestationType

O serviço microsoft Atestado do Azure dá suporte ao atesto de diferentes tipos de evidência, dependendo do ambiente. Atualmente, o MAA dá suporte aos seguintes ambientes de Execução Confiável:

  • OpenEnclave - Um processador Intel(tm) executando código em um enclave SGX em que a evidência de atestado foi coletada usando o OpenEnclave oe_get_report ou oe_get_evidence a API.
  • SgxEnclave - Um processador Intel(tm) executando código em um enclave SGX em que a evidência de atestado foi coletada usando o SDK do Intel SGX.
  • Tpm – um ambiente de segurança baseado em virtualização em que o Trusted Platform Module do processador é usado para fornecer a evidência de atestado.

Dados de runtime e dados de inittime

RuntimeData refere-se aos dados apresentados à lógica de geração de cotação intel SGX ou às oe_get_report/oe_get_evidence APIs. Se o chamador para a API atestar tiver fornecido um runtime_data atributo, o serviço Atestado do Azure validará se os primeiros 32 bytes do report_data campo na Aspa SGX/Relatório OE/Evidência OE correspondem ao hash SHA256 do runtime_data.

Os dados do InitTime referem-se aos dados usados para configurar o enclave SGX que está sendo atestado.

Observe que não há suporte para dados InitTime em máquinas virtuais da série DCsv2 do Azure.

Conceitos adicionais

Exemplos

Criar instância de cliente

Cria uma instância do Cliente de Atestado no URI endpoint, usando as credenciais padrão do 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();

Se você não estiver chamando a attestTpm API, não precisará fornecer credenciais para acessar o cliente de atestado. Isso significa que um cliente pode ser criado simplesmente com:

const client = new AttestationClient(endpoint);

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

Cria uma instância do Cliente de Administração de Atestado no URI endpoint.

Observe que o cliente de administração requer credenciais do Azure.

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

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

Obter política de atestado

O getPolicy método recupera a política de atestado do serviço. As políticas de atestado são instâncias por tipo de atestado, o AttestationType parâmetro define o tipo de instância a ser recuperada.

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`.

Definir uma política de atestado para um tipo de atestado especificado

Se a instância de serviço de atestado estiver em execução no modo Isolado, a API set_policy precisará fornecer um certificado de autenticação (e chave privada) que possa ser usado para validar se o chamador está autorizado a modificar a política na instância de atestado. Se a instância de serviço estiver em execução no modo AAD, o certificado de autenticação e a chave serão opcionais.

Se a instância de serviço estiver em execução no modo AAD, a chamada para setPolicy será conforme o esperado:

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);

Se a instância de serviço estiver em execução no modo Isolado, a chamada para setPolicy exigirá que o cliente seja capaz de provar que tem acesso a uma das chaves e certificados privados de gerenciamento de políticas.

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
  }
);

Nos covers, as APIs setPolicy criam um Token Web JSON contendo no documento certificate de política e assinado com o privateKey que é enviado para o serviço de atestado.

Se um cliente quiser garantir que o documento de política de atestado não tenha sido modificado antes que o documento de política seja recebido pelo enclave do serviço de atestado, ele poderá usar as propriedades retornadas no objct PolicyResult , que pode ser usado para verificar se o serviço recebeu o documento de política:

  • policySigner – se a setPolicy chamada incluir um certificate, esse valor será o certificado fornecido no momento da setPolicy chamada. Se nenhum signatário de política tiver sido definido, isso será nulo.
  • policyTokenHash - esse é o hash da Assinatura Web JSON enviada ao serviço para a API setPolicy.

Para verificar o hash, os clientes podem criar um token de política de atestado (uma classe auxiliar que representa o token usado para definir a política de atestado) e verificar o hash gerado a partir desse token:

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`.

Atestar o SGX e o Open Enclave

Use o attestSgxEnclave método para atestar um enclave SGX.

Um dos principais desafios que os clientes têm para interagir com ambientes criptografados é como garantir que você possa se comunicar com segurança com o código em execução no ambiente ("código de enclave").

Uma solução para esse problema é o que é conhecido como "Versão de Chave Segura", que é um padrão que permite a comunicação segura com o código de enclave.

Para implementar o padrão "Versão de Chave Segura", o código de enclave gera uma chave assimétrica efêmera. Em seguida, serializa a parte pública da chave para algum formato (possivelmente uma Chave Web JSON, ou PEM ou algum outro formato de serialização).

Em seguida, o código de enclave calcula o valor SHA256 da chave pública e o passa como uma entrada para o código que gera uma Cotação SGX (para OpenEnclave, que seria o oe_get_evidence ou oe_get_report).

Em seguida, o cliente envia a cotação SGX e a chave serializada para o serviço de atestado. O serviço de atestado validará a cotação e garantirá que o hash da chave esteja presente na cotação e emitirá um "Token de Atestado".

Em seguida, o cliente pode enviar esse Token de Atestado (que contém a chave serializada) para uma "terceira parte confiável". Em seguida, a terceira parte confiável valida que o token de atestado foi criado pelo serviço de atestado e, portanto, a chave serializada pode ser usada para criptografar alguns dados mantidos pela "terceira parte confiável" para enviar ao serviço.

Este exemplo mostra um padrão comum de chamada para o serviço de atestado para recuperar um token de atestado associado a uma solicitação.

Este exemplo pressupõe que você tenha um objeto existente AttestationClient configurado com o URI Attest para o ponto de extremidade. Ele também pressupõe que você tenha um relatório OpenEnclave (report) gerado de dentro do enclave SGX que você está atestando e "Dados de Runtime" (binaryRuntimeData) que é referenciado na Cotação SGX.

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

Também é possível que o binaryRuntimeData enviado para o serviço de atestado se destine a ser interpretado como dados JSON. Nesse caso, o cliente deve especificar runTimeJson na chamada à API atesta:

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

Da mesma forma, se você estiver usando o SDK da Intel para gerar uma "cotação", poderá validar a cotação usando:

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

Informações adicionais sobre como executar a validação de token de atestado podem ser encontradas no Exemplo de Atestado de Serviço do MAA.

Recuperar certificados de token

Use getSigningCertificates para recuperar os certificados que podem ser usados para validar o token retornado do serviço de atestado. Observe que essa chamada cria um cliente com credenciais do azure, que não é necessário se você estiver chamando as attestSgxEnclave APIs ou attestOpenEnclave

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

const attestationSigners = await client.getAttestationSigners();

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

Solução de problemas

A maioria das operações de serviço atestado gerará exceções definidas no Azure Core. As APIs de serviço de atestado lançarão um em caso de RestError falha com códigos de erro úteis. Muitos desses erros são recuperáveis.

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

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Informações adicionais de solução de problemas para o serviço MAA podem ser encontradas aqui

Próximas etapas

Para obter mais informações sobre o serviço microsoft Atestado do Azure, consulte nossa página de documentação.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite o site do Contrato de Licença de Colaborador.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas Frequentes Sobre o Código de Conduta ou entre em contato pelo email opencode@microsoft.com para enviar outras perguntas ou comentários.

Consulte CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essas bibliotecas.

Forneça comentários

Se você encontrar bugs ou tiver sugestões, registre um problema na seção Problemas do projeto.

Impressões