Verschlüsseln Sie Ihre AgentCore Policy-Engine mit einem vom Kunden verwalteten KMS-Schlüssel

Policy in AgentCore bietet standardmäßig Verschlüsselung, um vertrauliche Kundendaten im Speicher mithilfe AWS eigener Verschlüsselungsschlüssel zu schützen. Als zusätzliche Schutzebene AgentCore ermöglicht Ihnen Policy in die Verschlüsselung Ihrer Policy-Engines mithilfe von AWS Key Management Service (AWS KMS), Customer Managed Keys (CMK). Diese Funktion gewährleistet den Schutz sensibler Daten durch Verschlüsselung im Ruhezustand, was Ihnen hilft:

In den folgenden Abschnitten wird erklärt, wie Sie die Verschlüsselung für neue Policy-Engines konfigurieren und Ihre Verschlüsselungsschlüssel verwalten.

AWS KMS-Schlüsseltypen für Policy in AgentCore

Policy in ist in AWS KMS AgentCore integriert, um Verschlüsselungsschlüssel zu verwalten, die zum Verschlüsseln und Entschlüsseln von Kundendaten verwendet werden. Weitere Informationen zu Schlüsseltypen und -status finden Sie unter Konzepte des AWS Schlüsselverwaltungsdienstes im AWS KMS-Entwicklerhandbuch. Wenn Sie eine neue Policy-Engine erstellen, können Sie aus den folgenden AWS KMS-Schlüsseltypen wählen, um Ihre Daten zu verschlüsseln:

AWS eigener Schlüssel

Der Standard-Verschlüsselungstyp. Policy in AgentCore besitzt den Schlüssel, ohne dass Ihnen zusätzliche Kosten entstehen, und verschlüsselt die gespeicherten Ressourcendaten bei der Erstellung. In Ihrem Code oder Ihren Anwendungen ist keine zusätzliche Konfiguration erforderlich, um Ihre Daten mithilfe des Schlüssels zu verschlüsseln oder zu entschlüsseln, dessen Eigentümer Policy in ist. AgentCore Sie müssen diese Schlüssel nicht einsehen, verwalten, verwenden oder prüfen. Weitere Informationen finden Sie AWS im AWS KMS Developer Guide unter Eigene Schlüssel.

Kundenseitig verwalteter Schlüssel

Sie erstellen, besitzen und verwalten den Schlüssel in Ihrem AWS Konto. Sie haben die volle Kontrolle über den KMS-Schlüssel. AWS Für vom Kunden verwaltete Schlüssel fallen KMS-Gebühren an. Weitere Informationen finden Sie auf der Seite mit den AWS KMS-Preisen. Weitere Informationen zu Schlüsseltypen finden Sie unter Vom Kunden verwaltete Schlüssel im AWS KMS Developer Guide.

Wenn Sie einen vom Kunden verwalteten Schlüssel für die Verschlüsselung einer Policy-Engine angeben, AgentCore verschlüsselt Policy in die Policy-Engine und all ihre untergeordneten Ressourcen (Richtlinien, Richtliniengenerationen) mit diesem Schlüssel. Um eine Policy-Engine mit einem vom Kunden verwalteten Schlüssel zu verschlüsseln, müssen Sie AgentCore in Ihrer Schlüsselrichtlinie Zugriff auf Policy gewähren. Eine wichtige Richtlinie ist eine ressourcenbasierte Richtlinie, die Sie Ihrem vom Kunden verwalteten Schlüssel beifügen, um den Zugriff darauf zu kontrollieren. Weitere Informationen finden Sie unter Autorisieren der Verwendung Ihres AWS KMS-Schlüssels für Richtlinien unter AgentCore.

