Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# AWS-Verschlüsselungs-SDK for C
Die AWS-Verschlüsselungs-SDK for C stellt eine clientseitige Verschlüsselungsbibliothek für Entwickler bereit, die Anwendungen in C schreiben. Sie dient auch als Grundlage für Implementierungen von AWS Encryption SDK in höheren Programmiersprachen.
Wie alle Implementierungen von bietet sie erweiterte AWS Encryption SDK Datenschutzfunktionen. AWS-Verschlüsselungs-SDK for C Dazu gehören die [Envelope-Verschlüsselung](concepts.md#envelope-encryption), zusätzliche authentifizierte Daten (AAD) und [Algorithmen-Pakete](concepts.md#crypto-algorithm) mit sicherem, authentifiziertem, symmetrischem Schlüssel, wie z. B. 256-Bit-AES-GCM mit Schlüsselableitung und Signatur.
Alle sprachspezifischen Implementierungen von sind vollständig interoperabel. AWS Encryption SDK Beispielsweise können Sie Daten mit der verschlüsseln AWS-Verschlüsselungs-SDK for C und mit [jeder unterstützten Sprachimplementierung](programming-languages.md) entschlüsseln, einschließlich der [AWS Encryption](crypto-cli.md) CLI.
Das AWS-Verschlüsselungs-SDK for C erfordert die Interaktion AWS SDK für C\$1\$1 mit AWS Key Management Service ()AWS KMS. Sie müssen es nur verwenden, wenn Sie den optionalen [AWS KMS Schlüsselbund](use-kms-keyring.md) verwenden. Das erfordert AWS KMS jedoch AWS Encryption SDK keinen anderen AWS Dienst.
**Weitere Informationen**
+ Einzelheiten zur Programmierung mit dem AWS-Verschlüsselungs-SDK for C finden Sie in den [C-Beispielen](c-examples.md), den [Beispielen](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) im [aws-encryption-sdk-c Repository](https://github.com/aws/aws-encryption-sdk-c/) auf GitHub und in der [AWS-Verschlüsselungs-SDK for C API-Dokumentation](https://aws.github.io/aws-encryption-sdk-c/html/).
+ Eine Erläuterung zur Verwendung von AWS-Verschlüsselungs-SDK for C zum Verschlüsseln von Daten, sodass Sie sie in mehreren Bereichen entschlüsseln können AWS-Regionen, finden Sie unter [Wie entschlüsselt man Chiffretexte in mehreren Regionen mit dem in C AWS Encryption SDK im Sicherheitsblog](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/). AWS
**Topics**
+ [Installation](c-language-installation.md)
+ [Verwenden des C SDK](c-language-using.md)
+ [Beispiele](c-examples.md)
# Installation des AWS-Verschlüsselungs-SDK for C
Installieren Sie die neueste Version der AWS-Verschlüsselungs-SDK for C.
**Anmerkung**
Alle AWS-Verschlüsselungs-SDK for C Versionen vor 2.0.0 befinden sich in der [end-of-supportPhase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle).
Sie können sicher von Version 2.0 aus aktualisieren. *x* und höher auf die neueste Version von AWS-Verschlüsselungs-SDK for C ohne Code- oder Datenänderungen. In Version 2.0 wurden jedoch [neue Sicherheitsfunktionen](about-versions.md#version-2) eingeführt. *x* sind nicht abwärtskompatibel. Um von Versionen vor 1.7 zu aktualisieren. *x* auf Version 2.0. *x* und höher, Sie müssen zuerst auf die neueste Version 1 aktualisieren. *x-Version* von AWS-Verschlüsselungs-SDK for C. Details hierzu finden Sie unter [Migrieren Sie Ihre AWS Encryption SDK](migration.md).
Eine ausführliche Anleitung zur Installation und Erstellung von finden Sie AWS-Verschlüsselungs-SDK for C in der [README-Datei](https://github.com/aws/aws-encryption-sdk-c/#readme) des [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)Repositorys. Es enthält Anweisungen zum Erstellen auf Amazon Linux-, Ubuntu-, macOS- und Windows-Plattformen.
Bevor Sie beginnen, entscheiden Sie, ob Sie [AWS KMS Schlüsselringe](use-kms-keyring.md) in der AWS Encryption SDK verwenden möchten. Wenn Sie einen AWS KMS Schlüsselbund verwenden, müssen Sie den installieren. AWS SDK für C\$1\$1 Das AWS SDK ist für die Interaktion mit [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) erforderlich. Wenn Sie AWS KMS Schlüsselringe verwenden, werden diese AWS Encryption SDK verwendet, AWS KMS um die Verschlüsselungsschlüssel zu generieren und zu schützen, die Ihre Daten schützen.
Sie müssen den nicht installieren, AWS SDK für C\$1\$1 wenn Sie einen anderen Schlüsselbundtyp verwenden, z. B. einen RAW-AES-Schlüsselbund, einen RSA-Rohschlüsselbund oder einen Mehrfachschlüsselbund ohne Schlüsselbund. AWS KMS Wenn Sie jedoch einen unformatierten Schlüsselbund verwenden, müssen Sie Ihre eigenen Rawrap-Schlüssel generieren und schützen.
Wenn Sie Probleme mit Ihrer Installation haben, melden Sie [ein Problem](https://github.com/aws/aws-encryption-sdk-c/issues) im `aws-encryption-sdk-c` Repository oder verwenden Sie einen der Feedback-Links auf dieser Seite.
# Mit dem AWS-Verschlüsselungs-SDK for C
In diesem Thema werden einige der Funktionen von erläutert AWS-Verschlüsselungs-SDK for C , die in anderen Programmiersprachenimplementierungen nicht unterstützt werden.
Die Beispiele in diesem Abschnitt zeigen, wie [Version 2.0 verwendet wird. ](about-versions.md)*x* und später von AWS-Verschlüsselungs-SDK for C. Beispiele, die frühere Versionen verwenden, finden Sie in der [Release-Liste](https://github.com/aws/aws-encryption-sdk-c/releases) des [aws-encryption-sdk-c Repository-Repositorys](https://github.com/aws/aws-encryption-sdk-c/) unter GitHub.
Einzelheiten zur Programmierung mit dem AWS-Verschlüsselungs-SDK for C finden Sie in den [C-Beispielen](c-examples.md), den [Beispielen](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) im [aws-encryption-sdk-c Repository](https://github.com/aws/aws-encryption-sdk-c/) unter GitHub und in der [AWS-Verschlüsselungs-SDK for C API-Dokumentation](https://aws.github.io/aws-encryption-sdk-c/html/).
Weitere Informationen finden Sie auch unter: [Schlüsselringe](choose-keyring.md).
**Topics**
+ [Muster zum Ver- und Entschlüsseln von Daten](#c-language-using-pattern)
+ [Referenzzählung](#c-language-using-release)
## Muster zum Ver- und Entschlüsseln von Daten
Wenn Sie den verwenden AWS-Verschlüsselungs-SDK for C, folgen Sie einem ähnlichen Muster: Erstellen Sie einen [Schlüsselbund](concepts.md#keyring), erstellen Sie ein [CMM](concepts.md#crypt-materials-manager), das den Schlüsselbund verwendet, erstellen Sie eine Sitzung, die das CMM (und den Schlüsselbund) verwendet, und verarbeiten Sie dann die Sitzung.
1. Lädt Fehlerzeichenfolgen.
Rufen Sie die `aws_cryptosdk_load_error_strings()` Methode in Ihrem C- oder C\$1\$1-Code auf. Sie lädt Fehlerinformationen, die für das Debuggen sehr nützlich sind.
Sie müssen es nur einmal aufrufen, z. B. in Ihrer `main` Methode.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2. Erstellen Sie einen Schlüsselbund.
Konfigurieren Sie Ihren [Schlüsselbund](concepts.md#keyring) mit dem Umhüllungsschlüssel, den Sie verwenden möchten, um Ihre Daten zu verschlüsseln. In diesem Beispiel wird ein [AWS KMS Schlüsselbund](use-kms-keyring.md) mit einem Schlüsselbund verwendet AWS KMS key, aber Sie können stattdessen jeden beliebigen Schlüsselbund verwenden.
Um einen AWS KMS key in einem Verschlüsselungsschlüsselbund in der zu identifizieren AWS-Verschlüsselungs-SDK for C, geben Sie einen [Schlüssel-ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) oder [Alias-ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) an. 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](use-kms-keyring.md#kms-keyring-id).
```
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. Erstellen Sie eine Sitzung.
In der verwenden Sie eine *Sitzung AWS-Verschlüsselungs-SDK for C*, um eine einzelne Klartext-Nachricht zu verschlüsseln oder eine einzelne Chiffretext-Nachricht zu entschlüsseln, unabhängig von ihrer Größe. Die Sitzung behält den Status der Nachricht während der Verarbeitung.
Konfigurieren Sie Ihre Sitzung mit einem Allocator, einem Schlüsselbund und einem Modus: `AWS_CRYPTOSDK_ENCRYPT` oder `AWS_CRYPTOSDK_DECRYPT`. Wenn Sie den Modus der Sitzung ändern müssen, verwenden Sie die `aws_cryptosdk_session_reset`-Methode.
Wenn Sie eine Sitzung mit einem Schlüsselbund erstellen, erstellt der AWS-Verschlüsselungs-SDK for C automatisch einen standardmäßigen Cryptographic Materials Manager (CMM) für Sie. Sie müssen dieses Objekt nicht erstellen, pflegen oder zerstören.
Beispiel: Die folgende Sitzung verwendet den Allocator und den Schlüsselbund, der in Schritt 1 definiert wurde. Wenn Sie Daten verschlüsseln, lautet der Modus `AWS_CRYPTOSDK_ENCRYPT`.
```
struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
```
4. Verschlüsseln oder entschlüsseln Sie die Daten.
Um die Daten in der Sitzung zu verarbeiten, verwenden Sie die `aws_cryptosdk_session_process`-Methode. Wenn der Eingabepuffer groß genug ist, um den gesamten Klartext aufzunehmen, und der Ausgabepuffer groß genug ist, um den gesamten Chiffretext aufzunehmen, können Sie aufrufen. `aws_cryptosdk_session_process_full` Wenn Sie jedoch Streaming-Daten verarbeiten müssen, können Sie `aws_cryptosdk_session_process` in einer Schleife aufrufen. Ein Beispiel finden Sie im Beispiel [file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp). Das `aws_cryptosdk_session_process_full` ist in den AWS Encryption SDK Versionen 1.9 eingeführt. *x* und 2.2. *x.*
Wenn die Sitzung für das Verschlüsseln von Daten konfiguriert ist, beschreiben die Klartextfelder die Eingabe und die Verschlüsselungstext-Felder die Ausgabe. Das `plaintext`-Feld enthält die Nachricht, die Sie verschlüsseln möchten, und das `ciphertext`-Feld ruft die [verschlüsselte Nachricht](message-format.md) ab, die die Verschlüsselungsmethode zurückgibt.
```
/* Encrypting data */
aws_cryptosdk_session_process_full(session,
ciphertext,
ciphertext_buffer_size,
&ciphertext_length,
plaintext,
plaintext_length)
```
Wenn die Sitzung für das Entschlüsseln von Daten konfiguriert ist, beschreiben die Verschlüsselungstext-Felder die Eingabe und die Klartextfelder die Ausgabe. Das `ciphertext`-Feld enthält die [verschlüsselte Nachricht](message-format.md), die die Verschlüsselungsmethode zurückgegeben hat, und das `plaintext`-Feld ruft die Klartextnachricht ab, die die Entschlüsselungsmethode zurückgibt.
Um die Daten zu entschlüsseln, rufen Sie die `aws_cryptosdk_session_process_full`-Methode auf.
```
/* Decrypting data */
aws_cryptosdk_session_process_full(session,
plaintext,
plaintext_buffer_size,
&plaintext_length,
ciphertext,
ciphertext_length)
```
## Referenzzählung
Um Lecks im Arbeitsspeicher zu verhindern, müssen Sie Ihre Referenzen an alle Objekte freigeben, die Sie erstellen, wenn Sie mit diesen fertig sind. Andernfalls erhalten Sie Lecks im Arbeitsspeicher. Das SDK bietet Methoden, um diese Aufgabe zu vereinfachen.
Wenn Sie ein übergeordnetes Objekt mit einem der folgenden untergeordneten Objekte erstellen, erhält und behält das übergeordnete Objekt einen Verweis auf das untergeordnete Objekt wie folgt bei:
+ Ein [Schlüsselbund](concepts.md#keyring), z. B. das Erstellen einer Sitzung mit einem Schlüsselbund
+ Ein standardmäßiger [Cryptographic Materials Manager](concepts.md#crypt-materials-manager) (CMM), z. B. das Erstellen einer Sitzung oder ein benutzerdefiniertes CMM mit einem Standard-CMM
+ Ein [Datenschlüssel-Cache](data-key-caching.md), z. B. das Erstellen eines Caching-CMM mit einem Schlüsselbund und Cache
Wenn Sie keinen unabhängigen Verweis auf das untergeordnete Objekt benötigen, können Sie den Verweis auf das untergeordnete Objekt freigeben, sobald Sie das übergeordnete Objekt erstellen. Der verbleibende Verweis auf das untergeordnete Objekt wird freigegeben, wenn das übergeordnete Objekt zerstört wird. Durch dieses Muster wird sichergestellt, dass Sie die Referenz auf jedes Objekt nur so lange wie nötig behalten. Es kommt auch nicht zu einem Leck im Arbeitsspeicher aufgrund von nicht freigegebenen Referenzen.
Sie sind nur dafür verantwortlich, Verweise auf die untergeordneten Objekte freizugeben, die Sie explizit erstellen. Sie sind nicht verantwortlich für die Verwaltung von Verweisen auf Objekte, die das SDK für Sie erstellt. Wenn das SDK ein Objekt erstellt, z. B. das Standard-CMM, das die `aws_cryptosdk_caching_cmm_new_from_keyring` Methode einer Sitzung hinzufügt, verwaltet das SDK die Erstellung und Zerstörung des Objekts und seiner Verweise.
Wenn Sie im folgenden Beispiel eine Sitzung mit einem [Schlüsselbund](concepts.md#keyring) erstellen, erhält die Sitzung einen Verweis auf den Schlüsselbund und behält diesen Verweis bei, bis die Sitzung zerstört wird. Wenn Sie keinen zusätzlichen Verweis auf den Schlüsselbund beibehalten müssen, können Sie die `aws_cryptosdk_keyring_release`-Methode verwenden, um das Schlüsselbundobjekt freizugeben, sobald die Sitzung erstellt wird. Diese Methode verringert die Referenzanzahl für den Schlüsselbund. Der Verweis der Sitzung auf den Schlüsselbund wird freigegeben, wenn Sie `aws_cryptosdk_session_destroy` aufrufen, um die Sitzung zu zerstören.
```
// 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);
```
Für komplexere Aufgaben, wie die Wiederverwendung eines Schlüsselbunds für mehrere Sitzungen oder die Angabe einer Algorithmus-Suite in einem CMM, müssen Sie möglicherweise einen unabhängigen Verweis auf das Objekt beibehalten. Wenn ja, rufen Sie die Freigabemethoden nicht sofort auf. Geben Sie stattdessen Ihre Referenzen frei, wenn Sie die Objekte nicht mehr verwenden, zusätzlich zum Löschen der Sitzung.
[Diese Methode zur Referenzzählung funktioniert auch, wenn Sie eine alternative Methode verwenden CMMs, z. B. das CMM für die Zwischenspeicherung von Datenschlüsseln.](data-key-caching.md) Wenn Sie ein Cache-CMM aus einem Cache und einem Schlüsselbund erstellen, erhält das Caching-CMM einen Verweis auf beide Objekte. Sofern Sie sie nicht für eine andere Aufgabe benötigen, können Sie Ihre unabhängigen Verweise auf den Cache und den Schlüsselbund freigeben, sobald das Caching-CMM erstellt ist. Wenn Sie dann eine Sitzung mit dem Caching-CMM erstellen, können Sie Ihren Verweis auf das Caching-CMM freigeben.
Beachten Sie, dass Sie nur für die Freigabe von Verweisen auf Objekte verantwortlich sind, die Sie explizit erstellen. Objekte, die die Methoden für Sie erstellen, wie z. B. das Standard-CMM, das dem Caching-CMM zugrunde liegt, werden von der Methode verwaltet.
```
/ 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);
```
# AWS-Verschlüsselungs-SDK for C Beispiele
Die folgenden Beispiele zeigen Ihnen, wie Sie mit AWS-Verschlüsselungs-SDK for C dem Daten ver- und entschlüsseln können.
Die Beispiele in diesem Abschnitt zeigen, wie die Versionen 2.0 verwendet werden. *x* und später von AWS-Verschlüsselungs-SDK for C. Beispiele, die frühere Versionen verwenden, finden Sie in der [Release-Liste](https://github.com/aws/aws-encryption-sdk-c/releases) des [aws-encryption-sdk-c Repository-Repositorys](https://github.com/aws/aws-encryption-sdk-c/) unter GitHub.
Wenn Sie das installieren und erstellen AWS-Verschlüsselungs-SDK for C, ist der Quellcode für diese und andere Beispiele im `examples` Unterverzeichnis enthalten, und sie werden kompiliert und in das `build` Verzeichnis integriert. Sie finden sie auch im Unterverzeichnis [für Beispiele](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) des [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)Repositorys unter. GitHub
**Topics**
+ [Verschlüsseln und Entschlüsseln von Zeichenfolgen](#c-example-strings)
## Verschlüsseln und Entschlüsseln von Zeichenfolgen
Das folgende Beispiel zeigt Ihnen, wie Sie mit dem eine AWS-Verschlüsselungs-SDK for C Zeichenfolge ver- und entschlüsseln können.
Dieses Beispiel zeigt den [AWS KMS Schlüsselbund](use-kms-keyring.md), eine Art von Schlüsselbund, der ein AWS KMS key in [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) verwendet, um Datenschlüssel zu generieren und zu verschlüsseln. Das Beispiel enthält in C\$1\$1 geschriebenen Code. Das AWS-Verschlüsselungs-SDK for C erfordert den Aufruf AWS SDK für C\$1\$1 , AWS KMS wenn AWS KMS Schlüsselbunde verwendet werden. Wenn Sie einen Schlüsselbund verwenden, der nicht interagiert AWS KMS, wie z. B. einen RAW-AES-Schlüsselbund, einen RSA-Rohschlüsselbund oder einen Mehrfachschlüsselbund, der keinen Schlüsselbund enthält, ist der nicht erforderlich. AWS KMS AWS SDK für C\$1\$1
[https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) Hilfe zur Identifizierung von AWS KMS keys in einem AWS KMS Schlüsselbund finden Sie unter[Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund](use-kms-keyring.md#kms-keyring-id).
**Das vollständige Codebeispiel finden Sie unter**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [Verschlüsseln einer Zeichenfolge](#c-example-string-encrypt)
+ [Entschlüsseln einer Zeichenfolge](#c-example-string-decrypt)
### Verschlüsseln einer Zeichenfolge
Im ersten Teil dieses Beispiels wird ein Schlüsselbund mit einem AWS KMS Schlüsselbund verwendet, AWS KMS key um eine Klartext-Zeichenfolge zu verschlüsseln.
Schritt 1. Lädt Fehlerzeichenfolgen.
Rufen Sie die `aws_cryptosdk_load_error_strings()` Methode in Ihrem C- oder C\$1\$1-Code auf. Sie lädt Fehlerinformationen, die für das Debuggen sehr nützlich sind.
Sie müssen es nur einmal aufrufen, z. B. in Ihrer `main` Methode.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Schritt 2: Konstruieren Sie den Schlüsselbund.
Erstellen Sie einen AWS KMS Schlüsselbund für die Verschlüsselung. Der Schlüsselbund in diesem Beispiel ist mit einem Schlüsselbund konfiguriert AWS KMS key, aber Sie können einen AWS KMS Schlüsselbund mit mehreren AWS KMS keys, auch AWS KMS keys in verschiedenen AWS-Regionen Konten, konfigurieren.
Um einen AWS KMS key in einem Verschlüsselungsschlüsselbund in der zu identifizieren AWS-Verschlüsselungs-SDK for C, geben Sie einen [Schlüssel-ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) oder [Alias-ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) an. 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](use-kms-keyring.md#kms-keyring-id).
[Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund](use-kms-keyring.md#kms-keyring-id)
Wenn Sie einen Schlüsselbund mit mehreren Schlüsselbunden erstellen AWS KMS keys, geben Sie den Schlüssel an, der AWS KMS key zur Generierung und Verschlüsselung des Klartext-Datenschlüssels verwendet wird, sowie ein optionales Array von zusätzlichen Schlüsseln, AWS KMS keys die denselben Klartext-Datenschlüssel verschlüsseln. In diesem Fall geben Sie nur den Generator an. AWS KMS key
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);
```
Schritt 3: Erstellen Sie eine Sitzung.
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](c-language-using.md#c-language-using-release) 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);
```
Schritt 4: Legen Sie den Verschlüsselungskontext fest.
Ein [Verschlüsselungskontext](concepts.md#encryption-context) ist eine Art zufälliger, nicht geheimer, zusätzlich authentifizierter Daten. Wenn Sie bei Encrypt einen Verschlüsselungskontext angeben, bindet der Verschlüsselungskontext AWS Encryption SDK kryptografisch an den Chiffretext, sodass derselbe Verschlüsselungskontext zum Entschlüsseln der Daten erforderlich ist. 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)
```
Schritt 5: Verschlüsseln Sie die Zeichenfolge.
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 in Version 1.9 eingeführt. AWS Encryption SDK *x* und 2.2. *x* ist für die Verschlüsselung und Entschlüsselung ohne Streaming konzipiert. Um Streaming-Daten zu verarbeiten, rufen Sie den `aws_cryptosdk_session_process` in einer Schleife auf.
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](concepts.md#message), einschließlich des tatsächlichen Verschlüsselungstexts, der verschlüsselten Datenschlüssel und des Verschlüsselungskontexts. Sie können diese verschlüsselte Nachricht entschlüsseln, indem Sie die AWS Encryption SDK für jede unterstützte Programmiersprache verwenden.
```
/* 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;
}
```
Schritt 6: Bereinigen Sie die Sitzung.
Im letzten Schritt wird die Sitzung einschließlich der Verweise auf das CMM und den Schlüsselbund gelöscht.
Wenn Sie es vorziehen, die Sitzung nicht zu zerstören, können Sie die Sitzung mit demselben Schlüsselbund und CMM wiederverwenden, um die Zeichenfolge zu entschlüsseln oder um andere Nachrichten zu verschlüsseln oder zu entschlüsseln. 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.
### Entschlüsseln einer Zeichenfolge
Im zweiten Teil dieses Beispiels wird eine verschlüsselte Nachricht entschlüsselt, die den Verschlüsselungstext der ursprünglichen Zeichenfolge enthält.
Schritt 1: Fehlerzeichenfolgen laden.
Rufen Sie die `aws_cryptosdk_load_error_strings()` Methode in Ihrem C- oder C\$1\$1-Code auf. Sie lädt Fehlerinformationen, die für das Debuggen sehr nützlich sind.
Sie müssen es nur einmal aufrufen, z. B. in Ihrer `main` Methode.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Schritt 2: Konstruieren Sie den Schlüsselbund.
Wenn Sie Daten entschlüsseln AWS KMS, übergeben Sie die [verschlüsselte Nachricht, die die Verschlüsselungs-API](concepts.md#message) zurückgegeben hat. Die [Decrypt-API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) akzeptiert keine Eingabe. AWS KMS key AWS KMS Verwendet stattdessen dasselbe AWS KMS key zum Entschlüsseln des Chiffretextes, mit dem es ihn verschlüsselt hat. AWS Encryption SDK Mit können Sie jedoch einen AWS KMS Schlüsselbund angeben, bei dem die Option Verschlüsseln und Entschlüsseln aktiviert ist. AWS KMS keys
Beim Entschlüsseln können Sie einen Schlüsselbund konfigurieren, der nur den enthält AWS KMS keys , den Sie zum Entschlüsseln der verschlüsselten Nachricht verwenden möchten. Möglicherweise möchten Sie einen Schlüsselbund erstellen, der nur den enthält AWS KMS key , der von einer bestimmten Rolle in Ihrer Organisation verwendet wird. Der AWS Encryption SDK wird niemals einen verwenden, es AWS KMS key sei denn, er ist im Entschlüsselungsschlüsselbund enthalten. Wenn das SDK die verschlüsselten Datenschlüssel nicht mithilfe des AWS KMS keys von Ihnen angegebenen Schlüsselbunds entschlüsseln kann, entweder weil keiner der Schlüssel AWS KMS keys im Schlüsselbund zum Verschlüsseln eines der Datenschlüssel verwendet wurde oder weil der Anrufer nicht berechtigt ist, den Schlüssel AWS KMS keys im Schlüsselbund zum Entschlüsseln zu verwenden, schlägt der Entschlüsselungsaufruf fehl.
Wenn Sie AWS KMS key für eine Entschlüsselung einen Schlüsselbund angeben, müssen Sie seinen [Schlüssel-ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) verwenden. [Alias ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) sind nur in Schlüsselbunden für die Verschlüsselung zulässig. Hilfe zur Identifizierung von AWS KMS keys in einem AWS KMS Schlüsselbund finden Sie unter. [Identifizierung AWS KMS keys in einem AWS KMS Schlüsselbund](use-kms-keyring.md#kms-keyring-id)
In diesem Beispiel geben wir einen Schlüsselbund an, der mit demselben konfiguriert ist, der zur Verschlüsselung der Zeichenfolge AWS KMS key verwendet wurde. 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);
```
Schritt 3: Erstellen Sie eine Sitzung.
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);
```
Schritt 4: Entschlüsseln Sie die Zeichenfolge.
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 in den AWS Encryption SDK Versionen 1.9 eingeführt. *x* und 2.2. *x* ist für die Verschlüsselung und Entschlüsselung ohne Streaming konzipiert. Um Streaming-Daten zu verarbeiten, rufen Sie den `aws_cryptosdk_session_process` in einer Schleife auf.
Beim Entschlüsseln sind die Verschlüsselungstext-Felder Eingabefelder. Die Klartextfelder sind Ausgabefelder. Das `ciphertext_input`-Feld enthält die [verschlüsselte Nachricht](message-format.md), 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;
}
```
Schritt 5: Überprüfen Sie den Verschlüsselungskontext.
Stellen Sie sicher, dass der tatsächliche Verschlüsselungskontext — der, 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](concepts.md#crypt-materials-manager) (CMM) Paare zum angegebenen Verschlüsselungskontext hinzufügen kann, bevor die Nachricht verschlüsselt wird.
In der müssen Sie beim Entschlüsseln keinen Verschlüsselungskontext angeben AWS-Verschlüsselungs-SDK for C, 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();
}
}
```
Schritt 6: Bereinigen Sie die Sitzung.
Nachdem Sie den Verschlüsselungskontext überprüft haben, können Sie die Sitzung löschen oder wiederverwenden. Wenn Sie die Sitzung neu konfigurieren müssen, verwenden Sie die `aws_cryptosdk_session_reset` Methode.
```
aws_cryptosdk_session_destroy(session);
```