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

Artigo
04/05/2023

O serviço do Microsoft Atestado do Azure (MAA) é 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áveis), como enclaves do Intel(tm) Software Guard Extensions (SGX) e enclaves VBS (Virtualization-based Security).

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

Esse pacote foi testado com Python 2.7, 3.6 a 3.9.

Para obter uma exibição mais completa das bibliotecas do Azure, consulte a página de versão do SDK do Azure para Python.

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

Introdução

Pré-requisitos

Uma assinatura do Azure. Para usar os serviços do Azure, incluindo o serviço 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 os benefícios da 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 Atestado do Azure para Python com PyPI:

pip install azure-security-attestation

Autenticar o cliente

Para interagir com o serviço Atestado do Azure, você precisará criar uma instância da classe Cliente de Atestado ou Cliente de Administração de Atestado. Você precisa de um ponto de extremidade de atestado, que você pode ver como "Attest URI" no portal e credenciais do cliente (ID do cliente, segredo do cliente, id de 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 o pacote de 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:

pip 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 neste SDK de versão prévia:

Atestado de enclave SGX e TPM.
Descoberta e validação de certificado de autenticação de token de atestado maa.
Gerenciamento de política de atestado.
Gerenciamento de certificados de gerenciamento de políticas de atestado (sim, gerenciamento de gerenciamento de políticas).

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 Atestado do Azure 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 SGX intel(tm).

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 do 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 de oe_verify_attestation_certificate.

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 de 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 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 Atestado do Azure dá suporte ao atesto de diferentes tipos de evidências, 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 a API openEnclave oe_get_report ou oe_get_evidence .
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 Módulo de Plataforma Confiável do processador é usado para fornecer a evidência de atestado.

Dados de runtime e dados de tempo de inicialização

RuntimeData refere-se a dados que são apresentados à lógica de geração de cotação do Intel SGX ou às oe_get_report/oe_get_evidence APIs. Se o chamador para a API de atestar tiver fornecido um runtime_data atributo, o serviço Atestado do Azure validará se os primeiros 32 bytes do report_data campo na Aspas 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 uma instância de cliente de atestado
Atestar um enclave SGX
Obter política de atestado
Recuperar certificados de validação de token
Criar uma instância de cliente de atestado

Criar instância do cliente

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

attest_client = AttestationClient(
    endpoint=base_uri,
    credential=DefaultAzureCredential())

Obter política de atestado

O set_policy método recupera a política de atestado do serviço. As Políticas de Atestado são instânciadas por tipo de atestado, o AttestationType parâmetro define o tipo a ser recuperado.

policy, token = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
print('Instance SGX policy: ', policy)
print('Token: ', 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 precisará fornecer um certificado de autenticação (e chave privada) que pode 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 assinatura e a chave serão opcionais.

Sob as capas, 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.

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)
# `new_policy` will equal `attestation_policy`.

Se a instância de serviço estiver em execução no modo AAD, a chamada para set_policy poderá ser simplificada:

policy_set_response = attest_client.set_policy(AttestationType.SGX_ENCLAVE,            
    attestation_policy)
# Now retrieve the policy which was just set.
new_policy, _ = attest_client.get_policy(AttestationType.SGX_ENCLAVE)

Os clientes precisam ser capazes de verificar se o documento de política de atestado não foi modificado antes do documento de política ser 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:

policy_signer - se a set_policy chamada incluir um certificado de autenticação, esse será o certificado fornecido no momento da set_policy chamada. Se nenhum signatário de política tiver sido definido, isso será nulo.
policy_token_hash - esse é o hash do Token Web JSON enviado ao serviço.

Para verificar o hash, os clientes podem gerar um token de política de atestado e verificar o hash gerado a partir desse token:

from cryptography.hazmat.primitives import hashes

expected_policy = AttestationPolicyToken(
    attestation_policy,
    signing_key=key,
    signing_certificate=signing_certificate)
hasher = hashes.Hash(hashes.SHA256())
hasher.update(expected_policy.serialize().encode('utf-8'))
expected_hash = hasher.finalize()

# `expected_hash` will exactly match `policy_set_response.policy_token_hash`

Atestar enclave SGX

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

Um dos principais desafios que os clientes têm ao 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 ao 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 aspa SGX (quote) gerada de dentro do enclave SGX que você está atestando e "Dados de Runtime" (runtime_data) que é referenciada na Cotação SGX.

response, token = attest_client.attest_sgx_enclave(quote, runtime_data=runtime_data)

Neste ponto, o atributo enclave_held_data no attestationResult manterá o binário de entrada runtime_data.

O token agora é passado para a "terceira parte confiável". A terceira parte confiável validará se o token foi emitido pelo Serviço de Atestado. Em seguida, extrai a chave assimétrica do campo EnclaveHeldData. Em seguida, a terceira parte confiável criptografará seus dados de "chave" usando a chave assimétrica e os transmitirá de volta para o enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Agora, os dados criptografados podem ser passados para o enclave que pode descriptografar esses dados.

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

signers = attest_client.get_signing_certificates()
for signer in signers:
    from cryptography.hazmat.backends import default_backend
    cert = cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'), backend=default_backend())
    print('Cert  iss:', cert.issuer, '; subject:', cert.subject)

Solução de problemas

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

try:
    response, _ = attest_client.attest_sgx_enclave(
        quote,
        runtime_data=AttestationData(runtime_data, is_json=False))
except HttpResponseError as ex:
    # Ignore invalid quote errors.
    if ex.error == "InvalidParameter":
        pass
}

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 do 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

Compartilhar via