Claude Platform Docs
AmministrazioneChiavi di crittografia

Configurare AWS KMS per CMEK

Usa AWS KMS per fornire una chiave di crittografia per la tua organizzazione.

Configure with the /claude-api skill in Claude Code
claude "/claude-api help me configure a customer-managed encryption key with AWS KMS"

Questa guida illustra come configurare una chiave AWS KMS come customer-managed encryption key (chiave di crittografia gestita dal cliente), o CMEK per la tua organizzazione Anthropic.

Prerequisiti

  • Un account AWS con i permessi per creare chiavi KMS e impostare key policy (kms:CreateKey e kms:PutKeyPolicy).
  • Una chiave API Admin di Anthropic per la tua organizzazione.
  • La AWS CLI installata e autenticata.

Amazon Resource Name (ARN) per Anthropic

Affinché Anthropic utilizzi la tua chiave di crittografia, devi fornire al ruolo IAM di Anthropic una chiave KMS che possa usare per crittografare i dati. L'ARN per Anthropic CMEK è:

arn:aws:iam::915198916910:role/anthropic-cmek-client-us

Configurazione della chiave di crittografia

  1. Crea la chiave KMS con una key policy cross-account

    La key policy concede al ruolo IAM di Anthropic l'accesso cross-account. Sono necessarie tre dichiarazioni (statement):

    1. Amministratore root dell'account: il pattern KMS standard. Il tuo account mantiene il pieno controllo amministrativo.
    2. Crittografia e decrittografia di Anthropic: le azioni kms:Encrypt e kms:Decrypt, che Anthropic usa per crittografare e decrittografare le chiavi dati che proteggono i dati del tuo workspace (envelope encryption, ovvero crittografia a busta).
    3. Describe di Anthropic: la lettura dei metadati che Anthropic esegue all'avvio. È concessa separatamente perché DescribeKey non ha un parametro EncryptionContext, quindi una condizione EncryptionContext su questa azione negherebbe sempre l'accesso.
    export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)

aws kms create-key \
  --region <region> \
  --description "Anthropic CMEK" \
  --key-usage ENCRYPT_DECRYPT \
  --policy "{
    \"Version\": \"2012-10-17\",
    \"Statement\": [
      {
        \"Sid\": \"AccountRootAdmin\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},
        \"Action\": \"kms:*\",
        \"Resource\": \"*\"
      },
      {
        \"Sid\": \"AllowAnthropicCMEKCrypto\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},
        \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\"],
        \"Resource\": \"*\",
        \"Condition\": {
          \"StringEquals\": {
            \"kms:EncryptionContext:anthropic:compartment_uuid\": [
              \"00000000-0000-0000-0000-000000000000\",
              \"<compartment-uuid>\"
            ]
          }
        }
      },
      {
        \"Sid\": \"AllowAnthropicCMEKDescribe\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},
        \"Action\": \"kms:DescribeKey\",
        \"Resource\": \"*\"
      }
    ]
  }"

    Annota KeyMetadata.Arn dall'output. Ti servirà quando registri la chiave nel passaggio successivo.

    La condizione EncryptionContext è consigliata ma facoltativa. Anthropic include sempre l'ID del compartimento del tuo workspace nel contesto di crittografia, quindi il testo cifrato è comunque vincolato crittograficamente a quel compartimento. Aggiungere la condizione fornisce una difesa in profondità a livello IAM. Per iniziare senza di essa, ometti il blocco Condition dalla dichiarazione AllowAnthropicCMEKCrypto e aggiungilo in seguito con kms:PutKeyPolicy.

    Puoi anche creare la chiave dalla AWS Console. Scegli una chiave simmetrica con utilizzo della chiave encrypt and decrypt, una chiave single-region e origine del materiale della chiave KMS. La procedura guidata Create-key applica una key policy al passaggio Review: se lì aggiungi l'ID account di Anthropic 915198916910 sotto i permessi di utilizzo della chiave, la policy generata concede all'intero account Anthropic azioni più ampie (come kms:ReEncrypt* e kms:GenerateDataKey*) senza alcuna condizione EncryptionContext, e la validazione avrebbe comunque successo. Per evitare di lasciare una chiave eccessivamente permissiva, completa la procedura guidata solo con i permessi amministrativi, quindi apri la scheda Key policy della chiave e sostituisci il JSON con la policy limitata al ruolo mostrata in precedenza (le tre dichiarazioni limitate al ruolo anthropic-cmek-client-us, con la condizione EncryptionContext).

    Procedura guidata Create key di AWS KMS al passaggio Configure key, con tipo di chiave Symmetric, utilizzo della chiave Encrypt and decrypt e Single-Region key selezionati.
    Configure key (configura la chiave): symmetric (simmetrica), encrypt and decrypt (crittografa e decrittografa), single-region key (chiave a singola regione).
    Passaggio Add labels di AWS KMS con un alias anthropic-cmek e una descrizione Anthropic CMEK.
    Aggiungi un alias e una descrizione per la chiave.
    Passaggio Define key administrative permissions di AWS KMS che elenca i ruoli IAM che possono amministrare la chiave.
    Define key administrative permissions (definisci i permessi amministrativi della chiave), facoltativo. Il tuo account mantiene il pieno controllo amministrativo.
    Passaggio Define key usage permissions di AWS KMS con l'ID account di Anthropic inserito sotto Other AWS accounts.
    Non aggiungere qui l'ID account di Anthropic. Questo passaggio della procedura guidata produce una policy eccessivamente permissiva. Lascia vuoti i permessi di utilizzo (usage permissions) e modifica il JSON della Key policy dopo la creazione (vedi la key policy precedente).

