AWS-Verschlüsselungs-SDK for CBeispiele für

Rufen Sie dieaws_cryptosdk_load_error_strings()-Methode in Ihrem C- oder C++-Code. Es lädt Fehlerinformationen, die für das Debuggen sehr nützlich sind.

Sie müssen es nur einmal anrufen, z. B. in Ihremmain-Methode

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

Erstellen einesAWS KMSSchlüsselbund für die Verschlüsselung Der Schlüsselbund in diesem Beispiel ist mit einem konfiguriertAWS KMS key, aber Sie können einAWS KMSSchlüsselbund mit mehrerenAWS KMS keys, einschließlichAWS KMS keysin verschiedenenAWS-Regionenund verschiedene Konten.

So identifizieren Sie einAWS KMS keyin einem Verschlüsselungsschlüsselbund imAWS-Verschlüsselungs-SDK for C, geben Sie einSchüssel-ARNoderAlias-ARNaus. In einem Entschlüsselungsschlüsselbund müssen Sie einen Schlüssel-ARN verwenden. Details hierzu finden Sie unter Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund.

Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund

Wenn Sie einen Schlüsselbund mit mehreren erstellenAWS KMS keysgeben Sie dieAWS KMS keyWird verwendet, um den Klartext-Datenschlüssel zu generieren und zu verschlüsseln, sowie ein optionales Array von zusätzlichenAWS KMS keysDie den gleichen Klartext-Datenschlüssel verschlüsseln. In diesem Fall geben Sie nur den Generator anAWS KMS keyaus.

Ersetzen Sie vor Ausführung dieses Codes den ARN des Beispiel-Schlüssels durch einen gültigen.

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

Erstellen Sie eine Sitzung mithilfe des Allocators, eines Modus-Enumerators und des Schlüsselbunds.

Jede Sitzung erfordert eine Modus: entweder AWS_CRYPTOSDK_ENCRYPT zum Verschlüsseln oder AWS_CRYPTOSDK_DECRYPT zum Entschlüsseln. Um den Modus einer vorhandenen Sitzung zu ändern, verwenden Sie die aws_cryptosdk_session_reset-Methode.

Nach dem Erstellen einer Sitzung mit dem Schlüsselbund können Sie Ihre Referenz auf den Schlüsselbund unter Verwendung der Methode, die das SDK bietet, freigeben. Die Sitzung behält während ihrer Lebensdauer einen Verweis auf das Schlüsselbundobjekt bei. Verweise auf den Schlüsselbund und die Sitzungsobjekte werden freigegeben, wenn Sie die Sitzung zerstören. Diese Referenzzähltechnik hilft, Lecks im Arbeitsspeicher zu verhindern, und sorgt dafür, dass die Objekte nicht freigegeben werden, während sie verwendet werden.

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

Ein Verschlüsselungskontext ist eine Art zufälliger, nicht geheimer, zusätzlich authentifizierter Daten. Wenn Sie beim Verschlüsseln einen Verschlüsselungskontext angegeben, bindet das AWS Encryption SDK den Verschlüsselungskontext kryptografisch an den Verschlüsselungstext. Daher ist zum Entschlüsseln der Daten derselbe Verschlüsselungskontext erforderlich. Die Verwendung eines Verschlüsselungskontexts ist optional, aber wir empfehlen dies als eine bewährte Methode.

Erstellen Sie zuerst eine Hash-Tabelle, die die Zeichenfolgen des Verschlüsselungskontexts enthält.

