Configurazione del AWS Encryption SDK - AWS Encryption SDK
Selezione di un linguaggio di programmazioneSelezione dei tasti di avvolgimentoUtilizzo di più regioni AWS KMS keysScelta di una suite di algoritmiLimitazione delle chiavi di dati crittografateCreazione di un filtro di scopertaImpostazione di una politica di impegnoLavorare con dati in streamingMemorizzazione nella cache delle chiavi dati

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

Configurazione del AWS Encryption SDK

AWS Encryption SDK È progettato per essere facile da usare. Sebbene AWS Encryption SDK abbia diverse opzioni di configurazione, i valori predefiniti sono scelti con cura per essere pratici e sicuri per la maggior parte delle applicazioni. Tuttavia, potrebbe essere necessario modificare la configurazione per migliorare le prestazioni o includere una funzionalità personalizzata nel design.

Quando configuri l'implementazione, esamina le AWS Encryption SDK migliori pratiche e implementane quante più possibile.

Selezione di un linguaggio di programmazione

AWS Encryption SDK È disponibile in più linguaggi di programmazione. Le implementazioni del linguaggio sono progettate per essere completamente interoperabili e per offrire le stesse funzionalità, sebbene possano essere implementate in modi diversi. In genere, si utilizza la libreria compatibile con l'applicazione. Tuttavia, è possibile selezionare un linguaggio di programmazione per una particolare implementazione. Ad esempio, se preferisci lavorare con i portachiavi, puoi scegliere il SDK di crittografia AWS per C o il SDK di crittografia AWS per JavaScript.

Selezione dei tasti di avvolgimento

AWS Encryption SDK Genera una chiave dati simmetrica unica per crittografare ogni messaggio. A meno che non si utilizzi la memorizzazione nella cache delle chiavi dati, non è necessario configurare, gestire o utilizzare le chiavi dati. Lo AWS Encryption SDK fa per te.

Tuttavia, è necessario selezionare una o più chiavi di wrapping per crittografare ciascuna chiave di dati. AWS Encryption SDK Supporta chiavi AES simmetriche e chiavi RSA asimmetriche di diverse dimensioni. Supporta AWS Key Management Serviceanche la crittografia simmetrica ().AWS KMS AWS KMS keys Sei responsabile della sicurezza e della durata delle tue chiavi di wrapping, quindi ti consigliamo di utilizzare una chiave di crittografia in un modulo di sicurezza hardware o in un servizio di infrastruttura chiave, come. AWS KMS

Per specificare le chiavi di wrapping per la crittografia e la decrittografia, si utilizza un portachiavi (C e JavaScript) o un provider di chiavi master (Java, Python, Encryption). AWS CLI È possibile specificare una chiave di avvolgimento o più chiavi di avvolgimento dello stesso tipo o di tipi diversi. Se utilizzi più chiavi di wrapping per racchiudere una chiave dati, ogni chiave di wrapping crittograferà una copia della stessa chiave dati. Le chiavi dati crittografate (una per chiave di wrapping) vengono archiviate con i dati crittografati nel messaggio crittografato che restituiscono. AWS Encryption SDK Per decrittografare i dati, è AWS Encryption SDK necessario innanzitutto utilizzare una delle chiavi di wrapping per decrittografare una chiave dati crittografata.

Per specificare una chiave AWS KMS key in un portachiavi o un provider di chiavi master, utilizza un identificatore di chiave supportato. AWS KMS Per i dettagli sugli identificatori di chiave per una AWS KMS chiave, consulta Identificatori chiave nella Guida per gli sviluppatori.AWS Key Management Service

  • Quando si esegue la crittografia con SDK di crittografia AWS per Java, SDK di crittografia AWS per JavaScript SDK di crittografia AWS per Python, o la AWS crittografiaCLI, è possibile utilizzare qualsiasi identificatore di chiave valido (ID chiave, chiaveARN, nome alias o ARN alias) per una chiave. KMS Quando si esegue la crittografia con SDK di crittografia AWS per C, è possibile utilizzare solo un ID o una chiave. ARN

    Se si specifica un nome alias o un alias ARN per una KMS chiave durante la crittografia, AWS Encryption SDK salva la chiave ARN attualmente associata a quell'alias, ma non l'alias. Le modifiche all'alias non influiscono sulla KMS chiave utilizzata per decrittografare le chiavi dati.

  • Quando si esegue la decrittografia in modalità rigorosa (in cui si specificano chiavi di avvolgimento particolari), è necessario utilizzare una chiave per l'identificazione. ARN AWS KMS keys Questo requisito si applica a tutte le implementazioni di linguaggio di AWS Encryption SDK.

    Quando si esegue la crittografia con un AWS KMS portachiavi, la chiave viene AWS Encryption SDK memorizzata AWS KMS key nei metadati ARN della chiave dati crittografata. Quando si esegue la decrittografia in modalità rigorosa, AWS Encryption SDK verifica che la stessa chiave sia ARN presente nel portachiavi (o nel provider della chiave principale) prima di tentare di utilizzare la chiave di wrapping per decrittografare la chiave dati crittografata. Se si utilizza un identificatore di chiave diverso, non lo riconoscerà né lo AWS Encryption SDK utilizzerà AWS KMS key, anche se gli identificatori si riferiscono alla stessa chiave.