Registra la chiave con Anthropic

Il modo in cui registri la chiave dipende dal prodotto che usi.

  1. Registra la chiave con Anthropic

    Crea una configurazione di chiave esterna tramite l'Admin API.

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    display_name="<friendly-name>",
    geo="us",
    provider_config={"type": "aws", "kms_arn": "<key-arn-from-create-key-step>"},
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    La risposta contiene l'ID della chiave esterna:

    {
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

  2. Valida la chiave

    Avvia un ciclo completo di crittografia e decrittografia sulla tua chiave.

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    Una risposta riuscita ha questo aspetto:

    { "type": "external_key_validation", "status": "success", "error": null }

    Se la validazione fallisce, le cause comuni sono:

    • Mancata corrispondenza del contesto di crittografia: La validazione fallisce mentre il traffico dati funziona (o viceversa) con un'opaca AccessDeniedException quando una condizione kms:EncryptionContext:anthropic:compartment_uuid consente solo uno dei due valori che Anthropic invia. La validazione invia l'UUID composto da tutti zeri (00000000-0000-0000-0000-000000000000); il traffico reale invia l'ID compartimento del workspace collegato. Verifica che la condizione elenchi entrambi. Per escludere del tutto la condizione, rimuovi temporaneamente il blocco Condition dalla dichiarazione AllowAnthropicCMEKCrypto e riesegui la validazione.
    • Resource control policy (RCP): Se la tua organizzazione AWS ha una RCP che nega le operazioni KMS quando aws:PrincipalOrgID non corrisponde alla tua organizzazione, questa blocca il ruolo cross-account di Anthropic. La RCP necessita di un'eccezione per questa chiave o per l'ARN del ruolo di Anthropic. Le service control policy non si applicano qui, perché non vengono valutate per i principal esterni che effettuano chiamate tramite policy basate sulle risorse.
    • Accesso concesso tramite IAM invece che tramite la key policy: L'accesso KMS cross-account deve essere concesso nella key policy stessa, non tramite una policy IAM nel tuo account. Verifica con aws kms get-key-policy --key-id <id> --policy-name default.
    • Mancata corrispondenza della regione: Verifica che la regione della chiave sia una di quelle in cui Anthropic opera per il livello geografico che hai configurato.

  3. Collega la chiave a un workspace

    Una volta validata la chiave, collegala a un nuovo workspace prima di inviare qualsiasi richiesta a quel workspace. Per un workspace che riceve già richieste, la chiave può richiedere fino a un giorno per entrare in vigore.

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Configurare CMEK su Claude Platform on AWS

Su Claude Platform on AWS, CMEK usa solo chiavi AWS KMS, e la configurazione differisce dalle sezioni precedenti nei seguenti modi:

  • Principal: La tua key policy concede l'accesso al service principal AWS aws-external-anthropic.amazonaws.com. Il ruolo IAM e l'ID account di Anthropic non vengono usati, quindi l'ARN per Anthropic non si applica.
  • Requisiti della chiave: La chiave deve essere una chiave KMS simmetrica con utilizzo encrypt and decrypt, single-region, e nello stesso account AWS e nella stessa regione del workspace a cui la colleghi. Le chiavi cross-account non sono supportate: la chiave deve trovarsi nell'account AWS che ospita la tua organizzazione. Le chiavi multi-region (ID chiave che iniziano con mrk-) e gli ARN di alias vengono rifiutati quando registri la chiave; usa l'ARN della chiave.
  • Nessun passaggio di validazione separato: A parte questi controlli sull'ARN della chiave al momento della registrazione, la chiave viene validata quando la colleghi a un workspace. La chiamata di collegamento esegue un ciclo di crittografia/decrittografia sulla chiave con l'ID compartimento di quel workspace come contesto di crittografia, quindi un problema nella key policy emerge al momento del collegamento anziché alla registrazione. A differenza della policy di Claude Platform mostrata in precedenza in questa pagina, una condizione EncryptionContext non necessita quindi di alcuna voce con tutti zeri.
  • Dove gestisci le chiavi: Registra e collega le chiavi nella Claude Console, dopo aver effettuato l'accesso tramite AWS con il ruolo Admin. Gli endpoint delle chiavi esterne sono disponibili anche su Claude Platform on AWS, autorizzati tramite azioni IAM; lì, una chiave è identificata dal suo ARN della chiave KMS anziché da un ID ekey_.

Prerequisiti

  • L'account AWS che ospita la tua organizzazione Claude Platform on AWS, con i permessi per creare chiavi KMS e impostare key policy (kms:CreateKey e kms:PutKeyPolicy).
  • Il ruolo Admin nella Claude Console per Claude Platform on AWS. Consulta Usare la Claude Console.
  • Per il principal IAM con cui accedi alla Claude Console: oltre a aws-external-anthropic:AssumeConsole, le azioni IAM per le operazioni che esegui lì, perché la pagina Encryption keys e il collegamento delle chiavi passano attraverso il gateway AWS. Registrare una chiave corrisponde a RegisterKey (con ListKeys e GetKey per visualizzare le registrazioni), e collegarne una corrisponde a UpdateWorkspace o CreateWorkspace. Le azioni delle chiavi esterne (e CreateWorkspace) hanno ambito a livello di account, quindi concedile su Resource: "*"; una policy limitata agli ARN dei workspace non le include.
  • Per il principal IAM che collega la chiave a un workspace (l'identità con cui hai effettuato l'accesso alla Claude Console): kms:DescribeKey, kms:Encrypt e kms:Decrypt sulla chiave. L'accesso del tuo principal alla chiave viene verificato quando la colleghi, in aggiunta a quello del service principal.
  • Facoltativo, per il selettore di chiavi nella Claude Console: kms:ListKeys e kms:DescribeKey per il principal con cui accedi. Senza di essi, incolla invece l'ARN della chiave.

Crea la chiave KMS

La key policy ha tre dichiarazioni: la dichiarazione di amministratore root del tuo account; una dichiarazione che consente al service principal di Claude Platform on AWS di crittografare, decrittografare e generare chiavi dati; e una dichiarazione separata per kms:DescribeKey. Entrambe le dichiarazioni del service principal includono una condizione aws:SourceArn consigliata: il servizio chiama la tua chiave per conto di un workspace specifico e passa l'ARN di quel workspace come source ARN, quindi il pattern mostrato limita la concessione ai workspace nel tuo account AWS. DescribeKey è concessa separatamente perché non ha un parametro EncryptionContext, quindi una condizione EncryptionContext su quell'azione negherebbe sempre l'accesso.

Se prevedi di usare la condizione facoltativa EncryptionContext mostrata qui, crea prima il workspace (senza una chiave) e copia il suo ID compartimento dalla Claude Console sotto Workspace > Security, sotto Encryption key (il campo Compartment ID), oppure dal campo compartment_id restituito dall'endpoint Get Workspace. Sostituiscilo a <compartment-uuid>. Altrimenti, elimina la voce StringEquals dal blocco Condition di quella dichiarazione e mantieni la voce ArnLike.

export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)

