SDK di crittografia AWS per C Esempi di

Gli esempi seguenti illustrano come utilizzare SDK di crittografia AWS per C per crittografare e decrittare i dati.

Gli esempi in questa sezione mostrano come utilizzare le versioni 2.0.xe più tardi delSDK di crittografia AWS per C. Per esempi che utilizzano versioni precedenti, trova la tua versione nellaVersioni dielenco deiaws-encryption-sdk-c repositoryrepositoryGitHub.

Quando installi e crei l'SDK di crittografia AWS per C, il codice sorgente per questi e altri esempi è incluso nella sottodirectory examples e sono compilati e integrati nella directory build. È possibile anche trovarle nelesempisottodirectory delaws-encryption-sdk-crepositoryGitHub.

Crittografia e decrittazione di stringhe

L'esempio seguente illustra come utilizzare SDK di crittografia AWS per C per crittografare e decrittare una stringa.

Questo esempio presenta ilAWS KMSKeyring, un tipo di portachiavi che utilizza unAWS KMS keynelAWS Key Management Service(AWS KMS)per generare e crittografare le chiavi dati. L'esempio include il codice scritto in C++. LaSDK di crittografia AWS per Crichiede ilAWS SDK for C++per chiamareAWS KMSquando si utilizzaAWS KMSkeyring. Se usi un portachiavi che non interagisce conAWS KMS, come un portachiavi AES grezzo, un portachiavi RSA grezzo o un portachiavi multiplo che non includeAWS KMSKeyring, ilAWS SDK for C++non è obbligatorio.

Per aiuto nella creazione di unAWS KMS key, consultaCreazione di chiavinellaAWS Key Management ServiceGuida per gli sviluppatori. Per aiuto nell'identificazione delAWS KMS keysin unAWS KMSkeyring, consultaIdentificazione AWS KMS keys in un portachiavi AWS KMS.

Vedi l'esempio di codice completo: string.cpp

Argomenti

• Crittografare una stringa
• Decrittare una stringa

Crittografare una stringa

La prima parte di questo esempio utilizza unaAWS KMSKeyring con unaAWS KMS keyper crittografare una stringa di testo normale.

Fase 1. Carica le stringhe di errore.

Chiama ilaws_cryptosdk_load_error_strings()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();

Fase 2: Costruisci il keyring.

Creazione di unAWS KMSkeyring per crittografare. Il portachiavi in questo esempio è configurato con unoAWS KMS key, ma è possibile configurare unAWS KMSKeyring con piùAWS KMS keys, inclusoAWS KMS keysin diversiRegioni AWSe conti diversi.

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

Identificazione AWS KMS keys in un portachiavi AWS KMS

Quando crei un portachiavi con piùAWS KMS keys, si specifica ilAWS KMS keyutilizzato per generare e crittografare la chiave di dati di testo normale e una serie opzionale diAWS KMS keysche eseguono la crittografia della stessa chiave. In questo caso, è necessario specificare solo il generatoreAWS KMS key.

Prima di eseguire questo codice, sostituisci l'ARN della chiave di esempio con uno valido.

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);

Fase 3: Crea una sessione.

Crea una sessione utilizzando l'allocatore, un enumeratore di modalità e il keyring.

Ogni sessione richiede una modalità: AWS_CRYPTOSDK_ENCRYPT per la crittografia e AWS_CRYPTOSDK_DECRYPT per la decrittazione. Per modificare la modalità di una sessione esistente, utilizza il metodo aws_cryptosdk_session_reset.

Dopo aver creato una sessione con il keyring, puoi rilasciare il riferimento al keyring con il metodo fornito dall'SDK. La sessione mantiene un riferimento all'oggetto keyring durante la sua durata. I riferimenti al keyring e agli oggetti sessione vengono rilasciati quando si distrugge la sessione. Questa tecnica di conteggio dei riferimenti aiuta a prevenire perdite di memoria e a impedire che gli oggetti vengano rilasciati mentre sono in uso.

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

/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);

Fase 4: Imposta il contesto di crittografia.

