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à.
# Portachiavi
[Le implementazioni del linguaggio di programmazione supportate utilizzano i *portachiavi* per eseguire la crittografia delle buste.](concepts.md#envelope-encryption) I keyring generano, crittografano e decrittano le chiavi di dati. I portachiavi determinano l'origine delle chiavi dati univoche che proteggono ogni messaggio e delle chiavi di [avvolgimento che crittografano tale chiave](concepts.md#master-key) di dati. Puoi specificare un keyring durante la crittografia e lo stesso keyring o uno diverso durante la decrittazione. Puoi utilizzare i keyring forniti dall'SDK oppure scrivere keyring personalizzati compatibili.
I keyring possono essere utilizzati singolarmente o combinati in [keyring multipli](use-multi-keyring.md). Anche se la maggior parte dei keyring è in grado di generare, crittografare e decrittare le chiavi di dati, ne puoi creare uno che esegua solo una determinata operazione, ad esempio la generazione delle chiavi di dati, e utilizzarlo in combinazione con altri.
Ti consigliamo di utilizzare un portachiavi che protegga le tue chiavi di wrapping ed esegua operazioni crittografiche entro un limite sicuro, come il AWS KMS portachiavi, che utilizza that never leave () unencrypted. AWS KMS keys [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)AWS KMS Puoi anche scrivere un portachiavi che utilizzi chiavi di avvolgimento archiviate nei moduli di sicurezza hardware (HSMs) o protette da altri servizi di chiavi principali. Per informazioni dettagliate, consulta l'argomento [Interfaccia di keyring](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md) nella *Specifica di AWS Encryption SDK *.
I portachiavi svolgono il ruolo delle chiavi [principali e dei fornitori](concepts.md#master-key-provider) di [chiavi principali](concepts.md#master-key) utilizzati nelle implementazioni di altri linguaggi di programmazione. Se utilizzi implementazioni linguistiche diverse per crittografare e AWS Encryption SDK decrittografare i dati, assicurati di utilizzare portachiavi e fornitori di chiavi master compatibili. Per informazioni dettagliate, vedi [Compatibilità dei keyring](#keyring-compatibility).
Questo argomento spiega come utilizzare la funzionalità portachiavi di AWS Encryption SDK e come scegliere un portachiavi.
## Come funzionano i keyring
Quando si crittografano i dati, viene AWS Encryption SDK richiesto al portachiavi i materiali di crittografia. Il portachiavi restituisce una chiave dati in testo semplice e una copia della chiave dati crittografata da ciascuna delle chiavi di avvolgimento del portachiavi. AWS Encryption SDK Utilizza la chiave di testo semplice per crittografare i dati, quindi distrugge la chiave di dati in testo semplice. Quindi, AWS Encryption SDK restituisce un [messaggio crittografato che include le chiavi di dati crittografate](concepts.md#message) e i dati crittografati.
![\[Crittografia con un portachiavi con più chiavi di avvolgimento.\]](http://docs.aws.amazon.com/it_it/encryption-sdk/latest/developer-guide/images/keyring-encrypt.png)
Quando decifri i dati, puoi usare lo stesso portachiavi che hai usato per crittografare i dati o uno diverso. Per decrittografare i dati, un portachiavi di decrittografia deve includere (o avere accesso a) almeno una chiave di avvolgimento nel portachiavi di crittografia.
AWS Encryption SDK Passa le chiavi di dati crittografate dal messaggio crittografato al portachiavi e chiede al portachiavi di decrittografarle tutte. Il keyring utilizza le chiavi di wrapping per decrittare una delle chiavi di dati crittografate e restituisce una chiave di dati di testo normale. AWS Encryption SDK utilizza la chiave di dati di testo normale per decrittare i dati. Se nessuna delle chiavi di wrapping nel keyring è in grado di decrittare una qualsiasi delle chiavi di dati crittografate, l'operazione di decrittazione non riesce.
![\[Decrittografia con un portachiavi.\]](http://docs.aws.amazon.com/it_it/encryption-sdk/latest/developer-guide/images/keyring-decrypt.png)
Puoi utilizzare un singolo keyring o combinarne più di uno dello stesso tipo o di tipi diversi in un [keyring multiplo](use-multi-keyring.md). Quando esegui la crittografia dei dati, il keyring multiplo restituisce una copia della chiave di dati crittografata da tutte le chiavi di wrapping di tutti i keyring che costituiscono il keyring multiplo. È possibile decrittografare i dati utilizzando un portachiavi con una qualsiasi delle chiavi di avvolgimento del portachiavi multiplo.
## Compatibilità dei keyring
Sebbene le diverse implementazioni linguistiche di presentino alcune differenze architettoniche, AWS Encryption SDK sono completamente compatibili, soggette a vincoli linguistici. È possibile crittografare i dati utilizzando un'implementazione linguistica e decrittografarli con qualsiasi altra implementazione linguistica. Tuttavia, è necessario utilizzare la stessa chiave di wrapping o quella corrispondente per crittografare e decrittografare le chiavi dati. Per informazioni sui vincoli linguistici, consultate l'argomento relativo a ciascuna implementazione linguistica, ad esempio nell'argomento. [Compatibilità del SDK di crittografia AWS per JavaScript](javascript-compatibility.md) SDK di crittografia AWS per JavaScript
I portachiavi sono supportati nei seguenti linguaggi di programmazione:
+ SDK di crittografia AWS per C
+ SDK di crittografia AWS per JavaScript
+ AWS Encryption SDK per.NET
+ versione 3. *x* del SDK di crittografia AWS per Java
+ Versione 4. *x* di SDK di crittografia AWS per Python, se utilizzato con la dipendenza opzionale [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
+ AWS Encryption SDK per Rust
+ AWS Encryption SDK per Go
### Requisiti diversi per i portachiavi di crittografia
Nelle implementazioni AWS Encryption SDK linguistiche diverse dalla SDK di crittografia AWS per C, tutte le chiavi di inserimento in un portachiavi di crittografia (o portachiavi multiplo) o in un provider di chiavi master devono essere in grado di crittografare la chiave dati. Se una chiave di wrapping non riesce a crittografare, il metodo di crittografia fallisce. Di conseguenza, il chiamante deve disporre delle [autorizzazioni necessarie](use-kms-keyring.md#kms-keyring-permissions) per tutte le chiavi del portachiavi. Se si utilizza un portachiavi Discovery per crittografare i dati, da solo o in un portachiavi multiplo, l'operazione di crittografia non riesce.
L'eccezione è l'operazione di crittografia SDK di crittografia AWS per C, in cui l'operazione di crittografia ignora un portachiavi di rilevamento standard, ma ha esito negativo se si specifica un portachiavi di rilevamento multiregionale, da solo o in un portachiavi multiplo.
### Keyring e fornitori di chiavi master compatibili
La tabella seguente mostra quali chiavi master e provider di chiavi master sono compatibili con i portachiavi forniti. AWS Encryption SDK Qualsiasi incompatibilità minore dovuta a vincoli linguistici è spiegata nell'argomento relativo all'implementazione della lingua.
| Portachiavi: | Fornitore di chiavi principali: |
| --- | --- |
| [AWS KMS portachiavi](use-kms-keyring.md) | [KMSMasterChiave (Java)](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/kms/KmsMasterKey.html) [KMSMasterKeyProvider (Java)](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/kms/KmsMasterKeyProvider.html) [KMSMasterChiave (Python)](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.kms.html) [KMSMasterKeyProvider (Python)](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.kms.html#aws_encryption_sdk.key_providers.kms.KMSMasterKeyProvider) Gli SDK di crittografia AWS per Python e SDK di crittografia AWS per Java non includono una chiave master o un provider di chiavi master equivalente al [portachiavi Discovery AWS KMS regionale](use-kms-keyring.md#kms-keyring-regional). |
| [AWS KMS Portachiavi gerarchico](use-hierarchical-keyring.md) | Supportato dai seguenti linguaggi e versioni di programmazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/encryption-sdk/latest/developer-guide/choose-keyring.html) |
| [AWS KMS Portachiavi ECDH](use-kms-ecdh-keyring.md) | Supportato dai seguenti linguaggi e versioni di programmazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/encryption-sdk/latest/developer-guide/choose-keyring.html) |
| [Keyring non elaborato AES](use-raw-aes-keyring.md) | Se utilizzati con chiavi di crittografia simmetriche:[JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)(Java)[RawMasterKey](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.raw.html#aws_encryption_sdk.key_providers.raw.RawMasterKey)(Python) |
| [Keyring non elaborato RSA](use-raw-rsa-keyring.md) | Se utilizzati con chiavi di crittografia asimmetriche:[JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)(Java)[RawMasterKey](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.raw.html#aws_encryption_sdk.key_providers.raw.RawMasterKey)(Python) Il portachiavi Raw RSA non supporta le chiavi KMS asimmetriche. Se desideri utilizzare chiavi RSA KMS asimmetriche, versione 4. *x* e versioni successive di AWS Encryption SDK for .NET supportano i AWS KMS portachiavi che utilizzano la crittografia simmetrica () o l'RSA asimmetrica. `SYMMETRIC_DEFAULT` AWS KMS keys |
| [Portachiavi ECDH grezzo](use-raw-ecdh-keyring.md) | Supportato dai seguenti linguaggi e versioni di programmazione: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/encryption-sdk/latest/developer-guide/choose-keyring.html) |
# AWS KMS portachiavi
Un AWS KMS portachiavi viene utilizzato [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)per generare, crittografare e decrittografare chiavi di dati. AWS Key Management Service (AWS KMS) protegge le chiavi KMS ed esegue operazioni crittografiche entro i confini FIPS. Ti consigliamo di utilizzare un AWS KMS portachiavi o un portachiavi con proprietà di sicurezza simili, quando possibile.
Tutte le implementazioni del linguaggio di programmazione che supportano i portachiavi supportano i portachiavi che utilizzano AWS KMS chiavi KMS con crittografia simmetrica. Le seguenti implementazioni del linguaggio di programmazione supportano anche i portachiavi che utilizzano AWS KMS chiavi RSA KMS asimmetriche:
+ Versione 3. *x* del SDK di crittografia AWS per Java
+ Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
+ Versione 4. *x* di SDK di crittografia AWS per Python, se utilizzato con la dipendenza opzionale [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
+ Versione 1. *x* del AWS Encryption SDK per Rust
+ Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
Se si tenta di includere una chiave KMS asimmetrica in un portachiavi di crittografia in qualsiasi altra implementazione linguistica, la chiamata di crittografia ha esito negativo. Se la includi in un portachiavi di decrittografia, viene ignorata.
[È possibile utilizzare una chiave AWS KMS multiregionale in un portachiavi o in un provider di AWS KMS chiavi master a partire dalla versione 2.3. ](about-versions.md#version2.3)*x* della versione AWS Encryption SDK 3.0. *x* della CLI di AWS crittografia. Per dettagli ed esempi di utilizzo del multi-Region-aware simbolo, vedere[Utilizzo di più regioni AWS KMS keys](configure.md#config-mrks). Per informazioni sulle chiavi multiregionali, consulta [Uso delle chiavi multiregionali nella Guida](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) per gli *AWS Key Management Service sviluppatori*.
**Nota**
Tutte le menzioni relative ai portachiavi *KMS nella sezione si riferiscono ai portachiavi*. AWS Encryption SDK AWS KMS
AWS KMS i portachiavi possono includere due tipi di chiavi avvolgenti:
+ **Chiave generatrice: genera una chiave** di dati in testo semplice e la crittografa. Un portachiavi che crittografa i dati deve avere una chiave generatrice.
+ **Chiavi aggiuntive**: crittografa la chiave di dati in testo semplice generata dalla chiave del generatore. AWS KMS I portachiavi possono avere zero o più chiavi aggiuntive.
È necessario disporre di una chiave generatrice per crittografare i messaggi. Quando un AWS KMS portachiavi ha una sola chiave KMS, tale chiave viene utilizzata per generare e crittografare la chiave dati. Durante la decrittografia, la chiave del generatore è facoltativa e la distinzione tra chiavi del generatore e chiavi aggiuntive viene ignorata.
Come tutti i portachiavi, i AWS KMS portachiavi possono essere utilizzati indipendentemente o in un portachiavi [multiplo con altri portachiavi dello stesso](use-multi-keyring.md) tipo o di un tipo diverso.
**Topics**
+ [AWS KMS Autorizzazioni richieste per i portachiavi](#kms-keyring-permissions)
+ [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
+ [Creazione di un portachiavi AWS KMS](#kms-keyring-encrypt)
+ [AWS KMS Utilizzo di un portachiavi Discovery](#kms-keyring-discovery)
+ [Utilizzo di un portachiavi AWS KMS Regional Discovery](#kms-keyring-regional)
## AWS KMS Autorizzazioni richieste per i portachiavi
AWS Encryption SDK Non richiede un Account AWS e non dipende da nessuno. Servizio AWS Tuttavia, per utilizzare un AWS KMS portachiavi, sono necessarie le seguenti autorizzazioni Account AWS minime sul AWS KMS keys portachiavi.
+ Per crittografare con un AWS KMS portachiavi, è necessaria l'autorizzazione [kms: GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) sulla chiave del generatore. È necessaria l'autorizzazione [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) su tutte le chiavi aggiuntive nel portachiavi. AWS KMS
+ Per decriptare con un AWS KMS portachiavi, è necessaria l'autorizzazione [KMS:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) su almeno una chiave del portachiavi. AWS KMS
+ [Per crittografare con un portachiavi multiplo composto da portachiavi, è necessaria l'autorizzazione kms: sulla AWS KMS chiave del generatore nel portachiavi del generatore. GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) È necessaria l'autorizzazione [KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) su tutte le altre chiavi in tutti gli altri portachiavi. AWS KMS
+ Per crittografare con un AWS KMS portachiavi RSA asimmetrico, non è necessario [kms: GenerateDataKey o KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) [perché è necessario specificare il materiale della chiave pubblica che si desidera utilizzare per la crittografia](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) quando si crea il portachiavi. Non vengono effettuate chiamate durante la crittografia con questo portachiavi. AWS KMS [Per decrittografare con un portachiavi AWS KMS RSA asimmetrico, è necessaria l'autorizzazione KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
[https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html)
## Identificazione AWS KMS keys in un portachiavi AWS KMS
Un AWS KMS portachiavi può includerne uno o più. AWS KMS keys Per specificare un elemento AWS KMS key in un AWS KMS portachiavi, utilizzate un identificatore di AWS KMS chiave supportato. Gli identificatori di chiave che è possibile utilizzare per identificare un elemento AWS KMS key in un portachiavi variano a seconda dell'operazione e dell'implementazione del linguaggio. *Per informazioni dettagliate sugli identificatori chiave di an AWS KMS key, consulta [Key Identifiers](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) nella Developer Guide.AWS Key Management Service *
Come procedura consigliata, utilizzate l'identificatore di chiave più specifico e pratico per la vostra attività.
+ In un portachiavi di crittografia per SDK di crittografia AWS per C, è possibile utilizzare una [chiave ARN o un [alias ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) per identificare le chiavi KMS. In tutte le altre implementazioni linguistiche, puoi utilizzare un [ID chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id), un [ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN), un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN per crittografare i [dati](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN).
+ In un keyring di decrittazione devi utilizzare un ARN di chiave per identificare le AWS KMS keys. Questo requisito si applica a tutte le implementazioni di linguaggio di AWS Encryption SDK. Per informazioni dettagliate, vedi [Selezione dei tasti di avvolgimento](configure.md#config-keys).
+ In un keyring utilizzato per la crittografia e la decrittazione devi utilizzare un ARN di chiave per identificare le AWS KMS keys. Questo requisito si applica a tutte le implementazioni di linguaggio di AWS Encryption SDK.
Se si specifica un nome alias o un alias ARN per una chiave KMS in un portachiavi di crittografia, l'operazione di crittografia salva la chiave ARN attualmente associata all'alias nei metadati della chiave dati crittografata. Non salva l'alias. Le modifiche all'alias non influiscono sulla chiave KMS utilizzata per decrittografare le chiavi di dati crittografate.
## Creazione di un portachiavi AWS KMS
È possibile configurare ogni AWS KMS portachiavi con uno AWS KMS key o più portachiavi nello stesso e AWS KMS keys in modo diverso Account AWS . Regioni AWS AWS KMS keys Deve essere una chiave KMS con crittografia simmetrica (SYMMETRIC\$1DEFAULT) o una chiave KMS RSA asimmetrica. È inoltre possibile utilizzare una [chiave KMS multiregionale con crittografia simmetrica](configure.md#config-mrks). [È possibile utilizzare uno o più AWS KMS portachiavi in un portachiavi multiplo.](use-multi-keyring.md)
È possibile creare un AWS KMS portachiavi che crittografa e decrittografa i dati oppure creare AWS KMS portachiavi specifici per crittografare o decrittografare. Quando si crea un AWS KMS portachiavi per crittografare i dati, è necessario specificare una *chiave generatrice, AWS KMS key che viene utilizzata per generare una chiave* di dati in testo semplice e crittografarla. La chiave dati non è matematicamente correlata alla chiave KMS. Quindi, se lo desideri, puoi specificarne altre AWS KMS keys che crittografano la stessa chiave di dati in testo normale. Per decrittografare un campo crittografato protetto da questo portachiavi, il portachiavi di decrittografia utilizzato deve includere almeno uno dei valori definiti nel portachiavi, altrimenti no. AWS KMS keys AWS KMS keys[(Un AWS KMS portachiavi senza è noto come portachiavi Discovery. AWS KMS keys )AWS KMS](#kms-keyring-discovery)
Nelle implementazioni AWS Encryption SDK linguistiche diverse dalla SDK di crittografia AWS per C, tutte le chiavi di inserimento in un portachiavi di crittografia o in un portachiavi multiplo devono essere in grado di crittografare la chiave dati. Se una chiave di wrapping non riesce a crittografare, il metodo encrypt fallisce. Di conseguenza, il chiamante deve disporre delle [autorizzazioni necessarie](#kms-keyring-permissions) per tutte le chiavi del portachiavi. Se si utilizza un portachiavi Discovery per crittografare i dati, da solo o in un portachiavi multiplo, l'operazione di crittografia non riesce. L'eccezione è l'operazione di crittografia SDK di crittografia AWS per C, in cui l'operazione di crittografia ignora un portachiavi di rilevamento standard, ma ha esito negativo se si specifica un portachiavi di rilevamento multiregionale, da solo o in un portachiavi multiplo.
Gli esempi seguenti creano un AWS KMS portachiavi con una chiave generatrice e una chiave aggiuntiva. Sia la chiave del generatore che la chiave aggiuntiva sono chiavi KMS con crittografia simmetrica. Questi esempi utilizzano la [chiave ARNs per identificare le chiavi KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). Si tratta di una procedura ottimale per i AWS KMS portachiavi utilizzati per la crittografia e un requisito per i AWS KMS portachiavi utilizzati per la decrittografia. Per informazioni dettagliate, vedi [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id).
------
#### [ C ]
Per identificare un elemento AWS KMS key in un portachiavi di crittografia in SDK di crittografia AWS per C, specificare una [chiave ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) ARN. In un keyring di decrittografia devi utilizzare un ARN di chiave. Per informazioni dettagliate, vedi [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id).
Per un esempio completo, vedi [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp).
```
const char * generator_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
struct aws_cryptosdk_keyring *kms_encrypt_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key,{additional_key});
```
------
#### [ C\$1 / .NET ]
Per creare un portachiavi con una o più chiavi KMS in formato.NET, usa AWS Encryption SDK il metodo. `CreateAwsKmsMultiKeyring()` Questo esempio utilizza due AWS KMS chiavi. Per specificare una chiave KMS, utilizzate solo il `Generator` parametro. Il `KmsKeyIds` parametro che specifica le chiavi KMS aggiuntive è facoltativo.
L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDK Utilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del `Generator` parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (`us-west-2`), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. `us-west-2` Se è necessario personalizzare il AWS KMS client, utilizzare il `CreateAwsKmsKeyring()` metodo.
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in per.NET, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). AWS Encryption SDK](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni su come identificarlo in un portachiavi, consulta. AWS KMS keys AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente utilizza la versione 4. *x* del AWS Encryption SDK per .NET e il `CreateAwsKmsKeyring()` metodo per personalizzare il AWS KMS client.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List additionalKeys = new List { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };
// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
Generator = generatorKey,
KmsKeyIds = additionalKeys
};
var kmsEncryptKeyring = mpl.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);
```
------
#### [ JavaScript Browser ]
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in SDK di crittografia AWS per JavaScript, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID di chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni sull' AWS KMS keys identificazione di un portachiavi, vedere. AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
Per un esempio completo, vedi [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts) nel repository in. SDK di crittografia AWS per JavaScript GitHub
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const clientProvider = getClient(KMS, { credentials })
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
const additionalKey = 'alias/exampleAlias'
const keyring = new KmsKeyringBrowser({
clientProvider,
generatorKeyId,
keyIds: [additionalKey]
})
```
------
#### [ JavaScript Node.js ]
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in SDK di crittografia AWS per JavaScript, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID di chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni sull' AWS KMS keys identificazione di un portachiavi, vedere. AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
Per un esempio completo, vedi [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts) nel repository in. SDK di crittografia AWS per JavaScript GitHub
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
const additionalKey = 'alias/exampleAlias'
const keyring = new KmsKeyringNode({
generatorKeyId,
keyIds: [additionalKey]
})
```
------
#### [ Java ]
Per creare un portachiavi con una o più chiavi, usa il metodo. AWS KMS `CreateAwsKmsMultiKeyring()` Questo esempio utilizza due chiavi KMS. Per specificare una chiave KMS, usa solo il `generator` parametro. Il `kmsKeyIds` parametro che specifica le chiavi KMS aggiuntive è facoltativo.
L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDK Utilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del `Generator` parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (`us-west-2`), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. `us-west-2` Se è necessario personalizzare il AWS KMS client, utilizzare il `CreateAwsKmsKeyring()` metodo.
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in SDK di crittografia AWS per Java, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID di chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni sull' AWS KMS keys identificazione di un portachiavi, vedere. AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
Per un esempio completo, consulta [BasicEncryptionKeyringExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/keyrings/BasicEncryptionKeyringExample.java) nel SDK di crittografia AWS per Java repository in. GitHub
```
// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List additionalKey = Collections.singletonList("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(generatorKey)
.kmsKeyIds(additionalKey)
.build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
```
------
#### [ Python ]
Per creare un portachiavi con una o più AWS KMS chiavi, utilizzate il metodo. `create_aws_kms_multi_keyring()` Questo esempio utilizza due chiavi KMS. Per specificare una chiave KMS, usa solo il `generator` parametro. Il `kms_key_ids` parametro che specifica le chiavi KMS aggiuntive è facoltativo.
L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDK Utilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del `generator` parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (`us-west-2`), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. `us-west-2` Se è necessario personalizzare il AWS KMS client, utilizzare il `create_aws_kms_keyring()` metodo.
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in SDK di crittografia AWS per Python, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID di chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni sull' AWS KMS keys identificazione di un portachiavi, vedere. AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente crea un'istanza del AWS Encryption SDK client con la politica di [impegno predefinita](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Per un esempio completo, vedere [aws\$1kms\$1multi\$1keyring\$1example.py](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/aws_kms_multi_keyring_example.py) nel SDK di crittografia AWS per Python repository in. GitHub
```
# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
"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
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create the AWS KMS keyring
kms_multi_keyring_input: CreateAwsKmsMultiKeyringInput = CreateAwsKmsMultiKeyringInput(
generator="arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
kms_key_ids="arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
)
kms_multi_keyring: IKeyring = mat_prov.create_aws_kms_multi_keyring(
input=kms_multi_keyring_input
)
```
------
#### [ Rust ]
Per creare un portachiavi con una o più AWS KMS chiavi, utilizzate il `create_aws_kms_multi_keyring()` metodo. Questo esempio utilizza due chiavi KMS. Per specificare una chiave KMS, usa solo il `generator` parametro. Il `kms_key_ids` parametro che specifica le chiavi KMS aggiuntive è facoltativo.
L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDK Utilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del `generator` parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (`us-west-2`), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. `us-west-2` Se è necessario personalizzare il AWS KMS client, utilizzare il `create_aws_kms_keyring()` metodo.
[Quando si specifica un AWS KMS key per un portachiavi di crittografia in AWS Encryption SDK for Rust, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni sull'identificazione di un portachiavi, consulta. AWS KMS keys AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente crea un'istanza del AWS Encryption SDK client con la politica di [impegno predefinita](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Per un esempio completo, consulta [aws\$1kms\$1keyring\$1example.rs nella directory Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/keyring/aws_kms_keyring_example.rs) del repository on. aws-encryption-sdk GitHub
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().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);
// Optional: Create an 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 the AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
kms_multi_keyring: IKeyring = mpl.create_aws_kms_multi_keyring(
input=kms_multi_keyring_input
)
```
------
#### [ Go ]
Per creare un portachiavi con una o più chiavi, usa il metodo. AWS KMS `create_aws_kms_multi_keyring()` Questo esempio utilizza due chiavi KMS. Per specificare una chiave KMS, usa solo il `generator` parametro. Il `kms_key_ids` parametro che specifica le chiavi KMS aggiuntive è facoltativo.
L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDK Utilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del `generator` parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (`us-west-2`), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. `us-west-2` Se è necessario personalizzare il AWS KMS client, utilizzare il `create_aws_kms_keyring()` metodo.
[Quando si specifica un portachiavi di crittografia in AWS KMS keyAWS Encryption SDK for Go, è possibile utilizzare qualsiasi identificatore di chiave valido: un [ID chiave, un ARN di chiave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)[, un nome alias o un [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-name) ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) Per informazioni su come identificarlo in un portachiavi, consulta. AWS KMS keys AWS KMS [Identificazione AWS KMS keys in un portachiavi AWS KMS](#kms-keyring-id)
L'esempio seguente crea un'istanza del AWS Encryption SDK client con la politica di [impegno predefinita](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`
```
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"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// 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 the AWS KMS keyring
awsKmsMultiKeyringInput := mpltypes.CreateAwsKmsMultiKeyringInput{
Generator: "&arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
KmsKeyIds: []string{"arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"},
}
awsKmsMultiKeyring, err := matProv.CreateAwsKmsMultiKeyring(context.Background(), awsKmsMultiKeyringInput)
```
------
Supporta AWS Encryption SDK anche portachiavi che utilizzano AWS KMS chiavi RSA KMS asimmetriche. I portachiavi RSA asimmetrici possono contenere solo una coppia di AWS KMS chiavi.
Per crittografare con un AWS KMS portachiavi RSA asimmetrico, non hai bisogno di [kms: GenerateDataKey o KMS:Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) [perché devi specificare il materiale della chiave pubblica che desideri utilizzare per la crittografia](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) quando crei il portachiavi. Non vengono effettuate chiamate durante la crittografia con questo portachiavi. AWS KMS [Per decrittografare con un portachiavi AWS KMS RSA asimmetrico, è necessaria l'autorizzazione KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
**Nota**
Per creare un AWS KMS portachiavi che utilizzi chiavi RSA KMS asimmetriche, è necessario utilizzare una delle seguenti implementazioni del linguaggio di programmazione:
Versione 3. *x* del SDK di crittografia AWS per Java
Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
Versione 4. *x* di SDK di crittografia AWS per Python, se utilizzato con la dipendenza opzionale [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
Versione 1. *x* del AWS Encryption SDK per Rust
Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
Gli esempi seguenti utilizzano il `CreateAwsKmsRsaKeyring` metodo per creare un AWS KMS portachiavi con una chiave RSA KMS asimmetrica. Per creare un portachiavi RSA asimmetrico, fornisci i seguenti valori. AWS KMS
+ `kmsClient`: crea un nuovo client AWS KMS
+ `kmsKeyID`: la chiave ARN che identifica la tua chiave RSA KMS asimmetrica
+ `publicKey`: a ByteBuffer di un file PEM con codifica UTF-8 che rappresenta la chiave pubblica della chiave a cui hai passato `kmsKeyID`
+ `encryptionAlgorithm`: l'algoritmo di crittografia deve essere o `RSAES_OAEP_SHA_256` `RSAES_OAEP_SHA_1`
------
#### [ C\$1 / .NET ]
Per creare un AWS KMS portachiavi RSA asimmetrico, devi fornire la chiave pubblica e la chiave privata ARN della tua chiave RSA KMS asimmetrica. La chiave pubblica deve essere codificata in PEM. L'esempio seguente crea un AWS KMS portachiavi con una coppia di chiavi RSA asimmetrica.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = AWS KMS RSA private key ARN,
PublicKey = publicKey,
EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};
// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);
```
------
#### [ Java ]
Per creare un AWS KMS portachiavi RSA asimmetrico, devi fornire la chiave pubblica e la chiave privata ARN della tua chiave RSA KMS asimmetrica. La chiave pubblica deve essere codificata in PEM. L'esempio seguente crea un AWS KMS portachiavi con una coppia di chiavi RSA asimmetrica.
```
// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder()
// Specify algorithmSuite without asymmetric signing here
//
// ALG_AES_128_GCM_IV12_TAG16_NO_KDF("0x0014"),
// ALG_AES_192_GCM_IV12_TAG16_NO_KDF("0x0046"),
// ALG_AES_256_GCM_IV12_TAG16_NO_KDF("0x0078"),
// ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256("0x0114"),
// ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256("0x0146"),
// ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256("0x0178")
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a KMS RSA keyring.
// This keyring takes in:
// - kmsClient
// - kmsKeyId: Must be an ARN representing an asymmetric RSA KMS key
// - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
// key for the key passed into kmsKeyId
// - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
CreateAwsKmsRsaKeyringInput.builder()
.kmsClient(KmsClient.create())
.kmsKeyId(rsaKeyArn)
.publicKey(publicKey)
.encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
.build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
```
------
#### [ Python ]
Per creare un AWS KMS portachiavi RSA asimmetrico, devi fornire la chiave pubblica e la chiave privata ARN della tua chiave RSA KMS asimmetrica. La chiave pubblica deve essere codificata in PEM. L'esempio seguente crea un AWS KMS portachiavi con una coppia di chiavi RSA asimmetrica.
```
# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
"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
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create the AWS KMS keyring
keyring_input: CreateAwsKmsRsaKeyringInput = CreateAwsKmsRsaKeyringInput(
public_key="public_key",
kms_key_id="kms_key_id",
encryption_algorithm="RSAES_OAEP_SHA_256",
kms_client=kms_client
)
kms_rsa_keyring: IKeyring = mat_prov.create_aws_kms_rsa_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
Per creare un AWS KMS portachiavi RSA asimmetrico, devi fornire la chiave pubblica e la chiave privata ARN della tua chiave RSA KMS asimmetrica. La chiave pubblica deve essere codificata in PEM. L'esempio seguente crea un AWS KMS portachiavi con una coppia di chiavi RSA asimmetrica.
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().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);
// Optional: Create an 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 the AWS KMS keyring
let kms_rsa_keyring = mpl
.create_aws_kms_rsa_keyring()
.kms_key_id(kms_key_id)
.public_key(aws_smithy_types::Blob::new(public_key))
.encryption_algorithm(aws_sdk_kms::types::EncryptionAlgorithmSpec::RsaesOaepSha256)
.kms_client(kms_client)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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 the AWS KMS keyring
awsKmsRSAKeyringInput := mpltypes.CreateAwsKmsRsaKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyID,
PublicKey: kmsPublicKey,
EncryptionAlgorithm: kmstypes.EncryptionAlgorithmSpecRsaesOaepSha256,
}
awsKmsRSAKeyring, err := matProv.CreateAwsKmsRsaKeyring(context.Background(), awsKmsRSAKeyringInput)
if err != nil {
panic(err)
}
```
------
## AWS KMS Utilizzo di un portachiavi Discovery
Durante la decrittografia, è consigliabile specificare [le](best-practices.md) chiavi di wrapping che possono utilizzare. AWS Encryption SDK Per seguire questa procedura ottimale, utilizzate un portachiavi di AWS KMS decrittografia che limiti le chiavi di AWS KMS wrapping a quelle specificate. Tuttavia, puoi anche creare un *portachiavi AWS KMS Discovery, ovvero un AWS KMS portachiavi* che non specifichi alcuna chiave di avvolgimento.
AWS Encryption SDK Fornisce un portachiavi AWS KMS Discovery standard e un portachiavi Discovery per chiavi multiregionali. AWS KMS Per informazioni sull'utilizzo delle chiavi multiregionali con, vedere. AWS Encryption SDK[Utilizzo di più regioni AWS KMS keys](configure.md#config-mrks)
Poiché non specifica alcuna chiave di wrapping, un portachiavi Discovery non può crittografare i dati. Se si utilizza un portachiavi Discovery per crittografare i dati, da solo o in un portachiavi multiplo, l'operazione di crittografia non riesce. L'eccezione è l'operazione di crittografia SDK di crittografia AWS per C, in cui l'operazione di crittografia ignora un portachiavi di rilevamento standard, ma ha esito negativo se si specifica un portachiavi di rilevamento multiregionale, da solo o in un portachiavi multiplo.
Durante la decrittografia, un portachiavi Discovery consente di chiedere AWS KMS di AWS Encryption SDK decrittografare qualsiasi chiave di dati crittografata utilizzando quella che l'ha crittografata, indipendentemente da chi la possiede o ha accesso a AWS KMS key tale chiave. AWS KMS key La chiamata ha esito positivo solo quando il chiamante dispone dell'autorizzazione per. `kms:Decrypt` AWS KMS key
**Importante**
Se includi un portachiavi AWS KMS Discovery in un portachiavi [multiplo di decrittografia, il portachiavi](use-multi-keyring.md) Discovery ha la precedenza su tutte le restrizioni relative alle chiavi KMS specificate dagli altri portachiavi del portachiavi multiplo. Il portachiavi multiplo si comporta come il portachiavi meno restrittivo. Un portachiavi AWS KMS Discovery non ha alcun effetto sulla crittografia se utilizzato da solo o in un portachiavi multiplo.
AWS Encryption SDK Fornisce un portachiavi AWS KMS Discovery per una maggiore comodità. ma, se possibile, consigliamo di utilizzare un keyring di portata più limitata per i motivi seguenti.
+ **Autenticità**: un portachiavi AWS KMS Discovery può utilizzare qualsiasi chiave utilizzata per crittografare una chiave di dati nel messaggio crittografato, solo in modo AWS KMS key che il chiamante abbia il permesso di utilizzarla per decrittografarla. AWS KMS key Questo potrebbe non essere quello AWS KMS key che il chiamante intende utilizzare. Ad esempio, una delle chiavi di dati crittografate potrebbe essere stata crittografata con un metodo meno sicuro AWS KMS key che chiunque può utilizzare.
+ **Latenza e prestazioni**: un portachiavi AWS KMS Discovery potrebbe essere sensibilmente più lento rispetto ad altri portachiavi perché AWS Encryption SDK tenta di decrittografare tutte le chiavi di dati crittografate, comprese quelle crittografate AWS KMS keys in altre regioni, Account AWS e AWS KMS keys che il chiamante non è autorizzato a utilizzare per la decrittografia.
[Se utilizzi un portachiavi di rilevamento, ti consigliamo di utilizzare un [*filtro di rilevamento per limitare le chiavi KMS che possono essere utilizzate a quelle contenute*](configure.md#config-discovery) in partizioni e specifiche. Account AWS](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) I filtri Discovery sono supportati nelle versioni 1.7. *x* e versioni successive di AWS Encryption SDK. Per informazioni su come trovare l'ID e la partizione dell'account, consulta [I tuoi Account AWS identificatori e](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html) il formato [ARN in. *Riferimenti generali di AWS*](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)
Il codice seguente crea un'istanza di un portachiavi di AWS KMS rilevamento con un filtro di rilevamento che limita le chiavi KMS AWS Encryption SDK utilizzabili a quelle presenti nella partizione e nell'account di esempio 111122223333. `aws`
Prima di utilizzare questo codice, sostituisci i valori di esempio Account AWS e di partizione con valori validi per la tua partizione and. Account AWS Se le tue chiavi KMS si trovano nelle regioni della Cina, usa il valore della `aws-cn` partizione. Se le tue chiavi KMS sono inserite AWS GovCloud (US) Regions, usa il valore della `aws-us-gov` partizione. Per tutti gli altri Regioni AWS, usa il valore della `aws` partizione.
------
#### [ C ]
Per un esempio completo, vedi: [ 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")
.Build());
struct aws_cryptosdk_keyring *kms_discovery_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.BuildDiscovery(discovery_filter));
```
------
#### [ C\$1 / .NET ]
L'esempio seguente utilizza la versione 4. *x* del AWS Encryption SDK per .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
List account = new List { "111122223333" };
// In a discovery keyring, you specify an AWS KMS client and a discovery filter,
// but not a AWS KMS key
var kmsDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = account,
Partition = "aws"
}
};
var kmsDiscoveryKeyring = mpl.CreateAwsKmsDiscoveryKeyring(kmsDiscoveryKeyringInput);
```
------
#### [ JavaScript Browser ]
In JavaScript, è necessario specificare in modo esplicito la proprietà discovery.
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
In JavaScript, è necessario specificare in modo esplicito la proprietà discovery.
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const discovery = true
const keyring = new KmsKeyringNode({
discovery,
discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
```
------
#### [ Java ]
```
// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Python ]
```
# Instantiate the AWS Encryption SDK
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# Create a boto3 client for AWS KMS
kms_client = boto3.client('kms', region_name=aws_region)
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
"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
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create the AWS KMS discovery keyring
discovery_keyring_input: CreateAwsKmsDiscoveryKeyringInput = CreateAwsKmsDiscoveryKeyringInput(
kms_client=kms_client,
discovery_filter=DiscoveryFilter(
account_ids=[aws_account_id],
partition="aws"
)
)
discovery_keyring: IKeyring = mat_prov.create_aws_kms_discovery_keyring(
input=discovery_keyring_input
)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create a 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);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.account_ids(vec![aws_account_id.to_string()])
.partition("aws".to_string())
.build()?;
// Create the AWS KMS discovery keyring
let discovery_keyring = mpl
.create_aws_kms_discovery_keyring()
.kms_client(kms_client.clone())
.discovery_filter(discovery_filter)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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 discovery filter
discoveryFilter := mpltypes.DiscoveryFilter{
AccountIds: []string{kmsKeyAccountID},
Partition: "aws",
}
awsKmsDiscoveryKeyringInput := mpltypes.CreateAwsKmsDiscoveryKeyringInput{
KmsClient: kmsClient,
DiscoveryFilter: &discoveryFilter,
}
awsKmsDiscoveryKeyring, err := matProv.CreateAwsKmsDiscoveryKeyring(context.Background(), awsKmsDiscoveryKeyringInput)
if err != nil {
panic(err)
}
```
------
## Utilizzo di un portachiavi AWS KMS Regional Discovery
Un *portachiavi AWS KMS Regional Discovery* è un portachiavi che non specifica le ARNs chiavi KMS. Invece, consente la decrittografia utilizzando solo AWS Encryption SDK le chiavi KMS in particolare. Regioni AWS
Quando si decrittografa con un portachiavi AWS KMS Regional Discovery, AWS Encryption SDK decripta qualsiasi chiave di dati crittografata che è stata crittografata con un codice specificato. AWS KMS key Regione AWS Per avere successo, il chiamante deve disporre dell'`kms:Decrypt`autorizzazione su almeno una delle chiavi di dati specificate Regione AWS che hanno AWS KMS keys crittografato una chiave dati.
Come altri portachiavi Discovery, il portachiavi Discovery regionale non ha alcun effetto sulla crittografia. Funziona solo quando si decifrano messaggi crittografati. Se si utilizza un portachiavi Regional Discovery in un portachiavi multiplo utilizzato per la crittografia e la decrittografia, è efficace solo durante la decrittografia. Se si utilizza un portachiavi di rilevamento multiregionale per crittografare i dati, da solo o in un portachiavi multiregionale, l'operazione di crittografia non riesce.
**Importante**
Se includi un portachiavi di rilevamento AWS KMS regionale in un portachiavi multiplo di decrittografia, il portachiavi di rilevamento regionale ha la precedenza su tutte le restrizioni relative alle [chiavi KMS specificate dagli altri portachiavi del portachiavi multiplo](use-multi-keyring.md). Il portachiavi multiplo si comporta come il portachiavi meno restrittivo. Un portachiavi AWS KMS Discovery non ha alcun effetto sulla crittografia se utilizzato da solo o in un portachiavi multiplo.
Il portachiavi Regional Discovery SDK di crittografia AWS per C tenta di decriptare solo con chiavi KMS nella regione specificata. Quando si utilizza un portachiavi di rilevamento in SDK di crittografia AWS per JavaScript e AWS Encryption SDK per .NET, si configura la regione sul client. AWS KMS Queste AWS Encryption SDK implementazioni non filtrano le chiavi KMS per regione, ma AWS KMS falliranno una richiesta di decrittografia delle chiavi KMS al di fuori della regione specificata.
Se utilizzi un portachiavi di rilevamento, ti consigliamo di utilizzare un *filtro di rilevamento* per limitare le chiavi KMS utilizzate nella decrittografia a quelle nelle partizioni e nelle partizioni specificate. Account AWS I filtri Discovery sono supportati nelle versioni 1.7. *x* e versioni successive di AWS Encryption SDK.
Ad esempio, il codice seguente crea un portachiavi di rilevamento AWS KMS regionale con un filtro di scoperta. Questo portachiavi limita le AWS Encryption SDK chiavi KMS nel conto 111122223333 nella regione Stati Uniti occidentali (Oregon) (us-west-2).
------
#### [ C ]
Per esaminare un esempio che mostra questo keyring e il metodo `create_kms_client`, consulta [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")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ C\$1 / .NET ]
Il portachiavi AWS Encryption SDK per .NET non dispone di un portachiavi dedicato alla scoperta regionale. Tuttavia, è possibile utilizzare diverse tecniche per limitare le chiavi KMS utilizzate durante la decrittografia a una particolare regione.
Il modo più efficiente per limitare le regioni in un portachiavi di rilevamento consiste nell'utilizzare un portachiavi di multi-Region-aware rilevamento, anche se i dati sono stati crittografati utilizzando solo chiavi a regione singola. Quando incontra chiavi a regione singola, il multi-Region-aware portachiavi non utilizza alcuna funzionalità multiregionale.
Il portachiavi restituito dal `CreateAwsKmsMrkDiscoveryKeyring()` metodo filtra le chiavi KMS per regione prima della chiamata. AWS KMS Invia una richiesta di decrittografia AWS KMS solo quando la chiave di dati crittografata è stata crittografata da una chiave KMS nella regione specificata dal parametro nell'`Region`oggetto. `CreateAwsKmsMrkDiscoveryKeyringInput`
Gli esempi seguenti utilizzano la versione 4. *x* del AWS Encryption SDK per .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
List account = new List { "111122223333" };
// Create the discovery filter
var filter = DiscoveryFilter = new DiscoveryFilter
{
AccountIds = account,
Partition = "aws"
};
var regionalDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
Region = RegionEndpoint.USWest2,
DiscoveryFilter = filter
};
var kmsRegionalDiscoveryKeyring = mpl.CreateAwsKmsMrkDiscoveryKeyring(regionalDiscoveryKeyringInput);
```
Puoi anche limitare le chiavi KMS a uno specifico Regione AWS specificando una regione nell'istanza del AWS KMS client () [AmazonKeyManagementServiceClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/KeyManagementService/TKeyManagementServiceClient.html). Tuttavia, questa configurazione è meno efficiente e potenzialmente più costosa rispetto all'utilizzo di un multi-Region-aware portachiavi Discovery. Invece di filtrare le chiavi KMS AWS Encryption SDK per regione prima della chiamata AWS KMS, fo.NET chiama AWS KMS ogni chiave di dati crittografata (finché non ne decripta una) e si affida AWS KMS per limitare le chiavi KMS utilizzate alla regione specificata.
L'esempio seguente utilizza la versione 4. *x* del AWS Encryption SDK per .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
List account = new List { "111122223333" };
// Create the discovery filter,
// but not a AWS KMS key
var createRegionalDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = account,
Partition = "aws"
}
};
var kmsRegionalDiscoveryKeyring = mlp.CreateAwsKmsDiscoveryKeyring(createRegionalDiscoveryKeyringInput);
```
------
#### [ JavaScript Browser ]
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
Per visualizzare questo portachiavi e la `limitRegions` funzione, in un esempio funzionante, vedi [kms\$1regional\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_regional_discovery.ts).
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
```
------
#### [ Java ]
```
// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
.partition("aws")
.accountIds(111122223333)
.build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
.discoveryFilter(discoveryFilter)
.regions("us-west-2")
.build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);
```
------
#### [ Python ]
```
# Instantiate the AWS Encryption SDK
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# Create a boto3 client for AWS KMS
kms_client = boto3.client('kms', region_name=aws_region)
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
"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
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create the AWS KMS regional discovery keyring
regional_discovery_keyring_input: CreateAwsKmsMrkDiscoveryKeyringInput = \
CreateAwsKmsMrkDiscoveryKeyringInput(
kms_client=kms_client,
region=mrk_replica_decrypt_region,
discovery_filter=DiscoveryFilter(
account_ids=[111122223333],
partition="aws"
)
)
regional_discovery_keyring: IKeyring = mat_prov.create_aws_kms_mrk_discovery_keyring(
input=regional_discovery_keyring_input
)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Optional: Create an 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 client
let decrypt_kms_config = aws_sdk_kms::config::Builder::from(&sdk_config)
.region(Region::new(mrk_replica_decrypt_region.clone()))
.build();
let decrypt_kms_client = aws_sdk_kms::Client::from_conf(decrypt_kms_config);
// Create discovery filter
let discovery_filter = DiscoveryFilter::builder()
.account_ids(vec![aws_account_id.to_string()])
.partition("aws".to_string())
.build()?;
// Create the regional discovery keyring
let discovery_keyring = mpl
.create_aws_kms_mrk_discovery_keyring()
.kms_client(decrypt_kms_client)
.region(mrk_replica_decrypt_region)
.discovery_filter(discovery_filter)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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",
}
// Create discovery filter
discoveryFilter := mpltypes.DiscoveryFilter{
AccountIds: []string{awsAccountID},
Partition: "aws",
}
// Create the regional discovery keyring
awsKmsMrkDiscoveryInput := mpltypes.CreateAwsKmsMrkDiscoveryKeyringInput{
KmsClient: kmsClient,
Region: alternateRegionMrkKeyRegion,
DiscoveryFilter: &discoveryFilter,
}
awsKmsMrkDiscoveryKeyring, err := matProv.CreateAwsKmsMrkDiscoveryKeyring(context.Background(), awsKmsMrkDiscoveryInput)
if err != nil {
panic(err)
}
```
------
Esporta SDK di crittografia AWS per JavaScript anche una funzione per Node.js e il browser. `excludeRegions` Questa funzione crea un portachiavi di rilevamento AWS KMS regionale che omette AWS KMS keys in aree particolari. L'esempio seguente crea un portachiavi AWS KMS Regional Discovery che può essere utilizzato AWS KMS keys nell'account 111122223333 in tutti gli Stati Uniti Regione AWS ad eccezione di Stati Uniti orientali (Virginia settentrionale) (us-east-1).
Non SDK di crittografia AWS per C dispone di un metodo analogo, ma è possibile implementarne uno creandone uno personalizzato. [ClientSupplier](https://github.com/aws/aws-encryption-sdk-c/blob/master/aws-encryption-sdk-cpp/include/aws/cryptosdk/cpp/kms_keyring.h#L157)
Questo esempio mostra il codice per Node.js.
```
const discovery = true
const clientProvider = excludeRegions(['us-east-1'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})
```
# AWS KMS Portachiavi gerarchici
Con il portachiavi AWS KMS Hierarchical, puoi proteggere i tuoi materiali crittografici con una chiave KMS a crittografia simmetrica senza chiamare ogni volta che crittografi o decrittografi i dati. AWS KMS È una buona scelta per le applicazioni che devono ridurre al minimo le chiamate e le applicazioni che possono riutilizzare alcuni materiali crittografici AWS KMS senza violare i requisiti di sicurezza.
Il portachiavi Hierarchical è una soluzione di memorizzazione nella cache dei materiali crittografici che riduce il numero di AWS KMS chiamate utilizzando *chiavi branch AWS KMS * protette persistenti in una tabella Amazon DynamoDB e quindi memorizzando nella cache locale i materiali chiave delle branch utilizzati nelle operazioni di crittografia e decrittografia. La tabella DynamoDB funge da archivio di chiavi che gestisce e protegge le chiavi delle filiali. Memorizza la chiave di ramo attiva e tutte le versioni precedenti della chiave di ramo. La chiave di ramo *attiva* è la versione più recente della chiave di filiale. Il portachiavi Hierarchical utilizza una chiave dati unica per crittografare ogni messaggio e crittografa ogni chiave di crittografia dei dati per ogni richiesta di crittografia e crittografa ogni chiave di crittografia dei dati con una chiave di wrapping unica derivata dalla chiave branch attiva. Il portachiavi Hierarchical dipende dalla gerarchia stabilita tra le chiavi Active Branch e le relative chiavi di wrapping derivate.
Il portachiavi Hierarchical utilizza in genere ogni versione della chiave branch per soddisfare più richieste. Tuttavia, puoi controllare la misura in cui le chiavi di ramo attive vengono riutilizzate e determinare la frequenza con cui la chiave di ramo attiva viene ruotata. La versione attiva della chiave di ramo rimane attiva finché non viene [ruotata](rotate-branch-key.md). Le versioni precedenti della chiave branch attiva non verranno utilizzate per eseguire operazioni di crittografia, ma potranno comunque essere interrogate e utilizzate nelle operazioni di decrittografia.
Quando si crea un'istanza del portachiavi Hierarchical, viene creata una cache locale. Si specifica un [limite di cache](#cache-limit) che definisce la quantità massima di tempo in cui i materiali chiave del branch vengono archiviati nella cache locale prima che scadano e vengano rimossi dalla cache. Il portachiavi Hierarchical effettua una AWS KMS chiamata per decrittografare la chiave del ramo e assemblare i materiali delle chiavi del ramo la prima volta che a viene specificato in un'operazione. `branch-key-id` I materiali delle chiavi di filiale vengono quindi archiviati nella cache locale e riutilizzati per tutte le operazioni di crittografia e decrittografia che lo specificano fino alla scadenza del limite di cache. `branch-key-id` L'archiviazione dei materiali chiave della filiale nella cache locale riduce le chiamate. AWS KMS Ad esempio, si consideri un limite di cache di 15 minuti. Se si eseguono 10.000 operazioni di crittografia entro tale limite di cache, il [AWS KMS portachiavi tradizionale](use-kms-keyring.md) dovrebbe effettuare 10.000 AWS KMS chiamate per soddisfare 10.000 operazioni di crittografia. Se ne hai uno attivo`branch-key-id`, il portachiavi Hierarchical deve effettuare solo una AWS KMS chiamata per soddisfare 10.000 operazioni di crittografia.
La cache locale separa i materiali di crittografia dai materiali di decrittografia. I materiali di crittografia vengono assemblati a partire dalla chiave branch attiva e riutilizzati per tutte le operazioni di crittografia fino alla scadenza del limite della cache. I materiali di decrittografia vengono assemblati a partire dall'ID e dalla versione della chiave di filiale identificati nei metadati del campo crittografato e vengono riutilizzati per tutte le operazioni di decrittografia relative all'ID e alla versione della chiave di filiale fino alla scadenza del limite della cache. La cache locale può memorizzare più versioni della stessa chiave di ramo contemporaneamente. Quando la cache locale è configurata per utilizzare a[branch key ID supplier](#branch-key-id-supplier), può anche archiviare i materiali chiave delle branch provenienti da più chiavi di branch attive contemporaneamente.
**Nota**
Tutte le menzioni del portachiavi *gerarchico AWS Encryption SDK si riferiscono al portachiavi* gerarchico. AWS KMS
**Compatibilità del linguaggio di programmazione**
Il portachiavi Hierarchical è supportato dai seguenti linguaggi e versioni di programmazione:
+ Versione 3. *x* del SDK di crittografia AWS per Java
+ Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
+ Versione 4. *x* di SDK di crittografia AWS per Python, se usato con la dipendenza MPL opzionale.
+ Versione 1. *x* del AWS Encryption SDK per Rust
+ Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
**Topics**
+ [Come funziona](#how-hierarchical-keyring-works)
+ [Prerequisiti](#hierarchical-keyring-prereqs)
+ [Autorizzazioni richieste](#hierarchical-keyring-permissions)
+ [Scegli una cache](#hierarchical-keyring-caches)
+ [Crea un portachiavi gerarchico](#initialize-hierarchical-keyring)
## Come funziona
Le procedure dettagliate seguenti descrivono come il portachiavi Hierarchical assembla i materiali di crittografia e decrittografia e le diverse chiamate effettuate dal portachiavi per le operazioni di crittografia e decrittografia. [Per i dettagli tecnici sulla derivazione delle chiavi di wrapping e sui processi di crittografia delle chiavi di dati in chiaro, consulta Dettagli tecnici del portachiavi gerarchico.AWS KMS](hierarchical-keyring-details.md)
**Crittografa e firma**
La procedura dettagliata seguente descrive come il portachiavi Hierarchical assembla i materiali di crittografia e ricava una chiave di avvolgimento univoca.
1. Il metodo di crittografia richiede al portachiavi Hierarchical i materiali di crittografia. Il portachiavi genera una chiave di dati in testo semplice, quindi verifica se nella cache locale sono presenti materiali branch validi per generare la chiave di wrapping. **Se sono presenti materiali validi per le chiavi di filiale, il portachiavi passa alla Fase 4.**
1. Se non ci sono materiali validi per le chiavi di ramo, il portachiavi Hierarchical interroga l'archivio delle chiavi per la chiave di ramo attiva.
1. Il key store chiama AWS KMS per decrittografare la chiave branch attiva e restituisce la chiave branch attiva in testo semplice. I dati che identificano la chiave di ramo attiva vengono serializzati per fornire dati autenticati aggiuntivi (AAD) nella chiamata di decrittografia a. AWS KMS
1. L'archivio chiavi restituisce la chiave di ramo in testo semplice e i dati che la identificano, ad esempio la versione della chiave di filiale.
1. Il portachiavi Hierarchical assembla i materiali chiave del ramo (la chiave di ramo in testo semplice e la versione della chiave di ramo) e ne archivia una copia nella cache locale.
1. Il portachiavi Hierarchical ricava una chiave di avvolgimento unica dalla chiave branch in testo semplice e un sale casuale a 16 byte. Utilizza la chiave di wrapping derivata per crittografare una copia della chiave di dati in testo non crittografato.
Il metodo di crittografia utilizza i materiali di crittografia per crittografare i dati. Per ulteriori informazioni, consulta [Come AWS Encryption SDK crittografa i dati](how-it-works.md#encrypt-workflow).
**Decrittografa e verifica**
La procedura dettagliata seguente descrive come il portachiavi gerarchico assembla i materiali di decrittografia e decrittografa la chiave di dati crittografata.
1. Il metodo di decrittografia identifica la chiave di dati crittografata dal messaggio crittografato e la passa al portachiavi Hierarchical.
1. Il portachiavi Hierarchical deserializza i dati che identificano la chiave dati crittografata, inclusa la versione della chiave branch, il salt da 16 byte e altre informazioni che descrivono come è stata crittografata la chiave dati.
Per ulteriori informazioni, consulta [AWS KMS Dettagli tecnici del portachiavi gerarchico](hierarchical-keyring-details.md).
1. **Il portachiavi Hierarchical verifica se nella cache locale sono presenti materiali chiave di filiale validi che corrispondono alla versione della chiave di filiale identificata nel passaggio 2.** **Se sono presenti materiali validi per le chiavi di filiale, il portachiavi passa alla Fase 6.**
1. **Se non ci sono materiali validi per le chiavi di ramo, il portachiavi Hierarchical interroga l'archivio delle chiavi per la chiave di filiale che corrisponde alla versione della chiave di filiale identificata nello Step 2.**
1. Il key store chiama AWS KMS per decrittografare la chiave branch e restituisce la chiave branch attiva in testo semplice. I dati che identificano la chiave di ramo attiva vengono serializzati per fornire dati autenticati aggiuntivi (AAD) nella chiamata di decrittografia a. AWS KMS
1. L'archivio chiavi restituisce la chiave di ramo in testo semplice e i dati che la identificano, ad esempio la versione della chiave di filiale.
1. Il portachiavi Hierarchical assembla i materiali chiave del ramo (la chiave di ramo in testo semplice e la versione della chiave di ramo) e ne archivia una copia nella cache locale.
1. Il portachiavi Hierarchical utilizza i materiali delle chiavi branch assemblate e il sale da 16 byte identificato nella **fase 2** per riprodurre la chiave di avvolgimento univoca che crittografava la chiave dati.
1. Il portachiavi Hierarchical utilizza la chiave di wrapping riprodotta per decrittografare la chiave dati e restituisce la chiave dati in testo semplice.
Il metodo di decrittografia utilizza i materiali di decrittografia e la chiave di dati in testo semplice per decrittografare il messaggio crittografato. [Per ulteriori informazioni, consulta Come decripta un messaggio crittografato. AWS Encryption SDK](how-it-works.md#decrypt-workflow)
## Prerequisiti
Prima di creare e utilizzare un portachiavi gerarchico, assicurati che siano soddisfatti i seguenti prerequisiti.
+ Tu o il tuo amministratore dell'archivio chiavi avete [creato un archivio chiavi e [creato almeno una](create-branch-keys.md) chiave](create-keystore.md) di ramo attiva.
+ Hai [configurato le azioni del tuo archivio chiavi](keystore-actions.md#config-keystore-actions).
**Nota**
Il modo in cui configuri le azioni del tuo archivio di chiavi determina quali operazioni puoi eseguire e quali chiavi KMS possono essere utilizzate dal portachiavi Hierarchical. [Per ulteriori informazioni, consulta Key store actions.](keystore-actions.md)
+ Disponi delle AWS KMS autorizzazioni necessarie per accedere e utilizzare le chiavi del key store e del branch. Per ulteriori informazioni, consulta [Autorizzazioni richieste](#hierarchical-keyring-permissions).
+ Hai esaminato i tipi di cache supportati e configurato il tipo di cache più adatto alle tue esigenze. Per ulteriori informazioni, consulta [Scegli una cache](#hierarchical-keyring-caches)
## Autorizzazioni richieste
AWS Encryption SDK Non richiede una Account AWS e non dipende da nessuna Servizio AWS. Tuttavia, per utilizzare un portachiavi gerarchico, sono necessarie le seguenti autorizzazioni Account AWS minime per le AWS KMS key crittografie simmetriche presenti nell'archivio delle chiavi.
+ [Per crittografare e decrittografare i dati con il portachiavi Hierarchical, è necessario KMS:Decrypt.](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)
Per ulteriori informazioni sul controllo dell'accesso alle chiavi di filiale e all'archivio delle chiavi, consulta. [Implementazione di autorizzazioni con privilegio minimo](keystore-least-privilege.md)
## Scegli una cache
Il portachiavi gerarchico riduce il numero di chiamate effettuate AWS KMS memorizzando localmente nella cache i materiali chiave della filiale utilizzati nelle operazioni di crittografia e decrittografia. Prima di [creare il tuo portachiavi Hierarchical](#initialize-hierarchical-keyring), devi decidere che tipo di cache vuoi usare. È possibile utilizzare la cache predefinita o personalizzare la cache in base alle proprie esigenze.
Il portachiavi Hierarchical supporta i seguenti tipi di cache:
+ [Cache predefinita](#cache-default)
+ [MultiThreaded cache](#cache-multithreaded)
+ [StormTracking cache](#cache-stormtracking)
+ [Cache condivisa](#cache-shared)
**Importante**
Tutti i tipi di cache supportati sono progettati per supportare ambienti multithread.
Tuttavia, se utilizzato con SDK di crittografia AWS per Python, il portachiavi Hierarchical non supporta ambienti multithread. [Per ulteriori informazioni, consulta il file [Python README.rst](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/runtimes/python/README.rst) nel repository -library su. aws-cryptographic-material-providers](https://github.com/aws/aws-cryptographic-material-providers-library/tree/main) GitHub
### Cache predefinita
Per la maggior parte degli utenti, la cache predefinita soddisfa i requisiti di threading. La cache predefinita è progettata per supportare ambienti con molti multithread. Quando una voce relativa ai materiali delle chiavi di branch scade, la cache predefinita impedisce la chiamata di più thread AWS KMS notificando a un thread che la voce relativa ai materiali della chiave di branch sta per scadere con 10 secondi di anticipo. Ciò garantisce che solo un thread invii una richiesta di aggiornamento della cache AWS KMS .
Il valore predefinito e le StormTracking cache supportano lo stesso modello di threading, ma è sufficiente specificare la capacità di ingresso per utilizzare la cache predefinita. Per personalizzazioni più granulari della cache, usa. [StormTracking cache](#cache-stormtracking)
A meno che non si desideri personalizzare il numero di voci relative ai materiali chiave del ramo che possono essere archiviate nella cache locale, non è necessario specificare un tipo di cache quando si crea il portachiavi Hierarchical. Se non si specifica un tipo di cache, il portachiavi Hierarchical utilizza il tipo di cache predefinito e imposta la capacità di immissione su 1000.
Per personalizzare la cache predefinita, specificate i seguenti valori:
+ **Capacità di ingresso**: limita il numero di voci relative ai materiali chiave della filiale che possono essere archiviate nella cache locale.
------
#### [ Java ]
```
.cache(CacheType.builder()
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType defaultCache = new CacheType
{
Default = new DefaultCache{EntryCapacity = 100}
};
```
------
#### [ Python ]
```
default_cache = CacheTypeDefault(
value=DefaultCache(
entry_capacity=100
)
)
```
------
#### [ Rust ]
```
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
```
------
#### [ Go ]
```
cache := mpltypes.CacheTypeMemberDefault{
Value: mpltypes.DefaultCache{
EntryCapacity: 100,
},
}
```
------
### MultiThreaded cache
La MultiThreaded cache è sicura da usare in ambienti multithread, ma non fornisce alcuna funzionalità per ridurre al minimo AWS KMS le chiamate Amazon DynamoDB. Di conseguenza, quando scade l'immissione di materiali chiave in una filiale, tutti i thread verranno avvisati contemporaneamente. Ciò può comportare più AWS KMS chiamate per aggiornare la cache.
Per utilizzare la MultiThreaded cache, specificate i seguenti valori:
+ **Capacità di ingresso**: limita il numero di voci relative ai materiali chiave della filiale che possono essere archiviate nella cache locale.
+ **Entry Poting Tail Size**: definisce il numero di elementi da potare se viene raggiunta la capacità di ingresso.
------
#### [ Java ]
```
.cache(CacheType.builder()
.MultiThreaded(MultiThreadedCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType multithreadedCache = new CacheType
{
MultiThreaded = new MultiThreadedCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1
}
};
```
------
#### [ Python ]
```
multithreaded_cache = CacheTypeMultiThreaded(
value=MultiThreadedCache(
entry_capacity=100,
entry_pruning_tail_size=1
)
)
```
------
#### [ Rust ]
```
CacheType::MultiThreaded(
MultiThreadedCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.build()?)
```
------
#### [ Go ]
```
var entryPruningTailSize int32 = 1
cache := mpltypes.CacheTypeMemberMultiThreaded{
Value: mpltypes.MultiThreadedCache{
EntryCapacity: 100,
EntryPruningTailSize: &entryPruningTailSize,
},
}
```
------
### StormTracking cache
La StormTracking cache è progettata per supportare ambienti con molti multithread. Quando una voce relativa ai materiali della chiave di filiale scade, la StormTracking cache impedisce la chiamata di più thread AWS KMS notificando in anticipo a un thread che la voce relativa ai materiali chiave della branch sta per scadere. Ciò garantisce che solo un thread invii una richiesta di aggiornamento della cache AWS KMS .
Per utilizzare la StormTracking cache, specificate i seguenti valori:
+ **Capacità di ingresso**: limita il numero di voci relative ai materiali chiave della filiale che possono essere archiviate nella cache locale.
Valore predefinito: 1000 voci
+ **Dimensione della coda di potatura** di base: definisce il numero di materiali chiave del ramo da potare alla volta.
Valore predefinito: 1 voce
+ **Periodo di tolleranza**: definisce il numero di secondi prima della scadenza in cui viene effettuato un tentativo di aggiornare i materiali chiave della filiale.
Valore predefinito: 10 secondi
+ **Intervallo di grazia**: definisce il numero di secondi tra i tentativi di aggiornamento dei materiali chiave del ramo.
Valore predefinito: 1 secondo
+ **Fan out**: definisce il numero di tentativi simultanei che è possibile effettuare per aggiornare i materiali chiave della filiale.
Valore predefinito: 20 tentativi
+ **In flight time to live (TTL)**: definisce il numero di secondi che mancano al timeout di un tentativo di aggiornamento dei materiali chiave della filiale. Ogni volta che la cache ritorna `NoSuchEntry` in risposta a una`GetCacheEntry`, quella chiave di ramo viene considerata *in esecuzione finché la* stessa chiave non viene scritta con una `PutCache` voce.
Valore predefinito: 10 secondi
+ **Sleep**: definisce il numero di millisecondi in cui un thread deve dormire se viene superato il `fanOut` limite.
Valore predefinito: 20 millisecondi
------
#### [ Java ]
```
.cache(CacheType.builder()
.StormTracking(StormTrackingCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.gracePeriod(10)
.graceInterval(1)
.fanOut(20)
.inFlightTTL(10)
.sleepMilli(20)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType stormTrackingCache = new CacheType
{
StormTracking = new StormTrackingCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1,
FanOut = 20,
GraceInterval = 1,
GracePeriod = 10,
InFlightTTL = 10,
SleepMilli = 20
}
};
```
------
#### [ Python ]
```
storm_tracking_cache = CacheTypeStormTracking(
value=StormTrackingCache(
entry_capacity=100,
entry_pruning_tail_size=1,
fan_out=20,
grace_interval=1,
grace_period=10,
in_flight_ttl=10,
sleep_milli=20
)
)
```
------
#### [ Rust ]
```
CacheType::StormTracking(
StormTrackingCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.grace_period(10)
.grace_interval(1)
.fan_out(20)
.in_flight_ttl(10)
.sleep_milli(20)
.build()?)
```
------
#### [ Go ]
```
var entryPruningTailSize int32 = 1
cache := mpltypes.CacheTypeMemberStormTracking{
Value: mpltypes.StormTrackingCache{
EntryCapacity: 100,
EntryPruningTailSize: &entryPruningTailSize,
GraceInterval: 1,
GracePeriod: 10,
FanOut: 20,
InFlightTTL: 10,
SleepMilli: 20,
},
}
```
------
### Cache condivisa
Per impostazione predefinita, il portachiavi Hierarchical crea una nuova cache locale ogni volta che si crea un'istanza del portachiavi. Tuttavia, la cache condivisa può aiutare a risparmiare memoria consentendoti di condividere una cache tra più portachiavi gerarchici. Anziché creare una nuova cache di materiali crittografici per ogni portachiavi gerarchico istanziato, la cache condivisa archivia solo una cache in memoria, che può essere utilizzata da tutti i portachiavi gerarchici che vi fanno riferimento. La cache condivisa aiuta a ottimizzare l'utilizzo della memoria evitando la duplicazione di materiali crittografici tra portachiavi. I portachiavi gerarchici possono invece accedere alla stessa cache sottostante, riducendo l'ingombro complessivo della memoria.
Quando crei la cache condivisa, definisci comunque il tipo di cache. È possibile specificare un [Cache predefinita](#cache-default)[MultiThreaded cache](#cache-multithreaded), o [StormTracking cache](#cache-stormtracking) come tipo di cache o sostituire qualsiasi cache personalizzata compatibile.
**Partizioni**
Più portachiavi gerarchici possono utilizzare un'unica cache condivisa. **Quando si crea un portachiavi gerarchico con una cache condivisa, è possibile definire un ID di partizione opzionale.** L'ID di partizione distingue quale portachiavi gerarchico sta scrivendo nella cache. Se due portachiavi gerarchici fanno riferimento allo stesso ID di partizione e allo stesso ID di chiave di filiale[logical key store name](create-keystore.md#logical-key-store-name), i due portachiavi condivideranno le stesse voci della cache. Se si creano due portachiavi gerarchici con la stessa cache condivisa, ma una partizione diversa IDs, ogni portachiavi accederà alle voci della cache solo dalla propria partizione designata all'interno della cache condivisa. Le partizioni agiscono come divisioni logiche all'interno della cache condivisa, consentendo a ciascun portachiavi gerarchico di funzionare indipendentemente sulla propria partizione designata, senza interferire con i dati memorizzati nell'altra partizione.
Se si intende riutilizzare o condividere le voci della cache in una partizione, è necessario definire il proprio ID di partizione. Quando passate l'ID della partizione al portachiavi Hierarchical, il portachiavi può riutilizzare le voci della cache che sono già presenti nella cache condivisa, anziché dover recuperare e autorizzare nuovamente i materiali delle chiavi della branch. Se non si specifica un ID di partizione, un ID di partizione univoco viene assegnato automaticamente al portachiavi ogni volta che si crea un'istanza del portachiavi Hierarchical.
Le seguenti procedure mostrano come creare una cache condivisa con il [tipo di cache predefinito](#cache-default) e passarla a un portachiavi gerarchico.
1. Crea un `CryptographicMaterialsCache` (CMC) utilizzando la [Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
------
#### [ Java ]
```
// Instantiate the MPL
final MaterialProviders matProv =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a CacheType object for the Default cache
final CacheType cache =
CacheType.builder()
.Default(DefaultCache.builder().entryCapacity(100).build())
.build();
// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
CreateCryptographicMaterialsCacheInput.builder()
.cache(cache)
.build();
final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ C\$1 / .NET ]
```
// Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };
// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};
var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ Python ]
```
# Instantiate the MPL
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create a CacheType object for the default cache
cache: CacheType = CacheTypeDefault(
value=DefaultCache(
entry_capacity=100,
)
)
# Create a CMC using the default cache
cryptographic_materials_cache_input = CreateCryptographicMaterialsCacheInput(
cache=cache,
)
shared_cryptographic_materials_cache = mat_prov.create_cryptographic_materials_cache(
cryptographic_materials_cache_input
)
```
------
#### [ Rust ]
```
// Instantiate the MPL
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create a CacheType object for the default cache
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
// Create a CMC using the default cache
let shared_cryptographic_materials_cache: CryptographicMaterialsCacheRef = mpl.
create_cryptographic_materials_cache()
.cache(cache)
.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"
)
// Instantiate the MPL
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create a CacheType object for the default cache
cache := mpltypes.CacheTypeMemberDefault{
Value: mpltypes.DefaultCache{
EntryCapacity: 100,
},
}
// Create a CMC using the default cache
cmcCacheInput := mpltypes.CreateCryptographicMaterialsCacheInput{
Cache: &cache,
}
sharedCryptographicMaterialsCache, err := matProv.CreateCryptographicMaterialsCache(context.Background(), cmcCacheInput)
if err != nil {
panic(err)
}
```
------
1. Crea un `CacheType` oggetto per la cache condivisa.
Passa `sharedCryptographicMaterialsCache` il file creato nel **passaggio 1** al nuovo `CacheType` oggetto.
------
#### [ Java ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
CacheType.builder()
.Shared(sharedCryptographicMaterialsCache)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
```
------
#### [ Python ]
```
# Create a CacheType object for the shared_cryptographic_materials_cache
shared_cache: CacheType = CacheTypeShared(
value=shared_cryptographic_materials_cache
)
```
------
#### [ Rust ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
let shared_cache: CacheType = CacheType::Shared(shared_cryptographic_materials_cache);
```
------
#### [ Go ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
shared_cache := mpltypes.CacheTypeMemberShared{sharedCryptographicMaterialsCache}
```
------
1. Passa l'`sharedCache`oggetto dallo **Step 2** al tuo portachiavi gerarchico.
Quando crei un portachiavi gerarchico con una cache condivisa, puoi facoltativamente definire un portachiavi gerarchico `partitionID` per condividere le voci della cache su più portachiavi gerarchici. Se non si specifica un ID di partizione, il portachiavi Hierarchical assegna automaticamente al portachiavi un ID di partizione univoco.
**Nota**
I portachiavi gerarchici condivideranno le stesse voci della cache in una cache condivisa se crei due o più portachiavi che fanno riferimento allo stesso ID di partizione e allo stesso ID di chiave di filiale. [logical key store name](create-keystore.md#logical-key-store-name) Se non desideri che più portachiavi condividano le stesse voci della cache, devi utilizzare un ID di partizione univoco per ogni portachiavi gerarchico.
[L'esempio seguente crea un portachiavi Hierarchical con un [branch key ID supplier](#branch-key-id-supplier) limite di cache di 600 secondi.](#cache-limit) Per ulteriori informazioni sui valori definiti nella seguente configurazione del portachiavi gerarchico, vedere. [Crea un portachiavi gerarchico](#initialize-hierarchical-keyring)
------
#### [ Java ]
```
// Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(sharedCache)
.partitionID(partitionID)
.build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create the Hierarchical keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
Cache = sharedCache,
TtlSeconds = 600,
PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
```
------
#### [ Python ]
```
# Create the Hierarchical keyring
keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
key_store=keystore,
branch_key_id_supplier=branch_key_id_supplier,
ttl_seconds=600,
cache=shared_cache,
partition_id=partition_id
)
hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
```
// Create the Hierarchical keyring
let keyring1 = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store1)
.branch_key_id(branch_key_id.clone())
// CryptographicMaterialsCacheRef is an Rc (Reference Counted), so if you clone it to
// pass it to different Hierarchical Keyrings, it will still point to the same
// underlying cache, and increment the reference count accordingly.
.cache(shared_cache.clone())
.ttl_seconds(600)
.partition_id(partition_id.clone())
.send()
.await?;
```
------
#### [ Go ]
```
// Create the Hierarchical keyring
hkeyringInput := mpltypes.CreateAwsKmsHierarchicalKeyringInput{
KeyStore: keyStore1,
BranchKeyId: &branchKeyId,
TtlSeconds: 600,
Cache: &shared_cache,
PartitionId: &partitionId,
}
keyring, err := matProv.CreateAwsKmsHierarchicalKeyring(context.Background(), hkeyringInput)
if err != nil {
panic(err)
}
```
------
## Crea un portachiavi gerarchico
Per creare un portachiavi gerarchico, è necessario fornire i seguenti valori:
+ **Il nome di un archivio di chiavi**
Il nome della tabella DynamoDB che tu o il tuo amministratore del key store avete creato per fungere da archivio chiavi.
+
**Un limite di durata della cache (TTL)**
La quantità di tempo, in secondi, durante la quale una chiave di filiale deve essere inserita nella cache locale può essere utilizzata prima della scadenza. Il limite di cache TTL determina la frequenza con cui il client chiama AWS KMS per autorizzare l'uso delle chiavi della filiale. Questo valore deve essere maggiore di zero. Dopo la scadenza del limite di cache TTL, la voce non viene mai fornita e verrà rimossa dalla cache locale.
+ **Un identificatore di chiave di filiale**
Puoi configurare staticamente il codice `branch-key-id` che identifica una singola chiave di filiale attiva nel tuo archivio di chiavi o fornire un fornitore di ID per le chiavi di filiale.
Il *fornitore di ID della chiave di filiale* utilizza i campi memorizzati nel contesto di crittografia per determinare quale chiave di filiale è necessaria per decrittografare un record.
Consigliamo vivamente di utilizzare un fornitore di ID di chiavi di filiale per database multitenant in cui ogni tenant ha la propria chiave di filiale. Puoi utilizzare il fornitore di ID delle chiavi di filiale per creare un nome descrittivo per la tua chiave IDs di filiale e facilitare il riconoscimento dell'ID corretto della chiave di filiale per un tenant specifico. Ad esempio, il nome descrittivo consente di fare riferimento a una chiave di filiale come `tenant1` invece di`b3f61619-4d35-48ad-a275-050f87e15122`.
Per le operazioni di decrittografia, è possibile configurare staticamente un singolo portachiavi gerarchico per limitare la decrittografia a un singolo tenant, oppure è possibile utilizzare il fornitore di ID della chiave di filiale per identificare quale tenant è responsabile della decrittografia di un record.
+ **(Facoltativo) Una cache**
Se desideri personalizzare il tipo di cache o il numero di voci relative ai materiali chiave della filiale che possono essere archiviate nella cache locale, specifica il tipo di cache e la capacità di accesso quando inizializzi il portachiavi.
Il portachiavi Hierarchical supporta i seguenti tipi di cache: predefinita, MultiThreaded e condivisa. StormTracking Per ulteriori informazioni ed esempi che dimostrano come definire ogni tipo di cache, vedere. [Scegli una cache](#hierarchical-keyring-caches)
Se non si specifica una cache, il portachiavi gerarchico utilizza automaticamente il tipo di cache predefinito e imposta la capacità di ingresso su 1000.
+ **(Facoltativo) Un ID di partizione**
Se si specifica il[Cache condivisa](#cache-shared), è possibile definire facoltativamente un ID di partizione. L'ID di partizione distingue quale portachiavi Hierarchical sta scrivendo nella cache. Se si intende riutilizzare o condividere le voci della cache in una partizione, è necessario definire il proprio ID di partizione. È possibile specificare qualsiasi stringa per l'ID della partizione. Se non si specifica un ID di partizione, al portachiavi viene assegnato automaticamente un ID di partizione univoco al momento della creazione.
Per ulteriori informazioni, consulta [Partitions](#shared-cache-partitions).
**Nota**
I portachiavi gerarchici condivideranno le stesse voci della cache in una cache condivisa se crei due o più portachiavi che fanno riferimento allo stesso ID di partizione e allo stesso ID di chiave di filiale. [logical key store name](create-keystore.md#logical-key-store-name) Se non desideri che più portachiavi condividano le stesse voci della cache, devi utilizzare un ID di partizione univoco per ogni portachiavi gerarchico.
+ **(Facoltativo) Un elenco di token di concessione**
Se controlli l'accesso alla chiave KMS nel tuo portachiavi gerarchico con le [concessioni, devi fornire tutti i](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) token di concessione necessari quando inizializzi il portachiavi.
### Crea un portachiavi gerarchico con un ID di chiave branch statico
Gli esempi seguenti mostrano come creare un portachiavi gerarchico con un ID di chiave branch statico[Cache predefinita](#cache-default), the e un limite di cache TTL di 600 secondi.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyId(branch-key-id)
.ttlSeconds(600)
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyId = branch-key-id,
TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Python ]
```
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
key_store=keystore,
branch_key_id=branch_key_id,
ttl_seconds=600
)
hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store.clone())
.branch_key_id(branch_key_id)
.ttl_seconds(600)
.send()
.await?;
```
------
#### [ Go ]
```
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
hkeyringInput := mpltypes.CreateAwsKmsHierarchicalKeyringInput{
KeyStore: keyStore,
BranchKeyId: &branchKeyID,
TtlSeconds: 600,
}
hKeyRing, err := matProv.CreateAwsKmsHierarchicalKeyring(context.Background(), hkeyringInput)
if err != nil {
panic(err)
}
```
------
### Crea un portachiavi gerarchico con una chiave di filiale (ID fornitore)
Le seguenti procedure mostrano come creare un portachiavi gerarchico con un fornitore di ID di chiave di filiale.
1. Crea un fornitore di ID chiave di filiale
L'esempio seguente crea nomi descrittivi per due chiavi di filiale e chiamate `CreateDynamoDbEncryptionBranchKeyIdSupplier` per creare un fornitore di ID di chiavi di filiale.
------
#### [ Java ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
private static String branchKeyIdForTenant1;
private static String branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this.branchKeyIdForTenant1 = tenant1Id;
this.branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
.DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
.build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
.ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
.build()).branchKeyIdSupplier();
```
------
#### [ C\$1 / .NET ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
private String _branchKeyIdForTenant1;
private String _branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this._branchKeyIdForTenant1 = tenant1Id;
this._branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
{
DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
}).BranchKeyIdSupplier;
```
------
#### [ Python ]
```
# Create branch key ID supplier that maps the branch key ID to a friendly name
branch_key_id_supplier: IBranchKeyIdSupplier = ExampleBranchKeyIdSupplier(
tenant_1_id=branch_key_id_a,
tenant_2_id=branch_key_id_b,
)
```
------
#### [ Rust ]
```
// Create branch key ID supplier that maps the branch key ID to a friendly name
let branch_key_id_supplier = ExampleBranchKeyIdSupplier::new(
&branch_key_id_a,
&branch_key_id_b
);
```
------
#### [ Go ]
```
// Create branch key ID supplier that maps the branch key ID to a friendly name
keySupplier := branchKeySupplier{branchKeyA: branchKeyA, branchKeyB: branchKeyB}
```
------
1. Crea un portachiavi gerarchico
I seguenti esempi inizializzano un portachiavi gerarchico con il branch key ID supplier creato nel **passaggio 1**, un TLL limite di cache di 600 secondi e una dimensione massima della cache di 1000.
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 100 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Python ]
```
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsHierarchicalKeyringInput = CreateAwsKmsHierarchicalKeyringInput(
key_store=keystore,
branch_key_id_supplier=branch_key_id_supplier,
ttl_seconds=600,
cache=CacheTypeDefault(
value=DefaultCache(
entry_capacity=100
)
),
)
hierarchical_keyring: IKeyring = mat_prov.create_aws_kms_hierarchical_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store.clone())
.branch_key_id_supplier(branch_key_id_supplier)
.ttl_seconds(600)
.send()
.await?;
```
------
#### [ Go ]
```
hkeyringInput := mpltypes.CreateAwsKmsHierarchicalKeyringInput{
KeyStore: keyStore,
BranchKeyIdSupplier: &keySupplier,
TtlSeconds: 600,
}
hKeyRing, err := matProv.CreateAwsKmsHierarchicalKeyring(context.Background(), hkeyringInput)
if err != nil {
panic(err)
}
```
------
# AWS KMS Portachiavi ECDH
Un portachiavi AWS KMS ECDH utilizza un accordo di chiavi asimmetriche per ricavare una chiave di avvolgimento simmetrica [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/key-types.html)condivisa tra due parti. Innanzitutto, il portachiavi utilizza l'algoritmo di accordo delle chiavi Elliptic Curve Diffie-Hellman (ECDH) per ricavare un segreto condiviso dalla chiave privata nella coppia di chiavi KMS del mittente e dalla chiave pubblica del destinatario. Quindi, il portachiavi utilizza il segreto condiviso per derivare la chiave di wrapping condivisa che protegge le chiavi di crittografia dei dati. [La funzione di derivazione delle chiavi che AWS Encryption SDK utilizza (`KDF_CTR_HMAC_SHA384`) per derivare la chiave di wrapping condivisa è conforme alle raccomandazioni del NIST per la derivazione delle chiavi.](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf)
La funzione di derivazione delle chiavi restituisce 64 byte di materiale di codifica. Per garantire che entrambe le parti utilizzino il materiale di codifica corretto, AWS Encryption SDK utilizza i primi 32 byte come chiave di impegno e gli ultimi 32 byte come chiave di wrapping condivisa. In fase di decrittografia, se il portachiavi non è in grado di riprodurre la stessa chiave di impegno e la stessa chiave di wrapping condivisa memorizzate nel testo cifrato dell'intestazione del messaggio, l'operazione ha esito negativo. Ad esempio, se si crittografano i dati con un portachiavi configurato con la chiave privata **di Alice** e la chiave pubblica **di Bob**, un portachiavi configurato con la chiave privata **di Bob** e la chiave pubblica **di Alice** riprodurrà la stessa chiave di impegno e la stessa chiave di wrapping condivisa e sarà in grado di decrittografare i dati. Se la chiave pubblica di Bob non proviene da una coppia di chiavi KMS, Bob può creare un [portachiavi ECDH Raw](use-raw-ecdh-keyring.md) per decrittografare i dati.
Il portachiavi AWS KMS ECDH crittografa i dati con una chiave simmetrica utilizzando AES-GCM. La chiave dati viene quindi crittografata in busta con la chiave di avvolgimento condivisa derivata utilizzando AES-GCM. [Ogni portachiavi AWS KMS ECDH può avere solo una chiave di avvolgimento condivisa, ma è possibile includere più portachiavi AWS KMS ECDH, da soli o con altri portachiavi, in un portachiavi multiplo.](use-multi-keyring.md)
**Compatibilità del linguaggio di programmazione**
Il portachiavi AWS KMS ECDH è stato introdotto nella versione 1.5.0 della [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) ed è supportato dai seguenti linguaggi e versioni di programmazione:
+ Versione 3. *x* del SDK di crittografia AWS per Java
+ Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
+ Versione 4. *x* di SDK di crittografia AWS per Python, se usato con la dipendenza MPL opzionale.
+ Versione 1. *x* del AWS Encryption SDK per Rust
+ Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
**Topics**
+ [Autorizzazioni richieste per i portachiavi AWS KMS ECDH](#kms-ecdh-permissions)
+ [AWS KMS Creazione di un portachiavi ECDH](#kms-ecdh-create)
+ [Creazione di un portachiavi ECDH Discovery AWS KMS](#kms-ecdh-discovery)
## Autorizzazioni richieste per i portachiavi AWS KMS ECDH
AWS Encryption SDK Non richiede un AWS account e non dipende da alcun servizio. AWS Tuttavia, per utilizzare un portachiavi AWS KMS ECDH, è necessario un AWS account e le seguenti autorizzazioni minime presenti nel AWS KMS keys portachiavi. Le autorizzazioni variano in base allo schema di accordi chiave utilizzato.
+ Per crittografare e decrittografare i dati utilizzando lo schema di accordo `KmsPrivateKeyToStaticPublicKey` chiave, sono necessari [kms: GetPublicKey e kms: DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) [sulla coppia di chiavi KMS asimmetrica](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) del *mittente*. Se fornisci direttamente la chiave pubblica con codifica DER del mittente quando crei un'istanza del tuo portachiavi, hai solo bisogno dell'DeriveSharedSecretautorizzazione [kms: sulla coppia di chiavi KMS asimmetrica](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) del mittente.
+ Per decrittografare i dati utilizzando lo schema di accordo `KmsPublicKeyDiscovery` chiave, sono necessarie le GetPublicKey autorizzazioni [kms: DeriveSharedSecret e kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) [sulla coppia di chiavi KMS](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) asimmetrica specificata.
## AWS KMS Creazione di un portachiavi ECDH
Per creare un portachiavi AWS KMS ECDH che crittografa e decrittografa i dati, è necessario utilizzare lo schema degli accordi chiave. `KmsPrivateKeyToStaticPublicKey` Per inizializzare un portachiavi AWS KMS ECDH con lo schema degli accordi chiave, fornisci i seguenti valori: `KmsPrivateKeyToStaticPublicKey`
+ **ID del mittente AWS KMS key **
Deve identificare una coppia di chiavi KMS a curva ellittica (ECC) asimmetrica consigliata dal NIST con un valore di. `KeyUsage` `KEY_AGREEMENT` La chiave privata del mittente viene utilizzata per derivare il segreto condiviso.
+ **(Facoltativo) Chiave pubblica del mittente**
[Deve essere una chiave pubblica X.509 con codifica DER, nota anche come `SubjectPublicKeyInfo` (SPKI), come definita in RFC 5280.](https://tools.ietf.org/html/rfc5280)
L' AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operazione restituisce la chiave pubblica di una coppia di chiavi KMS asimmetrica nel formato codificato DER richiesto.
Per ridurre il numero di AWS KMS chiamate effettuate dal portachiavi, puoi fornire direttamente la chiave pubblica del mittente. Se non viene fornito alcun valore per la chiave pubblica del mittente, il portachiavi chiama AWS KMS per recuperare la chiave pubblica del mittente.
+ **Chiave pubblica del destinatario**
[È necessario fornire la chiave pubblica X.509 con codifica DER del destinatario, nota anche come `SubjectPublicKeyInfo` (SPKI), come definita in RFC 5280.](https://tools.ietf.org/html/rfc5280)
L' AWS KMS [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)operazione restituisce la chiave pubblica di una coppia di chiavi KMS asimmetrica nel formato codificato DER richiesto.
+ **Specificazione della curva**
Identifica la specifica della curva ellittica nelle coppie di chiavi specificate. Entrambe le coppie di chiavi del mittente e del destinatario devono avere la stessa specifica di curva.
Valori validi: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Facoltativo) Un elenco di token di concessione**
Se controlli l'accesso alla chiave KMS nel tuo portachiavi AWS KMS ECDH con le [sovvenzioni](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), devi fornire tutti i token di concessione necessari quando inizializzi il portachiavi.
------
#### [ C\$1 / .NET ]
L'esempio seguente crea un portachiavi AWS KMS ECDH con la chiave KMS del mittente, la chiave pubblica del mittente e la chiave pubblica del destinatario. Questo esempio utilizza il `SenderPublicKey` parametro opzionale per fornire la chiave pubblica del mittente. Se non fornisci la chiave pubblica del mittente, il portachiavi chiama AWS KMS per recuperare la chiave pubblica del mittente. Entrambe le coppie di chiavi del mittente e del destinatario sono pronte. `ECC_NIST_P256`
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Must be DER-encoded X.509 public keys
var BobPublicKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the AWS KMS ECDH static keyring
var staticConfiguration = new KmsEcdhStaticConfigurations
{
KmsPrivateKeyToStaticPublicKey = new KmsPrivateKeyToStaticPublicKeyInput
{
SenderKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
SenderPublicKey = BobPublicKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
L'esempio seguente crea un portachiavi AWS KMS ECDH con la chiave KMS del mittente, la chiave pubblica del mittente e la chiave pubblica del destinatario. Questo esempio utilizza il `senderPublicKey` parametro opzionale per fornire la chiave pubblica del mittente. Se non fornisci la chiave pubblica del mittente, il portachiavi chiama AWS KMS per recuperare la chiave pubblica del mittente. Entrambe le coppie di chiavi del mittente e del destinatario sono pronte. `ECC_NIST_P256`
```
// Retrieve public keys
// Must be DER-encoded X.509 public keys
ByteBuffer BobPublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab");
ByteBuffer AlicePublicKey = getPublicKeyBytes("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the AWS KMS ECDH static keyring
final CreateAwsKmsEcdhKeyringInput senderKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPrivateKeyToStaticPublicKey(
KmsPrivateKeyToStaticPublicKeyInput.builder()
.senderKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
.senderPublicKey(BobPublicKey)
.recipientPublicKey(AlicePublicKey)
.build()).build()).build();
```
------
#### [ Python ]
L'esempio seguente crea un portachiavi AWS KMS ECDH con la chiave KMS del mittente, la chiave pubblica del mittente e la chiave pubblica del destinatario. Questo esempio utilizza il `senderPublicKey` parametro opzionale per fornire la chiave pubblica del mittente. Se non fornisci la chiave pubblica del mittente, il portachiavi chiama AWS KMS per recuperare la chiave pubblica del mittente. Entrambe le coppie di chiavi del mittente e del destinatario sono pronte. `ECC_NIST_P256`
```
import boto3
from aws_cryptographic_materialproviders.mpl.models import (
CreateAwsKmsEcdhKeyringInput,
KmsEcdhStaticConfigurationsKmsPrivateKeyToStaticPublicKey,
KmsPrivateKeyToStaticPublicKeyInput,
)
from aws_cryptography_primitives.smithygenerated.aws_cryptography_primitives.models import ECDHCurveSpec
# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Retrieve public keys
# Must be DER-encoded X.509 public keys
bob_public_key = get_public_key_bytes("arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
alice_public_key = get_public_key_bytes("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321")
# Create the AWS KMS ECDH static keyring
sender_keyring_input = CreateAwsKmsEcdhKeyringInput(
kms_client = boto3.client('kms', region_name="us-west-2"),
curve_spec = ECDHCurveSpec.ECC_NIST_P256,
key_agreement_scheme = KmsEcdhStaticConfigurationsKmsPrivateKeyToStaticPublicKey(
KmsPrivateKeyToStaticPublicKeyInput(
sender_kms_identifier = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
sender_public_key = bob_public_key,
recipient_public_key = alice_public_key,
)
)
)
keyring = mat_prov.create_aws_kms_ecdh_keyring(sender_keyring_input)
```
------
#### [ Rust ]
L'esempio seguente crea un portachiavi AWS KMS ECDH con la chiave KMS del mittente, la chiave pubblica del mittente e la chiave pubblica del destinatario. Questo esempio utilizza il `sender_public_key` parametro opzionale per fornire la chiave pubblica del mittente. Se non fornisci la chiave pubblica del mittente, il portachiavi chiama AWS KMS per recuperare la chiave pubblica del mittente.
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create the 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);
// Optional: 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()),
]);
// Retrieve public keys
// Must be DER-encoded X.509 keys
let public_key_file_content_sender = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_SENDER))?;
let parsed_public_key_file_content_sender = parse(public_key_file_content_sender)?;
let public_key_sender_utf8_bytes = parsed_public_key_file_content_sender.contents();
let public_key_file_content_recipient = std::fs::read_to_string(Path::new(EXAMPLE_KMS_ECC_PUBLIC_KEY_FILENAME_RECIPIENT))?;
let parsed_public_key_file_content_recipient = parse(public_key_file_content_recipient)?;
let public_key_recipient_utf8_bytes = parsed_public_key_file_content_recipient.contents();
// Create KmsPrivateKeyToStaticPublicKeyInput
let kms_ecdh_static_configuration_input =
KmsPrivateKeyToStaticPublicKeyInput::builder()
.sender_kms_identifier(arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab)
// Must be a UTF8 DER-encoded X.509 public key
.sender_public_key(public_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let kms_ecdh_static_configuration = KmsEcdhStaticConfigurations::KmsPrivateKeyToStaticPublicKey(kms_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH keyring
let kms_ecdh_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client)
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_static_configuration)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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",
}
// Retrieve public keys
// Must be DER-encoded X.509 keys
publicKeySender, err := utils.LoadPublicKeyFromPEM(kmsEccPublicKeyFileNameSender)
if err != nil {
panic(err)
}
publicKeyRecipient, err := utils.LoadPublicKeyFromPEM(kmsEccPublicKeyFileNameRecipient)
if err != nil {
panic(err)
}
// Create KmsPrivateKeyToStaticPublicKeyInput
kmsEcdhStaticConfigurationInput := mpltypes.KmsPrivateKeyToStaticPublicKeyInput{
RecipientPublicKey: publicKeyRecipient,
SenderKmsIdentifier: arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab,
SenderPublicKey: publicKeySender,
}
kmsEcdhStaticConfiguration := &mpltypes.KmsEcdhStaticConfigurationsMemberKmsPrivateKeyToStaticPublicKey{
Value: kmsEcdhStaticConfigurationInput,
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create AWS KMS ECDH keyring
awsKmsEcdhKeyringInput := mpltypes.CreateAwsKmsEcdhKeyringInput{
CurveSpec: ecdhCurveSpec,
KeyAgreementScheme: kmsEcdhStaticConfiguration,
KmsClient: kmsClient,
}
awsKmsEcdhKeyring, err := matProv.CreateAwsKmsEcdhKeyring(context.Background(), awsKmsEcdhKeyringInput)
if err != nil {
panic(err)
}
```
------
## Creazione di un portachiavi ECDH Discovery AWS KMS
Durante la decrittografia, è consigliabile specificare le chiavi che possono utilizzare. AWS Encryption SDK Per seguire questa best practice, utilizzate un portachiavi AWS KMS ECDH con lo schema degli accordi chiave. `KmsPrivateKeyToStaticPublicKey` Tuttavia, puoi anche creare un portachiavi AWS KMS ECDH discovery, ovvero un portachiavi AWS KMS ECDH in grado di decrittografare qualsiasi messaggio in cui la chiave pubblica della coppia di chiavi KMS specificata corrisponda alla chiave pubblica del *destinatario* memorizzata nel testo cifrato del messaggio.
**Importante**
Quando decifrate i messaggi utilizzando lo schema degli accordi `KmsPublicKeyDiscovery` chiave, accettate tutte le chiavi pubbliche, indipendentemente da chi le possiede.
Per inizializzare un portachiavi AWS KMS ECDH con lo schema degli accordi `KmsPublicKeyDiscovery` chiave, fornite i seguenti valori:
+ **ID del destinatario AWS KMS key **
Deve identificare una coppia di chiavi KMS a curva ellittica (ECC) asimmetrica consigliata dal NIST con un valore di. `KeyUsage` `KEY_AGREEMENT`
+ **Specificazione della curva**
Identifica la specifica della curva ellittica nella coppia di chiavi KMS del destinatario.
Valori validi: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
+ **(Facoltativo) Un elenco di token di concessione**
Se controlli l'accesso alla chiave KMS nel tuo portachiavi AWS KMS ECDH con le [sovvenzioni](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), devi fornire tutti i token di concessione necessari quando inizializzi il portachiavi.
------
#### [ C\$1 / .NET ]
L'esempio seguente crea un portachiavi AWS KMS ECDH discovery con una coppia di chiavi KMS sulla curva. `ECC_NIST_P256` È necessario disporre delle DeriveSharedSecret autorizzazioni [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) sulla coppia di key pair KMS specificata. Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della coppia di chiavi KMS specificata corrisponde alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create the AWS KMS ECDH discovery keyring
var discoveryConfiguration = new KmsEcdhStaticConfigurations
{
KmsPublicKeyDiscovery = new KmsPublicKeyDiscoveryInput
{
RecipientKmsIdentifier = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
}
};
var createKeyringInput = new CreateAwsKmsEcdhKeyringInput
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KmsClient = new AmazonKeyManagementServiceClient(),
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateAwsKmsEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
L'esempio seguente crea un portachiavi AWS KMS ECDH discovery con una coppia di chiavi KMS sulla curva. `ECC_NIST_P256` È necessario disporre delle DeriveSharedSecret autorizzazioni [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) sulla coppia di key pair KMS specificata. Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della coppia di chiavi KMS specificata corrisponde alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
// Create the AWS KMS ECDH discovery keyring
final CreateAwsKmsEcdhKeyringInput recipientKeyringInput =
CreateAwsKmsEcdhKeyringInput.builder()
.kmsClient(KmsClient.create())
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
KmsEcdhStaticConfigurations.builder()
.KmsPublicKeyDiscovery(
KmsPublicKeyDiscoveryInput.builder()
.recipientKmsIdentifier("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321").build()
).build())
.build();
```
------
#### [ Python ]
L'esempio seguente crea un portachiavi AWS KMS ECDH discovery con una coppia di chiavi KMS sulla curva. `ECC_NIST_P256` È necessario disporre delle DeriveSharedSecret autorizzazioni [kms: GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) e [kms:](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) sulla coppia di key pair KMS specificata. Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della coppia di chiavi KMS specificata corrisponde alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
import boto3
from aws_cryptographic_materialproviders.mpl.models import (
CreateAwsKmsEcdhKeyringInput,
KmsEcdhStaticConfigurationsKmsPublicKeyDiscovery,
KmsPublicKeyDiscoveryInput,
)
from aws_cryptography_primitives.smithygenerated.aws_cryptography_primitives.models import ECDHCurveSpec
# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create the AWS KMS ECDH discovery keyring
create_keyring_input = CreateAwsKmsEcdhKeyringInput(
kms_client = boto3.client('kms', region_name="us-west-2"),
curve_spec = ECDHCurveSpec.ECC_NIST_P256,
key_agreement_scheme = KmsEcdhStaticConfigurationsKmsPublicKeyDiscovery(
KmsPublicKeyDiscoveryInput(
recipient_kms_identifier = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
)
)
)
keyring = mat_prov.create_aws_kms_ecdh_keyring(create_keyring_input)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create the 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);
// Optional: 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()),
]);
// Create KmsPublicKeyDiscoveryInput
let kms_ecdh_discovery_static_configuration_input =
KmsPublicKeyDiscoveryInput::builder()
.recipient_kms_identifier(ecc_recipient_key_arn)
.build()?;
let kms_ecdh_discovery_static_configuration = KmsEcdhStaticConfigurations::KmsPublicKeyDiscovery(kms_ecdh_discovery_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create AWS KMS ECDH discovery keyring
let kms_ecdh_discovery_keyring = mpl
.create_aws_kms_ecdh_keyring()
.kms_client(kms_client.clone())
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(kms_ecdh_discovery_static_configuration)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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",
}
// Create KmsPublicKeyDiscoveryInput
kmsEcdhDiscoveryStaticConfigurationInput := mpltypes.KmsPublicKeyDiscoveryInput{
RecipientKmsIdentifier: eccRecipientKeyArn,
}
kmsEcdhDiscoveryStaticConfiguration := &mpltypes.KmsEcdhStaticConfigurationsMemberKmsPublicKeyDiscovery{
Value: kmsEcdhDiscoveryStaticConfigurationInput,
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create AWS KMS ECDH discovery keyring
awsKmsEcdhDiscoveryKeyringInput := mpltypes.CreateAwsKmsEcdhKeyringInput{
CurveSpec: ecdhCurveSpec,
KeyAgreementScheme: kmsEcdhDiscoveryStaticConfiguration,
KmsClient: kmsClient,
}
awsKmsEcdhDiscoveryKeyring, err := matProv.CreateAwsKmsEcdhKeyring(context.Background(), awsKmsEcdhDiscoveryKeyringInput)
if err != nil {
panic(err)
}
```
------
# Keyring non elaborati AES
Ti AWS Encryption SDK consente di utilizzare una chiave simmetrica AES fornita come chiave di wrapping per proteggere la tua chiave dati. È necessario generare, archiviare e proteggere il materiale chiave, preferibilmente in un modulo di sicurezza hardware (HSM) o in un sistema di gestione delle chiavi. Usa un portachiavi Raw AES quando devi fornire la chiave di wrapping e crittografare le chiavi dati localmente o offline.
Il portachiavi Raw AES crittografa i dati utilizzando l'algoritmo AES-GCM e una chiave di wrapping specificata come array di byte. [È possibile specificare solo una chiave di avvolgimento in ogni portachiavi Raw AES, ma è possibile includere più portachiavi Raw AES, da soli o con altri portachiavi, in un portachiavi multiplo.](use-multi-keyring.md)
Il portachiavi Raw AES è equivalente e interagisce con la [JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)classe in e con la classe in SDK di crittografia AWS per Python quando viene SDK di crittografia AWS per Java utilizzato con una chiave di crittografia AES. [RawMasterKey](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.raw.html#aws_encryption_sdk.key_providers.raw.RawMasterKey) È possibile crittografare e decrittare i dati con implementazioni diverse, ma utilizzando la stessa chiave di wrapping. Per informazioni dettagliate, vedi [Compatibilità dei keyring](choose-keyring.md#keyring-compatibility).
**Namespace e nomi chiave**
*Per identificare la chiave AES in un portachiavi, il portachiavi Raw AES utilizza uno *spazio dei nomi e un nome chiave forniti* dall'utente.* Questi valori non sono segreti. Vengono visualizzati in testo semplice nell'intestazione del [messaggio crittografato restituito dall'operazione](concepts.md#message) di crittografia. Si consiglia di utilizzare uno spazio dei nomi delle chiavi (HSM o sistema di gestione delle chiavi) e un nome di chiave che identifichi la chiave AES in quel sistema.
**Nota**
Lo spazio dei nomi e il nome della chiave sono equivalenti ai campi *Provider ID (o *Provider**) e *Key* ID presenti nel e. `JceMasterKey` `RawMasterKey`
SDK di crittografia AWS per C and AWS Encryption SDK for .NET riserva il valore dello spazio dei nomi `aws-kms` chiave per le chiavi KMS. Non utilizzare questo valore dello spazio dei nomi in un portachiavi Raw AES o Raw RSA con queste librerie.
Se si creano portachiavi diversi per crittografare e decrittografare un determinato messaggio, lo spazio dei nomi e i valori del nome sono fondamentali. Se lo spazio dei nomi della chiave e il nome della chiave nel portachiavi di decrittografia non corrispondono esattamente, con distinzione tra maiuscole e minuscole, per lo spazio dei nomi della chiave e il nome della chiave nel portachiavi di crittografia, il portachiavi di decrittografia non viene utilizzato, anche se i byte del materiale della chiave sono identici.
Ad esempio, è possibile definire un portachiavi Raw AES con lo spazio dei nomi e il nome della chiave. `HSM_01` `AES_256_012` Quindi, usi quel portachiavi per crittografare alcuni dati. Per decrittografare quei dati, crea un portachiavi Raw AES con lo stesso spazio dei nomi delle chiavi, nome chiave e materiale chiave.
I seguenti esempi mostrano come creare un portachiavi Raw AES. La `AESWrappingKey` variabile rappresenta il materiale chiave fornito.
------
#### [ C ]
Per creare un'istanza di un portachiavi Raw AES in, usa. SDK di crittografia AWS per C`aws_cryptosdk_raw_aes_keyring_new()` [Per un esempio completo, vedete raw\$1aes\$1keyring.c.](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/raw_aes_keyring.c)
```
struct aws_allocator *alloc = aws_default_allocator();
AWS_STATIC_STRING_FROM_LITERAL(wrapping_key_namespace, "HSM_01");
AWS_STATIC_STRING_FROM_LITERAL(wrapping_key_name, "AES_256_012");
struct aws_cryptosdk_keyring *raw_aes_keyring = aws_cryptosdk_raw_aes_keyring_new(
alloc, wrapping_key_namespace, wrapping_key_name, aes_wrapping_key, wrapping_key_len);
```
------
#### [ C\$1 / .NET ]
Per creare un portachiavi Raw AES in.NET, usa il metodo. AWS Encryption SDK `materialProviders.CreateRawAesKeyring()` Per un esempio completo, vedete [Raw AESKeyring Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/RawAESKeyringExample.cs).
L'esempio seguente utilizza la versione 4. *x* e versioni successive di AWS Encryption SDK per .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var keyNamespace = "HSM_01";
var keyName = "AES_256_012";
// This example uses the key generator in Bouncy Castle to generate the key material.
// In production, use key material from a secure source.
var aesWrappingKey = new MemoryStream(GeneratorUtilities.GetKeyGenerator("AES256").GenerateKey());
// Create the keyring that determines how your data keys are protected.
var createKeyringInput = new CreateRawAesKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
WrappingKey = aesWrappingKey,
WrappingAlg = AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
};
var keyring = materialProviders.CreateRawAesKeyring(createKeyringInput);
```
------
#### [ JavaScript Browser ]
SDK di crittografia AWS per JavaScript Nel browser ottiene le sue primitive crittografiche dall'API. [WebCrypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) Prima di costruire il portachiavi, è necessario `RawAesKeyringWebCrypto.importCryptoKey()` importare il materiale grezzo della chiave nel backend. WebCrypto Ciò garantisce che il portachiavi sia completo anche se tutte le chiamate a sono asincrone. WebCrypto
Quindi, per creare un'istanza di un portachiavi Raw AES, usa il metodo. `RawAesKeyringWebCrypto()` È necessario specificare l'algoritmo di wrapping AES («wrapping suite») in base alla lunghezza del materiale chiave. Per un esempio completo, vedete [aes\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/aes_simple.ts) (Browser). JavaScript
[L'esempio seguente utilizza la `buildClient` funzione per specificare la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
RawAesWrappingSuiteIdentifier,
RawAesKeyringWebCrypto,
synchronousRandomValues,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const keyNamespace = 'HSM_01'
const keyName = 'AES_256_012'
const wrappingSuite =
RawAesWrappingSuiteIdentifier.AES256_GCM_IV12_TAG16_NO_PADDING
/* Import the plaintext AES key into the WebCrypto backend. */
const aesWrappingKey = await RawAesKeyringWebCrypto.importCryptoKey(
rawAesKey,
wrappingSuite
)
const rawAesKeyring = new RawAesKeyringWebCrypto({
keyName,
keyNamespace,
wrappingSuite,
aesWrappingKey
})
```
------
#### [ JavaScript Node.js ]
Per creare un'istanza di un portachiavi Raw AES in SDK di crittografia AWS per JavaScript for Node.js, create un'istanza della classe. ` RawAesKeyringNode` È necessario specificare l'algoritmo di wrapping AES («wrapping suite») in base alla lunghezza del materiale chiave. Per un esempio completo, vedete [aes\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript//blob/master/modules/example-node/src/aes_simple.ts) (Node.js). JavaScript
[L'esempio seguente utilizza la `buildClient` funzione per specificare la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
RawAesKeyringNode,
buildClient,
CommitmentPolicy,
RawAesWrappingSuiteIdentifier,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const keyName = 'AES_256_012'
const keyNamespace = 'HSM_01'
const wrappingSuite =
RawAesWrappingSuiteIdentifier.AES256_GCM_IV12_TAG16_NO_PADDING
const rawAesKeyring = new RawAesKeyringNode({
keyName,
keyNamespace,
aesWrappingKey,
wrappingSuite,
})
```
------
#### [ Java ]
Per creare un'istanza di un portachiavi Raw AES in, usa. SDK di crittografia AWS per Java`matProv.CreateRawAesKeyring()`
```
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput);
```
------
#### [ Python ]
[L'esempio seguente crea un'istanza del AWS Encryption SDK client con la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Per un esempio completo, vedere [raw\$1aes\$1keyring\$1example.py](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/raw_aes_keyring_example.py) nel SDK di crittografia AWS per Python repository in. GitHub
```
# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# Define the key namespace and key name
key_name_space = "HSM_01"
key_name = "AES_256_012"
# Optional: Create an encryption context
encryption_context: Dict[str, str] = {
"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
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create Raw AES keyring
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=AESWrappingKey,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Define the key namespace and key name
let key_namespace: &str = "HSM_01";
let key_name: &str = "AES_256_012";
// Optional: Create an 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 Raw AES keyring
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name(key_name)
.key_namespace(key_namespace)
.wrapping_key(aws_smithy_types::Blob::new(AESWrappingKey))
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.send()
.await?;
```
------
#### [ Go ]
```
import (
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"
)
//Instantiate the AWS Encryption SDK client.
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// Define the key namespace and key name
var keyNamespace = "A managed aes keys"
var keyName = "My 256-bit AES wrapping key"
// 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 Raw AES keyring
aesKeyRingInput := mpltypes.CreateRawAesKeyringInput{
KeyName: keyName,
KeyNamespace: keyNamespace,
WrappingKey: aesWrappingKey,
WrappingAlg: mpltypes.AesWrappingAlgAlgAes256GcmIv12Tag16,
}
aesKeyring, err := matProv.CreateRawAesKeyring(context.Background(), aesKeyRingInput)
if err != nil {
panic(err)
}
```
------
# Keyring non elaborato RSA
Il portachiavi Raw RSA esegue la crittografia e la decrittografia asimmetriche delle chiavi di dati nella memoria locale con una chiave pubblica e privata RSA fornita dall'utente. È necessario generare, archiviare e proteggere la chiave privata, preferibilmente in un modulo di sicurezza hardware (HSM) o in un sistema di gestione delle chiavi. La funzione di crittografia consente di crittografare la chiave di dati nella chiave pubblica RSA. La funzione di decrittazione consente di decrittare la chiave di dati con la chiave privata. Puoi scegliere tra i diverse [modalità di padding RSA](https://github.com/aws/aws-encryption-sdk-c/blob/master/include/aws/cryptosdk/cipher.h).
Un keyring non elaborato RSA che esegue crittografia e decrittazione deve includere una coppia di chiavi pubblica e privata asimmetriche. Tuttavia, è possibile crittografare i dati con un portachiavi Raw RSA che ha solo una chiave pubblica e decrittografare i dati con un portachiavi Raw RSA che ha solo una chiave privata. [Puoi includere qualsiasi portachiavi Raw RSA in un portachiavi multiplo.](use-multi-keyring.md) Se configuri un portachiavi Raw RSA con una chiave pubblica e una privata, assicurati che facciano parte della stessa coppia di chiavi. Alcune implementazioni linguistiche di non AWS Encryption SDK costruiranno un portachiavi Raw RSA con chiavi di coppie diverse. Altri si affidano a te per verificare che le tue chiavi appartengano alla stessa coppia di chiavi.
Il portachiavi Raw RSA è equivalente e interagisce con l'[JceMasterKey](https://aws.github.io/aws-encryption-sdk-java/com/amazonaws/encryptionsdk/jce/JceMasterKey.html)in SDK di crittografia AWS per Java e l'[RawMasterKey](https://aws-encryption-sdk-python.readthedocs.io/en/latest/generated/aws_encryption_sdk.key_providers.raw.html#aws_encryption_sdk.key_providers.raw.RawMasterKey)in the SDK di crittografia AWS per Python quando viene utilizzato con chiavi di crittografia asimmetriche RSA. È possibile crittografare e decrittare i dati con implementazioni diverse, ma utilizzando la stessa chiave di wrapping. Per informazioni dettagliate, vedi [Compatibilità dei keyring](choose-keyring.md#keyring-compatibility).
**Nota**
Il portachiavi Raw RSA non supporta le chiavi KMS asimmetriche. Se desideri utilizzare chiavi RSA KMS asimmetriche, i seguenti linguaggi di programmazione supportano i portachiavi che utilizzano RSA asimmetrico: AWS KMS AWS KMS keys
Versione 3. *x* del SDK di crittografia AWS per Java
Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
Versione 4. *x* di SDK di crittografia AWS per Python, se utilizzato con la dipendenza opzionale [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL).
Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
Se si crittografano i dati con un portachiavi Raw RSA che include la chiave pubblica di una chiave RSA KMS, né l'uno né l' AWS Encryption SDK altro possono decrittografarli. AWS KMS Non è possibile esportare la chiave privata di una chiave KMS AWS KMS asimmetrica in un portachiavi RSA Raw. [L'operazione Decrypt non può AWS KMS decrittografare il messaggio crittografato che restituisce.](concepts.md#message) AWS Encryption SDK
Quando crei un portachiavi Raw RSA in SDK di crittografia AWS per C, assicurati di fornire il *contenuto* del file PEM che include ogni chiave come stringa C con terminazione nulla, non come percorso o nome di file. Quando crei un keyring non elaborato RSA in JavaScript, controlla le [potenziale incompatibilità](javascript-compatibility.md) con altre implementazioni di linguaggio.
**Namespace e nomi**
*Per identificare il materiale chiave RSA in un portachiavi, il portachiavi Raw RSA utilizza uno spazio dei nomi e un *nome chiave* forniti dall'utente.* Questi valori non sono segreti. Vengono visualizzati in testo semplice nell'intestazione del messaggio [crittografato](concepts.md#message) restituito dall'operazione di crittografia. Ti consigliamo di utilizzare lo spazio dei nomi e il nome della chiave che identificano la coppia di chiavi RSA (o la relativa chiave privata) nel tuo HSM o sistema di gestione delle chiavi.
**Nota**
*Lo spazio dei nomi della chiave e il nome della chiave sono equivalenti ai campi *Provider ID (o *Provider**) e Key ID nel e.* `JceMasterKey` `RawMasterKey`
The SDK di crittografia AWS per C riserva il valore dello spazio dei nomi `aws-kms` chiave per le chiavi KMS. Non utilizzarlo in un portachiavi Raw AES o Raw RSA con. SDK di crittografia AWS per C
Se si creano portachiavi diversi per crittografare e decrittografare un determinato messaggio, lo spazio dei nomi e i valori del nome sono fondamentali. Se lo spazio dei nomi della chiave e il nome della chiave nel portachiavi di decrittografia non corrispondono esattamente, con distinzione tra maiuscole e minuscole, per lo spazio dei nomi della chiave e il nome della chiave nel portachiavi di crittografia, il portachiavi di decrittografia non viene utilizzato, anche se le chiavi appartengono alla stessa coppia di chiavi.
Lo spazio dei nomi e il nome chiave del materiale chiave nei portachiavi di crittografia e decrittografia devono essere gli stessi indipendentemente dal fatto che il portachiavi contenga la chiave pubblica RSA, la chiave privata RSA o entrambe le chiavi della coppia di chiavi. Ad esempio, supponiamo di crittografare i dati con un portachiavi RSA Raw per una chiave pubblica RSA con namespace e nome chiave. `HSM_01` `RSA_2048_06` Per decrittografare quei dati, crea un portachiavi Raw RSA con la chiave privata (o coppia di chiavi) e lo stesso namespace e nome della chiave.
**Modalità di imbottitura**
È necessario specificare una modalità di riempimento per i portachiavi Raw RSA utilizzati per la crittografia e la decrittografia oppure utilizzare funzionalità dell'implementazione del linguaggio che la specificano automaticamente.
AWS Encryption SDK Supporta le seguenti modalità di riempimento, soggette ai vincoli di ogni lingua. Consigliamo una modalità di riempimento [OAEP, in particolare OAEP](https://tools.ietf.org/html/rfc8017#section-7.1) con SHA-256 e con imbottitura SHA-256. MGF1 La modalità padding è supportata solo per la compatibilità con le versioni precedenti. [PKCS1](https://tools.ietf.org/html/rfc8017#section-7.2)
+ OAEP con SHA-1 e con imbottitura SHA-1 MGF1
+ OAEP con SHA-256 e con imbottitura SHA-256 MGF1
+ OAEP con SHA-384 e con imbottitura SHA-384 MGF1
+ OAEP con SHA-512 e MGF1 con imbottitura SHA-512
+ PKCS1 Imbottitura v1.5
Gli esempi seguenti mostrano come creare un portachiavi Raw RSA con la chiave pubblica e privata di una coppia di chiavi RSA e l'OAEP con SHA-256 e con modalità padding SHA-256. MGF1 Le variabili and rappresentano il materiale chiave fornito. `RSAPublicKey` `RSAPrivateKey`
------
#### [ C ]
Per creare un portachiavi Raw RSA in SDK di crittografia AWS per C, usa. `aws_cryptosdk_raw_rsa_keyring_new`
Quando crei un portachiavi Raw RSA in SDK di crittografia AWS per C, assicurati di fornire il *contenuto* del file PEM che include ogni chiave come stringa C con terminazione nulla, non come percorso o nome di file. [Per un esempio completo, vedete raw\$1rsa\$1keyring.c.](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/raw_rsa_keyring.c)
```
struct aws_allocator *alloc = aws_default_allocator();
AWS_STATIC_STRING_FROM_LITERAL(key_namespace, "HSM_01");
AWS_STATIC_STRING_FROM_LITERAL(key_name, "RSA_2048_06");
struct aws_cryptosdk_keyring *rawRsaKeyring = aws_cryptosdk_raw_rsa_keyring_new(
alloc,
key_namespace,
key_name,
private_key_from_pem,
public_key_from_pem,
AWS_CRYPTOSDK_RSA_OAEP_SHA256_MGF1);
```
------
#### [ C\$1 / .NET ]
Per creare un'istanza di un portachiavi Raw RSA in formato.NET, usa il metodo. AWS Encryption SDK `materialProviders.CreateRawRsaKeyring()` [Per un esempio completo, consulta Raw Example.cs. RSAKeyring](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/RawRSAKeyringExample.cs)
L'esempio seguente utilizza la versione 4. *x* e versioni successive di AWS Encryption SDK per .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var keyNamespace = "HSM_01";
var keyName = "RSA_2048_06";
// Get public and private keys from PEM files
var publicKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePublicKey.pem"));
var privateKey = new MemoryStream(System.IO.File.ReadAllBytes("RSAKeyringExamplePrivateKey.pem"));
// Create the keyring input
var createRawRsaKeyringInput = new CreateRawRsaKeyringInput
{
KeyNamespace = keyNamespace,
KeyName = keyName,
PaddingScheme = PaddingScheme.OAEP_SHA512_MGF1,
PublicKey = publicKey,
PrivateKey = privateKey
};
// Create the keyring
var rawRsaKeyring = materialProviders.CreateRawRsaKeyring(createRawRsaKeyringInput);
```
------
#### [ JavaScript Browser ]
SDK di crittografia AWS per JavaScript Nel browser ottiene le sue primitive crittografiche dalla libreria. [WebCrypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) Prima di costruire il portachiavi, è necessario `importPublicKey()` and/or `importPrivateKey()` importare il materiale grezzo della chiave nel backend. WebCrypto Ciò garantisce che il portachiavi sia completo anche se tutte le chiamate a sono asincrone. WebCrypto L'oggetto utilizzato dai metodi di importazione include l'algoritmo di wrapping e la relativa modalità di riempimento.
Dopo aver importato il materiale chiave, utilizzate il `RawRsaKeyringWebCrypto()` metodo per creare un'istanza del portachiavi. [Quando crei un portachiavi Raw RSA in JavaScript, tieni presente la potenziale incompatibilità con altre implementazioni linguistiche.](javascript-compatibility.md)
[L'esempio seguente utilizza la `buildClient` funzione per specificare la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
Per un esempio completo, vedete [rsa\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/rsa_simple.ts) (Browser). JavaScript
```
import {
RsaImportableKey,
RawRsaKeyringWebCrypto,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const privateKey = await RawRsaKeyringWebCrypto.importPrivateKey(
privateRsaJwKKey
)
const publicKey = await RawRsaKeyringWebCrypto.importPublicKey(
publicRsaJwKKey
)
const keyNamespace = 'HSM_01'
const keyName = 'RSA_2048_06'
const keyring = new RawRsaKeyringWebCrypto({
keyName,
keyNamespace,
publicKey,
privateKey,
})
```
------
#### [ JavaScript Node.js ]
Per creare un'istanza di un portachiavi Raw RSA in Node.js, create una nuova istanza della SDK di crittografia AWS per JavaScript classe. `RawRsaKeyringNode` Il `wrapKey` parametro contiene la chiave pubblica. Il `unwrapKey` parametro contiene la chiave privata. Il `RawRsaKeyringNode` costruttore calcola automaticamente una modalità di riempimento predefinita, sebbene sia possibile specificare una modalità di riempimento preferita.
[Quando crei un portachiavi RSA non elaborato JavaScript, tieni presente la potenziale incompatibilità con altre implementazioni linguistiche.](javascript-compatibility.md)
[L'esempio seguente utilizza la `buildClient` funzione per specificare la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
Per un esempio completo, vedere [rsa\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/rsa_simple.ts) (Node.js). JavaScript
```
import {
RawRsaKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const keyNamespace = 'HSM_01'
const keyName = 'RSA_2048_06'
const keyring = new RawRsaKeyringNode({ keyName, keyNamespace, rsaPublicKey, rsaPrivateKey})
```
------
#### [ Java ]
```
final CreateRawRsaKeyringInput keyringInput = CreateRawRsaKeyringInput.builder()
.keyName("RSA_2048_06")
.keyNamespace("HSM_01")
.paddingScheme(PaddingScheme.OAEP_SHA256_MGF1)
.publicKey(RSAPublicKey)
.privateKey(RSAPrivateKey)
.build();
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
IKeyring rawRsaKeyring = matProv.CreateRawRsaKeyring(keyringInput);
```
------
#### [ Python ]
[L'esempio seguente crea un'istanza del AWS Encryption SDK client con la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Per un esempio completo, vedere [raw\$1rsa\$1keyring\$1example.py](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/raw_rsa_keyring_example.py) nel SDK di crittografia AWS per Python repository in. GitHub
```
# Define the key namespace and key name
key_name_space = "HSM_01"
key_name = "RSA_2048_06"
# Instantiate the material providers
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Create Raw RSA keyring
keyring_input: CreateRawRsaKeyringInput = CreateRawRsaKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
padding_scheme=PaddingScheme.OAEP_SHA256_MGF1,
public_key=RSAPublicKey,
private_key=RSAPrivateKey
)
raw_rsa_keyring: IKeyring = mat_prov.create_raw_rsa_keyring(
input=keyring_input
)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Optional: Create an 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()),
]);
// Define the key namespace and key name
let key_namespace: &str = "HSM_01";
let key_name: &str = "RSA_2048_06";
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create Raw RSA keyring
let raw_rsa_keyring = mpl
.create_raw_rsa_keyring()
.key_name(key_name)
.key_namespace(key_namespace)
.padding_scheme(PaddingScheme::OaepSha256Mgf1)
.public_key(aws_smithy_types::Blob::new(RSAPublicKey))
.private_key(aws_smithy_types::Blob::new(RSAPrivateKey))
.send()
.await?;
```
------
#### [ Go ]
```
// Instantiate the material providers library
matProv, err := awscryptographymaterialproviderssmithygenerated.NewClient(awscryptographymaterialproviderssmithygeneratedtypes.MaterialProvidersConfig{})
// Create Raw RSA keyring
rsaKeyRingInput := awscryptographymaterialproviderssmithygeneratedtypes.CreateRawRsaKeyringInput{
KeyName: "rsa",
KeyNamespace: "rsa-keyring",
PaddingScheme: awscryptographymaterialproviderssmithygeneratedtypes.PaddingSchemePkcs1,
PublicKey: pem.EncodeToMemory(publicKeyBlock),
PrivateKey: pem.EncodeToMemory(privateKeyBlock),
}
rsaKeyring, err := matProv.CreateRawRsaKeyring(context.Background(), rsaKeyRingInput)
```
------
#### [ 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"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// 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",
}
// Define the key namespace and key name
var keyNamespace = "HSM_01"
var keyName = "RSA_2048_06"
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create Raw RSA keyring
rsaKeyRingInput := mpltypes.CreateRawRsaKeyringInput{
KeyName: keyName,
KeyNamespace: keyNamespace,
PaddingScheme: mpltypes.PaddingSchemeOaepSha512Mgf1,
PublicKey: (RSAPublicKey),
PrivateKey: (RSAPrivateKey),
}
rsaKeyring, err := matProv.CreateRawRsaKeyring(context.Background(), rsaKeyRingInput)
if err != nil {
panic(err)
}
```
------
# Portachiavi ECDH grezzi
Il portachiavi Raw ECDH utilizza le coppie di chiavi pubbliche-private a curva ellittica fornite dall'utente per ricavare una chiave di wrapping condivisa tra due parti. Innanzitutto, il portachiavi ricava un segreto condiviso utilizzando la chiave privata del mittente, la chiave pubblica del destinatario e l'algoritmo di accordo delle chiavi Elliptic Curve Diffie-Hellman (ECDH). Quindi, il portachiavi utilizza il segreto condiviso per derivare la chiave di avvolgimento condivisa che protegge le chiavi di crittografia dei dati. [La funzione di derivazione delle chiavi che AWS Encryption SDK utilizza (`KDF_CTR_HMAC_SHA384`) per derivare la chiave di wrapping condivisa è conforme alle raccomandazioni del NIST per la derivazione delle chiavi.](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1-upd1.pdf)
La funzione di derivazione delle chiavi restituisce 64 byte di materiale chiave. Per garantire che entrambe le parti utilizzino il materiale chiave corretto, AWS Encryption SDK utilizza i primi 32 byte come chiave di impegno e gli ultimi 32 byte come chiave di wrapping condivisa. Al momento della decrittografia, se il portachiavi non è in grado di riprodurre la stessa chiave di impegno e la stessa chiave di wrapping condivisa memorizzate nel testo cifrato dell'intestazione del messaggio, l'operazione ha esito negativo. Ad esempio, se si crittografano i dati con un portachiavi configurato con la chiave privata **di Alice** e la chiave pubblica **di Bob**, un portachiavi configurato con la chiave privata **di Bob** e la chiave pubblica **di Alice** riprodurrà la stessa chiave di impegno e la stessa chiave di wrapping condivisa e sarà in grado di decrittografare i dati. [Se la chiave pubblica di Bob proviene da una AWS KMS key coppia, Bob può creare un AWS KMS portachiavi ECDH per decrittografare i dati.](use-kms-ecdh-keyring.md)
Il portachiavi Raw ECDH crittografa i dati con una chiave simmetrica utilizzando AES-GCM. La chiave dati viene quindi crittografata in busta con la chiave di wrapping condivisa derivata utilizzando AES-GCM. [Ogni portachiavi Raw ECDH può avere solo una chiave di avvolgimento condivisa, ma è possibile includere più portachiavi Raw ECDH, da soli o con altri portachiavi, in un portachiavi multiplo.](use-multi-keyring.md)
L'utente è responsabile della generazione, dell'archiviazione e della protezione delle chiavi private, preferibilmente in un modulo di sicurezza hardware (HSM) o in un sistema di gestione delle chiavi. Le coppie di chiavi del mittente e del destinatario devono trovarsi sulla stessa curva ellittica. AWS Encryption SDK Supporta le seguenti specifiche della curva ellittica:
+ `ECC_NIST_P256`
+ `ECC_NIST_P384`
+ `ECC_NIST_P512`
**Compatibilità del linguaggio di programmazione**
Il portachiavi Raw ECDH è stato introdotto nella versione 1.5.0 della [Cryptographic Material Providers Library](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) ed è supportato dai seguenti linguaggi e versioni di programmazione:
+ Versione 3. *x* del SDK di crittografia AWS per Java
+ Versione 4. *x* e versioni successive di AWS Encryption SDK for .NET
+ Versione 4. *x* di SDK di crittografia AWS per Python, se usato con la dipendenza MPL opzionale.
+ Versione 1. *x* del AWS Encryption SDK per Rust
+ Versione 0.1. *x* o versione successiva di AWS Encryption SDK for Go
## Creazione di un portachiavi Raw ECDH
Il portachiavi Raw ECDH supporta tre schemi di accordi chiave:, e. `RawPrivateKeyToStaticPublicKey` `EphemeralPrivateKeyToStaticPublicKey` `PublicKeyDiscovery` Lo schema di accordo chiave selezionato determina quali operazioni crittografiche è possibile eseguire e come vengono assemblati i materiali di codifica.
**Topics**
+ [RawPrivateKeyToStaticPublicKey](#raw-ecdh-RawPrivateKeyToStaticPublicKey)
+ [EphemeralPrivateKeyToStaticPublicKey](#raw-ecdh-EphemeralPrivateKeyToStaticPublicKey)
+ [PublicKeyDiscovery](#raw-ecdh-PublicKeyDiscovery)
### RawPrivateKeyToStaticPublicKey
Utilizza lo schema degli accordi `RawPrivateKeyToStaticPublicKey` chiave per configurare staticamente la chiave privata del mittente e la chiave pubblica del destinatario nel portachiavi. Questo schema di accordo chiave può crittografare e decrittografare i dati.
Per inizializzare un portachiavi Raw ECDH con lo schema degli accordi `RawPrivateKeyToStaticPublicKey` chiave, fornite i seguenti valori:
+ **Chiave privata del mittente**
[È necessario fornire la chiave privata con codifica PEM del mittente ( PrivateKeyInfo strutture PKCS \$18), come definita in RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Chiave pubblica del destinatario**
[È necessario fornire la chiave pubblica X.509 con codifica DER del destinatario, nota anche come `SubjectPublicKeyInfo` (SPKI), come definita in RFC 5280.](https://tools.ietf.org/html/rfc5280)
È possibile specificare la chiave pubblica di una coppia di chiavi KMS con accordo di chiave asimmetrico o la chiave pubblica da una coppia di chiavi generata all'esterno di. AWS
+ **Specificazione della curva**
Identifica la specifica della curva ellittica nelle coppie di chiavi specificate. Entrambe le coppie di chiavi del mittente e del destinatario devono avere la stessa specifica di curva.
Valori validi: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var BobPrivateKey = new MemoryStream(new byte[] { });
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH static keyring
var staticConfiguration = new RawEcdhStaticConfigurations()
{
RawPrivateKeyToStaticPublicKey = new RawPrivateKeyToStaticPublicKeyInput
{
SenderStaticPrivateKey = BobPrivateKey,
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = staticConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
Il seguente esempio di Java utilizza lo schema di accordo delle `RawPrivateKeyToStaticPublicKey` chiavi per configurare staticamente la chiave privata del mittente e la chiave pubblica del destinatario. Entrambe le coppie di chiavi sono sulla `ECC_NIST_P256` curva.
```
private static void StaticRawKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair senderKeys = GetRawEccKey();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH static keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.RawPrivateKeyToStaticPublicKey(
RawPrivateKeyToStaticPublicKeyInput.builder()
// Must be a PEM-encoded private key
.senderStaticPrivateKey(ByteBuffer.wrap(senderKeys.getPrivate().getEncoded()))
// Must be a DER-encoded X.509 public key
.recipientPublicKey(ByteBuffer.wrap(recipient.getPublic().getEncoded()))
.build()
)
.build()
).build();
final IKeyring staticKeyring = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Python ]
Il seguente esempio di Python utilizza lo schema di accordo delle `RawEcdhStaticConfigurationsRawPrivateKeyToStaticPublicKey` chiavi per configurare staticamente la chiave privata del mittente e la chiave pubblica del destinatario. Entrambe le coppie di chiavi sono sulla curva. `ECC_NIST_P256`
```
import boto3
from aws_cryptographic_materialproviders.mpl.models import (
CreateRawEcdhKeyringInput,
RawEcdhStaticConfigurationsRawPrivateKeyToStaticPublicKey,
RawPrivateKeyToStaticPublicKeyInput,
)
from aws_cryptography_primitives.smithygenerated.aws_cryptography_primitives.models import ECDHCurveSpec
# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Must be a PEM-encoded private key
bob_private_key = get_private_key_bytes()
# Must be a DER-encoded X.509 public key
alice_public_key = get_public_key_bytes()
# Create the raw ECDH static keyring
raw_keyring_input = CreateRawEcdhKeyringInput(
curve_spec = ECDHCurveSpec.ECC_NIST_P256,
key_agreement_scheme = RawEcdhStaticConfigurationsRawPrivateKeyToStaticPublicKey(
RawPrivateKeyToStaticPublicKeyInput(
sender_static_private_key = bob_private_key,
recipient_public_key = alice_public_key,
)
)
)
keyring = mat_prov.create_raw_ecdh_keyring(raw_keyring_input)
```
------
#### [ Rust ]
Il seguente esempio di Python utilizza lo schema di accordo delle `raw_ecdh_static_configuration` chiavi per configurare staticamente la chiave privata del mittente e la chiave pubblica del destinatario. Entrambe le coppie di chiavi devono trovarsi sulla stessa curva.
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Optional: 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()),
]);
// Create keyring input
let raw_ecdh_static_configuration_input =
RawPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 PEM-encoded private key
.sender_static_private_key(private_key_sender_utf8_bytes)
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let raw_ecdh_static_configuration = RawEcdhStaticConfigurations::RawPrivateKeyToStaticPublicKey(raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH static keyring
let raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(raw_ecdh_static_configuration)
.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"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// Optional: Create your 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",
}
// Create keyring input
rawEcdhStaticConfigurationInput := mpltypes.RawPrivateKeyToStaticPublicKeyInput{
SenderStaticPrivateKey: privateKeySender,
RecipientPublicKey: publicKeyRecipient,
}
rawECDHStaticConfiguration := &mpltypes.RawEcdhStaticConfigurationsMemberRawPrivateKeyToStaticPublicKey{
Value: rawEcdhStaticConfigurationInput,
}
rawEcdhKeyRingInput := mpltypes.CreateRawEcdhKeyringInput{
CurveSpec: ecdhCurveSpec,
KeyAgreementScheme: rawECDHStaticConfiguration,
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create raw ECDH static keyring
rawEcdhKeyring, err := matProv.CreateRawEcdhKeyring(context.Background(), rawEcdhKeyRingInput)
if err != nil {
panic(err)
}
```
------
### EphemeralPrivateKeyToStaticPublicKey
I portachiavi configurati con lo schema `EphemeralPrivateKeyToStaticPublicKey` key agreement creano una nuova coppia di chiavi localmente e derivano una chiave di wrapping condivisa unica per ogni chiamata crittografata.
Questo schema di accordo chiave può solo crittografare i messaggi. Per decrittografare i messaggi crittografati con lo schema del contratto di `EphemeralPrivateKeyToStaticPublicKey` chiave, è necessario utilizzare uno schema di accordo con la chiave di rilevamento configurato con la chiave pubblica dello stesso destinatario. Per decrittografare, è possibile utilizzare un portachiavi ECDH non elaborato con l'algoritmo di accordo [`PublicKeyDiscovery`](#raw-ecdh-PublicKeyDiscovery)chiave oppure, se la chiave pubblica del destinatario proviene da una coppia di chiavi KMS con accordo di chiave asimmetrico, è possibile AWS KMS utilizzare un portachiavi ECDH con lo schema di accordo chiave. [KmsPublicKeyDiscovery](use-kms-ecdh-keyring.md#kms-ecdh-discovery)
Per inizializzare un portachiavi ECDH non elaborato con lo schema di accordo chiave, fornisci i seguenti valori: `EphemeralPrivateKeyToStaticPublicKey`
+ **Chiave pubblica del destinatario**
[È necessario fornire la chiave pubblica X.509 con codifica DER del destinatario, nota anche come `SubjectPublicKeyInfo` (SPKI), come definita in RFC 5280.](https://tools.ietf.org/html/rfc5280)
È possibile specificare la chiave pubblica di una coppia di chiavi KMS con accordo di chiave asimmetrico o la chiave pubblica da una coppia di chiavi generata all'esterno di. AWS
+ **Specificazione della curva**
Identifica la specifica della curva ellittica nella chiave pubblica specificata.
In encrypt, il portachiavi crea una nuova coppia di chiavi sulla curva specificata e utilizza la nuova chiave privata e la chiave pubblica specificata per derivare una chiave di wrapping condivisa.
Valori validi: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
L'esempio seguente crea un portachiavi ECDH non elaborato con lo schema di accordo delle chiavi. `EphemeralPrivateKeyToStaticPublicKey` Su encrypt, il portachiavi creerà una nuova coppia di chiavi localmente sulla curva specificata`ECC_NIST_P256`.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePublicKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH ephemeral keyring
var ephemeralConfiguration = new RawEcdhStaticConfigurations()
{
EphemeralPrivateKeyToStaticPublicKey = new EphemeralPrivateKeyToStaticPublicKeyInput
{
RecipientPublicKey = AlicePublicKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = ephemeralConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `EphemeralPrivateKeyToStaticPublicKey` Su encrypt, il portachiavi creerà una nuova coppia di chiavi localmente sulla curva specificata`ECC_NIST_P256`.
```
private static void EphemeralRawEcdhKeyring() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
ByteBuffer recipientPublicKey = getPublicKeyBytes();
// Create the Raw ECDH ephemeral keyring
final CreateRawEcdhKeyringInput ephemeralInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.EphemeralPrivateKeyToStaticPublicKey(
EphemeralPrivateKeyToStaticPublicKeyInput.builder()
.recipientPublicKey(recipientPublicKey)
.build()
)
.build()
).build();
final IKeyring ephemeralKeyring = materialProviders.CreateRawEcdhKeyring(ephemeralInput);
}
```
------
#### [ Python ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `RawEcdhStaticConfigurationsEphemeralPrivateKeyToStaticPublicKey` Su encrypt, il portachiavi creerà una nuova coppia di chiavi localmente sulla curva specificata`ECC_NIST_P256`.
```
import boto3
from aws_cryptographic_materialproviders.mpl.models import (
CreateRawEcdhKeyringInput,
RawEcdhStaticConfigurationsEphemeralPrivateKeyToStaticPublicKey,
EphemeralPrivateKeyToStaticPublicKeyInput,
)
from aws_cryptography_primitives.smithygenerated.aws_cryptography_primitives.models import ECDHCurveSpec
# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Your get_public_key_bytes must return a DER-encoded X.509 public key
recipient_public_key = get_public_key_bytes()
# Create the raw ECDH ephemeral private key keyring
ephemeral_input = CreateRawEcdhKeyringInput(
curve_spec = ECDHCurveSpec.ECC_NIST_P256,
key_agreement_scheme = RawEcdhStaticConfigurationsEphemeralPrivateKeyToStaticPublicKey(
EphemeralPrivateKeyToStaticPublicKeyInput(
recipient_public_key = recipient_public_key,
)
)
)
keyring = mat_prov.create_raw_ecdh_keyring(ephemeral_input)
```
------
#### [ Rust ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `ephemeral_raw_ecdh_static_configuration` Su encrypt, il portachiavi creerà una nuova coppia di chiavi localmente sulla curva specificata.
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Optional: 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()),
]);
// Load public key from UTF-8 encoded PEM files into a DER encoded public key.
let public_key_file_content = std::fs::read_to_string(Path::new(EXAMPLE_ECC_PUBLIC_KEY_FILENAME_RECIPIENT))?;
let parsed_public_key_file_content = parse(public_key_file_content)?;
let public_key_recipient_utf8_bytes = parsed_public_key_file_content.contents();
// Create EphemeralPrivateKeyToStaticPublicKeyInput
let ephemeral_raw_ecdh_static_configuration_input =
EphemeralPrivateKeyToStaticPublicKeyInput::builder()
// Must be a UTF8 DER-encoded X.509 public key
.recipient_public_key(public_key_recipient_utf8_bytes)
.build()?;
let ephemeral_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::EphemeralPrivateKeyToStaticPublicKey(ephemeral_raw_ecdh_static_configuration_input);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create raw ECDH ephemeral private key keyring
let ephemeral_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(ephemeral_raw_ecdh_static_configuration)
.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"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// Optional: Create your 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",
}
// Load public key from UTF-8 encoded PEM files into a DER encoded public key
publicKeyRecipient, err := LoadPublicKeyFromPEM(eccPublicKeyFileNameRecipient)
if err != nil {
panic(err)
}
// Create EphemeralPrivateKeyToStaticPublicKeyInput
ephemeralRawEcdhStaticConfigurationInput := mpltypes.EphemeralPrivateKeyToStaticPublicKeyInput{
RecipientPublicKey: publicKeyRecipient,
}
ephemeralRawECDHStaticConfiguration :=
mpltypes.RawEcdhStaticConfigurationsMemberEphemeralPrivateKeyToStaticPublicKey{
Value: ephemeralRawEcdhStaticConfigurationInput,
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create raw ECDH ephemeral private key keyring
rawEcdhKeyRingInput := mpltypes.CreateRawEcdhKeyringInput{
CurveSpec: ecdhCurveSpec,
KeyAgreementScheme: &ephemeralRawECDHStaticConfiguration,
}
ecdhKeyring, err := matProv.CreateRawEcdhKeyring(context.Background(), rawEcdhKeyRingInput)
if err != nil {
panic(err)
}
```
------
### PublicKeyDiscovery
Durante la decrittografia, è consigliabile specificare le chiavi di avvolgimento che possono utilizzare. AWS Encryption SDK Per seguire questa best practice, utilizzate un portachiavi ECDH che specifichi sia la chiave privata del mittente che la chiave pubblica del destinatario. Tuttavia, puoi anche creare un portachiavi Raw ECDH Discovery, ovvero un portachiavi ECDH non elaborato in grado di decrittografare qualsiasi messaggio in cui la chiave pubblica della chiave specificata corrisponda alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio. Questo schema di accordi chiave può solo decrittografare i messaggi.
**Importante**
Quando si decifrano i messaggi utilizzando lo schema del contratto di `PublicKeyDiscovery` chiave, si accettano tutte le chiavi pubbliche, indipendentemente dal proprietario.
Per inizializzare un portachiavi Raw ECDH con lo schema di accordo `PublicKeyDiscovery` chiave, fornite i seguenti valori:
+ **Chiave privata statica del destinatario**
[È necessario fornire la chiave privata con codifica PEM del destinatario ( PrivateKeyInfo strutture PKCS \$18), come definita in RFC 5958.](https://tools.ietf.org/html/rfc5958#section-2)
+ **Specificazione della curva**
Identifica la specifica della curva ellittica nella chiave privata specificata. Entrambe le coppie di chiavi del mittente e del destinatario devono avere la stessa specifica di curva.
Valori validi: `ECC_NIST_P256`, `ECC_NIS_P384`, `ECC_NIST_P512`
------
#### [ C\$1 / .NET ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `PublicKeyDiscovery` Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della chiave privata specificata corrisponda alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
// Instantiate material providers
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
var AlicePrivateKey = new MemoryStream(new byte[] { });
// Create the Raw ECDH discovery keyring
var discoveryConfiguration = new RawEcdhStaticConfigurations()
{
PublicKeyDiscovery = new PublicKeyDiscoveryInput
{
RecipientStaticPrivateKey = AlicePrivateKey
}
};
var createKeyringInput = new CreateRawEcdhKeyringInput()
{
CurveSpec = ECDHCurveSpec.ECC_NIST_P256,
KeyAgreementScheme = discoveryConfiguration
};
var keyring = materialProviders.CreateRawEcdhKeyring(createKeyringInput);
```
------
#### [ Java ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `PublicKeyDiscovery` Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della chiave privata specificata corrisponda alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
private static void RawEcdhDiscovery() {
// Instantiate material providers
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
KeyPair recipient = GetRawEccKey();
// Create the Raw ECDH discovery keyring
final CreateRawEcdhKeyringInput rawKeyringInput =
CreateRawEcdhKeyringInput.builder()
.curveSpec(ECDHCurveSpec.ECC_NIST_P256)
.KeyAgreementScheme(
RawEcdhStaticConfigurations.builder()
.PublicKeyDiscovery(
PublicKeyDiscoveryInput.builder()
// Must be a PEM-encoded private key
.recipientStaticPrivateKey(ByteBuffer.wrap(sender.getPrivate().getEncoded()))
.build()
)
.build()
).build();
final IKeyring publicKeyDiscovery = materialProviders.CreateRawEcdhKeyring(rawKeyringInput);
}
```
------
#### [ Python ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `RawEcdhStaticConfigurationsPublicKeyDiscovery` Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della chiave privata specificata corrisponda alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
import boto3
from aws_cryptographic_materialproviders.mpl.models import (
CreateRawEcdhKeyringInput,
RawEcdhStaticConfigurationsPublicKeyDiscovery,
PublicKeyDiscoveryInput,
)
from aws_cryptography_primitives.smithygenerated.aws_cryptography_primitives.models import ECDHCurveSpec
# Instantiate the material providers library
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
# Your get_private_key_bytes must return a PEM-encoded private key
recipient_private_key = get_private_key_bytes()
# Create the raw ECDH discovery keyring
raw_keyring_input = CreateRawEcdhKeyringInput(
curve_spec = ECDHCurveSpec.ECC_NIST_P256,
key_agreement_scheme = RawEcdhStaticConfigurationsPublicKeyDiscovery(
PublicKeyDiscoveryInput(
recipient_static_private_key = recipient_private_key,
)
)
)
keyring = mat_prov.create_raw_ecdh_keyring(raw_keyring_input)
```
------
#### [ Rust ]
L'esempio seguente crea un portachiavi Raw ECDH con lo schema di accordo chiave. `discovery_raw_ecdh_static_configuration` Questo portachiavi può decrittografare qualsiasi messaggio in cui la chiave pubblica della chiave privata specificata corrisponda alla chiave pubblica del destinatario memorizzata nel testo cifrato del messaggio.
```
// Instantiate the AWS Encryption SDK client and material providers library
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Optional: 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()),
]);
// Load keys from UTF-8 encoded PEM files.
let mut file = File::open(Path::new(EXAMPLE_ECC_PRIVATE_KEY_FILENAME_RECIPIENT))?;
let mut private_key_recipient_utf8_bytes = Vec::new();
file.read_to_end(&mut private_key_recipient_utf8_bytes)?;
// Create PublicKeyDiscoveryInput
let discovery_raw_ecdh_static_configuration_input =
PublicKeyDiscoveryInput::builder()
// Must be a UTF8 PEM-encoded private key
.recipient_static_private_key(private_key_recipient_utf8_bytes)
.build()?;
let discovery_raw_ecdh_static_configuration =
RawEcdhStaticConfigurations::PublicKeyDiscovery(discovery_raw_ecdh_static_configuration_input);
// Create raw ECDH discovery private key keyring
let discovery_raw_ecdh_keyring = mpl
.create_raw_ecdh_keyring()
.curve_spec(ecdh_curve_spec)
.key_agreement_scheme(discovery_raw_ecdh_static_configuration)
.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"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
panic(err)
}
// Optional: Create your 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",
}
// Load keys from UTF-8 encoded PEM files.
privateKeyRecipient, err := os.ReadFile(eccPrivateKeyFileNameRecipient)
if err != nil {
panic(err)
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create PublicKeyDiscoveryInput
discoveryRawEcdhStaticConfigurationInput := mpltypes.PublicKeyDiscoveryInput{
RecipientStaticPrivateKey: privateKeyRecipient,
}
discoveryRawEcdhStaticConfiguration := &mpltypes.RawEcdhStaticConfigurationsMemberPublicKeyDiscovery{
Value: discoveryRawEcdhStaticConfigurationInput,
}
// Create raw ECDH discovery private key keyring
discoveryRawEcdhKeyringInput := mpltypes.CreateRawEcdhKeyringInput{
CurveSpec: ecdhCurveSpec,
KeyAgreementScheme: discoveryRawEcdhStaticConfiguration,
}
discoveryRawEcdhKeyring, err := matProv.CreateRawEcdhKeyring(context.Background(), discoveryRawEcdhKeyringInput)
if err != nil {
panic(err)
}
```
------
# Keyring multipli
È possibile combinare più keyring in un keyring multiplo. Un *keyring multiplo* è composto da uno o più keyring dello stesso tipo o di tipi diversi. Il risultato è analogo a quello ottenuto utilizzando diversi keyring in serie. Quando utilizzi un keyring multiplo per crittografare i dati, questi possono essere decrittati con le chiavi di wrapping contenute in qualsiasi keyring.
Quando crei un keyring multiplo per crittografare i dati, uno dei keyring viene designato come *keyring generatore*, tutti gli altri keyring sono i *keyring figlio*. che si occupa di generare e crittografare la chiave di dati di testo normale. Quindi, tutte le chiavi di wrapping in tutti i keyring figlio crittografano la stessa chiave di dati di testo normale. Il keyring multiplo restituisce la chiave di dati di testo normale e una chiave di dati crittografata per ciascuna chiave di wrapping nel keyring multiplo. Se il portachiavi del generatore è un [portachiavi KMS](use-kms-keyring.md), la chiave del generatore nel AWS KMS portachiavi genera e crittografa la chiave in chiaro. Quindi, tutte le chiavi aggiuntive AWS KMS keys presenti nel portachiavi e tutte le AWS KMS chiavi inserite in tutti i portachiavi secondari del portachiavi multiplo crittografano la stessa chiave in chiaro.
Se create un portachiavi multiplo senza un generatore di chiavi, potete utilizzarlo da solo per decrittografare i dati, ma non per cifrarli. Oppure, per utilizzare un portachiavi multiplo senza un generatore nelle operazioni di crittografia, potete specificarlo come portachiavi secondario in un altro portachiavi multiplo. Un portachiavi multiplo senza portachiavi non può essere designato come portachiavi generatore in un altro portachiavi multiplo.
Durante la decrittografia, AWS Encryption SDK utilizza i portachiavi per cercare di decrittografare una delle chiavi di dati crittografate. I keyring sono chiamati nell'ordine in cui sono specificati nel keyring multiplo. L'elaborazione si interrompe non appena una chiave in qualsiasi keyring può decrittare una chiave di dati crittografata.
[A partire dalla versione 1.7. ](about-versions.md#version-1.7)*x*, quando una chiave dati crittografata viene crittografata con un portachiavi AWS Key Management Service (AWS KMS) (o provider di chiavi master), passa AWS Encryption SDK sempre l'ARN della chiave al parametro AWS KMS key `KeyId` AWS KMS [dell'](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)operazione Decrypt. Si tratta di una procedura AWS KMS consigliata che garantisce la decrittografia della chiave dati crittografata con la chiave di wrapping che si intende utilizzare.
Per un esempio di utilizzo di un keyring multiplo consulta:
+ C: [multi\$1keyring.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/multi_keyring.cpp)[]()
+ [C\$1 /.NET: .cs MultiKeyringExample](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/MultiKeyringExample.cs)
+ JavaScript [Node.js: multi\$1keyring.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/multi_keyring.ts)
+ JavaScript Browser: [multi\$1keyring.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/multi_keyring.ts)
+ [MultiKeyringExampleGiava: .java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/keyrings/MultiKeyringExample.java)
+ [Python: multi\$1keyring\$1example.py](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/multi_keyring_example.py)
Per creare un keyring multiplo, crea prima un'istanza dei keyring figlio. In questo esempio, utilizziamo un AWS KMS portachiavi e un portachiavi Raw AES, ma puoi combinare tutti i portachiavi supportati in un portachiavi multiplo.
------
#### [ C ]
```
/* Define an AWS KMS keyring. For details, see [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp) */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(example_key);
// Define a Raw AES keyring. For details, see [raw\$1aes\$1keyring.c](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/raw_aes_keyring.c) */
struct aws_cryptosdk_keyring *aes_keyring = aws_cryptosdk_raw_aes_keyring_new(
alloc, wrapping_key_namespace, wrapping_key_name, wrapping_key, AWS_CRYPTOSDK_AES256);
```
------
#### [ C\$1 / .NET ]
```
// Define an AWS KMS keyring. For details, see [AwsKmsKeyringExample.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/AwsKmsKeyringExample.cs).
var kmsKeyring = materialProviders.CreateAwsKmsKeyring(createKmsKeyringInput);
// Define a Raw AES keyring. For details, see [RawAESKeyringExample.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/Keyring/RawAESKeyringExample.cs).
var aesKeyring = materialProviders.CreateRawAesKeyring(createAesKeyringInput);
```
------
#### [ JavaScript Browser ]
[L'esempio seguente utilizza la `buildClient` funzione per specificare la politica di impegno predefinita,.](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
KMS,
getClient,
RawAesKeyringWebCrypto,
RawAesWrappingSuiteIdentifier,
MultiKeyringWebCrypto,
buildClient,
CommitmentPolicy,
synchronousRandomValues,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
const clientProvider = getClient(KMS, { credentials })
// Define an AWS KMS keyring. For details, see [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts).
const kmsKeyring = new KmsKeyringBrowser({ generatorKeyId: exampleKey })
// Define a Raw AES keyring. For details, see [aes\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/aes_simple.ts).
const aesKeyring = new RawAesKeyringWebCrypto({ keyName, keyNamespace, wrappingSuite, masterKey })
```
------
#### [ JavaScript Node.js ]
L'esempio seguente utilizza la `buildClient` funzione per specificare la [politica di impegno predefinita](migrate-commitment-policy.md),`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. È inoltre possibile utilizzare il `buildClient` per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta [Limitazione delle chiavi di dati crittografate](configure.md#config-limit-keys).
```
import {
MultiKeyringNode,
KmsKeyringNode,
RawAesKeyringNode,
RawAesWrappingSuiteIdentifier,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
// Define an AWS KMS keyring. For details, see [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts).
const kmsKeyring = new KmsKeyringNode({ generatorKeyId: exampleKey })
// Define a Raw AES keyring. For details, see [raw\$1aes\$1keyring\$1node.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/raw-aes-keyring-node/src/raw_aes_keyring_node.ts).
const aesKeyring = new RawAesKeyringNode({ keyName, keyNamespace, wrappingSuite, unencryptedMasterKey })
```
------
#### [ Java ]
```
// Define the raw AES keyring.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput createRawAesKeyringInput = CreateRawAesKeyringInput.builder()
.keyName("AES_256_012")
.keyNamespace("HSM_01")
.wrappingKey(AESWrappingKey)
.wrappingAlg(AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16)
.build();
IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(createRawAesKeyringInput);
// Define the AWS KMS keyring.
final CreateAwsKmsMrkMultiKeyringInput createAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
.generator(kmsKeyArn)
.build();
IKeyring awsKmsMrkMultiKeyring = matProv.CreateAwsKmsMrkMultiKeyring(createAwsKmsMrkMultiKeyringInput);
```
------
#### [ Python ]
L'esempio seguente crea un'istanza del AWS Encryption SDK client con la [politica di impegno predefinita](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`
```
# Create the AWS KMS keyring
kms_client = boto3.client('kms', region_name="us-west-2")
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
kms_keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
generator=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab,
kms_client=kms_client
)
kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
input=kms_keyring_input
)
# Create Raw AES keyring
key_name_space = "HSM_01"
key_name = "AES_256_012"
raw_aes_keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=AESWrappingKey,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=raw_aes_keyring_input
)
```
------
#### [ Rust ]
```
// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create the 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);
// 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?;
// Create a Raw AES keyring
let key_namespace: &str = "my-key-namespace";
let key_name: &str = "my-aes-key-name";
let raw_aes_keyring = mpl
.create_raw_aes_keyring()
.key_name(key_name)
.key_namespace(key_namespace)
.wrapping_key(aws_smithy_types::Blob::new(AESWrappingKey))
.wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
.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
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
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
})
// 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)
}
// Create a Raw AES keyring
var keyNamespace = "my-key-namespace"
var keyName = "my-aes-key-name"
aesKeyRingInput := mpltypes.CreateRawAesKeyringInput{
KeyName: keyName,
KeyNamespace: keyNamespace,
WrappingKey: AESWrappingKey,
WrappingAlg: mpltypes.AesWrappingAlgAlgAes256GcmIv12Tag16,
}
aesKeyring, err := matProv.CreateRawAesKeyring(context.Background(), aesKeyRingInput)
```
------
Crea quindi il keyring multiplo e specifica il keyring generatore, se presente. In questo esempio, creiamo un portachiavi multiplo in cui il portachiavi è il AWS KMS portachiavi del generatore e il portachiavi AES è il portachiavi per bambini.
------
#### [ C ]
Nel costruttore del keyring multiplo in C, specifica solo il keyring generatore.
```
struct aws_cryptosdk_keyring *multi_keyring = aws_cryptosdk_multi_keyring_new(alloc, kms_keyring);
```
Per aggiungere un keyring figlio al tuo keyring multiplo, usa il metodo `aws_cryptosdk_multi_keyring_add_child`. Devi chiamare il metodo una volta per ogni keyring figlio che aggiungi.
```
// Add the Raw AES keyring (C only)
aws_cryptosdk_multi_keyring_add_child(multi_keyring, aes_keyring);
```
------
#### [ C\$1 / .NET ]
Il `CreateMultiKeyringInput` costruttore.NET consente di definire un portachiavi del generatore e dei portachiavi secondari. L'`CreateMultiKeyringInput`oggetto risultante è immutabile.
```
var createMultiKeyringInput = new CreateMultiKeyringInput
{
Generator = kmsKeyring,
ChildKeyrings = new List() {aesKeyring}
};
var multiKeyring = materialProviders.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ JavaScript Browser ]
JavaScript i portachiavi multipli sono immutabili. Il JavaScript costruttore multi-portachiavi consente di specificare il portachiavi del generatore e più portachiavi per bambini.
```
const clientProvider = getClient(KMS, { credentials })
const multiKeyring = new MultiKeyringWebCrypto(generator: kmsKeyring, children: [aesKeyring]);
```
------
#### [ JavaScript Node.js ]
JavaScript i portachiavi multipli sono immutabili. Il JavaScript costruttore multi-portachiavi consente di specificare il portachiavi del generatore e più portachiavi per bambini.
```
const multiKeyring = new MultiKeyringNode(generator: kmsKeyring, children: [aesKeyring]);
```
------
#### [ Java ]
Il `CreateMultiKeyringInput` costruttore Java consente di definire un portachiavi del generatore e dei portachiavi secondari. L'`createMultiKeyringInput`oggetto risultante è immutabile.
```
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(awsKmsMrkMultiKeyring)
.childKeyrings(Collections.singletonList(rawAesKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
```
------
#### [ Python ]
```
multi_keyring_input: CreateMultiKeyringInput = CreateMultiKeyringInput(
generator=kms_keyring,
child_keyrings=[raw_aes_keyring]
)
multi_keyring: IKeyring = mat_prov.create_multi_keyring(
input=multi_keyring_input
)
```
------
#### [ Rust ]
```
let multi_keyring = mpl
.create_multi_keyring()
.generator(kms_keyring.clone())
.child_keyrings(vec![raw_aes_keyring.clone()])
.send()
.await?;
```
------
#### [ Go ]
```
createMultiKeyringInput := mpltypes.CreateMultiKeyringInput{
Generator: awsKmsKeyring,
ChildKeyrings: []mpltypes.IKeyring{rawAESKeyring},
}
multiKeyring, err := matProv.CreateMultiKeyring(context.Background(), createMultiKeyringInput)
if err != nil {
panic(err)
}
```
------
Ora puoi utilizzare il keyring multiplo per crittografare e decrittare i dati.