Um eine verschlüsselte Policy-Engine mit einem vom Kunden verwalteten Schlüssel zu erstellen oder API-Aufrufe an eine Policy-Engine zu tätigen, die mit einem vom Kunden verwalteten Schlüssel verschlüsselt wurde, muss der IAM-Benutzer oder die Rolle, die den Anruf tätigt, außerdem Zugriff auf den Schlüssel haben. Wenn Policy in AgentCore nicht auf den Schlüssel zugreifen kann, werden alle Autorisierungsentscheidungen verweigert, die Ressourcen betreffen, die mit diesem Schlüssel verschlüsselt wurden. Wenn Sie keinen Zugriff auf den Schlüssel haben, können Sie keine mit diesem Schlüssel verschlüsselten Ressourcen lesen, aktualisieren oder löschen, und alle Create-Aufrufe zur Verwendung des Schlüssels für die Verschlüsselung schlagen fehl.

Verwenden AWS KMS und Datenschlüssel mit aktivierter Richtlinie AgentCore

Die Funktion Policy in AgentCore Encryption at Rest verwendet einen KMS-Schlüssel und eine Hierarchie von Datenschlüsseln, um Ihre Ressourcendaten zu schützen.

Policy in AgentCore verwendet ein auf Zuschüssen basierendes Modell für den Zugriff auf Ihren vom Kunden verwalteten Schlüssel. Wenn Sie eine Policy-Engine mit einem vom Kunden verwalteten Schlüssel erstellen, AgentCore führt Policy in die folgenden Schritte aus:

Die beiden Zuschüsse dienen unterschiedlichen Zwecken:

Beide Genehmigungen sind durch den Verschlüsselungskontext eingeschränkt, der den Schlüssel verwendetaws:bedrock-agentcore-policy:policy-engine-arn, der die Zuweisungen an die spezifische Policy-Engine-Ressource bindet.

Wenn Sie eine Policy-Engine mit einem vom Kunden verwalteten Schlüssel löschen, werden beide Zuschüsse von Policy in AgentCore automatisch zurückgezogen.

Autorisieren Sie die Verwendung Ihres AWS KMS-Schlüssel für Policy in AgentCore

Um einen vom Kunden verwalteten Schlüssel mit eingeschalteter Richtlinie verwenden zu können AgentCore, muss Ihre AWS KMS-Schlüsselrichtlinie Ihrem AWS Konto Berechtigungen gewähren. Bei der Erstellung einer Policy-Engine kms:CreateGrant verwendet Policy in AgentCore Anrufen Ihre Identität über eine Forward Access Session (FAS). Daher muss die Schlüsselrichtlinie Ihrem Kontoprinzipal (nicht einem Dienstprinzipal) alle erforderlichen Berechtigungen gewähren kms:CreateGrant und stellt anhand dieser kms:ViaService Bedingung sicher, dass der Schlüssel nur über Policy in AgentCore verwendet wird.

Für Policy-In AgentCore sind mindestens die folgenden Berechtigungen für einen vom Kunden verwalteten Schlüssel erforderlich:

Den Quellkontext verstehen

Der Quellkontext liefert Informationen darüber, wie der Quellaufrufer versucht, AWS KMS-Aktionen für einen bestimmten Schlüssel auszuführen. Dadurch wird eine Verwechselung oder ein Missbrauch verschlüsselter Daten verhindert, indem der Kontext an die Datenquelle gebunden wird.

Wenn Policy in in Ihrem Namen AWS KMS-Operationen mithilfe von Zuschüssen AgentCore durchführt, identifiziert der Quellkontext die Richtlinie in der AgentCore Ressource, die die Anfrage initiiert hat. Sie können den Quellkontext als zusätzliche Bedingungen für die auf Zuschüssen basierenden Operationen in Ihrer Hauptrichtlinie verwenden, um die Schlüsselnutzung auf Anfragen zu beschränken, die von bestimmten Konten oder Ressourcen stammen.

Sie können beispielsweise aws:SourceArn Bedingungen zu den KMS-Vorgängen aws:SourceAccount und -Validierungsanweisungen in Ihrer wichtigsten Richtlinie hinzufügen, um sicherzustellen, dass diese Vorgänge nur dann erfolgreich sind, wenn die Anfrage von Ihrem Konto und für Ihre Policy-Engine-Ressourcen stammt:

