Aggiornamento dei provider di chiaviAWS KMS principali

Per migrare alla versione più recente 1. versione x diAWS Encryption SDK, e quindi alla versione 2.0. x o versione successiva, è necessario sostituire i provider di chiaviAWS KMS master esistenti con provider di chiavi master creati esplicitamente in modalità rigorosa o modalità discovery. I vecchi fornitori di chiavi master sono obsoleti nella versione 1.7. x e rimosso nella versione 2.0. x. Questa modifica è necessaria per le applicazioni e gli script che utilizzano l'interfaccia a riga di SDK di crittografia AWS per Javacomando SDK di crittografia AWS per Python, e la CLI diAWS crittografia. Gli esempi in questa sezione ti mostreranno come aggiornare il codice.

Nota

In Python, attiva gli avvisi di deprecazione. Questo ti aiuterà a identificare le parti del codice che devi aggiornare.

Se si utilizza una chiaveAWS KMS master (non un provider di chiavi master), è possibile saltare questo passaggio. AWS KMSle chiavi master non sono obsolete o rimosse. Crittografano e decifrano solo con le chiavi di wrapping specificate.

Gli esempi in questa sezione si concentrano sugli elementi del codice che è necessario modificare. Per un esempio completo del codice aggiornato, consulta la sezione Esempi del GitHub repository relativo al tuo linguaggio di programmazione. Inoltre, questi esempi utilizzano in genere gli ARN chiave per rappresentareAWS KMS keys. Quando si crea un provider di chiave master per la crittografia, è possibile utilizzare qualsiasi identificatore diAWS KMS chiave valido per rappresentare unAWS KMS key. Quando si crea un provider di chiavi master per la decrittografia, è necessario utilizzare una chiave ARN.

Ulteriori informazioni sulla migrazione

Per tuttiAWS Encryption SDK gli utenti, scopri come impostare la tua politica di impegno inImpostazione della politica di impegno.

PerSDK di crittografia AWS per C gliSDK di crittografia AWS per JavaScript utenti finali, scopri un aggiornamento opzionale dei portachiavi inAggiornamento in corsoAWS KMSportachiavi.

Migrazione alla modalità

Dopo l'aggiornamento alla versione più recente 1. versione x diAWS Encryption SDK, sostituisci i tuoi vecchi provider di chiavi master con fornitori di chiavi master in modalità rigorosa. In modalità rigorosa, è necessario specificare le chiavi di wrapping da utilizzare durante la crittografia e la decrittografia. AWS Encryption SDKUtilizza solo le chiavi di wrapping specificate. I provider di chiavi master obsolete possono decrittografare i dati utilizzando qualsiasiAWS KMS key chiave di dati crittografata, ancheAWS KMS keys in diverse regioniAccount AWS e regioni.

I fornitori di chiavi principali in modalità rigorosa vengono introdotti nellaAWS Encryption SDK versione 1.7. x. Sostituiscono i vecchi fornitori di chiavi master, che sono obsoleti nella versione 1.7. x e rimosso in 2.0. x. L'utilizzo di provider di chiavi master in modalità rigorosa è unaAWS Encryption SDK buona pratica.

Il codice seguente crea un provider di chiavi master in modalità rigorosa che è possibile utilizzare per la crittografia e la decrittografia.

Java

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.6.2 o precedente diSDK di crittografia AWS per Java.

Questo codice utilizza ilKmsMasterKeyProvider.builder() metodo per creare un'istanza di un provider di chiaviAWS KMS master che ne utilizza unaAWS KMS key come chiave di wrapping.

// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .withKeysForEncryption(awsKmsKey)
    .build();

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.7. x o versione successiva delSDK di crittografia AWS per Java. Per un esempio completo, vedere BasicEncryptionExample.java.

Builder.withKeysForEncryption()I metodiBuilder.build() and utilizzati nell'esempio precedente sono obsoleti nella versione 1.7. x e vengono rimossi dalla versione 2.0. x.