Un contesto di crittografia è rappresentato da tipi di dati autenticati aggiuntivi arbitrari e non segreti. Quando fornisci un contesto durante la crittografia, l'AWS Encryption SDK lo vincola al testo cifrato a livello crittografico, per cui dovrai utilizzare lo stesso contesto di crittografia per decrittare i dati. L'utilizzo di un contesto di crittografia è facoltativo, ma viene consigliato come best practice.

Crea innanzitutto una tabella hash che includa le stringhe del contesto di crittografia.

/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx) 

// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");

// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)

Ottieni un puntatore modificabile per il contesto di crittografia nella sessione. Quindi, utilizza la funzione aws_cryptosdk_enc_ctx_clone per copiare il contesto di crittografia nella sessione. Una copia viene salvata in my_enc_ctx per la convalida del valore dopo la decrittazione dei dati.

Il contesto di crittografia fa parte della sessione, non è un parametro assegnato alla funzione di elaborazione della sessione. Questo garantisce che lo stesso contesto di crittografia venga utilizzato per ogni segmento di un messaggio, anche se la funzione di elaborazione della sessione viene chiamata più volte per crittografare l'intero messaggio.

struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);

aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)

Fase 5: Crittografia della stringa.

Per crittografare la stringa di testo normale, utilizza il metodo aws_cryptosdk_session_process_full con la sessione in modalità di crittografia. Questo metodo, introdotto inAWS Encryption SDKversioni 1.9.xe 2.2.x, è progettato per la crittografia e la decrittografia non in streaming. Per gestire i dati in streaming, chiamare ilaws_cryptosdk_session_processin un loop.

Durante la crittografia, i campi in testo normale sono destinati all'input, mentre quelli cifrati sono i campi di output. Al termine dell'elaborazione, il campo ciphertext_output contiene il messaggio crittografato, inclusi il testo cifrato effettivo, le chiavi di dati crittografate e il contesto di crittografia. Puoi decrittare questo messaggio crittografato utilizzando AWS Encryption SDK per qualsiasi linguaggio di programmazione supportato.

/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
                                  ciphertext_output,
                                  ciphertext_buf_sz_output,
                                  &ciphertext_len_output,
                                  plaintext_input,
                                  plaintext_len_input)) {
    aws_cryptosdk_session_destroy(session);
    return 8;
}

Fase 6: Pulire la sessione.

Il passaggio finale distrugge la sessione, includendo i riferimenti al CMM e al keyring.

Se preferisci, invece di distruggere la sessione, puoi riutilizzare la sessione con lo stesso keyring e CMM per decrittare la stringa o per crittografare o decrittare altri messaggi. Per utilizzare la sessione per la decrittazione, scegli il metodo aws_cryptosdk_session_reset per modificare la modalità in AWS_CRYPTOSDK_DECRYPT.

Decrittare una stringa

La seconda parte di questo esempio spiega come decrittare un messaggio crittografato che contiene il testo cifrato della stringa originale.

Fase 1: Carica le stringhe di errore.

Chiama ilaws_cryptosdk_load_error_strings()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();

Fase 2: Costruisci il keyring.

Quando esegui la decrittazione dei dati in AWS KMS, passi il messaggio crittografato restituito dall'API di crittografia. LaAPI di decrittografianon prendeAWS KMS keycome input. invece AWS KMS utilizza la stessa AWS KMS key per decrittare il testo cifrato utilizzato per crittografarlo. Tuttavia, ilAWS Encryption SDKconsente di specificare unAWS KMSKeyring conAWS KMS keysper crittografare e decrittare.

Durante la decrittazione, puoi configurare un keyring solo con le AWS KMS keys da utilizzare per decrittare il messaggio crittografato. Ad esempio, puoi creare un keyring solo con la AWS KMS key utilizzata da un determinato ruolo nella tua azienda. LaAWS Encryption SDKnon utilizzerà mai unAWS KMS keyA meno che non sia presente nel keyring di decrittografia. Se l'SDK non riesce a decrittare le chiavi di dati crittografate con le AWS KMS keys nel keyring fornito, perché nessuna AWS KMS keys nel keyring è stata utilizzata per crittografare le chiavi di dati o perché l'intermediario non ha le autorizzazioni per utilizzare le AWS KMS keys nel keyring per la decrittazione, la chiamata di decrittazione non riesce.

