Compartir a través de

biblioteca cliente de Azure Attestation para Java: versión 1.1.18

  • Artículo

Microsoft Azure Attestation (versión preliminar) es una solución unificada que permite comprobar de forma remota la confiabilidad de una plataforma y la integridad de los archivos binarios que se ejecutan dentro de ella. El servicio admite la atestación de las plataformas respaldadas por módulos de plataforma segura (TPM), junto con la posibilidad de atestiguar el estado de los entornos de ejecución de confianza (TEE), como los enclaves Software Guard Extensions de Intel® (SGX) y de seguridad basada en virtualización (VBS).

La atestación es un proceso que se utiliza para demostrar que se ha creado correctamente una instancia de los archivos binarios de software en una plataforma de confianza. Así, los usuarios de confianza remotos pueden tener la seguridad de que solo se ejecuta el software previsto en el hardware de confianza. Azure Attestation consta de un servicio y un marco de trabajo unificados orientados al cliente para la atestación.

Azure Attestation utiliza paradigmas de seguridad de vanguardia, como la computación confidencial en Azure y la protección de inteligencia perimetral. Los clientes llevan tiempo solicitando la posibilidad de comprobar de forma independiente la ubicación de una máquina, la posición de una máquina virtual en esa máquina y el entorno en el que se ejecutan los enclaves en esa máquina virtual. Con Azure Attestation se podrán satisfacer estas y muchas otras solicitudes de los clientes.

Azure Attestation recibe la evidencia de entidades de proceso, las convierte en un conjunto de notificaciones, las valida con respecto a directivas configurables y genera pruebas criptográficas para aplicaciones basadas en notificaciones (por ejemplo, usuarios de confianza y autoridades de auditoría).

NOTA: Se trata de un SDK preliminar para el servicio Microsoft Azure Attestation. Proporciona toda la funcionalidad esencial para acceder al servicio Azure Attestation, pero requiere una cantidad significativa de infraestructura para funcionar correctamente.

Introducción

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de 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>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

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

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

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

Requisitos previos

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

Autenticar el cliente

Para interactuar con el servicio Azure Attestation, el cliente debe presentar un token de portador de Azure Active Directory al servicio.

La manera más sencilla de proporcionar un token de portador es usar el DefaultAzureCredential método de autenticación proporcionando credenciales de secreto de cliente en esta sección de introducción, pero puede encontrar más formas de autenticarse con azure-identity.

Conceptos clave

El servicio Microsoft Azure Attestation se ejecuta en dos modos independientes: "Aislado" y "AAD". Cuando el servicio se ejecuta en modo "aislado", el cliente debe proporcionar información adicional más allá de sus credenciales de autenticación para comprobar que están autorizados para modificar el estado de una instancia de atestación.

Hay cuatro tipos de cliente principales proporcionados en este SDK de versión preliminar:

Cada instancia de atestación funciona en uno de los dos modos de operación independientes:

  • Modo AAD.
  • Modo aislado

En el modo "AAD", el acceso al servicio se controla únicamente mediante el Access Control basado en roles de Azure. En el modo "Aislado", se espera que el cliente proporcione evidencia adicional para demostrar que el cliente está autorizado para modificar el servicio.

Por último, cada región en la que el servicio microsoft Azure Attestation está disponible admite una instancia "compartida", que se puede usar para atestiguar enclaves SGX que solo necesitan verificación en la línea base de Azure (no hay ninguna directiva aplicada a la instancia compartida). La atestación de TPM no está disponible en la instancia compartida. Aunque la instancia compartida requiere autenticación de AAD, no tiene ninguna directiva de RBAC: ningún cliente con un token de portador de AAD válido puede atestiguar mediante la instancia compartida.

Atestación

La atestación de SGX o TPM es el proceso de validar la evidencia recopilada de un entorno de ejecución de confianza para asegurarse de que cumple la línea de base de Azure para ese entorno y las directivas definidas por el cliente aplicadas a ese entorno.

Validación y detección de certificados de firma de tokens de atestación

La mayoría de las respuestas del servicio MAA se expresan en forma de token web JSON. Este token se firmará mediante un certificado de firma emitido por el servicio MAA para la instancia especificada. Si la instancia de servicio MAA se ejecuta en una región donde el servicio se ejecuta en un enclave SGX, el certificado emitido por el servidor se puede comprobar mediante la API de oe_verify_attestation_certificate().

Administración de directivas

Cada instancia del servicio de atestación tiene aplicada una directiva que define criterios adicionales que el cliente ha definido.

