Compartilhar via


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

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 com suporte de TPMs (Trusted Platform Modules) juntamente com a capacidade de atestar TEEs (Ambientes de Execução Confiável), como enclaves Intel® SGX (Software Guard Extensions) e enclaves 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).

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.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto

Introdução

Pré-requisitos

  • Uma assinatura do Azure. Para usar os serviços do Azure, incluindo o serviço microsoft Atestado do Azure, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar seus benefícios de assinatura do Visual Studio ao criar uma conta.
  • 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

Instale a biblioteca de clientes do Microsoft Atestado do Azure para .NET com o NuGet:

dotnet add package Azure.Security.Attestation --prerelease

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 você pode ver como "Nome DNS" no portal e credenciais de segredo do cliente (ID do cliente, segredo do cliente, id do locatário) para instanciar um objeto cliente.

A autenticação de credencial de segredo do cliente está sendo usada nesta seção de introdução, mas você pode encontrar mais maneiras de autenticar com a identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, você deve instalar o pacote Azure.Identity:

dotnet add package 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 à instância compartilhada). O atestado do TPM não está disponível na instância compartilhada. 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 duas propriedades main: Token e Value. A Token propriedade contém o token completo retornado pelo serviço de atestado, a Value propriedade 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. O serviço Atestado do Azure validará se os primeiros 32 bytes do report_data campo na Aspa SGX/OE Report/OE Evidence correspondem ao hash SHA256 do RuntimeData.

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.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | cliente Acessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

Criar instância de cliente

Cria uma instância do Cliente de Atestado no URI endpoint.

var options = new AttestationClientOptions();
return new AttestationClient(new Uri(endpoint), new DefaultAzureCredential(), options);

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 a ser recuperado.

var client = new AttestationAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

AttestationResponse<string> policyResult = await client.GetPolicyAsync(AttestationType.SgxEnclave);
string result = policyResult.Value;

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

Nos covers, as APIs SetPolicy criam um Token Web JSON com base no documento de política e nas informações de assinatura que são enviadas para o serviço de atestado.

string attestationPolicy = "version=1.0; authorizationrules{=> permit();}; issuancerules{};";

X509Certificate2 policyTokenCertificate = new X509Certificate2(<Attestation Policy Signing Certificate>);
AsymmetricAlgorithm policyTokenKey = <Attestation Policy Signing Key>;

var setResult = client.SetPolicy(AttestationType.SgxEnclave, attestationPolicy, new AttestationTokenSigningKey(policyTokenKey, policyTokenCertificate));

Os clientes precisam ser capazes de verificar se o documento de política de atestado não foi modificado antes que o documento de política seja recebido pelo enclave do serviço de atestado.

Há duas propriedades fornecidas no PolicyResult que podem ser usadas para verificar se o serviço recebeu o documento de política:

  • PolicySigner – se a SetPolicy chamada incluir um certificado de autenticação, esse 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 do Token Web JSON enviado ao serviço.

Para verificar o hash, os clientes podem gerar um token de atestado e verificar o hash gerado com base nesse token:

// The SetPolicyAsync API will create an AttestationToken signed with the TokenSigningKey to transmit the policy.
// To verify that the policy specified by the caller was received by the service inside the enclave, we
// verify that the hash of the policy document returned from the Attestation Service matches the hash
// of an attestation token created locally.
TokenSigningKey signingKey = new TokenSigningKey(<Customer provided signing key>, <Customer provided certificate>)
var policySetToken = new AttestationToken(
    BinaryData.FromObjectAsJson(new StoredAttestationPolicy { AttestationPolicy = attestationPolicy }),
    signingKey);

using var shaHasher = SHA256Managed.Create();
byte[] attestationPolicyHash = shaHasher.ComputeHash(Encoding.UTF8.GetBytes(policySetToken.Serialize()));

Debug.Assert(attestationPolicyHash.SequenceEqual(setResult.Value.PolicyTokenHash.ToArray()));

Atestar enclave SGX

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 de forma confiável 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 esse tipo de comunicação 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 base para o ponto de extremidade. Ele também pressupõe que você tenha uma Cotação SGX (binaryQuote) gerada de dentro do enclave SGX que você está atestando e "Dados de Runtime" (runtimeData) que é referenciada na Cotação SGX.

// Collect quote and runtime data from an SGX enclave.
// For the "Secure Key Release" scenario, the runtime data is normally a serialized asymmetric key.
// When the 'quote' (attestation evidence) is created specify the SHA256 hash of the runtime data when
// creating the evidence.
//
// When the generated evidence is created, the hash of the runtime data is included in the
// secured portion of the evidence.
//
// The Attestation service will validate that the Evidence is valid and that the SHA256 of the RuntimeData
// parameter is included in the evidence.
AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
{
    Evidence = BinaryData.FromBytes(binaryQuote),
    RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
});

// At this point, the EnclaveHeldData field in the attestationResult.Value property will hold the
// contain the input binaryRuntimeData.

// The token is now passed to the "relying party". The relying party will validate that the token was
// issued by the Attestation Service. It then extracts the asymmetric key from the EnclaveHeldData field.
// The relying party will then Encrypt it's "key" data using the asymmetric key and transmits it back
// to the enclave.
var encryptedData = SendTokenToRelyingParty(attestationResult.Token);

// Now the encrypted data can be passed into the enclave which can decrypt that data.

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 GetSigningCertificatesAsync para recuperar os certificados que podem ser usados para validar o token retornado do serviço de atestado.

var client = GetAttestationClient();

IReadOnlyList<AttestationSigner> signingCertificates = (await client.GetSigningCertificatesAsync()).Value;

Solução de problemas

A maioria das operações de serviço atestado lançará uma RequestFailedException em caso de falha com ErrorCodes úteis. Muitos desses erros são recuperáveis.

try
{
    AttestationResponse<AttestationResult> attestationResult = client.AttestSgxEnclave(new AttestationRequest
    {
        Evidence = BinaryData.FromBytes(binaryQuote),
        RuntimeData = new AttestationData(BinaryData.FromBytes(binaryRuntimeData), false),
    });
}
catch (RequestFailedException ex)
    when (ex.ErrorCode == "InvalidParameter")
    {
    // Ignore invalid quote errors.
    }

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.

Impressões