aws kms create-key \
  --region <workspace-region> \
  --description "Anthropic CMEK (Claude Platform on AWS)" \
  --key-usage ENCRYPT_DECRYPT \
  --policy "{
    \"Version\": \"2012-10-17\",
    \"Statement\": [
      {
        \"Sid\": \"AccountRootAdmin\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},
        \"Action\": \"kms:*\",
        \"Resource\": \"*\"
      },
      {
        \"Sid\": \"AllowClaudePlatformOnAWSCrypto\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},
        \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\", \"kms:GenerateDataKey\"],
        \"Resource\": \"*\",
        \"Condition\": {
          \"ArnLike\": {
            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"
          },
          \"StringEquals\": {
            \"kms:EncryptionContext:anthropic:compartment_uuid\": [
              \"<compartment-uuid>\"
            ]
          }
        }
      },
      {
        \"Sid\": \"AllowClaudePlatformOnAWSDescribe\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},
        \"Action\": \"kms:DescribeKey\",
        \"Resource\": \"*\",
        \"Condition\": {
          \"ArnLike\": {
            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"
          }
        }
      }
    ]
  }"

Annota KeyMetadata.Arn dall'output. Ti servirà quando registri la chiave.

Entrambe le condizioni sono un rafforzamento facoltativo, e si combinano. La condizione aws:SourceArn può essere scritta prima che esista qualsiasi workspace; per vincolare la chiave a workspace specifici invece che all'intero account, elenca i loro ARN completi di workspace al posto del pattern con wildcard, e per iniziare senza di essa, elimina la voce ArnLike da entrambe le dichiarazioni del service principal (rimuovendo un blocco Condition che questo lascia vuoto). Anche la condizione EncryptionContext è facoltativa. Ogni chiamata di crittografia, decrittografia e chiave dati effettuata per un workspace, incluso il controllo al momento del collegamento, include l'ID compartimento di quel workspace come anthropic:compartment_uuid, quindi la condizione elenca l'ID compartimento di ciascun workspace a cui colleghi la chiave e non necessita di alcuna voce con tutti zeri. Aggiungerla vincola la chiave ai workspace che elenchi anche a livello IAM. Poiché un ID compartimento esiste solo una volta che esiste il suo workspace, l'ordine è: crea il workspace, inserisci il suo ID compartimento nella condizione (alla creazione della chiave, o in seguito con kms:PutKeyPolicy), quindi collega la chiave. Prima di collegare la chiave a ciascun workspace aggiuntivo, aggiungi l'ID compartimento di quel workspace nello stesso modo. Per iniziare senza di essa, elimina la voce StringEquals dal blocco Condition della dichiarazione AllowClaudePlatformOnAWSCrypto; se la aggiungi in seguito, includi l'ID compartimento di ogni workspace a cui la chiave è già collegata.

