Verwendung der AWS-Verschlüsselungs-SDK for C

Dieses Thema erklärt einige der Funktionen des AWS-Verschlüsselungs-SDK for C, die in Implementierungen anderer Programmiersprachen nicht unterstützt werden.

Die Beispiele in diesem Abschnitt zeigen, wie Sie verwenden könnenVersion 2.0.xund später von derAWS-Verschlüsselungs-SDK for Caus. Für Beispiele, die frühere Versionen verwenden, finden Sie Ihre Version im-Versionen-Liste desaws-encryption-sdk-c Repository-Repository auf GitHub.

Weitere Informationen zur Programmierung mit dem AWS-Verschlüsselungs-SDK for C finden Sie in den C-Beispielen, in den Beispielen im GitHub-Repository aws-encryption-sdk-c und in der AWS-Verschlüsselungs-SDK for C- API-Dokumentation.

Weitere Informationen finden Sie auch unter: Verwenden von Schlüsselbunden.

Muster zum Ver- und Entschlüsseln von Daten

Wenn Sie das AWS-Verschlüsselungs-SDK for C verwenden, folgen Sie einem Muster, das in etwa so aussieht: Erstellen eines Schlüsselbunds, Erstellen eines CMM, der den Schlüsselbund verwendet, Erstellen einer Sitzung, die den CMM (und Schlüsselbund) verwendet, und Verarbeiten der Sitzung.

1. Ladefehlerzeichenfolgen.

Rufen Sie denaws_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();

2. Erstellen Sie einen Schlüsselbund.

Konfigurieren Sie Ihren Schlüsselbund mit dem Umhüllungsschlüssel, den Sie verwenden möchten, um Ihre Daten zu verschlüsseln. In diesem Beispiel verwenden wir einenAWS KMSSchlüsselringmit einemAWS KMS keyverwenden, Sie können aber jede Art von Schlüsselbund verwenden.

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.

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.

Im AWS-Verschlüsselungs-SDK for C verwenden Sie eine Sitzung zum Verschlüsseln einer einzelnen Klartextnachricht oder zum Entschlüsseln einer einzelnen Verschlüsselungstext-Nachricht, 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, wird derAWS-Verschlüsselungs-SDK for CErstellt automatisch einen Standard-Manager von kryptographischen Materialien (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 zu speichern und der Ausgabepuffer groß genug ist, um den gesamten Verschlüsselungstext zu speichern, können Sieaws_cryptosdk_session_process_fullaus. Wenn Sie jedoch Streaming-Daten verarbeiten müssen, können Sieaws_cryptosdk_session_processin einer Schleife. Ein Beispiel finden Sie im Beispiel file_streaming.cpp. Dieaws_cryptosdk_session_process_fullwird in eingeführtAWS Encryption SDKVersionen 1.9.xund 2.2xaus.

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 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, 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, z. B. das Erstellen einer Sitzung mit einem Schlüsselbund

• Eine Standard-Manager kryptographischer Materialien(CMM), z. B. das Erstellen einer Sitzung oder eines benutzerdefinierten CMM mit einem Standard-CMM

• Ein Datenschlüssel-Cache, 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, dasaws_cryptosdk_caching_cmm_new_from_keyring-Methode fügt zu einer Sitzung hinzu, das SDK verwaltet die Erstellung und Zerstörung des Objekts und seiner Referenzen.

Wenn Sie im folgenden Beispiel eine Sitzung mit einem Schlüsselbund 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, z. B. die Wiederverwendung eines Schlüsselbunds für mehrere Sitzungen oder das Angeben eines Algorithmen-Pakets 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 Referenzzähltechnik funktioniert auch, wenn Sie alternative CMMs verwenden, z. B. den Caching-Datenschlüssel-Cachingaus. Wenn Sie einen Caching- CMM aus einem Cache und einem Schlüsselbund erstellen, erhält der Caching- einen Verweis auf beide Objekte. Wenn Sie sie nicht für eine andere Aufgabe benötigen, können Sie Ihre unabhängigen Referenzen auf den Cache und Schlüsselbund freigeben, sobald der Caching- erstellt wird. Wenn Sie dann eine Sitzung mit dem Caching- CMM erstellen, können Sie Ihren Verweis auf den Caching- CMM freigeben.

Beachten Sie, dass Sie nur für die Freigabe von Verweisen auf Objekte verantwortlich sind, die Sie explizit erstellen. Objekte, die von den Methoden für Sie erstellt werden, 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);