Utilizzo di SDK di crittografia AWS per C

Questo argomento illustra alcune delle caratteristiche del SDK di crittografia AWS per C che non sono supportate in altre implementazioni del linguaggio di programmazione.

Gli esempi in questa sezione mostrano come utilizzareversione 2.0.xe successivamente delSDK di crittografia AWS per C. Per esempi che utilizzano versioni precedenti, trova la versione nella sezioneVersioni dielenco direpository aws-encryption-sdk-crepository di in GitHub.

Per informazioni dettagliate sulla programmazione con SDK di crittografia AWS per C, vedere gli esempi C, gli esempi in aws-encryption-sdk-c repository su GitHub e la documentazione dell'API SDK di crittografia AWS per C.

Consulta anche: Utilizzo dei keyring

Modelli per la crittografia e la decrittazione dei dati

Quando utilizzi il SDK di crittografia AWS per C, segui un modello simile al seguente: crei un keyring, un CMM che utilizza il keyring, una sessione che utilizza il CMM (e il keyring) e infine elabori la sessione.

1. Carica stringhe di errore.

Chiama ilaws_cryptosdk_load_error_strings()metodo nel codice C o C++. Carica informazioni di errore molto utili per il debug.

Devi chiamarlo solo una volta, come nel tuomainmetodo.

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

2. Crea un keyring.

Configura il keyring con le chiavi di wrapping da utilizzare per crittografare le chiavi di dati. Questo esempio utilizza unAWS KMSKeyringcon unaAWS KMS keyma puoi scegliere qualsiasi tipo di keyring al suo posto.

Per identificare unAWS KMS keyin un portachiavi di crittografia nelSDK di crittografia AWS per C, specificare unARN della chiaveoARN dell'alias. In un keyring di decrittografia devi utilizzare un ARN di chiave. Per dettagli, consultare Identificazione AWS KMS keys in un portachiavi AWS KMS.

const char * KEY_ARN = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"    
struct aws_cryptosdk_keyring *kms_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(KEY_ARN);

3. Crea una sessione.

Nel SDK di crittografia AWS per C, per crittografare un singolo messaggio di testo normale o decrittare un singolo messaggio di testo cifrato, indipendentemente dalle dimensioni, viene utilizzata una sessione. La sessione mantiene lo stato del messaggio durante tutta l'elaborazione.

Configura la sessione con un allocatore, un CMM e una modalità: AWS_CRYPTOSDK_ENCRYPT o AWS_CRYPTOSDK_DECRYPT. Per modificare la modalità della sessione, utilizza il metodo aws_cryptosdk_session_reset.

Quando crei una sessione con un keyring, ilSDK di crittografia AWS per CCrea automaticamente un gestore di materiali crittografici (CMM) predefinito. Non è necessario creare, mantenere o eliminare in modo permanente questo oggetto.

Ad esempio, la sessione seguente utilizza l'allocatore e il keyring definito nella fase 1. Quando esegui la crittografia dei dati, la modalità è AWS_CRYPTOSDK_ENCRYPT.

struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);

4. Esegui la crittografia o la decrittazione dei dati.

Per elaborare i dati della sessione, utilizza il metodo aws_cryptosdk_session_process. Se il buffer di input è abbastanza grande da contenere l'intero testo normale e il buffer di output è abbastanza grande da contenere l'intero testo cifrato, è possibile chiamareaws_cryptosdk_session_process_full. Tuttavia, se devi gestire i dati di streaming, puoi chiamareaws_cryptosdk_session_processin un loop. Per un esempio, consulta file_streaming.cpp. Laaws_cryptosdk_session_process_fullè introdotto inAWS Encryption SDKversioni 1.9.xe 2.2.x.

Quando la sessione è configurata per crittografare i dati, i campi di testo normale descrivono l'input, mentre quelli di testo cifrato l'output. Il campo plaintext contiene il messaggio da crittografare, mentre il campo ciphertext riceve il messaggio crittografato restituito dal metodo di crittografia.

/* Encrypting data */
aws_cryptosdk_session_process_full(session,
                                   ciphertext,
                                   ciphertext_buffer_size,
                                   &ciphertext_length,
                                   plaintext,
                                   plaintext_length)
                              