Puoi anche creare la chiave dalla AWS Console: scegli una chiave simmetrica con utilizzo della chiave encrypt and decrypt, una chiave single-region e origine del materiale della chiave KMS, nella regione del workspace. Lascia vuoti i permessi di utilizzo della chiave nella procedura guidata Create-key, quindi apri la scheda Key policy della chiave e sostituisci il JSON con la policy mostrata qui.

Registra e collega la chiave

  1. Registra la chiave

    Nella Claude Console, apri Settings > Encryption keys e fai clic su Add key. Inserisci un nome visualizzato, quindi scegli la chiave dal selettore di chiavi oppure scegli Enter ARN manually e incolla l'ARN della chiave, e fai clic su Add. La chiave deve trovarsi nell'account AWS che ospita la tua organizzazione; le chiavi cross-account non sono supportate. Il selettore elenca le chiavi abilitate, gestite dal cliente, simmetriche e single-region nel tuo account in una delle regioni della tua organizzazione; per una chiave che il selettore non elenca, inserisci l'ARN. Elenca le chiavi solo se il principal con cui hai effettuato l'accesso può chiamare kms:ListKeys e kms:DescribeKey.

  2. Collega la chiave a un workspace

    Collega la chiave a un nuovo workspace prima di inviare qualsiasi richiesta a quel workspace. Per un workspace che riceve già richieste, la chiave può richiedere fino a un giorno per entrare in vigore. Nella Claude Console, apri il workspace e, sotto Security, seleziona la chiave in Encryption key, salva e conferma. Puoi anche selezionare una chiave quando crei un workspace nella Claude Console, ma solo se la tua key policy non nomina ancora workspace specifici (nessuna condizione EncryptionContext, e il pattern aws:SourceArn a livello di account anziché ARN di singoli workspace), perché l'ID del workspace e l'ID compartimento vengono assegnati alla creazione. Una volta collegata, la chiave di un workspace non può essere modificata.

    È in questo momento che la chiave viene validata: la chiamata di collegamento verifica l'accesso del tuo principal alla chiave ed esegue un ciclo di crittografia/decrittografia su di essa con l'ID compartimento del workspace come contesto di crittografia, quindi un problema con la key policy o con i permessi del tuo principal emerge come errore su quella chiamata. Se il collegamento fallisce con un errore di accesso KMS, verifica quanto segue:

    • La key policy nomina il service principal aws-external-anthropic.amazonaws.com e concede kms:Encrypt, kms:Decrypt e kms:GenerateDataKey, più kms:DescribeKey in una dichiarazione separata che non ha alcuna condizione EncryptionContext.
    • La condizione aws:SourceArn corrisponde all'ARN di questo workspace (il tuo ID account, e il workspace se hai elencato ARN specifici), e qualsiasi condizione EncryptionContext include l'ID compartimento di questo workspace.
    • La chiave è abilitata, single-region, e nello stesso account AWS e nella stessa regione del workspace.
    • Il principal con cui hai effettuato l'accesso ha kms:DescribeKey, kms:Encrypt e kms:Decrypt sulla chiave.
    • Nessuna service control policy o resource control policy nella tua organizzazione AWS impedisce al service principal o al tuo principal di usare la chiave.
    • Se la policy sembra corretta e il collegamento fallisce comunque, trova l'evento kms: negato in CloudTrail nell'account della chiave (mostra il principal chiamante e, per le chiamate crittografiche, il contesto di crittografia), quindi riprova con la condizione aws:SourceArn temporaneamente rimossa per distinguere una mancata corrispondenza del source ARN da una mancata corrispondenza del contesto di crittografia.

Terraform

Per i deployment infrastructure-as-code, gli stessi passaggi corrispondono al provider aws con le risorse aws_kms_key e aws_kms_alias.

Was this page helpful?