/* 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)

Rufen Sie einen veränderlichen Zeiger auf den Verschlüsselungskontext in der Sitzung ab. Verwenden Sie anschließend die aws_cryptosdk_enc_ctx_clone-Funktion zum Kopieren des Verschlüsselungskontexts in die Sitzung. Halten Sie die Kopie in my_enc_ctx, damit Sie den Wert nach der Entschlüsselung der Daten validieren können.

Der Verschlüsselungskontext ist Teil der Sitzung, nicht ein Parameter, der an die Sitzungs-Verarbeitungsfunktion übergeben wird. Dadurch wird sichergestellt, dass derselbe Verschlüsselungskontext für jedes Segment einer Nachricht verwendet wird, auch wenn die Sitzungs-Verarbeitungsfunktion mehrmals aufgerufen wird, um die gesamte Nachricht zu verschlüsseln.

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)

Verwenden Sie zum Verschlüsseln der Klartext-Zeichenfolge die aws_cryptosdk_session_process_full-Methode, wobei sich die Sitzung im Verschlüsselungsmodus befinden muss. Diese Methode wurde eingeführt inAWS Encryption SDK-Versionen 1.9xund 2.2x, ist für die Nicht-Streaming-Verschlüsselung und Entschlüsselung konzipiert. Um mit Streaming-Daten umzugehen, rufen Sie dieaws_cryptosdk_session_processin einer Schleife.

Beim Verschlüsseln sind die Klartextfelder Eingabefelder. Die Verschlüsselungstext-Felder sind Ausgabefelder. Wenn die Verarbeitung abgeschlossen ist, enthält das ciphertext_output-Feld die verschlüsselte Nachricht, einschließlich des tatsächlichen Verschlüsselungstexts, der verschlüsselten Datenschlüssel und des Verschlüsselungskontexts. Sie können diese verschlüsselte Nachricht durch Verwenden des AWS Encryption SDK für jede unterstützte Programmiersprache entschlüsseln.

/* 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;
}

Im letzten Schritt wird die Sitzung einschließlich Referenzen auf das CMM und den Schlüsselbund zerstört.

Wenn Sie die Sitzung nicht zerstören möchten, können Sie sie mit demselben Schlüsselbund und und CMM zum Entschlüsseln der Zeichenfolge oder zum Verschlüsseln oder Entschlüsseln von anderen Nachrichten verwenden. Um die Sitzung zum Entschlüsseln zu verwenden, wenden Sie die aws_cryptosdk_session_reset-Methode an, um den Modus in AWS_CRYPTOSDK_DECRYPT zu ändern.

Rufen Sie dieaws_cryptosdk_load_error_strings()-Methode in Ihrem C- oder C++-Code. Es lädt Fehlerinformationen, die für das Debuggen sehr nützlich sind.

Sie müssen es nur einmal anrufen, z. B. in Ihremmain-Methode

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

Wenn Sie Daten in AWS KMS entschlüsseln, übergeben Sie die verschlüsselte Nachricht, die die API zurückgegeben hat. DieAPI entschlüsselnnimmt keinAWS KMS keyals Eingabe. Stattdessen verwendet AWS KMS denselben AWS KMS key zum Entschlüsseln des Verschlüsselungstexts, der auch für die Verschlüsselung verwendet wurde. Allerdings ist derAWS Encryption SDKkönnen Sie eine angebenAWS KMSSchlüsselbund mitAWS KMS keysbeim Verschlüsseln und Entschlüsseln von.

Beim Entschlüsseln können Sie einen Schlüsselbund konfigurieren, der nur die AWS KMS keys enthält, die Sie zum Entschlüsseln der verschlüsselten Nachricht verwenden möchten. Beispielsweise möchten Sie einen Schlüsselbund mit nur dem AWS KMS key erstellen, der von einer bestimmten Rolle in Ihrer Organisation verwendet wird. DieAWS Encryption SDKwird niemals ein benutzenAWS KMS keyEs sei denn, er erscheint im Entschlüsselungsschlüsselbund. Wenn das SDK die verschlüsselten Datenschlüssel nicht mithilfe der AWS KMS keys im von Ihnen bereitgestellten Schlüsselbund entschlüsseln kann, weil entweder keiner der AWS KMS keys im Schlüsselbund zum Verschlüsseln der Datenschlüssel verwendet wurde oder weil der Aufrufer die AWS KMS keys im Schlüsselbund nicht für die Entschlüsselung verwenden darf, schlägt die Entschlüsselung fehl.

Wenn Sie einAWS KMS keyFür einen Entschlüsselungsschlüsselbund müssen Sie dessenSchüssel-ARNaus. Alias-ARNssind nur in Verschlüsselungsschlüsselbunden zulässig. Hilfe bei der Identifizierung desAWS KMS keysin einemAWS KMSSchlüsselbund, sieheIdentifizierung AWS KMS keys in einem AWS KMS Schlüsselbundaus.

In diesem Beispiel geben wir einen Schlüsselbund an, der mit demselben konfiguriert wurdeAWS KMS keyWird verwendet, um die Zeichenfolge zu verschlüsseln. Ersetzen Sie vor Ausführung dieses Codes den ARN des Beispiel-Schlüssels durch einen gültigen.

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

Erstellen Sie eine Sitzung unter Verwendung des Allocators und des Schlüsselbunds. Zum Konfigurieren der Sitzung für die Entschlüsselung konfigurieren Sie die Sitzung mit dem AWS_CRYPTOSDK_DECRYPT-Modus.

Nach dem Erstellen einer Sitzung mit einem Schlüsselbund können Sie Ihre Referenz auf den Schlüsselbund unter Verwendung der Methode, die das SDK bietet, freigeben. Die Sitzung behält während ihrer Lebensdauer einen Verweis auf das Schlüsselbundobjekt bei und sowohl die Sitzung als auch der Schlüsselbund werden freigegeben, wenn Sie die Sitzung zerstören. Diese Referenzzähltechnik hilft, Lecks im Arbeitsspeicher zu verhindern, und sorgt dafür, dass die Objekte nicht freigegeben werden, während sie verwendet werden.

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

Verwenden Sie zum Entschlüsseln der Zeichenfolge die aws_cryptosdk_session_process_full-Methode mit der Sitzung, die für die Entschlüsselung konfiguriert ist. Diese Methode wurde eingeführt inAWS Encryption SDK-Versionen 1.9xund 2.2x, ist für die Nicht-Streaming-Verschlüsselung und Entschlüsselung konzipiert. Um mit Streaming-Daten umzugehen, rufen Sie dieaws_cryptosdk_session_processin einer Schleife.

Beim Entschlüsseln sind die Verschlüsselungstext-Felder Eingabefelder. Die Klartextfelder sind Ausgabefelder. Das ciphertext_input-Feld enthält die verschlüsselte Nachricht, die die Verschlüsselungsmethode zurückgegeben hat. Wenn die Verarbeitung abgeschlossen ist, enthält das plaintext_output-Feld die Klartext-Zeichenfolge (entschlüsselt).

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

Stellen Sie sicher, dass der eigentliche Verschlüsselungskontext - der zum Entschlüsseln der Nachricht verwendet wurde - den Verschlüsselungskontext enthält, den Sie beim Verschlüsseln der Nachricht angegeben haben. Der tatsächliche Verschlüsselungskontext kann zusätzliche Paare enthalten, da der Manager von kryptographischen Materialien (CMM) Paare zum angegebenen Verschlüsselungskontext hinzufügen kann, bevor die Nachricht verschlüsselt wird.

Im AWS-Verschlüsselungs-SDK for C müssen Sie beim Entschlüsseln keinen Verschlüsselungskontext angeben, da der Verschlüsselungskontext in der verschlüsselten Nachricht enthalten ist, die das SDK zurückgibt. Aber bevor sie die Klartext-Nachricht zurückgibt, sollte Ihre Entschlüsselungsfunktion überprüfen, dass alle Paare im angegebenen Verschlüsselungskontext in dem Verschlüsselungskontext erscheinen, der zum Entschlüsseln der Nachricht verwendet wurde.

Rufen Sie zuerst einen schreibgeschützten Zeiger auf die Hash-Tabelle in der Sitzung ab. Diese Hash-Tabelle enthält den Verschlüsselungskontext, der zum Entschlüsseln der Nachricht verwendet wurde.

const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);

Durchlaufen Sie anschließend den Verschlüsselungskontext in der my_enc_ctx-Hash-Tabelle, die Sie beim Verschlüsseln kopiert haben. Überprüfen Sie, dass alle Paare in der my_enc_ctx-Hash-Tabelle, die zum Verschlüsseln verwendet wurde, in der session_enc_ctx-Hash-Tabelle erscheinen, die zur Entschlüsselung verwendet wurde. Wenn ein Schlüssel nicht vorhanden ist oder dieser Schlüssel einen anderen Wert hat, beenden Sie die Verarbeitung und schreiben Sie eine Fehlermeldung.

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

Nachdem Sie den Verschlüsselungskontext überprüft haben, können Sie die Sitzung zerstören oder wiederverwenden. Wenn Sie die Sitzung neu konfigurieren müssen, verwenden Sie dieaws_cryptosdk_session_reset-Methode

aws_cryptosdk_session_destroy(session);