Per l'aggiornamento a un provider di chiavi master in modalità rigorosa, questo codice sostituisce le chiamate ai metodi obsoleti con una chiamata al nuovoBuilder.buildStrict() metodo. Questo esempio ne specifica unaAWS KMS key come chiave di avvolgimento, ma ilBuilder.buildStrict() metodo può accettare un elenco di più chiaviAWS KMS keys.

// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your Account AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);

Python

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.4.1 diSDK di crittografia AWS per Python. Questo codice utilizzaKMSMasterKeyProvider, che è obsoleto nella versione 1.7. x e rimosso dalla versione 2.0. x. Durante la decrittografia, utilizza qualsiasi chiave di dati crittografata indipendentemente daAWS KMS key quellaAWS KMS keys specificata.

Nota che nonKMSMasterKey è obsoleto o rimosso. Durante la crittografia e la decrittografia, utilizza soloAWS KMS key i dati specificati.

# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"

aws_kms_master_key_provider = KMSMasterKeyProvider(
   key_ids=[key_1, key_2]
)

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.7. x delSDK di crittografia AWS per Python. Per un esempio completo, vedere basic_encryption.py.

Per l'aggiornamento a un provider di chiavi master in modalità rigorosa, questo codice sostituisce la chiamata aKMSMasterKeyProvider() con una chiamata aStrictAwsKmsMasterKeyProvider().

# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your Account AWS
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"

aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
    key_ids=[key_1, key_2]
)

AWS Encryption CLI

Questo esempio mostra come crittografare e decrittografare utilizzando laAWS Encryption CLI versione 1.1.7 o precedente.

Nella versione 1.1.7 e precedenti, durante la crittografia, si specificano una o più chiavi master (o chiavi di wrapping), ad esempio unaAWS KMS key. Durante la decrittografia, non è possibile specificare alcuna chiave di wrapping a meno che non si utilizzi un provider di chiavi master personalizzato. La CLI diAWS crittografia può utilizzare qualsiasi chiave di wrapping che crittografi una chiave di dati.

\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --master-keys key=$keyArn \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext               
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .  

Questo esempio mostra come crittografare e decrittografare utilizzando laAWS Encryption CLI versione 1.7. x o versioni successive. Per esempi completi, vedereEsempi diAWSCLI di crittografia.

Il--master-keys parametro è obsoleto nella versione 1.7. x e rimosso nella versione 2.0. x. È stato sostituito dal--wrapping-keys parametro by, necessario nei comandi di crittografia e decrittografia. Questo parametro supporta la modalità rigorosa e la modalità di rilevamento. La modalità rigorosa è unaAWS Encryption SDK procedura consigliata che garantisce l'utilizzo della chiave di wrapping desiderata.

Per passare alla modalità rigorosa, utilizzate l'attributo key del--wrapping-keys parametro per specificare una chiave di wrapping durante la crittografia e la decrittografia.

\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext               
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

Migrazione alla modalità di rilevamento

A partire dalla versione 1.7. x, è consigliabile utilizzare la modalità rigorosa per i provider di chiaviAWS KMS master, ovvero specificare le chiavi di wrapping durante la crittografia e la decrittografia.AWS Encryption SDK È necessario specificare sempre le chiavi di wrapping durante la crittografia. Ma ci sono situazioni in cui specificare gli ARN chiaveAWS KMS keys per la decrittografia non è pratico. Ad esempio, se si utilizzano alias per identificareAWS KMS keys durante la crittografia, si perde il vantaggio degli alias se è necessario elencare gli ARN chiave durante la decrittografia. Inoltre, poiché i provider di chiavi master in modalità discovery si comportano come i provider di chiavi master originali, potresti utilizzarli temporaneamente come parte della tua strategia di migrazione e quindi passare ai provider di chiavi master in modalità rigorosa in un secondo momento.

