Partilhar via

Azure Attestation biblioteca de cliente para JavaScript – versão 1.0.0

  • Artigo

O serviço microsoft Azure Attestation (MAA) é uma solução unificada para verificar remotamente a fiabilidade de uma plataforma e integridade dos binários em execução no mesmo. O serviço suporta o atestado das plataformas apoiadas por Trusted Platform Modules (TPMs) juntamente com a capacidade de atestar o estado dos Ambientes de Execução Fidedignos (TEEs), como enclaves intel(tm) Software Guard Extensions (SGX) e enclaves de Segurança Baseada em Virtualização (VBS).

O atestado é um processo para demonstrar que os binários de software foram instanciados corretamente numa plataforma fidedigna. As entidades confiadoras remotas podem então ganhar confiança de que apenas esse software pretendido está em execução em hardware fidedigno. Azure Attestation é um serviço e uma arquitetura unificados destinados ao cliente para atestado.

Azure Attestation permite paradigmas de segurança de ponta, como a computação Confidencial do Azure e a proteção inteligente do Edge. Os clientes têm pedido a capacidade de verificar independentemente a localização de uma máquina, a postura de uma máquina virtual (VM) nessa máquina e o ambiente no qual os enclaves estão a ser executados nessa VM. Azure Attestation irá capacitar estes e muitos pedidos adicionais de clientes.

Azure Attestation recebe provas de entidades de computação, transforma-as num conjunto de afirmações, valida-as contra políticas configuráveis e produz provas criptográficas para aplicações baseadas em afirmações (por exemplo, entidades confiadoras e autoridades de auditoria).

Para obter uma vista mais completa das bibliotecas do Azure, veja a versão typescript do sdk do azure.

NOTA: este é um SDK de pré-visualização para o serviço microsoft Azure Attestation. Fornece todas as funcionalidades essenciais para aceder ao serviço Azure Attestation, deve ser considerada "tal como está" e está sujeita a alterações no futuro que possam interromper a compatibilidade com versões anteriores.

Ligações principais:

Introdução

Ambientes atualmente suportados

Veja a nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma Subscrição do Azure
  • Uma Instância de Azure Attestation existente ou pode utilizar o "fornecedor partilhado" disponível em cada região do Azure. Se precisar de criar uma instância de serviço Azure Attestation, pode utilizar o Portal do Azure ou a CLI do Azure.

Instalar o pacote @azure/attestation

Instale a biblioteca de cliente do Microsoft Azure Attestation para JavaScript com o NPM:

npm install @azure/attestation

Autenticar o cliente

Para interagir com o serviço microsoft Azure Attestation, terá de criar uma instância da classe Cliente de Atestado ou Cliente de Administração de Atestado. Precisa de um URL de instância de atestado, que será o "Attest URI" apresentado no portal ou será um dos fornecedores de atestado partilhados. Também precisará de credenciais de cliente para utilizar o Cliente de Administração do Atestado ou chamar a attestTpm API. As credenciais do cliente requerem (ID de cliente, segredo do cliente, ID do inquilino) para instanciar um objeto de cliente.

Nesta secção de introdução, vamos autenticar com as credenciais do segredo do cliente através do fornecedor DefaultAzureCredential , mas oferecemos mais mecanismos de autenticação através do pacote de @azure/identidade . Para instalar o @azure/identity pacote:

npm install @azure/identity

Criar/Obter credenciais

Utilize o fragmento da CLI do Azure abaixo para criar/obter credenciais do segredo do cliente.

  • Crie um principal de serviço e configure o respetivo acesso aos recursos do Azure:

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

    Resultado:

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

  • Tome nota do objectId do principal de serviço

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

    Resultado:

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

  • Utilize as credenciais devolvidas acima para definir variáveis de ambiente AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (palavra-passe) e AZURE_TENANT_ID (inquilino). O exemplo seguinte mostra uma forma de o fazer 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 utilizá-las, veja Biblioteca de cliente da Identidade do Azure

Conceitos-chave

Existem quatro grandes famílias de funcionalidades fornecidas neste SDK de pré-visualização:

O serviço microsoft Azure Attestation é executado em dois modos separados: "Isolado" e "AAD". Quando o serviço está em execução no modo "Isolado", o cliente tem de fornecer informações adicionais além das 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 microsoft Azure Attestation está disponível suporta uma instância "partilhada", que pode ser utilizada para atestar enclaves SGX que só precisam de ser verificados na linha de base do Azure (não existem políticas aplicadas ao fornecedor partilhado). O atestado TPM não está disponível no fornecedor partilhado. Embora a instância partilhada necessite de autenticação do AAD, não tem políticas RBAC – qualquer cliente com um token de portador do AAD válido pode atestar a utilização da instância partilhada.

Atestado

O atestado SGX ou TPM é o processo de validação de provas recolhidas a partir de um ambiente de execução fidedigno para garantir que cumpre a linha de base do Azure para esse ambiente e as políticas definidas pelo cliente aplicadas a esse ambiente.

Deteção e validação do certificado de assinatura de tokens do serviço de atestado

Uma das principais garantias operacionais do Serviço Azure Attestation é que o serviço opera "operacionalmente fora do TCB". Por outras palavras, não é possível que um operador da Microsoft possa adulterar o funcionamento do serviço ou danificar os dados enviados do cliente. Para garantir esta garantia, o núcleo do serviço de atestado é executado num enclave SGX Intel(tm).

Para permitir que os clientes verifiquem se as operações foram efetivamente realizadas no enclave, a maioria das respostas do Serviço de Atestado são codificadas num Token Web JSON, que é assinado por uma chave contida no enclave do serviço de atestado.

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