{
  "Sid": "Allow Policy for KMS operations with source context",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:root"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
      "aws:SourceAccount": "111122223333"
    },
    "StringLike": {
      "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:policy-engine/*",
      "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
    }
  }
}

Diese wichtige Richtlinie ermöglicht es Policy in AgentCore , AWS KMS-Anrufe in Ihrem Namen über Grants zu tätigen, sofern das Quellkonto mit dem Konto identisch ist, in dem sich dieser KMS-Schlüssel befindet. Diese Werte sollten überprüfbar sein, wenn in den CloudTrail Auditprotokollen nach dem KMS-Schlüssel gesucht wird. Weitere Informationen zu globalen AWS Bedingungsschlüsseln finden Sie unter Using aws: SourceArn or aws: SourceAccount condition keys im AWS KMS Developer Guide.

KMS verstehen: ViaService

Der kms:ViaService Bedingungsschlüssel beschränkt die Verwendung eines KMS-Schlüssels auf Anfragen von bestimmten AWS Diensten. Dieser Bedingungsschlüssel gilt für Forward Access Sessions (FAS). Weitere Informationen zu finden Sie kms:ViaService unter kms: ViaService im AWS KMS Developer Guide.

In der Schlüsselrichtlinie folgt der kms:ViaService Wert dem Formatbedrock-agentcore.REGION.amazonaws.com, in dem die AWS Region REGION angegeben ist, in der Ihre Policy-Engine erstellt wurde (z. B.bedrock-agentcore.us-east-1.amazonaws.com).

Den Verschlüsselungskontext verstehen

Der Verschlüsselungskontext besteht aus einer Reihe von Schlüssel-Wert-Paaren, die zusätzliche authentifizierte Daten für Integritätsprüfungen der Verschlüsselung enthalten. Wenn Sie einen Verschlüsselungskontext in eine Datenverschlüsselungsanforderung aufnehmen, bindet AWS KMS den Verschlüsselungskontext kryptografisch an die verschlüsselten Daten. Um die Daten zu entschlüsseln, müssen Sie denselben Verschlüsselungskontext übergeben. Weitere Informationen finden Sie unter Verschlüsselungskontext im AWS KMS-Entwicklerhandbuch.

Policy in AgentCore verwendet den folgenden Verschlüsselungskontext bei allen kryptografischen Vorgängen von AWS KMS und kann anhand von CloudTrail Protokollen verifiziert werden, wenn Policy in in Ihrem Namen AWS KMS-Aufrufe für Verschlüsselungs- und Entschlüsselungsprozesse AgentCore durchführt:

{
  "aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:policy-engine/POLICY_ENGINE_ID"
}

Sie können diesen Verschlüsselungskontext in Ihren wichtigsten Richtlinienbedingungen verwenden, um einzuschränken, welche Policy-Engines den Schlüssel verwenden können. Die Schlüsselrichtlinie im folgenden Abschnitt verwendet beispielsweise eine kms:EncryptionContext Bedingung, die es erlaubt, dass der Schlüssel nur für Policy-Engine-Ressourcen verwendet wird.

Complete AWS KMS-Schlüsselrichtlinie