Quando la sessione è configurata per decrittare i dati, i campi di testo cifrato descrivono l'input, mentre quelli di testo normale l'output. Il campo ciphertext contiene il messaggio crittografato restituito dal metodo di crittografia, mentre il campo plaintext riceve il messaggio di testo normale restituito dal metodo di decrittazione.

Per decrittare i dati, chiama il metodo aws_cryptosdk_session_process_full.

/* Decrypting data */
aws_cryptosdk_session_process_full(session,
                                   plaintext,
                                   plaintext_buffer_size,
                                   &plaintext_length,
                                   ciphertext,
                                   ciphertext_length)
                                   

Conteggio dei riferimenti

Per evitare perdite di memoria, assicurati di rilasciare i riferimenti a tutti gli oggetti che crei quando finisci di utilizzarli. In caso contrario, potrebbero verificarsi perdite di memoria. L'SDK offre dei metodi per semplificare questa operazione.

Ogni volta che crei un oggetto padre con uno dei seguenti oggetti figlio, l'oggetto padre ottiene e mantiene un riferimento all'oggetto figlio, come indicato di seguito:

• Un keyring, ad esempio la creazione di una sessione con un keyring

• Un predefinitoresponsabile dei materiali crittografici(CMM), ad esempio la creazione di una sessione o di un CMM personalizzato con un CMM predefinito

• Una cache della chiave di dati, ad esempio un CMM di caching con un keyring e una cache

A meno che non sia necessario un riferimento indipendente all'oggetto figlio, puoi rilasciare il riferimento all'oggetto figlio non appena crei l'oggetto padre. Il rimanente riferimento all'oggetto figlio viene rilasciato quando l'oggetto padre viene eliminato in modo permanente. Questo modello consente di mantenere il riferimento a ogni oggetto solo per il tempo necessario ed evita le perdite di memoria causate da riferimenti non rilasciati.

Sarai responsabile solo del rilascio dei riferimenti agli oggetti figlio creati in modo esplicito. Non sei responsabile della gestione dei riferimenti a qualsiasi oggetto creato dall'SDK. Se l'SDK crea un oggetto, ad esempio il CMM predefinito che ilaws_cryptosdk_caching_cmm_new_from_keyringIl metodo aggiunge a una sessione, l'SDK gestisce la creazione e la distruzione dell'oggetto e dei relativi riferimenti.

Nell'esempio seguente, quando crei una sessione con un keyring, la sessione ottiene un riferimento al keyring e mantiene tale riferimento fino a quando la sessione non viene eliminata in modo permanente. Se non è necessario mantenere un riferimento aggiuntivo al keyring, puoi utilizzare il metodo aws_cryptosdk_keyring_release per rilasciare l'oggetto keyring non appena viene creata la sessione. Questo metodo riduce il conteggio dei riferimenti per il keyring. Il riferimento della sessione al keyring viene rilasciato quando chiami aws_cryptosdk_session_destroy per eliminare in modo permanente la sessione.

// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =	
	aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);

// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);

Per attività più complesse, ad esempio riutilizzare un keyring per più sessioni o specificare una suite di algoritmi in un CMM, potrebbe essere necessario mantenere un riferimento indipendente all'oggetto. In tal caso, non chiamare immediatamente i metodi di rilascio. Al contrario, rilascia i riferimenti quando non utilizzi più gli oggetti, oltre ad eliminare in modo permanente la sessione.

Questa tecnica di conteggio dei riferimenti funziona anche quando si utilizzano CMM alternativi, ad esempio il di caching CMM percaching della chiave dei dati. Quando crei un CMM di caching da una cache e da un keyring, il CMM di caching ottiene un riferimento a entrambi gli oggetti. A meno che non siano necessari per un'altra attività, è possibile rilasciare i riferimenti indipendenti alla cache e al keyring non appena viene creato il CMM di caching. Quindi, quando crei una sessione con il CMM di caching, puoi rilasciare il riferimento al CMM di caching.

Sei responsabile solo del rilascio dei riferimenti agli oggetti creati in modo esplicito. Gli oggetti creati dai metodi creati per l'utente, ad esempio il CMM predefinito alla base del di caching CMM, vengono gestiti dal metodo.

/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);

// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);

// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);

// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);

// ...

aws_cryptosdk_session_destroy(session);