Freigeben über

Azure Attestation Clientbibliothek für Java – Version 1.1.18

  • Artikel

Microsoft Azure Attestation (Vorschau) ist eine einheitliche Lösung zur Remoteüberprüfung der Vertrauenswürdigkeit einer Plattform und der Integrität der darin ausgeführten Binärdateien. Der Dienst unterstützt den Nachweis der TPM-basierten (Trusted Platform Module) Plattformen sowie den Nachweis des Zustands vertrauenswürdiger Ausführungsumgebungen (Trusted Execution Environments, TEEs), wozu beispielsweise SGX-Enclaves (Intel® Software Guard Extensions) und VBS-Enclaves (virtualisierungsbasierte Sicherheit) zählen.

Der Nachweis ist ein Prozess, um zu veranschaulichen, dass Softwarebinärdateien auf einer vertrauenswürdigen Plattform ordnungsgemäß instanziiert wurden. Vertrauende Remoteseiten können dann sicher sein, dass nur die vorgesehene Software auf vertrauenswürdiger Hardware ausgeführt wird. Azure Attestation ist ein einheitlicher Service für die Kunden und ein Framework für den Nachweis.

Azure Attestation ermöglicht innovative Sicherheitsparadigmen wie Confidential Computing unter Azure und Intelligent Edge-Schutz. Kunden haben die Möglichkeit angefordert, den Standort eines Computers, die Stellung eines virtuellen Computers (VM) auf diesem Computer und die Umgebung, in der die Enclaves auf diesem virtuellen Computer ausgeführt werden, einzeln zu überprüfen. Azure Attestation ermöglicht diese und viele zusätzliche Kundenanforderungen.

Azure Attestation erhält Beweise von Compute-Entitäten, wandelt sie in einen Satz von Ansprüchen um, überprüft sie anhand konfigurierbarer Richtlinien und erzeugt kryptografische Nachweise für anspruchsbasierte Anwendungen (z. B. vertrauende Seiten und Überwachungsbehörden).

HINWEIS: Dies ist ein vorläufiges SDK für den Microsoft Azure Attestation-Dienst. Es bietet alle wichtigen Funktionen für den Zugriff auf den Azure Attestation-Dienst, erfordert jedoch eine erhebliche Menge an Infrastruktur, um ordnungsgemäß zu funktionieren.

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der General Availability (GA)-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

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

und fügen Sie dann die direkte Abhängigkeit in den Abschnitt abhängigkeiten ohne das Versionstag ein, wie unten gezeigt.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Voraussetzungen

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

Authentifizieren des Clients

Um mit dem Azure Attestation-Dienst zu interagieren, muss Ihr Client dem Dienst ein Azure Active Directory-Bearertoken vorlegen.

Die einfachste Möglichkeit zum Bereitstellen eines Bearertokens besteht darin, die DefaultAzureCredential Authentifizierungsmethode zu verwenden, indem Sie anmeldeinformationen für geheime Clientschlüssel angeben, die in diesem Abschnitt mit den ersten Schritten verwendet werden. Sie finden jedoch weitere Möglichkeiten zur Authentifizierung mit azure-identity.

Wichtige Begriffe

Der Microsoft Azure Attestation-Dienst wird in zwei separaten Modi ausgeführt: "Isoliert" und "AAD". Wenn der Dienst im Modus "Isoliert" ausgeführt wird, muss der Kunde zusätzliche Informationen über seine Authentifizierungsanmeldeinformationen hinaus bereitstellen, um zu überprüfen, ob er autorisiert ist, den Status eines Nachweises instance zu ändern.

Es gibt vier Hauptclienttypen, die in diesem Vorschau-SDK bereitgestellt werden:

Jede Nachweis-instance wird in einem von zwei separaten Betriebsmodi ausgeführt:

  • AAD-Modus.
  • Isolierter Modus

Im "AAD"-Modus wird der Zugriff auf den Dienst ausschließlich von Azure Role Based Access Control gesteuert. Im Modus "Isoliert" wird erwartet, dass der Client zusätzliche Beweise bereitstellt, um zu beweisen, dass der Client zum Ändern des Diensts autorisiert ist.