Per specificare una AESchiave grezza o una coppia di RSA chiavi non elaborate come chiave di avvolgimento in un portachiavi, è necessario specificare uno spazio dei nomi e un nome. In un provider di chiavi master, Provider ID è l'equivalente dello spazio dei nomi e il Key ID è l'equivalente del nome. Durante la decrittografia, è necessario utilizzare lo stesso identico spazio dei nomi e lo stesso nome per ogni chiave di wrapping non elaborata utilizzata durante la crittografia. Se utilizzate un namespace o un nome diverso, non riconosceranno né AWS Encryption SDK utilizzeranno la chiave di wrapping, anche se il materiale della chiave è lo stesso.

Utilizzo di più regioni AWS KMS keys

È possibile utilizzare i tasti multiregionali AWS Key Management Service (AWS KMS) come chiavi di avvolgimento in. AWS Encryption SDK Se si esegue la crittografia con una chiave multiregionale in una Regione AWS, è possibile decrittografare utilizzando una chiave multiregionale correlata in un'altra. Regione AWS Il supporto per le chiavi multiregione è stato introdotto nella versione 2.3. x della AWS Encryption SDK e versione 3.0. x della AWS crittografiaCLI.

AWS KMS Le chiavi multiregionali sono un insieme di AWS KMS keys chiavi diverse Regioni AWS che hanno lo stesso materiale chiave e lo stesso ID di chiave. È possibile utilizzare queste chiavi correlate come se fossero la stessa chiave in regioni diverse. Le chiavi multiregionali supportano scenari di disaster recovery e backup comuni che richiedono la crittografia in una regione e la decrittografia in un'altra regione senza effettuare una chiamata interregionale a. AWS KMSPer informazioni sulle chiavi multiregionali, consulta Using Multiregion Keys nella Developer Guide.AWS Key Management Service

Per supportare le chiavi multiregionali, sono AWS Encryption SDK inclusi portachiavi compatibili con AWS KMS più regioni e fornitori di chiavi principali. Il nuovo multi-Region-aware simbolo in ogni linguaggio di programmazione supporta sia chiavi a regione singola che a più regioni.

Nei multi-Region-aware portachiavi e nei provider di chiavi principali che utilizzano più di una chiave, puoi specificare più KMS chiavi singole e multiregionali. Tuttavia, è possibile specificare solo una chiave per ogni set di chiavi di replica multiregione correlate. Se specificate più di un identificatore di chiave con lo stesso ID chiave, la chiamata al costruttore ha esito negativo.

È inoltre possibile utilizzare una chiave multiregionale con i portachiavi standard a regione singola e i provider di AWS KMS chiavi principali. Tuttavia, è necessario utilizzare la stessa chiave multiregionale nella stessa regione per crittografare e decrittografare. I portachiavi a regione singola e i provider di chiavi master tentano di decrittografare il testo cifrato solo con le chiavi che hanno crittografato i dati.

Gli esempi seguenti mostrano come crittografare e decrittografare i dati utilizzando chiavi multiregionali e i nuovi portachiavi e fornitori di chiavi master. multi-Region-aware Questi esempi crittografano i dati nella us-east-1 regione e decrittografano i dati nella regione utilizzando chiavi di replica multiregione correlate in us-west-2 ciascuna regione. Prima di eseguire questi esempi, sostituisci la chiave multiregionale di esempio ARN con un valore valido tratto dal tuo. Account AWS

C

Per crittografare con una chiave multiregionale, utilizzate il Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metodo per creare un'istanza del portachiavi. Specificate una chiave multiregionale.

Questo semplice esempio non include un contesto di crittografia. Per un esempio che utilizza un contesto di crittografia in C, vediCrittografia e decrittazione di stringhe.

Per un esempio completo, vedi kms_multi_region_keys.cpp nel SDK di crittografia AWS per C repository su GitHub.

/* Encrypt with a multi-Region KMS key in us-east-1 */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";   

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Encrypt the data
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

Per crittografare con una chiave multiregionale nella regione Stati Uniti orientali (Virginia settentrionale) (us-east-1), crea un'istanza di un CreateAwsKmsMrkKeyringInput oggetto con un identificatore di chiave per la chiave multiregione e un client per la regione specificata. AWS KMS Quindi utilizzate il metodo per creare il portachiavi. CreateAwsKmsMrkKeyring()

Il CreateAwsKmsMrkKeyring() metodo crea un portachiavi con esattamente una chiave multiregionale. Per crittografare con più chiavi di avvolgimento, inclusa una chiave multiregionale, utilizzate il metodo. CreateAwsKmsMrkMultiKeyring()

