Share via

Azure Attestation biblioteca de clientes para Python - 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 que estão dentro dela. O serviço suporta a atestação das plataformas apoiadas por Módulos de Plataforma Fidedigna (TPMs) juntamente com a capacidade de atestar o estado de Ambientes de Execução Fidedigna (TEEs) como enclaves de extensões de guarda de software (SGX) da Intel(tm) e enclaves de Segurança (VBS) baseados na virtualização.

Attestation é um processo para demonstrar que binários de software foram corretamente instantâneos numa plataforma de confiança. As partes de confiança remota podem então ganhar confiança de que apenas esse software pretendido está a ser gerido em hardware de confiança. Azure Attestation é um serviço unificado virado para o cliente e enquadramento para a atestação.

Azure Attestation permite paradigmas de segurança de ponta, como a computação Azure Confidential e a proteção Intelligent Edge. Os clientes têm vindo a solicitar a possibilidade de verificar de forma independente a localização de uma máquina, a postura de uma máquina virtual (VM) naquela máquina, e o ambiente em que os enclaves estão a funcionar nesse VM. Azure Attestation irá capacitar estes e muitos pedidos adicionais de clientes.

Azure Attestation recebe provas de entidades computadoras, transforma-as num conjunto de reclamações, valida-as contra políticas configuráveis e produz provas criptográficas para aplicações baseadas em sinistros (por exemplo, partes dependentes e autoridades de auditoria).

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

Para uma visão mais completa das bibliotecas Azure, consulte a página de lançamento do Azure SDK para Python.

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

Introdução

Pré-requisitos

  • Uma subscrição do Azure. Para utilizar os serviços Azure, incluindo o serviço Azure Attestation, você precisará de uma subscrição. Se não tiver uma conta Azure existente, poderá inscrever-se para um teste gratuito ou utilizar os seus benefícios de Subscrição de Estúdio Visual quando criar uma conta.
  • Um Azure Attestation Instance existente, ou pode utilizar o "fornecedor partilhado" disponível em cada região de Azure. Se precisar de criar uma Azure Attestation de serviço, pode utilizar o Portal Azure ou o Azure CLI.

Instale o pacote

Instale a biblioteca de clientes Azure Attestation para Python com PyPI:

pip install azure-security-attestation

Autenticar o cliente

Para interagir com o serviço Azure Attestation, terá de criar uma instância da classe Cliente da Attestation ou da Attestation Administration Client. Você precisa de um ponto final de attestation, que você pode ver como "Attest URI" no portal, e credenciais de cliente (identificação de cliente, segredo de cliente, id inquilino) para instantaneaizar um objeto de cliente.

A autenticação secreta da credencial do cliente está a ser usada nesta secção de início, mas pode encontrar mais formas de autenticar com o pacote de identidade Azure. Para utilizar o fornecedor DefaultAzureCredential apresentado abaixo, ou outros fornecedores de credenciais fornecidos com o Azure SDK, deverá instalar o pacote de identidade azul:

pip install azure-identity

Criar/Obter credenciais

Use o snippet Azure CLI abaixo para criar/obter credenciais secretas do cliente.

  • Crie um principal serviço e configuure o seu acesso aos recursos da 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 objeto principal de serviçoId

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

    Resultado:

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

  • Use as credenciais devolvidas acima para definir AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (palavra-passe) e AZURE_TENANT_ID (inquilina) variáveis ambientais. O exemplo a seguir mostra uma forma de o fazer em Powershell:

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

Para mais informações sobre as APIs de Identidade Azure e como usá-las, consulte a biblioteca de clientes da Identidade Azure

Conceitos-chave

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

O serviço microsoft Azure Attestation funciona em dois modos distintos: "Isolado" e "AAD". Quando o serviço está em funcionamento no modo "Isolado", o cliente necessita de fornecer informações adicionais para além das suas credenciais de autenticação para verificar se estão autorizados a modificar o estado de uma instância de atestado.

Por último, cada região em que o serviço Azure Attestation está disponível suporta uma instância "partilhada", que pode ser utilizada para atestar enclaves de SGX que só precisam de ser verificados contra a linha de base azul (não existem políticas aplicadas à instância partilhada). O atestado TPM não está disponível no caso partilhado. Embora a instância partilhada exija a autenticação da AAD, não tem nenhuma política de RBAC - qualquer cliente com um token portador de AAD válido pode atestar usando a instância partilhada.

Atestado

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

Attestation serviço token assinando certificação e validação

Uma das principais garantias operacionais do Serviço Azure Attestation é que o serviço opera "operacionalmente fora do TCB". Por outras palavras, não há forma de um operador da Microsoft poder interferir no funcionamento do serviço, ou de corromper os dados enviados do cliente. Para garantir esta garantia, o núcleo do serviço de atestado funciona num enclave SGX intel(tm).

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

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

Se a instância de serviço maa estiver em execução numa região onde o serviço funciona num enclave SGX, então o certificado emitido pelo servidor pode ser verificado usando a API oe_verify_attestation_certificate.

Gestão de Políticas

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

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

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 o caso terá fornecido um certificado de gestão de políticas no momento da criação do caso. Todas as operações de modificação de políticas exigem que o cliente assine os dados da apólice 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 aos clientes "rolar" os certificados de gestão de políticas.