Se a instância do serviço MAA estiver em execução numa região onde o serviço é executado num enclave SGX, o certificado emitido pelo servidor pode ser verificado com 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 devolvido pelo serviço de atestado, o value atributo contém o corpo da resposta do Token Web JSON.

Gestão de Políticas

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

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

Gestão de certificados de Gestão de Políticas

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

Modo Isolado e Modo AAD

Cada instância de serviço do Microsoft Azure Attestation funciona no modo "AAD" ou no modo "Isolado". Quando uma instância do MAA está a funcionar no modo AAD, significa que o cliente que criou a instância de atestado permite que o Azure Active Directory e as políticas de controlo de Acesso Baseado em Funções do Azure verifiquem o acesso à instância de atestado.

AttestationType

O serviço microsoft Azure Attestation suporta a atestação de diferentes tipos de provas consoante o ambiente. Atualmente, o MAA suporta os seguintes ambientes de Execução Fidedigna:

  • OpenEnclave - Um Processador Intel(tm) a executar código num Enclave SGX onde as provas de atestado foram recolhidas com a OpenEnclave oe_get_report ou oe_get_evidence a API.
  • SgxEnclave - Um processador Intel(tm) a executar código num Enclave SGX onde as provas de atestado foram recolhidas com o SDK Intel SGX.
  • Tpm – um ambiente de Segurança Baseado em Virtualização onde o Módulo de Plataforma Fidedigna do processador é utilizado para fornecer as provas de atestado.

Dados de Runtime e Dados do Inittime

RuntimeData refere-se a dados que são apresentados à lógica de geração de Cotações SGX intel ou às oe_get_report/oe_get_evidence APIs. Se o autor da chamada à API de atestado tiver fornecido um runtime_data atributo, o serviço Azure Attestation validará que os primeiros 32 bytes do report_data campo no Relatório OE/Citação SGX correspondem ao hash SHA256 do runtime_data.

Os dados do InitTime referem-se aos dados que são utilizados para configurar o enclave SGX que está a ser atestado.

Tenha em atenção que os dados do InitTime não são suportados 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 endpointcom as credenciais predefinidas 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 não estiver a chamar a attestTpm API, não precisa de fornecer credenciais para aceder ao cliente de atestado. Isto 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 do Atestado no URI endpoint.

Tenha em atenção 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 obtém 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 obter.

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 do serviço de atestado estiver em execução no modo Isolado, a API de set_policy tem de fornecer um certificado de assinatura (e uma chave privada) que pode ser utilizado para validar que o autor da chamada 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 assinatura e a chave são opcionais.

Se a instância de serviço estiver em execução no modo AAD, a chamada para setPolicy é a esperada:

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 requer que o cliente possa provar que tem acesso a uma das chaves privadas e certificados de gestão 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 bastidores, as APIs setPolicy criam um Token Web JSON que contém 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 foi modificado antes de o documento de política ter sido recebido pelo enclave do serviço de atestado, pode utilizar as propriedades devolvidas no objct PolicyResult , que pode ser utilizado para verificar se o serviço recebeu o documento da política:

  • policySigner - se a setPolicy chamada incluir um certificate, este valor será o certificado fornecido no momento da setPolicy chamada. Se não tiver sido definido nenhum signatário de política, será nulo.
  • policyTokenHash - este é o hash da Assinatura Web JSON enviada para o 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 utilizado 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`.

Attest SGX e Open Enclave

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

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

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

Para implementar o padrão "Versão de Chave Segura", o código do 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, PEM ou outro formato de serialização).

Em seguida, o código do enclave calcula o valor SHA256 da chave pública e transmite-o como uma entrada para o código que gera uma Proposta 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 está presente na proposta e emitirá um "Token de Atestado".

Em seguida, o cliente pode enviar esse Token de Atestado (que contém a chave serializada) para uma "entidade confiadora" de terceiros. Em seguida, a entidade confiadora valida que o token de atestado foi criado pelo serviço de atestado e, por conseguinte, a chave serializada pode ser utilizada para encriptar alguns dados mantidos pela "entidade confiadora" para enviar para o serviço.

Este exemplo mostra um padrão comum de chamar para o serviço de atestado para obter um token de atestado associado a um pedido.

Este exemplo pressupõe que tem um objeto existente AttestationClient configurado com o URI attest para o ponto final. Também pressupõe que tem um relatório OpenEnclave (report) gerado a partir do enclave SGX que está a atestar 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 de atestado:

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

Da mesma forma, se estiver a utilizar o SDK Intel para gerar uma "proposta", pode validar a cotação com:

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

Pode encontrar informações adicionais sobre como executar a validação de tokens de atestado no Exemplo de Atestado do Serviço MAA.

Obter Certificados de Token

Utilize getSigningCertificates para obter os certificados que podem ser utilizados para validar o token devolvido do serviço de atestado. Tenha em atenção que esta chamada cria um cliente com credenciais do Azure, o que não é necessário se estiver a chamar 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`);

Resolução de problemas

A maioria das operações de serviço do Atestado gerará exceções definidas no Azure Core. As APIs do serviço de atestado irão gerar uma RestError falha com códigos de erro úteis. Muitos destes erros são recuperáveis.

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

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar os registos, pode ver os documentos do pacote @azure/logger.

Pode encontrar informações de resolução de problemas adicionais para o serviço MAA aqui

Passos seguintes

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

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite o site do Contrato de Licença de Contribuidor.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer questões ou comentários adicionais.

Veja CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para estas bibliotecas.

Enviar Comentários

Se encontrar erros ou tiver sugestões, submeta um problema na secção Problemas do projeto.

Impressões