Per un esempio completo, consulta AwsKmsMrkKeyringExample.cs nel modulo. AWS Encryption SDK NETrepository su. GitHub

//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();


// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Create the keyring
// You can specify the Region or get the Region from the key ARN
var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
    KmsKeyId = mrkUSEast1
};
var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput);

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

// Encrypt your plaintext data.
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = mrkEncryptKeyring,
    EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Questo esempio crittografa il hello.txt file con una chiave multiregionale nella regione us-east-1. Poiché l'esempio specifica una chiave ARN con un elemento Region, questo esempio non utilizza l'attributo region del parametro. --wrapping-keys

Quando l'ID di chiave della chiave di wrapping non specifica una regione, è possibile utilizzare l'attributo region di --wrapping-keys per specificare la regione, ad esempio. --wrapping-keys key=$keyID region=us-east-1 

# Encrypt with a multi-Region KMS key in us-east-1 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$mrkUSEast1 \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .
Java

Per crittografare con una chiave multiregionale, crea un'istanza AwsKmsMrkAwareMasterKeyProvider e specifica una chiave multiregionale.

Per un esempio completo, vedi BasicMultiRegionKeyEncryptionExample.javanel SDK di crittografia AWS per Java repository su. GitHub

//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate an AWS KMS master key provider in strict mode for multi-Region keys
// Configure it to encrypt with the multi-Region key in us-east-1
final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .buildStrict(mrkUSEast1);

// Create an encryption context
final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test");

// Encrypt your plaintext data
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData(
    kmsMrkProvider,
    encryptionContext,
    sourcePlaintext);
byte[] ciphertext = encryptResult.getResult();
JavaScript Browser

Per crittografare con una chiave multiregionale, utilizzate il buildAwsKmsMrkAwareStrictMultiKeyringBrowser() metodo per creare il portachiavi e specificare una chiave multiregionale.

Per un esempio completo, vedi kms_multi_region_simple.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

/* Encrypt with a multi-Region KMS key in us-east-1 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The SDK di crittografia AWS per JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-east-1 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsEastKey,
    clientProvider,
  })


/* Set the encryption context */
const context = {
    purpose: 'test',
  }

/* Test data to encrypt */
const cleartext = new Uint8Array([1, 2, 3, 4, 5])

/* Encrypt the data */
const { result } = await encrypt(encryptKeyring, cleartext, {
    encryptionContext: context,
  })
JavaScript Node.js

Per crittografare con una chiave multiregionale, utilizzate il metodo per creare il portachiavi e specificare una chiave multiregionale. buildAwsKmsMrkAwareStrictMultiKeyringNode()

Per un esempio completo, vedi kms_multi_region_simple.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

//Encrypt with a multi-Region KMS key in us-east-1 Region

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the AWS Encryption SDK client
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Test string to encrypt */
const cleartext = 'asdf'

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsEastKey,
  })

/* Specify an encryption context */
const context = {
    purpose: 'test',
  }

/* Create an encryption keyring */
const { result } = await encrypt(mrkEncryptKeyring, cleartext, {
    encryptionContext: context,
  })
Python

Per crittografare con una chiave multiregionale, utilizzate il metodo e specificate una AWS KMS chiave multiregionale. MRKAwareStrictAwsKmsMasterKeyProvider()

Per un esempio completo, consulta mrk_aware_kms_provider.py nel repository su. SDK di crittografia AWS per Python GitHub

* Encrypt with a multi-Region KMS key in us-east-1 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Specify a multi-Region key in us-east-1
mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_east_1]
)

# Set the encryption context
encryption_context = {
        "purpose": "test"
    }

# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
        source=source_plaintext,
        encryption_context=encryption_context,
        key_provider=strict_mrk_key_provider
)

Quindi, sposta il testo cifrato nella regione. us-west-2 Non è necessario crittografare nuovamente il testo cifrato.

Per decrittografare il testo cifrato in modalità rigorosa nella us-west-2 regione, crea un'istanza del multi-Region-aware simbolo con la chiave della chiave multiregionale correlata nella regione. ARN us-west-2 Se specificate la chiave ARN di una chiave multiregionale correlata in una regione diversa (inclusa quella in cui è stata crittografata)us-east-1, il multi-Region-aware simbolo effettuerà una chiamata interregionale in tal senso. AWS KMS key

Durante la decrittografia in modalità rigorosa, il multi-Region-aware simbolo richiede una chiave. ARN Accetta solo una chiave per ARN ogni set di chiavi multiregionali correlate.

Prima di eseguire questi esempi, sostituisci la chiave multiregionale di esempio ARN con un valore valido tra i tuoi. Account AWS

C

Per decrittografare in modalità rigorosa con una chiave multiregionale, utilizzate il Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metodo per creare un'istanza del portachiavi. Specificare la chiave multiregione correlata nella regione locale (us-west-2).

