SDK di crittografia AWS per C esempi - AWS Encryption SDK
Crittografia e decrittazione di stringhe

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

SDK di crittografia AWS per C esempi

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

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

Quando installi e compili SDK di crittografia AWS per C, il codice sorgente di questi e altri esempi viene incluso nella examples sottodirectory, e vengono compilati e incorporati nella directory. build Puoi trovarli anche nella sottodirectory examples del aws-encryption-sdk-crepository su. GitHub

Crittografia e decrittazione di stringhe

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

Questo esempio presenta il AWS KMS portachiavi, un tipo di portachiavi che utilizza un AWS KMS key in AWS Key Management Service (AWS KMS) per generare e crittografare le chiavi di dati. L'esempio include codice scritto in C++. SDK di crittografia AWS per C Richiede la AWS SDK for C++ chiamata AWS KMS quando si usano i AWS KMS portachiavi. Se utilizzi un portachiavi che non interagisce con AWS KMS, ad esempio un portachiavi AES non elaborato, un portachiavi RSA non elaborato o un portachiavi multiplo che non include un AWS KMS portachiavi, non è necessario. AWS SDK for C++

Per informazioni sulla creazione di un AWS KMS key, consulta Creating Keys nella Developer Guide.AWS Key Management Service Per informazioni su come identificarle AWS KMS keys in un AWS KMS portachiavi, consultaIdentificazione AWS KMS keys in un portachiavi AWS KMS.

Vedi l'esempio di codice completo: string.cpp

Crittografare una stringa

La prima parte di questo esempio utilizza un AWS KMS portachiavi con uno AWS KMS key per crittografare una stringa di testo in chiaro.

Fase 1: Stringhe di errore di caricamento.

Chiama il aws_cryptosdk_load_error_strings() metodo nel 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();
Fase 2: Costruisci il portachiavi.

Crea un AWS KMS portachiavi per la crittografia. Il portachiavi in questo esempio è configurato con uno AWS KMS key, ma è possibile configurare un AWS KMS portachiavi con più portachiavi AWS KMS keys, anche AWS KMS keys in account diversi Regioni AWS e diversi.

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.

Identificazione AWS KMS keys in un portachiavi AWS KMS

Quando si crea un portachiavi con più chiavi AWS KMS keys, si specifica la chiave di dati in testo normale AWS KMS key utilizzata per generare e crittografare la stessa chiave di dati in testo semplice e una matrice opzionale aggiuntiva AWS KMS keys che crittografa la stessa chiave di dati in testo semplice. In questo caso, si specifica solo il generatore. AWS 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: creare 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: impostare il contesto di crittografia.

Un contesto di crittografia è rappresentato da tipi di dati autenticati aggiuntivi arbitrari e non segreti. Quando si fornisce un contesto di crittografia su encrypt, associa AWS Encryption SDK crittograficamente il contesto di crittografia al testo cifrato in modo che sia necessario lo stesso contesto di crittografia per decrittografare 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: crittografare la 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 nelle versioni 1.9. AWS Encryption SDK x e 2.2. x, è progettato per la crittografia e la decrittografia non in streaming. Per gestire i dati in streaming, chiamali aws_cryptosdk_session_process in 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. È possibile decrittografare questo messaggio crittografato utilizzando il 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;
}
Passaggio 6: pulire la sessione.

Il passaggio finale distrugge la sessione, inclusi i riferimenti alla CMM e al portachiavi.

Se preferisci, invece di distruggere la sessione, puoi riutilizzare la sessione con lo stesso portachiavi e la stessa CMM per decrittografare la stringa o per crittografare o decrittografare 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.

Passaggio 1: caricare le stringhe di errore.

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();
Fase 2: Costruisci il portachiavi.

Quando decifri i dati AWS KMS, trasmetti il messaggio crittografato restituito dall'API di crittografia. L'API Decrypt non accetta un input as. AWS KMS key AWS KMS Utilizza invece lo stesso AWS KMS key per decrittografare il testo cifrato che ha usato per crittografarlo. Tuttavia, AWS Encryption SDK consente di specificare un AWS KMS portachiavi con crittografia e decrittografia. AWS KMS keys

In fase di decrittografia, è possibile configurare un portachiavi solo con AWS KMS keys quello che si desidera utilizzare per decrittografare il messaggio crittografato. Ad esempio, potresti voler creare un portachiavi con solo AWS KMS key quello utilizzato da un particolare ruolo all'interno dell'organizzazione. Non ne AWS Encryption SDK useranno mai uno AWS KMS key a meno che non compaia nel portachiavi di decrittografia. Se l'SDK non è AWS KMS keys in grado di decrittografare le chiavi di dati crittografate utilizzando il portachiavi fornito, o perché nessuna delle chiavi presenti AWS KMS keys nel portachiavi è stata utilizzata per crittografare nessuna delle chiavi dati o perché il chiamante non è autorizzato a utilizzare il portachiavi incluso AWS KMS keys nel portachiavi per decrittografare, la chiamata di decrittografia ha esito negativo.

Quando si specifica un portachiavi AWS KMS key per la decrittografia, è necessario utilizzare la relativa chiave ARN. Gli alias ARNs sono consentiti solo nei portachiavi di crittografia. Per informazioni su come identificarli AWS KMS keys in un AWS KMS portachiavi, consulta. Identificazione AWS KMS keys in un portachiavi AWS KMS

In questo esempio, specifichiamo un portachiavi configurato con lo stesso AWS KMS key utilizzato 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: creare 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: decrittare la stringa.

Per decrittare la stringa, utilizza il metodo aws_cryptosdk_session_process_full con la sessione configurata per la decrittazione. Questo metodo, introdotto nelle AWS Encryption SDK versioni 1.9. x e 2.2. x, è progettato per la crittografia e la decrittografia non in streaming. Per gestire i dati in streaming, chiamali aws_cryptosdk_session_process in 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: verificare il contesto di crittografia.

Assicurati che il contesto di crittografia effettivo, quello utilizzato per decrittografare 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 decrittografia, poiché il contesto di crittografia è 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();
    }
}
Passaggio 6: pulire la sessione.

Dopo aver verificato il contesto di crittografia, puoi eliminare la sessione o riutilizzarla. Se è necessario riconfigurare la sessione, utilizzare il aws_cryptosdk_session_reset metodo.

aws_cryptosdk_session_destroy(session);