Quando si specifica unaAWS KMS keyper un keyring di decrittografia è necessario utilizzarneARN della chiave. ARN di aliassono consentiti solo nei keyring di crittografia. Per aiuto nell'identificazione delAWS KMS keysin unAWS KMSkeyring, consultaIdentificazione AWS KMS keys in un portachiavi AWS KMS.

In questo esempio è stato specificato un keyring configurato con la stessaAWS KMS keyutilizzato per crittografare la stringa. Prima di eseguire questo codice, sostituisci l'ARN della chiave di esempio con uno valido.

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);

Fase 3: Crea una sessione.

Crea una sessione utilizzando l'allocatore e il keyring. Per configurare la sessione per la decrittazione, configura la sessione con la modalità AWS_CRYPTOSDK_DECRYPT.

Dopo aver creato una sessione con un keyring, puoi rilasciare il riferimento al keyring con il metodo fornito dall'SDK. La sessione mantiene un riferimento all'oggetto keyring durante la sua durata e sia la sessione che il keyring vengono rilasciati quando si distrugge la sessione. Questa tecnica di conteggio dei riferimenti aiuta a prevenire perdite di memoria e a impedire che gli oggetti vengano rilasciati mentre sono in uso.

struct aws_cryptosdk_session *session =	
	aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);

/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);

Fase 4: Decrittografia della stringa.

Per decrittare la stringa, utilizza il metodo aws_cryptosdk_session_process_full con la sessione configurata per la decrittazione. Questo metodo, introdotto inAWS Encryption SDKversioni 1.9.xe 2.2.x, è progettato per la crittografia e la decrittografia non in streaming. Per gestire i dati in streaming, chiamare ilaws_cryptosdk_session_processin un loop.

Durante la decrittazione, i campi in testo cifrato sono destinati all'input, mentre quelli in testo normale sono i campi di output. Il campo ciphertext_input contiene il messaggio crittografato restituito dal metodo di crittografia. Al termine dell'elaborazione, il campo plaintext_output contiene la stringa di testo normale (decrittato).

size_t plaintext_len_output;

if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
                                  plaintext_output,
                                  plaintext_buf_sz_output,
                                  &plaintext_len_output,
                                  ciphertext_input,
                                  ciphertext_len_input)) {
    aws_cryptosdk_session_destroy(session);
    return 13;
}

Fase 5: Verifica il contesto di crittografia.

Assicurarsi che il contesto di crittografia effettivo, quello utilizzato per decrittare il messaggio, contenga il contesto di crittografia fornito durante la crittografia del messaggio. Il contesto di crittografia effettivo potrebbe includere coppie supplementari, perché il responsabile dei materiali crittografici (CMM) può aggiungere delle coppie a tale contesto prima della crittografia del messaggio.

In SDK di crittografia AWS per C, non è necessario fornire un contesto di crittografia durante la decrittazione perché è incluso nel messaggio crittografato restituito dall'SDK. Tuttavia, prima di restituire il messaggio di testo normale, la funzione di decrittazione deve verificare che tutte le coppie nel contesto di crittografia fornito siano anche presenti nel contesto di crittografia utilizzato per decrittare il messaggio.

Ottieni innanzitutto un puntatore di sola lettura per la tabella hash nella sessione. Questa tabella hash contiene il contesto di crittografia utilizzato per decrittare il messaggio.

const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);

Quindi, esamina il contesto di crittografia nella tabella hash my_enc_ctx copiata durante la crittografia. Verifica che ogni coppia nella tabella hash my_enc_ctx utilizzata per la crittografia sia presente nella tabella hash session_enc_ctx utilizzata per la decrittazione. Se una chiave è mancante o ha un valore differente, interrompi l'elaborazione e scrivi un messaggio di errore.

for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
      aws_hash_iter_next(&iter)) {
     struct aws_hash_element *session_enc_ctx_kv_pair;
     aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)

    if (!session_enc_ctx_kv_pair ||
        !aws_string_eq(
            (struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
        fprintf(stderr, "Wrong encryption context!\n");
        abort();
    }
}

Fase 6: Pulire la sessione.

Dopo aver verificato il contesto di crittografia, puoi eliminare la sessione o riutilizzarla. Se devi riconfigurare la sessione, utilizza laaws_cryptosdk_session_resetmetodo.

aws_cryptosdk_session_destroy(session);