Per un esempio completo, consulta kms_multi_region_keys.cpp nel repository su. SDK di crittografia AWS per C GitHub

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";    

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_session_set_commitment_policy(session,
    COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

Per decrittografare in modalità rigorosa con un'unica chiave multiregionale, utilizzate gli stessi costruttori e metodi utilizzati per assemblare l'input e creare il portachiavi per la crittografia. Crea un'istanza di un CreateAwsKmsMrkKeyringInput oggetto con la chiave ARN di una chiave multiregionale correlata e un AWS KMS client per la regione Stati Uniti occidentali (Oregon) (us-west-2). Quindi utilizzate il CreateAwsKmsMrkKeyring() metodo per creare un portachiavi multiregione con una chiave multiregionale. KMS

Per un esempio completo, vedi AwsKmsMrkKeyringExample.cs nel modulo. AWS Encryption SDK NETrepository su. GitHub

// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Specify the key ARN of the multi-Region key in us-west-2
string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate the keyring input
// You can specify the Region or get the Region from the key ARN
var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    KmsKeyId = mrkUSWest2
};

// Create the multi-Region keyring        
var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDecryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Per decrittografare con la relativa chiave multiregionale nella regione us-west-2, utilizzate l'attributo key del parametro per specificarne la chiave. --wrapping-keys ARN 

# Decrypt with a related multi-Region KMS key in us-west-2 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$mrkUSWest2 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Per decrittografare in modalità rigorosa, crea un'istanza AwsKmsMrkAwareMasterKeyProvider e specifica la chiave multiregione correlata nella regione locale (us-west-2).

Per un esempio completo, consulta .java nel repository su. BasicMultiRegionKeyEncryptionExample SDK di crittografia AWS per Java GitHub

// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field.
String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Use the multi-Region method to create the master key provider
// in strict mode
AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder()
    .buildStrict(mrkUSWest2);

// Decrypt your ciphertext
CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData(
        kmsMrkProvider,
        ciphertext);
byte[] decrypted = decryptResult.getResult();
JavaScript Browser

Per decrittografare in modalità rigorosa, utilizzate il buildAwsKmsMrkAwareStrictMultiKeyringBrowser() metodo per creare il portachiavi e specificare la chiave multiregione correlata nella regione locale (us-west-2).

Per un esempio completo, vedi kms_multi_region_simple.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The SDK di crittografia AWS per JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-west-2 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsWestKey,
    clientProvider,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)
JavaScript Node.js

Per decrittografare in modalità rigorosa, utilizzate il buildAwsKmsMrkAwareStrictMultiKeyringNode() metodo per creare il portachiavi e specificare la chiave multiregione correlata nella regione locale (us-west-2).

Per un esempio completo, vedi kms_multi_region_simple.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the client
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-west-2
 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsWestKey,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
Python

Per decrittografare in modalità rigorosa, utilizzate il metodo per creare il provider della chiave principale. MRKAwareStrictAwsKmsMasterKeyProvider() Specificare la chiave multiregione correlata nella regione locale (us-west-2).

Per un esempio completo, consulta mrk_aware_kms_provider.py nel repository su. SDK di crittografia AWS per Python GitHub

# Decrypt with a related multi-Region KMS key in us-west-2 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field
mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_west_2]
)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=strict_mrk_key_provider
)

È inoltre possibile decrittografare in modalità di rilevamento con AWS KMS chiavi multiregionali. Durante la decrittografia in modalità di rilevamento, non ne viene specificata alcuna. AWS KMS keys(Per informazioni sui portachiavi Single-Region AWS KMS Discovery, consulta.) Utilizzo di un portachiavi Discovery AWS KMS

Se è stata crittografata con una chiave multiregionale, il multi-Region-aware simbolo in modalità di individuazione tenterà di decrittografare utilizzando una chiave multiregionale correlata nella regione locale. Se non ne esiste nessuna, la chiamata ha esito negativo. In modalità di rilevamento, non AWS Encryption SDK tenterà di effettuare una chiamata interregionale per la chiave multiregionale utilizzata per la crittografia.

Nota

Se si utilizza un multi-Region-aware simbolo in modalità di rilevamento per crittografare i dati, l'operazione di crittografia non riesce.

L'esempio seguente mostra come decrittografare con il multi-Region-aware simbolo in modalità di rilevamento. Poiché non si specifica un AWS KMS key, AWS Encryption SDK deve ottenere la regione da una fonte diversa. Quando possibile, specifica la regione locale in modo esplicito. Altrimenti, AWS Encryption SDK ottiene la regione locale dalla regione configurata nel linguaggio di AWS SDK programmazione in uso.

Prima di eseguire questi esempi, sostituisci l'ID account di esempio e la chiave multiregionale ARN con valori validi del tuo Account AWS.

C

Per decrittografare in modalità di individuazione con una chiave multiregionale, utilizzate il Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() metodo per creare il portachiavi e il Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() metodo per creare il filtro di individuazione. Per specificare la regione locale, definisci una ClientConfiguration e specificala nel client. AWS KMS

Per un esempio completo, consulta kms_multi_region_keys.cpp nel SDK di crittografia AWS per C repository su GitHub.