Basierend auf den Konzepten in den vorherigen Abschnitten bietet das folgende Beispiel für eine Schlüsselrichtlinie die erforderlichen Berechtigungen, um eine Policy-Engine zu verschlüsseln und eine verschlüsselte Policy-Engine zu verwenden. Die Richtlinie enthält Bedingungsschlüssel, um den bewährten Sicherheitsmethoden zu entsprechen.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Allow Policy to create grants",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com",
          "kms:GrantConstraintType": "EncryptionContextSubset"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        },
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Encrypt",
            "Decrypt",
            "GenerateDataKey",
            "GenerateDataKeyWithoutPlaintext",
            "ReEncryptFrom",
            "ReEncryptTo"
          ]
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS operations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-policy:policy-engine-arn": "arn:aws*:bedrock-agentcore:*:*:policy-engine/*"
        }
      }
    },
    {
      "Sid": "Allow Policy for KMS validation",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "bedrock-agentcore.us-east-1.amazonaws.com"
        }
      }
    }
  ]
}

Die Richtlinie enthält die folgenden Aussagen:

Voraussetzungen für die Verschlüsselung Ihrer Policy-Engine

Bevor Sie Ihre Policy-Engine verschlüsseln, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllt haben:

Weitere Informationen zur Steuerung der IAM-Berechtigungen für einen KMS-Schlüssel finden Sie unter KMS-Schlüsselzugriff und -berechtigungen im AWS KMS-Entwicklerhandbuch.

Eine verschlüsselte Policy-Engine erstellen

Bevor Sie eine verschlüsselte Policy-Engine erstellen, stellen Sie sicher, dass für den von Ihnen verwendeten, vom Kunden verwalteten Schlüssel die richtigen Richtlinien für die Verwendung des Schlüssels für die Verschlüsselung und Entschlüsselung festgelegt sind. AgentCore Informationen zu den erforderlichen Berechtigungen finden Sie unter Autorisieren der Verwendung Ihres AWS KMS-Schlüssels AgentCore für Richtlinien.

Um Ihre Policy-Engine mit der AWS CLI zu verschlüsseln, geben Sie beim Senden einer create-policy-engine Anfrage den --encryption-key-arn Parameter an:

aws bedrock-agentcore-control create-policy-engine \
  --name "MyPolicyEngine" \
  --description "Policy engine with customer-managed encryption" \
  --encryption-key-arn "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"

Die Antwort umfasst den ARN und den Status der Policy-Engine:

{
  "policyEngineId": "MyPolicyEngine-abc123",
  "name": "MyPolicyEngine",
  "description": "Policy engine with customer-managed encryption",
  "policyEngineArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/MyPolicyEngine-abc123",
  "status": "CREATING",
  "statusReasons": [],
  "encryptionKeyArn": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
  "createdAt": "2026-02-24T12:00:00Z",
  "updatedAt": "2026-02-24T12:00:00Z"
}

Einschränkungen

Die folgenden Einschränkungen gelten für die vom Kunden verwaltete Schlüsselverschlüsselung für Policy-Engines:

Fehlerbehebung

In diesem Abschnitt werden häufig auftretende Fehler im Zusammenhang mit kundenverwalteten Schlüsseln beschrieben, die bei der Verwendung von Policy in auftreten können, AgentCore und es werden Schritte zur Behebung dieser Fehler beschrieben.

Zugriff verweigert: AWS Problem mit der KMS-Berechtigung

Fehler: „Zugriff für den angegebenen KMS-Schlüssel verweigert. Stellen Sie sicher, dass die Schlüsselrichtlinie die erforderlichen Berechtigungen gewährt.“

Dies könnte bedeuten, dass der Anrufer nicht über die erforderlichen kms: *-Aktionsberechtigungen in seiner IAM-Richtlinie oder AWS KMS-Schlüsselrichtlinie verfügt oder dass der Schlüssel, auf den verwiesen wird, nicht oder nicht mehr existiert.

Um dieses Problem zu lösen:

Ausnahme bei der Validierung: AWS Konfiguration des KMS-Schlüssels

Fehler: „Der angegebene KMS-Schlüssel befindet sich nicht in einem verwendbaren Zustand. Stellen Sie sicher, dass der Schlüssel aktiviert ist und nicht gelöscht werden muss.“

Das bedeutet, dass der Schlüssel, auf den verwiesen wird, aufgrund seiner aktuellen Konfiguration nicht für die vom Kunden verwaltete Schlüsselverschlüsselung verwendet werden kann. Mögliche Gründe sind:

So beheben Sie dieses Problem: Stellen Sie sicher, dass der Schlüssel die unter Voraussetzungen für die Verschlüsselung Ihrer Policy-Engine beschriebenen Voraussetzungen erfüllt.