Schließlich unterstützt jede Region, in der der Microsoft Azure Attestation-Dienst verfügbar ist, eine "freigegebene" instance, die verwendet werden kann, um SGX-Enklaven zu bestätigen, die nur mit der Azure-Baseline überprüft werden müssen (es gibt keine Richtlinien, die auf die freigegebene instance angewendet werden). Der TPM-Nachweis ist im freigegebenen instance nicht verfügbar. Die freigegebene instance erfordert zwar die AAD-Authentifizierung, verfügt jedoch über keine RBAC-Richtlinien. Jeder Kunde mit einem gültigen AAD-Bearertoken kann dies mithilfe des freigegebenen instance nachweisen.

Nachweis

SGX- oder TPM-Nachweis ist der Prozess der Überprüfung von Beweisen, die aus einer vertrauenswürdigen Ausführungsumgebung gesammelt wurden, um sicherzustellen, dass sie sowohl die Azure-Baseline für diese Umgebung als auch kundendefinierte Richtlinien erfüllt, die auf diese Umgebung angewendet werden.

Ermittlung und Überprüfung des Zertifikats für die Signatur des Nachweistokens

Die meisten Antworten des MAA-Diensts werden in Form eines JSON-Webtokens ausgedrückt. Dieses Token wird von einem Signaturzertifikat signiert, das vom MAA-Dienst für die angegebene instance ausgestellt wurde. Wenn der MAA-Dienst instance in einer Region ausgeführt wird, in der der Dienst in einer SGX-Enclave ausgeführt wird, kann das vom Server ausgestellte Zertifikat mithilfe der oe_verify_attestation_certificate()-API überprüft werden.

Richtlinienverwaltung

Für jeden Nachweisdienst instance wird eine Richtlinie angewendet, die zusätzliche Kriterien definiert, die der Kunde definiert hat.

Weitere Informationen zu Nachweisrichtlinien finden Sie unter Nachweisrichtlinie.

Zertifikatverwaltung der Richtlinienverwaltung

Wenn ein Nachweis instance im Modus "Isoliert" ausgeführt wird, hat der Kunde, der die instance erstellt hat, zum Zeitpunkt der Erstellung des instance ein Richtlinienverwaltungszertifikat bereitgestellt. Für alle Richtlinienänderungsvorgänge muss der Kunde die Richtliniendaten mit einem der vorhandenen Richtlinienverwaltungszertifikate signieren. Mit den Zertifikatverwaltungs-APIs für die Richtlinienverwaltung können Clients die Richtlinienverwaltungszertifikate hinzufügen, entfernen oder aufzählen.

Beispiele

Instanziieren eines synchronen Nachweisclients

Die AttestationClientBuilder -Klasse wird verwendet, um Instanzen des Nachweisclients zu erstellen:

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

Abrufen von Tokenvalidierungszertifikaten

Verwenden Sie listAttestationSigners , um den Satz von Zertifikaten abzurufen, mit dem das vom Nachweisdienst zurückgegebene Token überprüft werden kann. Normalerweise sind diese Informationen nicht erforderlich, da das Nachweis-SDK die Validierung im Rahmen der Interaktion mit dem Nachweisdienst durchführt. Die APIs werden jedoch zur Vollständigkeit und zur Erleichterung der unabhängigen Überprüfung der Nachweisergebnisse des Kunden bereitgestellt.

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

Nachweis einer SGX-Enclave

Verwenden Sie die attestSgxEnclave -Methode, um eine SGX-Enklave zu bestätigen.

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

Instanziieren eines synchronen Administratorclients

Alle administrativen Clients werden authentifiziert.

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

Abrufen der Nachweisrichtlinie

Verwenden Sie die getAttestationPolicy API, um die aktuelle Nachweisrichtlinie für eine bestimmte TEE abzurufen.

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

Festlegen einer Richtlinie für nicht signierte Nachweise

Wenn sich ein Nachweis instance im AAD-Modus befindet, kann der Aufrufer eine Komfortmethode verwenden, um eine Nachweisrichtlinie ohne Vorzeichen auf dem instance festzulegen.

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

