Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Migrazione del tuo AWS Encryption SDK
AWS Encryption SDK Supporta più [implementazioni di linguaggi di programmazione](programming-languages.md) interoperabili, ognuna delle quali è sviluppata in un repository open source su. GitHub Come [procedura ottimale](best-practices.md), si consiglia di utilizzare la versione più recente di per ogni lingua. AWS Encryption SDK
È possibile eseguire l'aggiornamento dalla versione 2.0 in tutta sicurezza. *x* o versione successiva o AWS Encryption SDK alla versione più recente. Tuttavia, la 2.0. la versione *x* di AWS Encryption SDK introduce nuove importanti funzionalità di sicurezza, alcune delle quali stanno apportando modifiche sostanziali. Per eseguire l'aggiornamento da versioni precedenti alla 1.7. *x* alle versioni 2.0. *x* e versioni successive, è necessario prima eseguire l'aggiornamento alla versione 1 più recente. versione *x*. Gli argomenti di questa sezione sono progettati per aiutarti a comprendere le modifiche, selezionare la versione corretta per l'applicazione e migrare in modo sicuro e corretto alle versioni più recenti di. AWS Encryption SDK
Per informazioni sulle versioni più importanti di AWS Encryption SDK, vedere. [Versioni di AWS Encryption SDK](about-versions.md)
**Importante**
Non eseguire l'aggiornamento direttamente da una versione precedente alla 1.7. *x* alla versione 2.0. *x* o versione successiva senza prima eseguire l'aggiornamento alla versione 1 più recente. *versione x.* Se esegui l'aggiornamento direttamente alla versione 2.0. *x* o versione successiva e abiliti immediatamente tutte le nuove funzionalità, AWS Encryption SDK non saranno in grado di decrittografare il testo cifrato crittografato con le versioni precedenti di. AWS Encryption SDK
**Nota**
La prima versione di per.NET è AWS Encryption SDK la versione 3.0. *x*. Tutte le versioni di AWS Encryption SDK for .NET supportano le best practice di sicurezza introdotte nella versione 2.0. *x* di AWS Encryption SDK. È possibile eseguire l'aggiornamento alla versione più recente in tutta sicurezza senza modifiche al codice o ai dati.
AWS CLI di crittografia: durante la lettura di questa guida alla migrazione, utilizza la versione 1.7. *x* istruzioni di migrazione per AWS Encryption CLI 1.8. *x* e usa la versione 2.0. *x* istruzioni di migrazione per AWS Encryption CLI 2.1. *x.* Per informazioni dettagliate, vedi [Versioni della CLI AWS di crittografia](crypto-cli-versions.md).
Le nuove funzionalità di sicurezza sono state originariamente rilasciate nelle versioni 1.7 di AWS Encryption CLI. *x* e 2.0. *x*. Tuttavia, AWS Encryption CLI versione 1.8. *x* sostituisce la versione 1.7. *x* e AWS Encryption CLI 2.1. *x* sostituisce 2.0. *x.* Per i dettagli, [consulta l'avviso di sicurezza](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) pertinente nel [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repository su. GitHub
**Nuovi utenti**
Se non conosci il AWS Encryption SDK, installa la versione più recente di AWS Encryption SDK per il tuo linguaggio di programmazione. I valori predefiniti abilitano tutte le funzionalità di sicurezza di AWS Encryption SDK, tra cui la crittografia con firma, la derivazione delle [chiavi e l'impegno delle chiavi](concepts.md#key-commitment) di. AWS Encryption SDK
**Utenti attuali**
Ti consigliamo di eseguire l'aggiornamento dalla versione corrente all'ultima versione disponibile il prima possibile. Tutto 1. Le versioni *x* di AWS Encryption SDK sono in [end-of-support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) di sviluppo, così come le versioni successive in alcuni linguaggi di programmazione. Per informazioni dettagliate sullo stato del supporto e della manutenzione di AWS Encryption SDK nel linguaggio di programmazione in uso, vedere[Support e manutenzione](introduction.md#support).
AWS Encryption SDK versioni 2.0. *x* e versioni successive forniscono nuove funzionalità di sicurezza per proteggere i dati. Tuttavia, AWS Encryption SDK la versione 2.0. *x* include modifiche sostanziali che non sono compatibili con le versioni precedenti. Per garantire una transizione sicura, inizia migrando dalla versione corrente alla versione più recente 1. *x* nel tuo linguaggio di programmazione. Quando il tuo ultimo 1. la versione *x* è completamente implementata e funziona correttamente, puoi migrare in sicurezza alle versioni 2.0. *x e versioni* successive. Questo [processo in due fasi](migration-guide.md) è fondamentale soprattutto per le applicazioni distribuite.
*Per ulteriori informazioni sulle funzionalità di AWS Encryption SDK sicurezza alla base di queste modifiche, consulta [Crittografia lato client migliorata: impegno esplicito KeyIds e fondamentale nel](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/) blog sulla sicurezza.AWS *
Cerchi aiuto per l'utilizzo di con? SDK di crittografia AWS per Java AWS SDK for Java 2.x Per informazioni, consulta [Prerequisiti](java.md#java-prerequisites).
**Topics**
+ [Come migrare e distribuire il AWS Encryption SDK](migration-guide.md)
+ [Aggiornamento dei provider di chiavi AWS KMS principali](migrate-mkps-v2.md)
+ [Aggiornamento dei AWS KMS portachiavi](migrate-keyrings-v2.md)
+ [Impostazione della politica di impegno](migrate-commitment-policy.md)
+ [Risoluzione dei problemi relativi alla migrazione alle versioni più recenti](troubleshooting-migration.md)
# Come migrare e distribuire il AWS Encryption SDK
Durante la migrazione da una AWS Encryption SDK versione precedente alla 1.7. *x* alla versione 2.0. *x* o versione successiva, è necessario passare in modo sicuro alla crittografia con [impegno chiave](concepts.md#key-commitment). In caso contrario, l'applicazione incontrerà testi cifrati che non potrà decifrare. Se si utilizzano provider di chiavi AWS KMS master, è necessario eseguire l'aggiornamento a nuovi costruttori che creino provider di chiavi master in modalità rigorosa o in modalità di scoperta.
**Nota**
Questo argomento è stato progettato per gli utenti che effettuano la migrazione dalle versioni precedenti AWS Encryption SDK alla versione 2.0. *x* o versione successiva. Se non conosci la versione più recente AWS Encryption SDK, puoi iniziare a utilizzare immediatamente l'ultima versione disponibile con le impostazioni predefinite.
Per evitare una situazione critica in cui non è possibile decrittografare il testo cifrato che è necessario leggere, si consiglia di eseguire la migrazione e la distribuzione in più fasi distinte. Verifica che ogni fase sia completa e completamente implementata prima di iniziare la fase successiva. Ciò è particolarmente importante per le applicazioni distribuite con più host.
## Fase 1: aggiorna l'applicazione alla versione più recente 1. versione *x*
Aggiornamento alla versione più recente 1. versione *x* per il tuo linguaggio di programmazione. Esegui un test accurato, implementa le modifiche e conferma che l'aggiornamento si sia propagato a tutti gli host di destinazione prima di iniziare la fase 2.
**Importante**
Verifica che la versione più recente sia 1. la versione *x* è la versione 1.7. *x* o versione successiva di AWS Encryption SDK.
L'ultimo 1. le versioni *x* di AWS Encryption SDK sono retrocompatibili con le versioni precedenti di AWS Encryption SDK e successive compatibili con le versioni 2.0. *x* e versioni successive. Includono le nuove funzionalità presenti nella versione 2.0. *x*, ma include impostazioni predefinite sicure progettate per questa migrazione. Consentono di aggiornare i fornitori di chiavi AWS KMS principali, se necessario, e di utilizzare in modo completo suite di algoritmi in grado di decrittografare il testo cifrato con l'impegno di una chiave.
+ Sostituisci gli elementi obsoleti, inclusi i costruttori per i fornitori di chiavi master legacy. AWS KMS In [Python](https://docs.python.org/3/library/warnings.html), assicurati di attivare gli avvisi di deprecazione. Elementi di codice obsoleti nell'ultima versione 1. le versioni *x* vengono rimosse dalle versioni 2.0. *x* e versioni successive.
+ Imposta esplicitamente la tua politica di impegno su`ForbidEncryptAllowDecrypt`. Sebbene questo sia l'unico valore valido nell'ultimo 1. *x* versioni, questa impostazione è richiesta quando si utilizza quella APIs introdotta in questa versione. Impedisce all'applicazione di rifiutare il testo cifrato crittografato senza l'impegno di una chiave durante la migrazione alla versione 2.0. *x e versioni successive.* Per informazioni dettagliate, vedi [Impostazione della politica di impegno](migrate-commitment-policy.md).
+ Se si utilizzano provider di chiavi AWS KMS master, è necessario aggiornare i provider di chiavi master legacy con provider di chiavi master che supportano la *modalità rigorosa* e la *modalità di rilevamento*. Questo aggiornamento è necessario per SDK di crittografia AWS per Java SDK di crittografia AWS per Python, e la CLI di AWS crittografia. Se si utilizzano provider di chiavi principali in modalità di rilevamento, si consiglia di implementare il filtro di rilevamento che limita le chiavi di wrapping utilizzate in particolare a tali provider. Account AWS Questo aggiornamento è facoltativo, ma è una [best practice](best-practices.md) che consigliamo. Per informazioni dettagliate, vedi [Aggiornamento dei provider di chiavi AWS KMS principali](migrate-mkps-v2.md).
+ Se utilizzi [portachiavi AWS KMS Discovery](use-kms-keyring.md#kms-keyring-discovery), ti consigliamo di includere un filtro di rilevamento che limiti le chiavi di avvolgimento utilizzate nella decrittografia a quelle in particolare. Account AWS Questo aggiornamento è facoltativo, ma è una [procedura consigliata](best-practices.md). Per informazioni dettagliate, vedi [Aggiornamento dei AWS KMS portachiavi](migrate-keyrings-v2.md).
## Fase 2: aggiorna l'applicazione alla versione più recente
Dopo aver distribuito la versione più recente 1. versione *x* con successo su tutti gli host, è possibile eseguire l'aggiornamento alle versioni 2.0. *x* e versioni successive. Versione 2.0. *x* include modifiche sostanziali per tutte le versioni precedenti di AWS Encryption SDK. Tuttavia, se si apportano le modifiche al codice consigliate nella Fase 1, è possibile evitare errori durante la migrazione alla versione più recente.
Prima di eseguire l'aggiornamento alla versione più recente, verificate che la vostra politica di impegno sia impostata in modo coerente. `ForbidEncryptAllowDecrypt` Quindi, a seconda della configurazione dei dati, puoi migrare secondo i tuoi ritmi `RequireEncryptAllowDecrypt` e poi all'impostazione predefinita,`RequireEncryptRequireDecrypt`. Consigliamo una serie di passaggi di transizione come il seguente schema.
1. Inizia con la tua [politica di impegno](migrate-commitment-policy.md) impostata su`ForbidEncryptAllowDecrypt`. AWS Encryption SDK Può decrittografare i messaggi con un impegno chiave, ma non lo fa ancora con un impegno chiave.
1. Quando sei pronto, aggiorna la tua politica di impegno a. `RequireEncryptAllowDecrypt` AWS Encryption SDK Inizia a crittografare i tuoi dati con [impegno fondamentale](concepts.md#key-commitment). Può decrittografare il testo cifrato con e senza impegno chiave.
Prima di aggiornare la tua politica di impegno a`RequireEncryptAllowDecrypt`, verifica che la tua ultima versione 1. la versione *x* viene distribuita su tutti gli host, inclusi gli host di tutte le applicazioni che decrittografano il testo cifrato prodotto. Versioni della versione precedente alla 1.7. AWS Encryption SDK *x* non è in grado di decrittografare i messaggi crittografati con key commitment.
Questo è anche un buon momento per aggiungere metriche alla vostra applicazione per misurare se state ancora elaborando testo cifrato senza alcun impegno chiave. Questo ti aiuterà a determinare quando è sicuro aggiornare l'impostazione della tua politica di impegno. `RequireEncryptRequireDecrypt` Per alcune applicazioni, come quelle che crittografano i messaggi in una coda Amazon SQS, ciò potrebbe significare attendere abbastanza a lungo prima che tutto il testo cifrato crittografato nelle versioni precedenti venga ricrittografato o eliminato. Per altre applicazioni, come gli oggetti S3 crittografati, potrebbe essere necessario scaricare, crittografare nuovamente e caricare nuovamente tutti gli oggetti.
1. Quando sei sicuro di non avere messaggi crittografati senza l'impegno della chiave, puoi aggiornare la tua politica di impegno a. `RequireEncryptRequireDecrypt` Questo valore garantisce che i tuoi dati siano sempre crittografati e decrittografati con impegno chiave. Questa è l'impostazione predefinita, quindi non è necessario impostarla in modo esplicito, ma è consigliabile. Un'impostazione esplicita [faciliterà il debug](troubleshooting-migration.md) e qualsiasi potenziale ripristino che potrebbe essere necessario se l'applicazione incontra testo cifrato crittografato senza impegno di chiave.
# Aggiornamento dei provider di chiavi AWS KMS principali
Per migrare alla versione più recente 1. versione *x* di e AWS Encryption SDK quindi alla versione 2.0. *x* o versione successiva, è necessario sostituire i provider di chiavi AWS KMS master precedenti con fornitori di chiavi master creati esplicitamente in [*modalità rigorosa o in modalità* di *rilevamento*](about-versions.md#changes-to-mkps). I provider di chiavi master legacy 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 la [SDK di crittografia AWS per Java[SDK di crittografia AWS per Python](python.md)](java.md), e la [CLI di AWS crittografia](crypto-cli.md). Gli esempi in questa sezione ti mostreranno come aggiornare il codice.
**Nota**
In Python, [attiva gli avvisi di deprecazione](https://docs.python.org/3/library/warnings.html). Questo ti aiuterà a identificare le parti del codice che devi aggiornare.
Se utilizzi una chiave AWS KMS master (non un fornitore di chiavi master), puoi saltare questo passaggio. AWS KMS le chiavi master non sono obsolete o rimosse. Crittografano e decrittografano solo con le chiavi di wrapping specificate dall'utente.
Gli esempi di questa sezione si concentrano sugli elementi del codice che è necessario modificare. Per un esempio completo del codice aggiornato, consultate la sezione Esempi del GitHub repository relativo al [linguaggio di programmazione](programming-languages.md) in uso. Inoltre, questi esempi in genere utilizzano la chiave ARNs per rappresentare AWS KMS keys. Quando si crea un provider di chiavi principali per la crittografia, è possibile utilizzare qualsiasi [identificatore di AWS KMS chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) valido per rappresentare un. AWS KMS key Quando si crea un provider di chiavi master per la decrittografia, è necessario utilizzare una chiave ARN.
**Scopri di più sulla migrazione**
Per tutti AWS Encryption SDK gli utenti, scopri come impostare la tua politica di impegno in[Impostazione della politica di impegno](migrate-commitment-policy.md).
Per SDK di crittografia AWS per C gli SDK di crittografia AWS per JavaScript utenti finali, scopri di più su un aggiornamento opzionale dei portachiavi in[Aggiornamento dei AWS KMS portachiavi](migrate-keyrings-v2.md).
**Topics**
+ [Migrazione alla modalità rigorosa](#migrate-mkp-strict-mode)
+ [Migrazione alla modalità di rilevamento](#migrate-mkp-discovery-mode)
## Migrazione alla modalità rigorosa
Dopo l'aggiornamento alla versione più recente 1. versione *x* di AWS Encryption SDK, sostituisci i tuoi provider di chiavi master precedenti con fornitori di chiavi master in modalità rigorosa. In modalità rigorosa, è necessario specificare le chiavi di wrapping da utilizzare per la crittografia e la decrittografia. AWS Encryption SDK Utilizza solo le chiavi di avvolgimento specificate. I provider di chiavi master obsolete possono decrittografare i dati utilizzando qualsiasi chiave AWS KMS key che abbia crittografato una chiave dati, anche in diverse regioni. AWS KMS keys Account AWS
I provider di chiavi principali in modalità rigorosa vengono introdotti nella versione 1.7. AWS Encryption SDK *x*. Sostituiscono i provider di chiavi master legacy, che sono obsoleti nella versione 1.7. *x* e rimosso nella 2.0. *x*. L'utilizzo di provider di chiavi principali in modalità rigorosa è una [procedura AWS Encryption SDK consigliata](best-practices.md).
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 di. SDK di crittografia AWS per Java
Questo codice utilizza il `KmsMasterKeyProvider.builder()` metodo per creare un'istanza di un provider di chiavi AWS KMS master che ne utilizza una AWS 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 in un'applicazione che utilizza la versione 1.7. *x* o versione successiva di SDK di crittografia AWS per Java . Per un esempio completo, consulta [BasicEncryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)
I `Builder.withKeysForEncryption()` metodi `Builder.build()` and utilizzati nell'esempio precedente sono obsoleti nella versione 1.7. *x* e vengono rimossi dalla versione 2.0. *x*.
Per eseguire l'aggiornamento a un provider di chiavi master in modalità rigorosa, questo codice sostituisce le chiamate ai metodi obsoleti con una chiamata al nuovo metodo. `Builder.buildStrict()` Questo esempio ne specifica uno AWS KMS key come chiave di avvolgimento, ma il `Builder.buildStrict()` metodo può accettare un elenco di più elementi. AWS 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 in un'applicazione che utilizza la versione 1.4.1 di. SDK di crittografia AWS per Python Questo codice utilizza`KMSMasterKeyProvider`, che è obsoleto nella versione 1.7. *x* e rimosso dalla versione 2.0. *x*. Durante la decrittografia, utilizza qualsiasi chiave di dati AWS KMS key che ha crittografato una chiave di dati indipendentemente da quanto specificato AWS KMS keys .
Nota che non `KMSMasterKey` è obsoleto o rimosso. Durante la crittografia e la decrittografia, utilizza solo i dati specificati dall'utente. AWS KMS key
```
# 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* di SDK di crittografia AWS per Python. Per un esempio completo, vedere [basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py).
Per eseguire l'aggiornamento a un provider di chiavi master in modalità rigorosa, questo codice sostituisce la chiamata a `KMSMasterKeyProvider()` con una chiamata a`StrictAwsKmsMasterKeyProvider()`.
```
# 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 la Encryption AWS 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 una. AWS 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 di AWS crittografia può utilizzare qualsiasi chiave di wrapping che crittografa una chiave 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 la Encryption AWS CLI versione 1.7. *x o versione successiva.* Per esempi completi, vedere[Esempi di CLI AWS di crittografia](crypto-cli-examples.md).
Il `--master-keys` parametro è obsoleto nella versione 1.7. *x* e rimosso nella versione 2.0. *x*. È stato sostituito dal `--wrapping-keys` parametro by, richiesto nei comandi encrypt e decrypt. Questo parametro supporta la modalità rigorosa e la modalità di rilevamento. La modalità rigorosa è una procedura AWS Encryption SDK consigliata che garantisce l'utilizzo della chiave di wrapping desiderata.
Per eseguire l'aggiornamento 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](best-practices.md) *modalità rigorosa* per i fornitori di chiavi AWS KMS master, ovvero specificare le chiavi di wrapping durante la crittografia e la decrittografia. AWS Encryption SDK È sempre necessario specificare le chiavi di wrapping durante la crittografia. Ma ci sono situazioni in cui specificare la chiave ARNs di decrittografia non è AWS KMS keys pratico. Ad esempio, se si utilizzano alias per l'identificazione AWS KMS keys durante la crittografia, si perde il vantaggio degli alias se è necessario elencare la chiave durante la decrittografia. ARNs Inoltre, poiché i provider di chiavi master in modalità di rilevamento si comportano come i provider di chiavi master originali, è possibile utilizzarli temporaneamente come parte della 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à di scoperta*. Questi fornitori di chiavi master non consentono di specificare chiavi di wrapping, quindi non è possibile utilizzarle per la crittografia. Durante la decrittografia, possono utilizzare qualsiasi chiave di wrapping che ha crittografato una chiave dati. Ma a differenza dei provider di chiavi master legacy, che si comportano allo stesso modo, li crei in modalità di scoperta in modo esplicito. Quando si utilizzano provider di chiavi master in modalità di scoperta, è possibile limitare le chiavi di wrapping che possono essere utilizzate a questi in particolare. Account AWS Questo filtro di rilevamento è facoltativo, ma è una best practice che consigliamo. Per informazioni su AWS partizioni e account, consulta [Amazon Resource Names](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) nel *Riferimenti generali di AWS*.
Gli esempi seguenti creano un provider di chiavi AWS KMS master in modalità rigorosa per la crittografia e un provider di chiavi AWS KMS master in modalità di scoperta per la decrittografia. Il provider di chiavi master in modalità di scoperta utilizza un filtro di rilevamento per limitare le chiavi di wrapping utilizzate per la decrittografia alla partizione e a un esempio particolare. `aws` Account AWS Sebbene il filtro dell'account non sia necessario in questo esempio molto semplice, si tratta di una best practice molto utile quando un'applicazione crittografa i dati e un'altra applicazione decrittografa i dati.
------
#### [ Java ]
Questo esempio rappresenta il codice in un'applicazione che utilizza la versione 1.7. *x* o versione successiva di SDK di crittografia AWS per Java. Per un esempio completo, consulta [DiscoveryDecryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)
Per creare un'istanza di un provider di chiavi master in modalità rigorosa per la crittografia, questo esempio utilizza il metodo. `Builder.buildStrict()` Per creare un'istanza di un provider di chiavi master in modalità di scoperta per la decrittografia, utilizza il metodo. `Builder.buildDiscovery()` Il `Builder.buildDiscovery()` metodo utilizza un valore `DiscoveryFilter` che limita la partizione e AWS Encryption SDK gli AWS KMS keys account specificati AWS .
```
// 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 in un'applicazione che utilizza la versione 1.7. *x* o versione successiva di SDK di crittografia AWS per Python . Per un esempio completo, vedere [discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py).
Per creare un provider di chiavi master in modalità rigorosa per la crittografia, questo esempio utilizza`StrictAwsKmsMasterKeyProvider`. Per creare un provider di chiavi master in modalità di rilevamento per la decrittografia, viene utilizzato `DiscoveryAwsKmsMasterKeyProvider` with AWS Encryption SDK a `DiscoveryFilter` che limita il valore nella AWS partizione e AWS KMS keys 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 la Encryption AWS CLI versione 1.7. *x o versione successiva.* 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, vedere[Esempi di CLI AWS di crittografia](crypto-cli-examples.md).
Durante la crittografia, questo esempio specifica una chiave di wrapping, che è obbligatoria. Durante la decrittografia, sceglie esplicitamente la *modalità di rilevamento* utilizzando l'`discovery`attributo del parametro con un valore di. `--wrapping-keys` `true`
Per limitare le chiavi di wrapping che AWS Encryption SDK possono essere utilizzate in modalità discovery a quelle in particolare Account AWS, questo esempio utilizza gli attributi `discovery-partition` e `discovery-account` del parametro. `--wrapping-keys` Questi attributi opzionali sono validi solo quando l'`discovery`attributo è impostato su. `true` È necessario utilizzare gli `discovery-account` attributi `discovery-partition` e 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 .
```
------
# Aggiornamento dei AWS KMS portachiavi
I AWS KMS portachiavi inclusi in [SDK di crittografia AWS per C](c-language.md), the [AWS Encryption SDK for .NET](dot-net.md) e the [SDK di crittografia AWS per JavaScript](javascript.md)supportano le [migliori pratiche](best-practices.md) in quanto consentono di specificare chiavi di avvolgimento durante la crittografia e la decrittografia. Se si crea un [portachiavi AWS KMS Discovery](use-kms-keyring.md#kms-keyring-discovery), lo si fa in modo esplicito.
**Nota**
La prima versione di per.NET è AWS Encryption SDK la versione 3.0. *x*. Tutte le versioni di AWS Encryption SDK for .NET supportano le best practice di sicurezza introdotte nella versione 2.0. *x* di AWS Encryption SDK. È possibile eseguire l'aggiornamento alla versione più recente in tutta sicurezza senza modifiche al codice o ai dati.
Quando si esegue l'aggiornamento alla versione più recente 1. versione *x* di AWS Encryption SDK, è possibile utilizzare un [filtro di rilevamento per limitare a quelle](use-kms-keyring.md#kms-keyring-discovery) in particolare le chiavi di avvolgimento utilizzate da un [portachiavi AWS KMS Discovery](use-kms-keyring.md#kms-keyring-discovery) o da un [portachiavi di rilevamento AWS KMS regionale](use-kms-keyring.md#kms-keyring-regional) per la decrittografia. Account AWS[Il filtraggio di un Discovery Keyring è una procedura consigliata. AWS Encryption SDK](best-practices.md)
Gli esempi in questa sezione mostreranno come aggiungere il filtro Discovery a un portachiavi Discovery AWS KMS regionale.
**Scopri di più sulla migrazione**
Per tutti AWS Encryption SDK gli utenti, scopri come impostare la tua politica di impegno in[Impostazione della politica di impegno](migrate-commitment-policy.md).
Per SDK di crittografia AWS per Java gli SDK di crittografia AWS per Python utenti della CLI di AWS crittografia e per gli utenti di Encryption CLI, scopri un aggiornamento richiesto per i provider di chiavi principali in. [Aggiornamento dei provider di chiavi AWS KMS principali](migrate-mkps-v2.md)
È possibile che nell'applicazione sia presente un codice simile al seguente. Questo esempio crea un portachiavi di rilevamento AWS KMS regionale che può utilizzare chiavi di avvolgimento solo nella regione Stati Uniti occidentali (Oregon) (us-west-2). Questo esempio rappresenta il codice nelle AWS Encryption SDK versioni precedenti alla 1.7. *x*. Tuttavia, è ancora valido nelle versioni 1.7. *x* e versioni successive.
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
A partire dalla versione 1.7. *x*, puoi aggiungere un filtro Discovery a qualsiasi portachiavi AWS KMS Discovery. Questo filtro di rilevamento limita i AWS KMS keys dati che AWS Encryption SDK possono utilizzare per la decrittografia a quelli contenuti nella partizione e negli account specificati. Prima di utilizzare questo codice, modifica la partizione, se necessario, e sostituisci l'account IDs di esempio con altri validi.
------
#### [ C ]
Per un esempio completo, vedete [kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp).
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
Per un esempio completo, vedi [kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts).
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# Impostazione della politica di impegno
[Key Commitment](concepts.md#key-commitment) garantisce che i dati crittografati vengano sempre decrittografati nello stesso testo in chiaro. Per fornire questa proprietà di sicurezza, a partire dalla versione 1.7. *x*, AWS Encryption SDK utilizza nuove [suite di algoritmi](supported-algorithms.md) con impegno chiave. Per determinare se i dati sono crittografati e decrittografati con key commitment, utilizza l'impostazione di configurazione della [policy di impegno](concepts.md#commitment-policy). [La crittografia e la decrittografia dei dati con impegno chiave è una best practice.AWS Encryption SDK](best-practices.md)
La definizione di una politica di impegno è una parte importante della seconda fase del processo di migrazione: la migrazione dalla versione più recente 1. *x* versioni delle due AWS Encryption SDK versioni 2.0. *x* e versioni successive. Dopo aver impostato e modificato la politica di impegno, assicuratevi di testare a fondo l'applicazione prima di distribuirla in produzione. Per indicazioni sulla migrazione, consulta[Come migrare e distribuire il AWS Encryption SDK](migration-guide.md).
L'impostazione della politica di impegno ha tre valori validi nelle versioni 2.0. *x* e versioni successive. Nell'ultimo 1. versioni *x* (a partire dalla versione 1.7. *x*), solo `ForbidEncryptAllowDecrypt` è valido.
+ `ForbidEncryptAllowDecrypt`— AWS Encryption SDK Non possono crittografare con un impegno chiave. Può decrittografare testi cifrati crittografati con o senza impegno di chiave.
Negli ultimi 1. *x* versioni, questo è l'unico valore valido. Garantisce che non si esegua la crittografia con l'impegno della chiave finché non si è completamente preparati a decrittografare con impegno chiave. L'impostazione del valore impedisce esplicitamente che la politica di impegno venga modificata automaticamente al `require-encrypt-require-decrypt` momento dell'aggiornamento alla versione 2.0. *x* o versioni successive. Puoi invece [migrare la tua politica di impegno](#migrate-commitment-policy) in più fasi.
+ `RequireEncryptAllowDecrypt`— Crittografa AWS Encryption SDK sempre con un impegno fondamentale. Può decrittografare testi cifrati crittografati con o senza impegno di chiave. Questo valore viene aggiunto nella versione 2.0. *x*.
+ `RequireEncryptRequireDecrypt`— Crittografa e decrittografa AWS Encryption SDK sempre con impegno fondamentale. Questo valore viene aggiunto nella versione 2.0. *x*. È il valore predefinito nelle versioni 2.0. *x* e versioni successive.
Nell'ultimo 1. *x* versioni, l'unico valore valido della politica di impegno è`ForbidEncryptAllowDecrypt`. Dopo la migrazione alla versione 2.0. *x* o versione successiva, puoi [modificare la tua politica di impegno gradualmente](migration-guide.md) man mano che sei pronto. Non aggiornate la vostra politica di impegno `RequireEncryptRequireDecrypt` finché non sarete certi di non avere messaggi crittografati senza l'impegno di una chiave.
Questi esempi mostrano come impostare la politica di impegno più recente 1. versioni *x* e nelle versioni 2.0. *x* e versioni successive. La tecnica dipende dal linguaggio di programmazione utilizzato.
**Scopri di più sulla migrazione**
Per SDK di crittografia AWS per Java e sulla AWS Encryption CLI, scopri le modifiche necessarie ai provider di chiavi master in. SDK di crittografia AWS per Python[Aggiornamento dei provider di chiavi AWS KMS principali](migrate-mkps-v2.md)
Per SDK di crittografia AWS per C e SDK di crittografia AWS per JavaScript, scopri come aggiornare facoltativamente i portachiavi in. [Aggiornamento dei AWS KMS portachiavi](migrate-keyrings-v2.md)
## Come impostare la tua politica di impegno
La tecnica utilizzata per impostare la politica di impegno varia leggermente a seconda dell'implementazione linguistica. Questi esempi mostrano come farlo. Prima di modificare la tua politica di impegno, esamina l'approccio in più fasi contenuto in[Come migrare e implementare](migration-guide.md).
------
#### [ C ]
A partire dalla versione 1.7. *x* of the SDK di crittografia AWS per C, si utilizza la `aws_cryptosdk_session_set_commitment_policy` funzione per impostare la politica di impegno per le sessioni di crittografia e decrittografia. La politica di impegno impostata si applica a tutte le operazioni di crittografia e decrittografia eseguite in quella sessione.
Le `aws_cryptosdk_session_new_from_cmm` funzioni `aws_cryptosdk_session_new_from_keyring` and sono obsolete nella versione 1.7. *x* e rimosso nella versione 2.0. *x*. Queste funzioni vengono sostituite da `aws_cryptosdk_session_new_from_keyring_2` e `aws_cryptosdk_session_new_from_cmm_2` funzioni che restituiscono una sessione.
Quando si utilizza `aws_cryptosdk_session_new_from_keyring_2` la `aws_cryptosdk_session_new_from_cmm_2` versione più recente di 1. *x* versioni, è necessario chiamare la `aws_cryptosdk_session_set_commitment_policy` funzione con il valore della policy di `COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT` impegno. Nelle versioni 2.0. *x* e versioni successive, la chiamata a questa funzione è facoltativa e richiede tutti i valori validi. La politica di impegno predefinita per le versioni 2.0. *x* e versioni successive sono`COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Per un esempio completo, vedi [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp).
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
Il `require-encrypt-require-decrypt` valore è la politica di impegno predefinita in tutte le versioni di per.NET. AWS Encryption SDK È possibile impostarla in modo esplicito come procedura consigliata, ma non è obbligatoria. Tuttavia, se si utilizza for.NET AWS Encryption SDK per decrittografare il testo cifrato che è stato crittografato con un'implementazione in un'altra lingua dell'impegno AWS Encryption SDK senza chiave, è necessario modificare il valore della policy di impegno in o. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` In caso contrario, i tentativi di decrittografare il testo cifrato falliranno.
In per.NET, si imposta la politica di impegno su un'istanza di. AWS Encryption SDK AWS Encryption SDK Crea un'istanza di un `AwsEncryptionSdkConfig` oggetto con un `CommitmentPolicy` parametro e usa l'oggetto di configurazione per creare l' AWS Encryption SDK istanza. Quindi, chiamate i `Decrypt()` metodi `Encrypt()` and dell'istanza AWS Encryption SDK configurata.
Questo esempio imposta la politica di impegno su`require-encrypt-allow-decrypt`.
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
Per impostare una politica di impegno nella CLI di AWS crittografia, utilizzare il `--commitment-policy` parametro. Questo parametro è stato introdotto nella versione 1.8. *x*.
Nell'ultimo 1. versione *x*, quando si utilizza il `--wrapping-keys` parametro in un `--decrypt` comando `--encrypt` or, è richiesto un `--commitment-policy` parametro con il `forbid-encrypt-allow-decrypt` valore. Altrimenti, il `--commitment-policy` parametro non è valido.
Nelle versioni 2.1. *x* e versioni successive, il `--commitment-policy` parametro è facoltativo e il valore predefinito è il `require-encrypt-require-decrypt` valore, che non crittograferà o decrittograferà alcun testo cifrato crittografato senza l'impegno di una chiave. Tuttavia, ti consigliamo di impostare la politica di impegno in modo esplicito in tutte le chiamate di crittografia e decrittografia per facilitare la manutenzione e la risoluzione dei problemi.
Questo esempio imposta la politica di impegno. Utilizza inoltre il `--wrapping-keys` parametro che sostituisce il `--master-keys` parametro a partire dalla versione 1.8. *x.* Per informazioni dettagliate, vedi [Aggiornamento dei provider di chiavi AWS KMS principali](migrate-mkps-v2.md). Per esempi completi, vedere[Esempi di CLI AWS di crittografia](crypto-cli-examples.md).
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
A partire dalla versione 1.7. *x* di SDK di crittografia AWS per Java, imposti la politica di impegno sulla tua istanza di`AwsCrypto`, l'oggetto che rappresenta il AWS Encryption SDK client. Questa impostazione della politica di impegno si applica a tutte le operazioni di crittografia e decrittografia eseguite su quel client.
Il `AwsCrypto()` costruttore è obsoleto nell'ultima versione 1. le versioni *x* di SDK di crittografia AWS per Java and vengono rimosse nella versione 2.0. *x*. Viene sostituito da una nuova `Builder` classe, da un `Builder.withCommitmentPolicy()` metodo e dal tipo `CommitmentPolicy` enumerato.
Nell'ultimo 1. *x* versioni, la `Builder` classe richiede il `Builder.withCommitmentPolicy()` metodo e l'`CommitmentPolicy.ForbidEncryptAllowDecrypt`argomento. A partire dalla versione 2.0. *x*, il `Builder.withCommitmentPolicy()` metodo è facoltativo; il valore predefinito è`CommitmentPolicy.RequireEncryptRequireDecrypt`.
Per un esempio completo, consulta [SetCommitmentPolicyExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
A partire dalla versione 1.7. *x* of the SDK di crittografia AWS per JavaScript, è possibile impostare la politica di impegno quando si chiama la nuova `buildClient` funzione che crea un'istanza di un AWS Encryption SDK client. La `buildClient` funzione assume un valore enumerato che rappresenta la politica di impegno dell'utente. Restituisce `decrypt` funzioni aggiornate `encrypt` e che applicano la politica di impegno dell'utente durante la crittografia e la decrittografia.
Nell'ultimo 1. *x* versioni, la `buildClient` funzione richiede l'`CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`argomento. A partire dalla versione 2.0. *x*, l'argomento della politica di impegno è facoltativo e il valore predefinito è`CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Il codice per Node.js e il browser sono identici per questo scopo, tranne per il fatto che il browser necessita di una dichiarazione per impostare le credenziali.
L'esempio seguente crittografa i dati con un AWS KMS portachiavi. La nuova `buildClient` funzione imposta la politica di impegno su`FORBID_ENCRYPT_ALLOW_DECRYPT`, il valore predefinito nell'ultimo 1. Versioni *x*. Gli aggiornamenti `encrypt` e le `decrypt` funzioni `buildClient` restituite applicano la politica di impegno impostata.
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
A partire dalla versione 1.7. *x* di SDK di crittografia AWS per Python, imposti la politica di impegno sulla tua istanza di`EncryptionSDKClient`, un nuovo oggetto che rappresenta il AWS Encryption SDK client. La politica di impegno che hai impostato si applica a tutte `encrypt` le `decrypt` chiamate che utilizzano quell'istanza del client.
Nell'ultima versione 1. versioni *x*, il `EncryptionSDKClient` costruttore richiede il valore `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` enumerato. A partire dalla versione 2.0. *x*, l'argomento della politica di impegno è facoltativo e il valore predefinito è`CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Questo esempio utilizza il nuovo `EncryptionSDKClient` costruttore e imposta la politica di impegno su 1.7. *x* valore predefinito. Il costruttore crea un'istanza di un client che rappresenta il. AWS Encryption SDK Quando chiami i `stream` metodi `encrypt``decrypt`, o su questo client, questi applicano la politica di impegno che hai impostato. Questo esempio utilizza anche il nuovo costruttore per la `StrictAwsKmsMasterKeyProvider` classe, che specifica AWS KMS keys quando crittografare e decrittografare.
[Per un esempio completo, vedete set\$1commitment.py.](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py)
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
Il `require-encrypt-require-decrypt` valore è la politica di impegno predefinita in tutte le versioni di AWS Encryption SDK for Rust. Puoi impostarla esplicitamente come best practice, ma non è obbligatoria. Tuttavia, se si utilizza AWS Encryption SDK for Rust per decrittografare il testo cifrato che è stato crittografato con un'implementazione in un'altra lingua dell'impegno AWS Encryption SDK senza chiave, è necessario modificare il valore della politica di impegno in o. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Altrimenti, i tentativi di decrittografare il testo cifrato falliranno.
In AWS Encryption SDK for Rust, si imposta la politica di impegno su un'istanza di. AWS Encryption SDK Crea un'istanza di un `AwsEncryptionSdkConfig` oggetto con un `comitment_policy` parametro e usa l'oggetto di configurazione per creare l' AWS Encryption SDK istanza. Quindi, chiamate i `Decrypt()` metodi `Encrypt()` and dell'istanza AWS Encryption SDK configurata.
Questo esempio imposta la politica di impegno su`forbid-encrypt-allow-decrypt`.
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
// Decrypt your ciphertext
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# Risoluzione dei problemi relativi alla migrazione alle versioni più recenti
Prima di aggiornare l'applicazione alla versione 2.0. *x* o versione successiva di AWS Encryption SDK, aggiorna alla versione più recente 1. versione *x* di AWS Encryption SDK e distribuiscila completamente. Questo ti aiuterà a evitare la maggior parte degli errori che potresti riscontrare durante l'aggiornamento alle versioni 2.0. *x* e versioni successive. Per una guida dettagliata, inclusi esempi, vedere[Migrazione del tuo AWS Encryption SDK](migration.md).
**Importante**
Verifica che il tuo ultimo 1. la versione *x* è la versione 1.7. *x* o versione successiva di AWS Encryption SDK.
**Nota**
**AWS Encryption CLI**: riferimenti in questa guida alla versione 1.7. *x* di si AWS Encryption SDK applica alla versione 1.8. *x* della CLI di AWS crittografia. Riferimenti in questa guida alla versione 2.0. *x* di si AWS Encryption SDK applica alla versione 2.1. *x* della CLI di AWS crittografia.
Le nuove funzionalità di sicurezza sono state originariamente rilasciate nelle versioni 1.7 di AWS Encryption CLI. *x* e 2.0. *x*. Tuttavia, AWS Encryption CLI versione 1.8. *x* sostituisce la versione 1.7. *x* e AWS Encryption CLI 2.1. *x* sostituisce 2.0. *x.* Per i dettagli, [consulta l'avviso di sicurezza](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) pertinente nel [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repository su. GitHub
Questo argomento è stato progettato per aiutarti a riconoscere e risolvere gli errori più comuni che potresti riscontrare.
**Topics**
+ [Oggetti obsoleti o rimossi](#deprecated-removed)
+ [Conflitto di configurazione: politica di impegno e suite di algoritmi](#configuration-conflict_1)
+ [Conflitto di configurazione: politica di impegno e testo cifrato](#configuration-conflict_2)
+ [La convalida dell'impegno chiave non è riuscita](#commitment-failed)
+ [Altri errori di crittografia](#encrypt-failed)
+ [Altri errori di decrittografia](#decrypt-failed)
+ [Considerazioni sul rollback](#migration-rollback)
## Oggetti obsoleti o rimossi
Versione 2.0. *x* include diverse modifiche sostanziali, inclusa la rimozione di costruttori, metodi, funzioni e classi obsoleti nella versione 1.7. *x*. Per evitare errori nel compilatore, errori di importazione, errori di sintassi ed errori relativi ai simboli non trovati (a seconda del linguaggio di programmazione), esegui prima l'aggiornamento alla versione 1 più recente. versione *x* di AWS Encryption SDK per il tuo linguaggio di programmazione. (Questa deve essere la versione 1.7. *x* o versione successiva.) Durante l'utilizzo dell'ultimo 1. versione *x*, puoi iniziare a utilizzare gli elementi sostitutivi prima che i simboli originali vengano rimossi.
Se è necessario eseguire l'aggiornamento alla versione 2.0. *x* o versione successiva immediatamente, [consultate il changelog](about-versions.md) del vostro linguaggio di programmazione e sostituite i simboli precedenti con i simboli consigliati dal changelog.
## Conflitto di configurazione: politica di impegno e suite di algoritmi
Se si specifica una suite di algoritmi che è in conflitto con la [politica di impegno](concepts.md#commitment-policy), la chiamata alla crittografia ha esito negativo e viene generato un errore di *conflitto di configurazione*.
Per evitare questo tipo di errore, non specificate una suite di algoritmi. Per impostazione predefinita, AWS Encryption SDK sceglie l'algoritmo più sicuro e compatibile con la politica di impegno dell'utente. Tuttavia, se devi specificare una suite di algoritmi, ad esempio una senza firma, assicurati di scegliere una suite di algoritmi compatibile con la tua politica di impegno.
| Politica di impegno | Suite di algoritmi compatibili |
| --- | --- |
| ForbidEncryptAllowDecrypt | Qualsiasi suite di algoritmi *senza* impegno chiave, come:AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384([03 78](algorithms-reference.md)) (con firma) `AES_256_GCM_IV12_TAG16_HKDF_SHA256`([01 78](algorithms-reference.md)) (senza firma) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | Qualsiasi suite di algoritmi *con* impegno chiave, ad esempio:AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384([05 78](algorithms-reference.md)) (con firma) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY`([04 78](algorithms-reference.md)) (senza firma) |
Se si verifica questo errore quando non è stata specificata una suite di algoritmi, è possibile che la suite di algoritmi in conflitto sia stata scelta dal [gestore dei materiali crittografici](concepts.md#crypt-materials-manager) (CMM). La CMM predefinita non selezionerà una suite di algoritmi in conflitto, ma una CMM personalizzata sì. Per assistenza, consulta la documentazione della tua CMM personalizzata.
## Conflitto di configurazione: politica di impegno e testo cifrato
[La [politica di `RequireEncryptRequireDecrypt` impegno](concepts.md#commitment-policy) non consente di AWS Encryption SDK decrittografare un messaggio che è stato crittografato senza l'impegno della chiave.](concepts.md#key-commitment) *Se si chiede di AWS Encryption SDK decrittografare un messaggio senza l'impegno della chiave, viene restituito un errore di conflitto di configurazione.*
Per evitare questo errore, prima di impostare la `RequireEncryptRequireDecrypt` politica di commit, assicurati che tutti i testi cifrati crittografati senza l'impegno della chiave vengano decrittografati e ricrittografati con l'impegno della chiave o gestiti da un'applicazione diversa. Se si verifica questo errore, è possibile restituire un errore per il testo cifrato in conflitto o modificare temporaneamente la politica di impegno in. `RequireEncryptAllowDecrypt`
Se riscontrate questo errore perché avete effettuato l'aggiornamento alla versione 2.0. *x* o versione successiva da una versione precedente alla 1.7. *x* senza prima eseguire l'aggiornamento alla versione più recente 1. versione *x* (versione 1.7). *x* o versione successiva), considera la [possibilità di tornare](#migration-rollback) alla versione 1 più recente. versione *x* e distribuzione di tale versione su tutti gli host prima dell'aggiornamento alla versione 2.0. *x* o versione successiva. Per assistenza, consulta [Come migrare e distribuire il AWS Encryption SDK](migration-guide.md).
## La convalida dell'impegno chiave non è riuscita
Quando decifri i messaggi crittografati con l'impegno della chiave, potresti ricevere un messaggio di errore di *convalida dell'impegno chiave* non riuscita. Ciò indica che la chiamata di decrittografia non è riuscita perché una chiave dati in un [messaggio crittografato](concepts.md#DEK) non è identica alla chiave dati univoca del messaggio. Convalidando la chiave dati durante la decrittografia, [key](concepts.md#key-commitment) commit ti protegge dalla decrittografia di un messaggio che potrebbe comportare più di un testo in chiaro.
Questo errore indica che il messaggio crittografato che si stava tentando di decrittografare non è stato restituito da. AWS Encryption SDK Potrebbe essere un messaggio creato manualmente o il risultato di un danneggiamento dei dati. Se si verifica questo errore, l'applicazione può rifiutare il messaggio e continuare o interrompere l'elaborazione di nuovi messaggi.
## Altri errori di crittografia
La crittografia può fallire per diversi motivi. Non è possibile utilizzare un [portachiavi di AWS KMS rilevamento](use-kms-keyring.md#kms-keyring-discovery) o un [provider di chiavi master in modalità di rilevamento](migrate-mkps-v2.md) per crittografare un messaggio.
Assicuratevi di specificare un portachiavi o un fornitore di chiavi master con chiavi di wrapping che possiate utilizzare [per la crittografia](use-kms-keyring.md#kms-keyring-permissions). *Per informazioni sull'attivazione delle autorizzazioni AWS KMS keys, consulta [Visualizzare una policy chiave](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html) e [Determinare l'accesso a una AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html) nella Guida per gli AWS Key Management Service sviluppatori.*
## Altri errori di decrittografia
Se il tentativo di decrittografare un messaggio crittografato fallisce, significa che non è AWS Encryption SDK stato possibile (o non ha voluto) decrittografare nessuna delle chiavi di dati crittografate contenute nel messaggio.
Se hai utilizzato un portachiavi o un provider di chiavi master che specifica le chiavi di avvolgimento, AWS Encryption SDK utilizza solo le chiavi di avvolgimento specificate dall'utente. Verifica di utilizzare le chiavi di avvolgimento che intendi utilizzare e di disporre dell'`kms:Decrypt`autorizzazione per almeno una delle chiavi di avvolgimento. [Se utilizzi AWS KMS keys, come fallback, puoi provare a decrittografare il messaggio con un portachiavi di rilevamento o un provider di [chiavi principali in modalità di AWS KMS scoperta](use-kms-keyring.md#kms-keyring-discovery).](migrate-mkps-v2.md) Se l'operazione ha esito positivo, prima di restituire il testo in chiaro, verifica che la chiave utilizzata per decrittografare il messaggio sia attendibile.
## Considerazioni sul rollback
[Se l'applicazione non riesce a crittografare o decrittografare i dati, in genere è possibile risolvere il problema aggiornando i simboli di codice, i portachiavi, i fornitori di chiavi principali o la politica di impegno.](concepts.md#commitment-policy) Tuttavia, in alcuni casi, potreste decidere che è meglio ripristinare l'applicazione a una versione precedente di. AWS Encryption SDK
Se è necessario eseguire il rollback, fatelo con cautela. Versioni AWS Encryption SDK precedenti alla 1.7. *x* [non è in grado di decrittografare il testo cifrato crittografato con l'impegno della chiave.](concepts.md#key-commitment)
+ Tornando indietro dalla versione più recente 1. La versione *x* di una versione precedente di AWS Encryption SDK è generalmente sicura. Potrebbe essere necessario annullare le modifiche apportate al codice per utilizzare simboli e oggetti non supportati nelle versioni precedenti.
+ Dopo aver iniziato a crittografare con key commit (impostando la politica di impegno su`RequireEncryptAllowDecrypt`) nella versione 2.0. *x* o versione successiva, puoi tornare alla versione 1.7. *x*, ma non a nessuna versione precedente. Versioni AWS Encryption SDK precedenti alla 1.7. *x* [non è in grado di decrittografare il testo cifrato crittografato con l'impegno della chiave.](concepts.md#key-commitment)
Se abiliti accidentalmente la crittografia con l'impegno della chiave prima che tutti gli host possano decrittografare con l'impegno della chiave, potrebbe essere meglio continuare con l'implementazione piuttosto che ripristinarla. Se i messaggi sono temporanei o possono essere eliminati in modo sicuro, potresti prendere in considerazione un rollback con perdita di messaggi. Se è necessario un rollback, potresti prendere in considerazione la possibilità di scrivere uno strumento che decrittografi e ricrittografi tutti i messaggi.