/* Decrypt in discovery mode with a multi-Region KMS key */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct a discovery filter for the account and partition. The
 *  filter is optional, but it's a best practice that we recommend.
 */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";

Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
    Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
        .WithKmsClient(kms_client)
        .BuildDiscovery(region, discovery_filter);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

Per creare un portachiavi multi-Region-aware Discovery in formato Form. AWS Encryption SDK NET, crea un'istanza di un CreateAwsKmsMrkDiscoveryKeyringInput oggetto che utilizza un AWS KMS client per un determinato Regione AWS client e un filtro di rilevamento opzionale che limita KMS le chiavi a una AWS partizione e a un account particolari. Quindi chiamate il CreateAwsKmsMrkDiscoveryKeyring() metodo con l'oggetto di input. Per un esempio completo, vedi AwsKmsMrkDiscoveryKeyringExample.cs nel modulo AWS Encryption SDK . NETrepository su. GitHub

Per creare un portachiavi multi-Region-aware Discovery per più di uno Regione AWS, usa il CreateAwsKmsMrkDiscoveryMultiKeyring() metodo per creare un portachiavi multiplo oppure usa il metodo CreateAwsKmsMrkDiscoveryKeyring() per creare diversi portachiavi multi-Region-aware Discovery e poi usa il CreateMultiKeyring() metodo per combinarli in un portachiavi multiplo.

Per un esempio, consulta .cs. AwsKmsMrkDiscoveryMultiKeyringExample

// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

List<string> account = new List<string> { "111122223333" };

// Instantiate the discovery filter
DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

// Create the keyring
var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = mrkDiscoveryFilter
};
var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput);


// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDiscoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Per decrittografare in modalità di rilevamento, utilizzate l'attributo discovery del parametro. --wrapping-keys Gli attributi discovery-account e discovery-partition creano un filtro di scoperta facoltativo, ma consigliato.

Per specificare la regione, questo comando include l'attributo region del parametro. --wrapping-keys

# Decrypt in discovery mode with a multi-Region KMS key

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                                     region=us-west-2 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Per specificare la regione locale, utilizzate il builder().withDiscoveryMrkRegion parametro. Altrimenti, AWS Encryption SDK ottiene la regione locale dalla regione configurata in AWS SDK for Java.

Per un esempio completo, consulta DiscoveryMultiRegionDecryptionExample.java nel SDK di crittografia AWS per Java repository su. GitHub

// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();
                
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .withDiscoveryMrkRegion(Region.US_WEST_2)
    .buildDiscovery(discoveryFilter);

// Decrypt your ciphertext
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto
    .decryptData(mrkDiscoveryProvider, ciphertext);
JavaScript Browser

Per decrittografare in modalità di rilevamento con una chiave simmetrica multiregionale, utilizzate il metodo. AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser()

Per un esempio completo, vedi kms_multi_region_discovery.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient()

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2', credentials })


/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }


/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
    client,
    discoveryFilter,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)
JavaScript Node.js

Per decrittografare in modalità di scoperta con una chiave multiregionale simmetrica, utilizzate il metodo. AwsKmsMrkAwareSymmetricDiscoveryKeyringNode()

Per un esempio completo, vedi kms_multi_region_discovery.ts nel repository su. SDK di crittografia AWS per JavaScript GitHub

/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-node'

/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })

/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }

/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
    client,
    discoveryFilter,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
Python

Per decrittografare in modalità di scoperta con una chiave multiregionale, usa il metodo. MRKAwareDiscoveryAwsKmsMasterKeyProvider()

Per un esempio completo, consulta mrk_aware_kms_provider.py nel repository su. SDK di crittografia AWS per Python GitHub

# Decrypt in discovery mode with a multi-Region KMS key

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient()

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

# Use the multi-Region method to create the master key provider
# in discovery mode
mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=mrk_discovery_key_provider
)

Scelta di una suite di algoritmi

AWS Encryption SDK Supporta diversi algoritmi di crittografia simmetrica e asimmetrica per crittografare le chiavi di dati con le chiavi di wrapping specificate. Tuttavia, quando utilizza tali chiavi dati per crittografare i dati, l' AWS Encryption SDK impostazione predefinita è una suite di algoritmi consigliata che utilizza l'algoritmo AES - GCM con derivazione delle chiavi, firme digitali e impegno delle chiavi. Sebbene la suite di algoritmi predefinita sia probabilmente adatta alla maggior parte delle applicazioni, è possibile scegliere una suite di algoritmi alternativa. Ad esempio, alcuni modelli di fiducia sarebbero soddisfatti da una suite di algoritmi senza firme digitali. Per informazioni sulle suite di algoritmi AWS Encryption SDK supportate, vedereSuite di algoritmi supportate in AWS Encryption SDK.

