Azure Attestation biblioteca de cliente para JavaScript – versão 1.0.0
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
- Versões LTS do Node.js
- Versões mais recentes do Safari, Chrome, Edge e Firefox.
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:
- Atestado de enclave SGX e TPM.
- Deteção e validação do certificado de assinatura do Token de Atestado maA.
- Gestão de Políticas de Atestado.
- Gestão de certificados de gestão de políticas de atestado (sim, gestão de políticas).
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
ouoe_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 uma instância de cliente de atestado
- Atestar um enclave SGX
- Obter política de atestado
- Obter certificados de validação de tokens
- Criar uma instância de cliente de atestado
Criar instância de cliente
Cria uma instância do Cliente de Atestado no URI endpoint
com 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 asetPolicy
chamada incluir umcertificate
, este valor será o certificado fornecido no momento dasetPolicy
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.
Projetos relacionados
Azure SDK for JavaScript