Modo isolado e modo AAD

Cada Azure Attestation de serviço da Microsoft funciona no modo "AAD" ou no modo "Isolado". Quando uma instância MAA está a funcionar no modo AAD, significa que o cliente que criou a instância de atestado permite que as políticas de controlo de acesso baseado em função Azure e Azure Role Para verificar o acesso à instância de atestado.

AttestationType

O serviço Azure Attestation suporta atestando diferentes tipos de evidência dependendo do ambiente. Atualmente, o MAA suporta os seguintes ambientes de execução fidedigna:

  • OpenEnclave - Um código de funcionamento do processador Intel(tm) num Enclave SGX onde foram recolhidas as provas do atestado utilizando a API de oe_get_report OpenEnclave ou oe_get_evidence .
  • SgxEnclave - Um código de funcionamento do processador Intel(tm) num Enclave SGX onde foram recolhidas as provas de atestado utilizando o Intel SGX SDK.
  • 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 tempo de execução e dados inittime

O RuntimeData refere-se a dados apresentados à lógica de geração de citações Intel SGX ou às oe_get_report/oe_get_evidence APIs. Se o chamador para a API atestar fornecer um runtime_data atributo, o serviço Azure Attestation validará que os primeiros 32 bytes do report_data campo no Relatório de Cotação/OE/OE da SGX correspondem ao haxixe SHA256 do runtime_data.

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

Note que os dados do InitTime não são suportados em máquinas virtuais da Série Azure DCsv2 .

Conceitos adicionais

Exemplos

Criar a instância do cliente

Cria um exemplo do Cliente Attestation na uri endpoint.

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

Obtenha a política de atestado

O set_policy método recupera a política de atestado do serviço. As políticas de atestação são instanced on a attestation type, o AttestationType parâmetro define o tipo de recuperação.

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 atestação estiver em funcionamento em modo isolado, a API set_policy precisa de fornecer um certificado de assinatura (e chave privada) que pode ser usado para validar que o chamador está autorizado a modificar a política na instância do atestado. Se a instância de serviço estiver em execução no modo AAD, então o certificado de assinatura e a chave são opcionais.

Sob as capas, as APIs setPolicy criam um Token Web JSON baseado no documento de política e na assinatura de informações 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 pode 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 de poder verificar se 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.

Existem 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 incluiu um certificado de assinatura, este será o certificado fornecido no momento da set_policy chamada. Se não for definido nenhum signatário da apólice, isto será nulo.
  • policy_token_hash - este é o haxixe do JSON Web Token enviado para o serviço.

Para verificar o haxixe, os clientes podem gerar uma ficha 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

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

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

Uma solução para este problema é o que é conhecido como "Secure Key Release", que é um padrão que permite uma comunicação segura com o código enclave.

Para implementar o padrão "Desbloqueio de Chave Segura", o código 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).

O código enclave calcula então o valor SHA256 da chave pública e passa-o como uma entrada para 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 haxixe da chave está presente na cotação e emitirá um "Attestation Token".

O cliente pode então enviar a Attestation Token (que contém a chave serializada) para uma 3ª parte "contando". O partido que conta valida então que o token do atestado foi criado pelo serviço de atestado, e assim a chave serializada pode ser usada para encriptar alguns dados detidos pela "parte de confiação" para enviar para o 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 um pedido.

Este exemplo pressupõe que tem um objeto existente AttestationClient que está configurado com o URI base para o seu ponto final. Também assume que tem uma cotação SGX (quote) gerada dentro do enclave SGX que está a atestar, e "Dados de Tempo de Execução" (runtime_data) que é referenciado na Cotação SGX.

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

Neste ponto, o atributo enclave_held_data no atestesResult irá manter a entrada binária runtime_data.

O símbolo é agora passado para a "festa da conta". A parte contadora validará que o símbolo foi emitido pelo Attestation Service. Em seguida, extrai a chave assimétrica do campo EnclaveHeldData. A parte que conta irá então encriptar os seus dados "chave" utilizando a chave assimétrica e transmiti-los de volta para o enclave.

encrypted_data = send_token_to_relying_party(attestationResult.Token)

Agora os dados encriptados podem ser transmitidos para o enclave que pode desencriptar esses dados.

Informações adicionais sobre como realizar a validação de fichas de atestado podem ser encontradas na Amostra de Attestation do Serviço MAA.

Recuperar Certificados Simbólicos

Utilize get_signing_certificates para recuperar os certificados que podem ser utilizados para validar o token devolvido 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)

Resolução de problemas

A maioria das operações de serviço da Attestation levantarão exceções definidas no Núcleo de Azure. As APIs do serviço de atestado lançarão uma HttpResponseError falha com códigos de erro úteis. Muitos destes 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 resolução de problemas para o serviço MAA podem ser encontradas aqui

Passos seguintes

Para 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 mais informações, visite o site do Contrato de Licença de Contribuinte.

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.

Consulte CONTRIBUTING.md para obter detalhes sobre a construção, teste e contribuição para estas bibliotecas.

Enviar Comentários

Se encontrar algum bug ou tiver sugestões, por favor preencha um problema na secção Questões do projeto.

Impressões