Gli esempi seguenti mostrano come selezionare una suite di algoritmi alternativa durante la crittografia. Questi esempi selezionano una suite di GCM algoritmi consigliata AES con derivazione delle chiavi e impegno delle chiavi, ma senza firme digitali. Quando esegui la crittografia con una suite di algoritmi che non include firme digitali, utilizza la modalità di decrittografia solo senza segno durante la decrittografia. Questa modalità, che fallisce se incontra un testo cifrato firmato, è particolarmente utile durante la decrittografia in streaming.

C

Per specificare una suite di algoritmi alternativa in, è necessario crearne una in modo esplicito SDK di crittografia AWS per C. CMM Quindi utilizzate la suite di algoritmi aws_cryptosdk_default_cmm_set_alg_id con CMM e la suite di algoritmi selezionata.

/* Specify an algorithm suite without signing */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);

/* To set an alternate algorithm suite, create an cryptographic 
   materials manager (CMM) explicitly
 */
struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 

/* Specify the algorithm suite for the CMM */
aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY);
    
/* Construct the session with the CMM, 
   then release the CMM reference 
 */
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm);
aws_cryptosdk_cmm_release(cmm);

/* Encrypt the data 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session, 
                          ciphertext, 
                          ciphertext_buf_sz, 
                          &ciphertext_len, 
                          plaintext, 
                          plaintext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

Per decrittografare dati crittografati senza firme digitali, usa. AWS_CRYPTOSDK_DECRYPT_UNSIGNED Ciò causa l'esito negativo della decrittografia se viene rilevato testo cifrato firmato.

/* Decrypt unsigned streaming data */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
    
/* Create a session for decrypting with the AWS KMS keyring
   Then release the keyring reference
 */
struct aws_cryptosdk_session *session =
        aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 
   
if (!session) {
    return AWS_OP_ERR;
}
    
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1);
  
/* Decrypt 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
    if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session,                          
                          plaintext,
                          plaintext_buf_sz,
                          &plaintext_len,
                          ciphertext,
                          ciphertext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}
C# / .NET

Per specificare una suite di algoritmi alternativa nel modulo. AWS Encryption SDK NET, specifica la AlgorithmSuiteId proprietà di un EncryptInputoggetto. Il AWS Encryption SDK per. NETinclude costanti che è possibile utilizzare per identificare la suite di algoritmi preferita.

Il AWS Encryption SDK per. NETnon dispone di un metodo per rilevare il testo cifrato firmato durante la decrittografia in streaming perché questa libreria non supporta lo streaming di dati.

// Specify an algorithm suite without signing

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Create the keyring
var keyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput);

// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Durante la crittografia del hello.txt file, questo esempio utilizza il --algorithm parametro per specificare una suite di algoritmi senza firme digitali. 

# Specify an algorithm suite without signing

# 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

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --commitment-policy require-encrypt-require-decrypt \
                     --output hello.txt.encrypted \
                     --decode

Durante la decrittografia, questo esempio utilizza il parametro. --decrypt-unsigned Questo parametro è consigliato per garantire la decrittografia di testo cifrato non firmato, in particolare conCLI, che trasmette sempre input e output in streaming.

# Decrypt unsigned streaming data

# 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

$ aws-encryption-cli --decrypt-unsigned \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --max-encrypted-data-keys 1 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .
Java

Per specificare una suite di algoritmi alternativa, utilizzate il metodo. AwsCrypto.builder().withEncryptionAlgorithm() Questo esempio specifica una suite di algoritmi alternativa senza firme digitali.

// Specify an algorithm suite without signing

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
    .build();

String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a master key provider in strict mode
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);
    
// Create an encryption context to identify this ciphertext
        Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming");

// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
    masterKeyProvider,
    sourcePlaintext,
    encryptionContext);
byte[] ciphertext = encryptResult.getResult();

Quando trasmettete dati in streaming per la decrittografia, utilizzate il createUnsignedMessageDecryptingStream() metodo per assicurarvi che tutto il testo cifrato che state decriptando non sia firmato.

// Decrypt unsigned streaming data

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
  .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
  .withMaxEncryptedDataKeys(1)
  .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);

// Decrypt the encrypted message
FileInputStream in = new FileInputStream(srcFile + ".encrypted");  
CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in);
  
// Return the plaintext data
// Write the plaintext data to disk
FileOutputStream out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
JavaScript Browser

Per specificare una suite di algoritmi alternativa, utilizzate il parametro con un valore enum. suiteId AlgorithmSuiteIdentifier

// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key 
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Durante la decrittografia, utilizzate il metodo standard. decrypt SDK di crittografia AWS per JavaScript nel browser non è disponibile una decrypt-unsigned modalità perché il browser non supporta lo streaming. 

// Decrypt unsigned streaming data

// Instantiate the client 
const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Decrypt the encrypted message 
const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)
JavaScript Node.js

Per specificare una suite di algoritmi alternativa, utilizzate il suiteId parametro con un valore AlgorithmSuiteIdentifier enum.

// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringNode({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Per decrittografare dati crittografati senza firme digitali, utilizzate Stream. decryptUnsignedMessage Questo metodo fallisce se rileva testo cifrato firmato.

// Decrypt unsigned streaming data

// Instantiate the client 
const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringNode({ generatorKeyId })

// Decrypt the encrypted message 
const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))
Python

Per specificare un algoritmo di crittografia alternativo, utilizzate il algorithm parametro con un valore enum. Algorithm 

# Specify an algorithm suite without signing

# Instantiate a client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# 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 the plaintext using an alternate algorithm suite
ciphertext, encrypted_message_header = client.encrypt(
    algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
)

Quando decifrate messaggi crittografati senza firme digitali, utilizzate la modalità decrypt-unsigned streaming, specialmente quando decifrate durante lo streaming. 

# Decrypt unsigned streaming data

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# 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]
)

# Decrypt with decrypt-unsigned
with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext:
    with client.stream(mode="decrypt-unsigned", 
                       source=ciphertext, 
                       key_provider=master_key_provider) as decryptor:
        for chunk in decryptor:
            plaintext.write(chunk)

# Verify that the encryption context
assert all(
   pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items()
)
return ciphertext_filename, cycled_plaintext_filename

Limitazione delle chiavi di dati crittografate

È possibile limitare il numero di chiavi dati crittografate in un messaggio crittografato. Questa funzionalità basata sulle best practice può aiutarti a rilevare un portachiavi configurato in modo errato durante la crittografia o un testo cifrato dannoso durante la decrittografia. Inoltre, evita chiamate inutili, costose e potenzialmente esaustive all'infrastruttura chiave. La limitazione delle chiavi di dati crittografate è particolarmente utile quando si decifrano messaggi da una fonte non attendibile.

Sebbene la maggior parte dei messaggi crittografati disponga di una chiave dati crittografata per ogni chiave di wrapping utilizzata nella crittografia, un messaggio crittografato può contenere fino a 65.535 chiavi dati crittografate. Un malintenzionato potrebbe creare un messaggio crittografato con migliaia di chiavi di dati crittografate, nessuna delle quali può essere decrittografata. Di conseguenza, AWS Encryption SDK tenterebbe di decrittografare ogni chiave di dati crittografata fino a esaurire le chiavi di dati crittografate contenute nel messaggio.

Per limitare le chiavi dati crittografate, utilizzate il parametro. MaxEncryptedDataKeys Questo parametro è disponibile per tutti i linguaggi di programmazione supportati a partire dalla versione 1.9. x e 2.2. x del AWS Encryption SDK. È facoltativo e valido per la crittografia e la decrittografia. Gli esempi seguenti decrittografano i dati crittografati con tre diverse chiavi di wrapping. Il MaxEncryptedDataKeys valore è impostato su 3.

C
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = 
      Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 });

/* Create a session */
struct aws_cryptosdk_session *session = 
    aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);