Festlegen einer Richtlinie für signierte Nachweise

Bei Nachweisinstanzen im isolierten Modus muss die Set- oder Reset-Richtlinienanforderung mit dem Schlüssel signiert werden, der den Zertifikaten für die Nachweissignatur zugeordnet ist, die für den Nachweis instance konfiguriert sind.

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

Auflisten von Richtlinienverwaltungszertifikaten

Wenn sich ein Nachweis instance im Isolated Modus befindet, benötigen die Richtlinien-APIs einen zusätzlichen Autorisierungsnachweis. Dieser Nachweis wird über den Parameter bereitgestellt, der AttestationSigningKey an die Set- und Zurücksetzungsrichtlinien-APIs übergeben wird.

Jeder Isolated Modus instance verfügt über eine Gruppe von Zertifikaten, die bestimmen, ob ein Aufrufer über die Berechtigung zum Festlegen einer Nachweisrichtlinie verfügt. Wenn eine Nachweisrichtlinie festgelegt wird, stellt der Client dem Dienst ein signiertes "Token" vor, das vom Schlüssel in AttestationSigningKeysigniert ist. Das signierte Token, einschließlich des Zertifikats in, AttestationSigningKey wird an den Nachweisdienst gesendet, der überprüft, ob das Token mit dem privaten Schlüssel signiert wurde, der dem öffentlichen Schlüssel im Token entspricht. Der Vorgang zum Festlegen oder Zurücksetzen der Richtlinie ist nur erfolgreich, wenn das Zertifikat im Token eines der Richtlinienverwaltungstoken ist. Durch diese Interaktion wird sichergestellt, dass der Client im Besitz des privaten Schlüssels ist, der einem der Richtlinienverwaltungszertifikate zugeordnet ist und somit zum Ausführen des Vorgangs autorisiert ist.

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

Hinzufügen eines Richtlinienverwaltungszertifikats

Fügt dem Satz der Richtlinienverwaltungszertifikate ein neues Zertifikat hinzu. Die Anforderung zum Hinzufügen des Richtlinienverwaltungszertifikats muss mit dem privaten Schlüssel signiert werden, der einem der vorhandenen Richtlinienverwaltungszertifikate zugeordnet ist (dadurch wird sichergestellt, dass der Aufrufer autorisiert ist, den Satz von Richtlinienzertifikaten zu aktualisieren).

Hinweis: Zweimaliges Hinzufügen desselben Zertifikats wird nicht als Fehler betrachtet. Wenn das Zertifikat bereits vorhanden ist, wird die Ergänzung ignoriert (dieses möglicherweise überraschende Verhalten ist vorhanden, da Wiederholungen dazu führen können, dass die Ergänzung mehrmals ausgeführt wird).

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

Zertifikat für die Nachweissignatur entfernen

Entfernt ein Zertifikat aus dem Satz von Richtlinienverwaltungszertifikaten. Die Anforderung zum Entfernen des Richtlinienverwaltungszertifikats muss mit dem privaten Schlüssel signiert werden, der einem der vorhandenen Richtlinienverwaltungszertifikate zugeordnet ist (dadurch wird sichergestellt, dass der Aufrufer autorisiert ist, den Satz der Richtlinienzertifikate zu aktualisieren).

Hinweis: Das Entfernen eines nicht vorhandenen Zertifikats wird nicht als Fehler betrachtet. Wenn das Zertifikat nicht vorhanden ist, wird die Entfernung ignoriert (dieses möglicherweise überraschende Verhalten ist vorhanden, da Wiederholungen dazu führen können, dass die Entfernung mehrmals ausgeführt wird).

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

Problembehandlung

Informationen zur Problembehandlung für den MAA-Dienst finden Sie hier.

Nächste Schritte

Weitere Informationen zum Microsoft Azure Attestation-Dienst finden Sie auf unserer Dokumentationsseite.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den FAQ zum Verhaltenskodex, oder wenden Sie sich mit weiteren Fragen oder Kommentaren an opencode@microsoft.com.

Aufrufe