Para obtener más información sobre las directivas de atestación, consulte Directiva de atestación.

Administración de certificados de administración de directivas

Cuando una instancia de atestación se ejecuta en modo "aislado", el cliente que creó la instancia proporcionará un certificado de administración de directivas en el momento en que se crea la instancia. Todas las operaciones de modificación de directivas requieren que el cliente firme los datos de la directiva con uno de los certificados de administración de directivas existentes. Las API de administración de certificados de administración de directivas permiten a los clientes agregar, quitar o enumerar los certificados de administración de directivas.

Ejemplos

Creación de una instancia de un cliente de atestación sincrónica

La AttestationClientBuilder clase se usa para crear instancias del cliente de atestación:

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

Recuperación de certificados de validación de tokens

Use listAttestationSigners para recuperar el conjunto de certificados, que se puede usar para validar el token devuelto por el servicio de atestación. Normalmente, esta información no es necesaria, ya que el SDK de atestación realizará la validación como parte de la interacción con el servicio de atestación, pero las API se proporcionan para completarse y facilitar la validación independiente de los resultados de la atestación del 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());
    });
});

Atestación de un enclave de SGX

Use el attestSgxEnclave método para atestiguar un 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());

Creación de una instancia de un cliente administrativo sincrónico

Todos los clientes administrativos se autentican.

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

Obtención de la directiva de atestación

Use la getAttestationPolicy API para recuperar la directiva de atestación actual de un TEE determinado.

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

Establecimiento de una directiva de atestación sin firmar

Cuando una instancia de atestación está en modo AAD, el autor de la llamada puede usar un método de conveniencia para establecer una directiva de atestación sin firmar en la instancia.

// 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());

Establecimiento de la directiva de atestación firmada

En el caso de las instancias de atestación de modo aislado, la solicitud de directiva de establecimiento o restablecimiento debe firmarse con la clave asociada a los certificados de firma de atestación configurados en la instancia de atestación.

// 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());

Enumeración de certificados de administración de directivas

Cuando una instancia de atestación está en Isolated modo, las API de directiva necesitan una prueba de autorización adicional. Esta prueba se proporciona a través del AttestationSigningKey parámetro pasado a las API de directiva establecidas y de restablecimiento.

Cada Isolated instancia de modo tiene un conjunto de certificados, que determinan si un autor de la llamada tiene la autoridad para establecer una directiva de atestación. Cuando se establece una directiva de atestación, el cliente presenta un "token" firmado al servicio, que está firmado por la clave en .AttestationSigningKey El token firmado, incluido el certificado de , AttestationSigningKey se envía al servicio de atestación, que comprueba que el token se firmó con la clave privada correspondiente a la clave pública del token. La operación de establecimiento o restablecimiento de directiva solo se realizará correctamente si el certificado del token es uno de los tokens de administración de directivas. Esta interacción garantiza que el cliente esté en posesión de la clave privada asociada a uno de los certificados de administración de directivas y, por tanto, esté autorizado para realizar la operación.

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());
}

Agregar certificado de administración de directivas

Agrega un nuevo certificado al conjunto de certificados de administración de directivas. La solicitud para agregar el certificado de administración de directivas debe firmarse con la clave privada asociada a uno de los certificados de administración de directivas existentes (esto garantiza que el autor de la llamada esté autorizado para actualizar el conjunto de certificados de directiva).

Nota: Agregar el mismo certificado dos veces no se considera un error: si el certificado ya está presente, se omite la adición (este comportamiento posiblemente sorprendente está ahí porque los reintentos podrían provocar que la adición se ejecute varias veces).

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());

Eliminación del certificado de firma de atestación

Quita un certificado del conjunto de certificados de administración de directivas. La solicitud para quitar el certificado de administración de directivas debe estar firmada con la clave privada asociada a uno de los certificados de administración de directivas existentes (esto garantiza que el autor de la llamada esté autorizado para actualizar el conjunto de certificados de directiva).

Nota: La eliminación de un certificado inexistente no se considera un error: si el certificado no está presente, se omite la eliminación (este comportamiento posiblemente sorprendente está ahí porque los reintentos podrían hacer que la eliminación se ejecute varias veces).

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());

Solución de problemas

Puede encontrar información de solución de problemas para el servicio MAA aquí.

Pasos siguientes

Para obtener más información sobre el servicio Microsoft Azure Attestation, consulte nuestra página de documentación.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para obtener más información, vea las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com si tiene preguntas o comentarios.

Impresiones