/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3);
  
/* Decrypt */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(session,
    plaintext_output,
    plaintext_buf_sz_output,
    &plaintext_len_output,
    ciphertext_input,
    ciphertext_len_input,
    &ciphertext_consumed_output);
assert(aws_cryptosdk_session_is_done(session));
assert(ciphertext_consumed == ciphertext_len);
C# / .NET

Per limitare le chiavi di dati crittografate nel AWS Encryption SDK modulo. NET, crea un'istanza di un client per il AWS Encryption SDK modulo. NETe imposta il MaxEncryptedDataKeys parametro opzionale sul valore desiderato. Quindi, chiama il Decrypt() metodo sull' AWS Encryption SDK istanza configurata.

// Decrypt with limited data keys

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI
# Decrypt with limited encrypted data keys

$ aws-encryption-cli --decrypt \
    --input hello.txt.encrypted \
    --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
    --buffer \
    --max-encrypted-data-keys 3 \
    --encryption-context purpose=test \
    --metadata-output ~/metadata \
    --output .
Java
// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
  .withMaxEncryptedDataKeys(3)
  .build();

// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
      .buildStrict(keyArn1, keyArn2, keyArn3);
   
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
JavaScript Browser
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}
const clientProvider = getClient(KMS, {
  credentials: { accessKeyId, secretAccessKey, sessionToken }
})

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  clientProvider,
  keyIds: [keyArn1, keyArn2, keyArn3],
})

// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
JavaScript Node.js
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  keyIds: [keyArn1, keyArn2, keyArn3],
})
  
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
Python
# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)

# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
    key_ids=[key_arn1, key_arn2, key_arn3])

# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

Creazione di un filtro di scoperta

Quando si decifrano dati crittografati con KMS chiavi, è consigliabile decrittografarli in modalità rigorosa, ovvero limitare le chiavi di wrapping utilizzate solo a quelle specificate dall'utente. Tuttavia, se necessario, puoi anche decrittografare in modalità di scoperta, in cui non specifichi alcuna chiave di wrapping. In questa modalità, è AWS KMS possibile decrittografare la chiave dati crittografata utilizzando la KMS chiave che l'ha crittografata, indipendentemente da chi possiede o ha accesso a tale chiave. KMS

Se è necessario decrittografare in modalità di rilevamento, si consiglia di utilizzare sempre un filtro di rilevamento, che limita le KMS chiavi che possono essere utilizzate a quelle presenti in una partizione e specificata. Account AWS Il filtro di individuazione è facoltativo, ma è una procedura consigliata.

Utilizza la tabella seguente per determinare il valore della partizione per il filtro di rilevamento.

Regione Partizione
Regioni AWS aws
Regioni della Cina aws-cn
AWS GovCloud (US) Regions aws-us-gov

Gli esempi in questa sezione mostrano come creare un filtro di rilevamento. Prima di utilizzare il codice, sostituite i valori di esempio con valori validi per la partizione Account AWS and.

C

Per un esempio completo, vedere kms_discovery.cpp in. SDK di crittografia AWS per C

/* Create a discovery filter for an AWS account and partition */
    
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();
C# / .NET

Per un esempio completo, vedere DiscoveryFilterExample.cs nel modulo AWS Encryption SDK . NET.

// Create a discovery filter for an AWS account and partition

List<string> account = new List<string> { "111122223333" };

DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}
AWS Encryption CLI
# Decrypt in discovery mode with a discovery filter

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Per un esempio completo, DiscoveryDecryptionExamplevedi.java in. SDK di crittografia AWS per Java

// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
JavaScript (Node and Browser)

Per esempi completi, vedere kms_filtered_discovery.ts (Node.js) e kms_multi_region_discovery.ts (Browser) in. SDK di crittografia AWS per JavaScript

/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = { 
  accountIDs: ['111122223333'], 
  partition: 'aws',
}
Python

Per un esempio completo, vedere discovery_kms_provider.py in. SDK di crittografia AWS per Python

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

Impostazione di una politica di impegno

Una policy di impegno è un'impostazione di configurazione che determina se l'applicazione esegue la crittografia e la decrittografia con un impegno chiave. La crittografia e la decrittografia con impegno chiave è una procedura consigliata.AWS Encryption SDK

L'impostazione e la modifica della politica di impegno è un passaggio fondamentale nella migrazione dalle versioni 1.7. x e versioni precedenti della versione AWS Encryption SDK 2.0. x e versioni successive. Questa progressione è spiegata in dettaglio nell'argomento sulla migrazione.

Il valore predefinito della politica di impegno nelle versioni più recenti di AWS Encryption SDK (a partire dalla versione 2.0). x)RequireEncryptRequireDecrypt, è ideale per la maggior parte delle situazioni. Tuttavia, se è necessario decrittografare un testo cifrato che è stato crittografato senza l'impegno di una chiave, potrebbe essere necessario modificare la politica di impegno in. RequireEncryptAllowDecrypt Per esempi su come impostare una politica di impegno in ogni linguaggio di programmazione, vedi. Impostazione della politica di impegno

Lavorare con dati in streaming

Quando trasmetti dati in streaming per la decrittografia, tieni presente che AWS Encryption SDK restituisce testo in chiaro decrittografato dopo il completamento dei controlli di integrità, ma prima della verifica della firma digitale. Per evitare che venga restituito o utilizzato testo non crittografato fino alla verifica della firma, consigliamo di memorizzare nel buffer il testo non crittografato trasmesso in streaming fino al completamento dell'intero processo di decrittografia.

Questo problema si verifica solo quando si esegue lo streaming di testo cifrato per la decrittografia e solo quando si utilizza una suite di algoritmi, come la suite di algoritmi predefinita, che include firme digitali.

Per semplificare il buffering, alcune implementazioni del AWS Encryption SDK linguaggio, ad esempio SDK di crittografia AWS per JavaScript in Node.js, includono una funzionalità di buffering come parte del metodo di decrittografia. La AWS crittografiaCLI, che trasmette sempre input e output, ha introdotto un parametro nelle versioni 1.9. --buffer x e 2.2. x. In altre implementazioni linguistiche, è possibile utilizzare le funzionalità di buffering esistenti. (Il per. AWS Encryption SDK NETnon supporta lo streaming.)

Se utilizzi una suite di algoritmi senza firme digitali, assicurati di utilizzare la decrypt-unsigned funzionalità in ogni implementazione linguistica. Questa funzionalità decrittografa il testo cifrato ma fallisce se incontra testo cifrato firmato. Per informazioni dettagliate, consultare Scelta di una suite di algoritmi.

Memorizzazione nella cache delle chiavi dati

In generale, il riutilizzo delle chiavi dati è sconsigliato, ma AWS Encryption SDK offre un'opzione di memorizzazione nella cache delle chiavi dati che consente un riutilizzo limitato delle chiavi dati. La memorizzazione nella cache delle chiavi di dati può migliorare le prestazioni di alcune applicazioni e ridurre le chiamate all'infrastruttura chiave. Prima di utilizzare la memorizzazione nella cache delle chiavi di dati in produzione, regolate le soglie di sicurezza e verificate che i vantaggi superino gli svantaggi del riutilizzo delle chiavi dati.