Atestado do Azure biblioteca de clientes para Java – versão 1.1.18

  • Artigo

O Atestado do Microsoft Azure (versão prévia) é uma solução unificada para verificar remotamente a confiabilidade de uma plataforma e a integridade dos binários em execução dentro dela. 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 preliminar para o serviço microsoft Atestado do Azure. Ele fornece toda a funcionalidade essencial para acessar o serviço Atestado do Azure, mas requer uma quantidade significativa de infraestrutura para funcionar corretamente.

Introdução

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-attestation</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<!-- Install the Azure Attestation SDK -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-attestation</artifactId>
    <version>1.1.18</version>
</dependency>

Pré-requisitos

az attestation create --resource-group <your-resource-group-name> --name <your-instance-name>

Autenticar o cliente

Para interagir com o serviço Atestado do Azure, seu cliente deve apresentar um token de portador do Azure Active Directory ao serviço.

A maneira mais simples de fornecer um token de portador é usar o DefaultAzureCredential método de autenticação fornecendo credenciais de segredo do cliente está sendo usada nesta seção de introdução, mas você pode encontrar mais maneiras de autenticar com azure-identity.

Principais conceitos

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 ele está autorizado a modificar o estado de uma instância de atestado.

Há quatro tipos de cliente principais fornecidos neste SDK de versão prévia:

Cada instância de atestado opera em um dos dois modos de operação separados:

  • Modo AAD.
  • Modo isolado

No modo "AAD", o acesso ao serviço é controlado exclusivamente por Controle de Acesso baseado em função do Azure. No modo "Isolado", espera-se que o cliente forneça evidências adicionais para provar que o cliente está autorizado a modificar o serviço.

Por fim, cada região na qual o serviço microsoft 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 atestado

A maioria das respostas do serviço MAA é expressa na forma de um Token Web JSON. 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 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 adicionem, removam ou enumerem os certificados de gerenciamento de políticas.

Exemplos

Criar uma instância de um cliente de atestado síncrono

A AttestationClientBuilder classe é usada para criar instâncias do cliente de atestado:

AttestationClientBuilder attestationBuilder = new AttestationClientBuilder();
// Note that the "attest" calls do not require authentication.
AttestationClient client = attestationBuilder
    .endpoint(endpoint)
    .buildClient();

Recuperar certificados de validação de token

Use listAttestationSigners para recuperar o conjunto de certificados, que pode ser usado para validar o token retornado do serviço de atestado. Normalmente, essas informações não são necessárias, pois o SDK de atestado executará a validação como parte da interação com o serviço de atestado, no entanto, as APIs são fornecidas para integridade e para facilitar a validação independente dos resultados do atestado do cliente.

AttestationSignerCollection certs = client.listAttestationSigners();

certs.getAttestationSigners().forEach(cert -> {
    System.out.println("Found certificate.");
    if (cert.getKeyId() != null) {
        System.out.println("    Certificate Key ID: " + cert.getKeyId());
    } else {
        System.out.println("    Signer does not have a Key ID");
    }
    cert.getCertificates().forEach(chainElement -> {
        System.out.println("        Cert Subject: " + chainElement.getSubjectDN().getName());
        System.out.println("        Cert Issuer: " + chainElement.getIssuerDN().getName());
    });
});

Atestar um enclave SGX

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

BinaryData decodedRuntimeData = BinaryData.fromBytes(SampleCollateral.getRunTimeData());
BinaryData sgxQuote = BinaryData.fromBytes(SampleCollateral.getSgxEnclaveQuote());

// Attest evidence from an OpenEnclave enclave specifying runtime data which should be
// interpreted as binary data.
AttestationResult result = client.attestSgxEnclave(new AttestationOptions(sgxQuote)
    .setRunTimeData(
        new AttestationData(decodedRuntimeData, AttestationDataInterpretation.BINARY)));

String issuer = result.getIssuer();

System.out.println("Attest Sgx Enclave completed. Issuer: " + issuer);
System.out.printf("Runtime Data Length: %d\n", result.getEnclaveHeldData().getLength());

Criar uma instância de um cliente administrativo síncrono

Todos os clientes administrativos são autenticados.

AttestationAdministrationClientBuilder attestationBuilder = new AttestationAdministrationClientBuilder();
// Note that the "policy" calls require authentication.
AttestationAdministrationClient client = attestationBuilder
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Obter política de atestado

Use a getAttestationPolicy API para recuperar a política de atestado atual para um determinado TEE.

String currentPolicy = client.getAttestationPolicy(AttestationType.OPEN_ENCLAVE);
System.out.printf("Current policy for OpenEnclave is: %s\n", currentPolicy);

Definir política de atestado sem sinal

Quando uma instância de atestado está no modo AAD, o chamador pode usar um método de conveniência para definir uma política de atestado sem sinal na instância.

// Set the listed policy on an attestation instance. Please note that this particular policy will deny all
// attestation requests and should not be used in production.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.OPEN_ENCLAVE,
    "version=1.0; authorizationrules{=> deny();}; issuancerules{};");
System.out.printf("Policy set for OpenEnclave result: %s\n", policyResult.getPolicyResolution());

Definir política de atestado assinado

Para instâncias de atestado de modo isolado, a solicitação de política de definição ou redefinição deve ser assinada usando a chave associada aos certificados de autenticação de atestado configurados na instância de atestado.

// Set the listed policy on an attestation instance using a signed policy token.
PolicyResult policyResult = client.setAttestationPolicy(AttestationType.SGX_ENCLAVE,
    new AttestationPolicySetOptions()
        .setAttestationPolicy("version=1.0; authorizationrules{=> permit();}; issuancerules{};")
            .setAttestationSigner(new AttestationSigningKey(certificate, privateKey)));
System.out.printf("Policy set for Sgx result: %s\n", policyResult.getPolicyResolution());

Listar certificados de gerenciamento de políticas

Quando uma instância de atestado está no Isolated modo , as APIs de política precisam de uma prova adicional de autorização. Essa prova é fornecida por meio do AttestationSigningKey parâmetro passado para as APIs de política definidas e redefinidas.

Cada Isolated instância de modo tem um conjunto de certificados, que determinam se um chamador tem autoridade para definir uma política de atestado. Quando uma política de atestado é definida, o cliente apresenta um "token" assinado para o serviço, que é assinado pela chave no AttestationSigningKey. O token assinado, incluindo o certificado no AttestationSigningKey , é enviado para o serviço de atestado, que verifica se o token foi assinado com a chave privada correspondente à chave pública no token. A operação definir ou redefinir a política só terá êxito se o certificado no token for um dos tokens de gerenciamento de política. Essa interação garante que o cliente esteja em posse da chave privada associada a um dos certificados de gerenciamento de políticas e, portanto, esteja autorizado a executar a operação.

AttestationSignerCollection signers = client.listPolicyManagementCertificates();
System.out.printf("Instance %s contains %d signers.\n", endpoint, signers.getAttestationSigners().size());
for (AttestationSigner signer : signers.getAttestationSigners()) {
    System.out.printf("Certificate Subject: %s", signer.getCertificates().get(0).getSubjectDN().toString());
}

Adicionar certificado de gerenciamento de política

Adiciona um novo certificado ao conjunto de certificados de gerenciamento de políticas. A solicitação para adicionar o certificado de gerenciamento de políticas deve ser assinada com a chave privada associada a um dos certificados de gerenciamento de política existentes (isso garante que o chamador esteja autorizado a atualizar o conjunto de certificados de política).

Observação: adicionar o mesmo certificado duas vezes não é considerado um erro – se o certificado já estiver presente, a adição será ignorada (esse comportamento possivelmente surpreendente está lá porque novas tentativas podem fazer com que a adição seja executada várias vezes)

System.out.printf("Adding new certificate %s\n", certificateToAdd.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.addPolicyManagementCertificate(
    new PolicyManagementCertificateOptions(certificateToAdd,
        new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate add result: %s\n",
    modificationResult.getCertificateResolution());
System.out.printf("Added certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());

Remover certificado de autenticação de atestado

Remove um certificado do conjunto de certificados de gerenciamento de políticas. A solicitação para remover o certificado de gerenciamento de políticas deve ser assinada com a chave privada associada a um dos certificados de gerenciamento de política existentes (isso garante que o chamador esteja autorizado a atualizar o conjunto de certificados de política).

Observação: a remoção de um certificado inexistente não é considerada um erro – se o certificado não estiver presente, a remoção será ignorada (esse comportamento possivelmente surpreendente está lá porque novas tentativas podem fazer com que a remoção seja executada várias vezes)

System.out.printf("Removing existing certificate %s\n", certificateToRemove.getSubjectDN().toString());
PolicyCertificatesModificationResult modificationResult = client.deletePolicyManagementCertificate(
    new PolicyManagementCertificateOptions(certificateToRemove,
        new AttestationSigningKey(isolatedCertificate, isolatedKey)));
System.out.printf("Updated policy certificate, certificate remove result: %s\n",
    modificationResult.getCertificateResolution());
System.out.printf("Removed certificate thumbprint: %s\n", modificationResult.getCertificateThumbprint());

Solução de problemas

As informações 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 https://cla.microsoft.com.

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 saber mais, confira as Perguntas frequentes sobre o Código de Conduta ou contate o opencode@microsoft.com caso tenha outras dúvidas ou comentários.

Impressões