In casi come questo, puoi utilizzare i provider di chiavi master in modalità discovery. Questi provider di chiavi master non consentono di specificare le chiavi di wrapping, quindi non è possibile utilizzarli per la crittografia. Durante la decrittografia, possono utilizzare qualsiasi chiave di wrapping che crittografi una chiave di dati. Ma a differenza dei provider di chiavi master legacy, che si comportano allo stesso modo, li crei esplicitamente in modalità discovery. Quando si utilizzano provider di chiavi master in modalità discovery, è possibile limitare le chiavi di wrapping che possono essere utilizzate a quelle in particolareAccount AWS. Questo filtro di rilevamento è facoltativo, ma è una procedura consigliata. Per informazioni suAWS partizioni e account, consulta Amazon Resource Names nel Riferimenti generali di AWS.

Gli esempi seguenti creano un provider di chiaviAWS KMS master in modalità rigorosa per la crittografia e un provider di chiaviAWS KMS master in modalità discovery per la decrittografia. Il provider di chiavi master in modalità discovery utilizza un filtro di rilevamento per limitare le chiavi di wrapping utilizzate per la decrittografia allaaws partizione e a un esempio particolareAccount AWS. Sebbene il filtro dell'account non sia necessario in questo esempio molto semplice, è una buona pratica molto utile quando un'applicazione crittografa i dati e un'altra applicazione li decrittografa.

Java

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.7. x o versione successiva delSDK di crittografia AWS per Java. Per un esempio completo, vedere DiscoveryDecryptionExample.java.

Per creare un'istanza di un provider di chiavi master in modalità rigorosa per la crittografia, questo esempio utilizza ilBuilder.buildStrict() metodo. Per creare un'istanza di un provider di chiavi master in modalità discovery per la decrittografia, utilizza ilBuilder.buildDiscovery() metodo. IlBuilder.buildDiscovery() metodo accetta un valoreDiscoveryFilter che limita l'AWS KMS keysaccessoAWS Encryption SDK allaAWS partizione e agli account specificati.

// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your Account AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";

KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);

// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));

KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
    .buildDiscovery(accounts);

Python

Questo esempio rappresenta il codice di un'applicazione che utilizza la versione 1.7. x o versione successiva delSDK di crittografia AWS per Python. Per un esempio completo, vedere discovery_kms_provider.py.

Per creare un provider di chiavi master in modalità rigorosa per la crittografia, questo esempio utilizzaStrictAwsKmsMasterKeyProvider. Per creare un provider di chiavi master in modalità discovery per la decrittografia, utilizzaDiscoveryAwsKmsMasterKeyProvider unDiscoveryFilter che limita ilAWS Encryption SDK numero aAWS KMS keys nellaAWS partizione e negli account specificati.

# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your Account AWS.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"

aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
    key_ids=[key_1, key_2]
)

# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
    partition="aws",
    account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
        discovery_filter=accounts
)

AWS Encryption CLI

Questo esempio mostra come crittografare e decrittografare utilizzando laAWS Encryption CLI versione 1.7. x o versioni successive. A partire dalla versione 1.7. x, il--wrapping-keys parametro è necessario per la crittografia e la decrittografia. Il--wrapping-keys parametro supporta la modalità rigorosa e la modalità di rilevamento. Per esempi completi, vedereEsempi diAWSCLI di crittografia.

Durante la crittografia, questo esempio specifica una chiave di wrapping, che è obbligatoria. Durante la decrittografia, sceglie esplicitamente la modalità di rilevamento utilizzando l'discoveryattributo del--wrapping-keys parametro con un valore ditrue.

Per limitare le chiavi di wrapping cheAWS Encryption SDK possono essere utilizzate in modalità discovery a quelle in particolareAccount AWS, questo esempio utilizza glidiscovery-account attributidiscovery-partition and del--wrapping-keys parametro. Questi attributi opzionali sono validi solo quando l'discoveryattributo è impostato sutrue. È necessario utilizzarediscovery-account gli attributidiscovery-partition and insieme; nessuno dei due è valido da solo.

\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias

\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyAlias \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values           
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \
                                     discovery-partition=aws \
                                     discovery-account=111122223333 \
                                     discovery-account=444455556666 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .