Usando il SDK di crittografia AWS per C

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

Gli esempi in questa sezione mostrano come utilizzare la versione 2.0. x e versioni successive di SDK di crittografia AWS per C. Per esempi che utilizzano versioni precedenti, trova la tua versione nell'elenco Releases del aws-encryption-sdk-c repository del repository su. GitHub

Per i dettagli sulla programmazione con SDK di crittografia AWS per C, consulta gli esempi in C, gli esempi nel aws-encryption-sdk-c repository on GitHub e la documentazione dell'SDK di crittografia AWS per C API.

Consulta anche: Portachiavi

Modelli per la crittografia e la decrittazione dei dati

Quando si utilizza il SDK di crittografia AWS per C, si segue uno schema simile al seguente: si crea un portachiavi, si crea una CMM che utilizza il portachiavi, si crea una sessione che utilizza il CMM (e il portachiavi) e quindi si elabora la sessione.

1. Stringhe di errore di caricamento.

Chiama il aws_cryptosdk_load_error_strings() metodo nel tuo codice C o C++. Carica informazioni sugli errori che sono molto utili per il debug.

Devi chiamarlo solo una volta, ad esempio nel tuo metodo. main

/* 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. In questo esempio viene utilizzato un AWS KMS portachiavi con uno AWS KMS key, ma è possibile utilizzare qualsiasi tipo di portachiavi al suo posto.

Per identificare un elemento AWS KMS key in un portachiavi di crittografia in SDK di crittografia AWS per C, specificare una chiave ARN o un alias ARN. In un keyring di decrittografia devi utilizzare un ARN di chiave. Per informazioni dettagliate, 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.

In SDK di crittografia AWS per C, si utilizza una sessione per crittografare un singolo messaggio di testo in chiaro o decrittografare un singolo messaggio di testo cifrato, indipendentemente dalla sua dimensione. 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 portachiavi, crea SDK di crittografia AWS per C automaticamente un gestore di materiali crittografici (CMM) predefinito per te. 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 in chiaro e il buffer di output è abbastanza grande da contenere l'intero testo cifrato, puoi chiamare. aws_cryptosdk_session_process_full Tuttavia, se è necessario gestire lo streaming di dati, è possibile effettuare chiamate in loop. aws_cryptosdk_session_process Per un esempio, consulta file_streaming.cpp. aws_cryptosdk_session_process_fullÈ stato introdotto nelle AWS Encryption SDK versioni 1.9. x e 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 gestore di materiali crittografici (CMM) predefinito, ad esempio la creazione di una sessione o una CMM personalizzata con una CMM predefinita

• 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 la CMM predefinita che il aws_cryptosdk_caching_cmm_new_from_keyring 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, come riutilizzare un portachiavi per più sessioni o specificare una suite di algoritmi in una 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 alternative CMMs, come la cache CMM per la memorizzazione nella cache delle chiavi di dati. Quando si crea una CMM memorizzata nella cache da una cache e da un portachiavi, la CMM memorizzata nella cache ottiene un riferimento a entrambi gli oggetti. A meno che non ne abbiate bisogno per un'altra attività, potete rilasciare i riferimenti indipendenti alla cache e al portachiavi non appena viene creata la CMM che memorizza nella cache. Quindi, quando create una sessione con la CMM che memorizza nella cache, potete rilasciare il riferimento alla CMM che memorizza nella cache.

Sei responsabile solo del rilascio dei riferimenti agli oggetti creati in modo esplicito. Gli oggetti creati automaticamente dai metodi, come la CMM predefinita che sta alla base della CMM memorizzata nella cache, 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);