Exemples Kit SDK de chiffrement AWS pour C

Les exemples suivants montrent comment utiliser le kit Kit SDK de chiffrement AWS pour C afin de chiffrer et de déchiffrer des données.

Les exemples de cette section montrent comment utiliser les versions 2.0.h/24, j/7et plus tard duKit SDK de chiffrement AWS pour C. Pour obtenir des exemples utilisant des versions antérieures, recherchez votre version dans leVersionsliste desaws-encryption-sdk-crepository surGitHub.

Lorsque vous installez et générez le kit Kit SDK de chiffrement AWS pour C, le code source de ces éléments et d'autres exemples sont inclus dans le sous-répertoire examples et compilés et intégrés dans le répertoire build. Vous pouvez également les trouver dans leexemplessous-répertoire duaws-encryption-sdk-crepository surGitHub.

Chiffrement et déchiffrement de chaînes

L'exemple suivant montre comment utiliser le kit Kit SDK de chiffrement AWS pour C pour chiffrer et déchiffrer une chaîne.

Cet exemple présente leAWS KMSPorte-clés, un type de porte-clés qui utilise unAWS KMS keydansAWS Key Management Service(AWS KMS)pour générer et chiffrer des clés de données. L'exemple inclut du code écrit en C++. LeKit SDK de chiffrement AWS pour Cnécessite laAWS SDK for C++AppelezAWS KMSlors de l'utilisationAWS KMSporte-clés. Si vous utilisez un porte-clés qui n'interagit pas avecAWS KMS, comme un porte-clés AES brut, un porte-clés RSA brut ou un porte-clés multi-clés qui ne comprend pas deAWS KMSporte-clés, leAWS SDK for C++n'est pas obligatoire.

Pour obtenir de l'aide pour créer unAWS KMS key, voirCréation de clésdans leAWS Key Management ServiceManuel du développeur. Pour obtenir de l'aide pour identifier leAWS KMS keysdans unAWS KMSporte-clés, voirIdentification de clés AWS KMS keys dans un porte-clés AWS KMS.

Consultez l'exemple de code complet : string.cpp

Rubriques

• Chiffrement d'une chaîne
• Déchiffrement d'une chaîne

Chiffrement d'une chaîne

La première partie de cet exemple utilise unAWS KMSporte-clés avec unAWS KMS keypour chiffrer une chaîne en texte brut.

Étape 1. Chargez des chaînes d'erreur.

Appelez leaws_cryptosdk_load_error_strings()dans votre code C ou C++. Il charge des informations d'erreur très utiles pour le débogage.

Vous n'avez besoin de l'appeler qu'une seule fois, par exemple dans votremainméthode.

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

Étape 2 : Construction du porte-clés.

Création d'unAWS KMSporte-clés pour chiffrement. Le porte-clés de cet exemple est configuré avec unAWS KMS key, mais vous pouvez configurer unAWS KMSporte-clés avec plusieursAWS KMS keys, y comprisAWS KMS keysdans différentsRégions AWSet d'autres comptes.

Pour identifier unAWS KMS keydans un porte-clés de chiffrement dans leKit SDK de chiffrement AWS pour C, spécifiez unARN de cléouARN d'alias. Dans un porte-clés de déchiffrement, vous devez utiliser un ARN de clé. Pour plus d'informations, consultez Identification de clés AWS KMS keys dans un porte-clés AWS KMS.

Identification de clés AWS KMS keys dans un porte-clés AWS KMS

Lorsque vous créez un porte-clés avec plusieursAWS KMS keys, vous spécifiez leAWS KMS keyutilisée pour générer et chiffrer la clé de données en texte brut et, si vous le souhaitez, un ensemble de supplémentairesAWS KMS keysqui chiffrent la même clé de données en texte brut. Dans ce cas, vous spécifiez uniquement la du générateurAWS KMS key.

Avant d'exécuter ce code, remplacez l'exemple d'ARN de clé par un ARN valide.

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

Étape 3 : Créez une session.

Créez une session à l'aide de l'allocateur, d'un énumérateur de mode et du porte-clés.

Chaque session nécessite un mode : soit AWS_CRYPTOSDK_ENCRYPT pour chiffrer, soit AWS_CRYPTOSDK_DECRYPT pour déchiffrer. Pour modifier le mode d'une session existante, utilisez la méthode aws_cryptosdk_session_reset.

Après avoir créé une session avec le porte-clés, vous pouvez libérer votre référence au porte-clés à l'aide de la méthode fournie par le kit SDK. La session conserve une référence à l'objet de porte-clés pendant sa durée de vie. Les références aux objets de porte-clés et de session sont libérées lorsque vous détruisez la session. Cette technique de comptage de référence permet d'éviter les fuites de mémoire et d'empêcher la libération des objets pendant leur utilisation.

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

Étape 4 : Définition du contexte de chiffrement.

Un contexte de chiffrement est un ensemble de données authentifiées supplémentaires non secrètes et arbitraires. Lorsque vous fournissez un contexte de chiffrement lors du chiffrement, le kit AWS Encryption SDK le lie de façon cryptographique au texte chiffré de sorte que le même contexte de chiffrement est requis pour déchiffrer les données. L'utilisation d'un contexte de chiffrement est facultative, mais nous vous le recommandons dans le cadre des bonnes pratiques.

Tout d'abord, créez une table de hachage qui inclut le contexte de chiffrement des chaînes.

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

Obtenez un pointeur réversible dans le contexte de chiffrement de la session. Ensuite, utilisez la fonction aws_cryptosdk_enc_ctx_clone pour copier le contexte de chiffrement dans la session. Conservez la copie dans my_enc_ctx afin de pouvoir valider la valeur après le déchiffrement des données.

Le contexte de chiffrement fait partie de la session. Il ne s'agit pas d'un paramètre transmis à la fonction du processus de session. Cela garantit que le même contexte de chiffrement est utilisé pour chaque segment d'un message, même si la fonction du processus de session est appelée plusieurs fois pour chiffrer l'intégralité du message.

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)

Étape 5 : Chiffrement de la chaîne.

Pour chiffrer la chaîne en texte brut, utilisez la méthode aws_cryptosdk_session_process_full avec la session dans le mode de chiffrement. Cette méthode, introduite dansAWS Encryption SDKversions 1.9.h/24, j/7et 2.2.h/24, j/7, est conçu pour le chiffrement et le déchiffrement sans streaming. Pour gérer les données en streaming, appelez leaws_cryptosdk_session_processen boucle.

Lors du chiffrement, les champs de texte brut sont des champs d'entrée ; les champs de texte chiffré sont des champs de sortie. Une fois le traitement terminé, le champ ciphertext_output contient le message chiffré, y compris le texte chiffré réel, des clés de données chiffrées et le contexte de chiffrement. Vous pouvez déchiffrer ce message à l'aide du kit AWS Encryption SDK pour n'importe quel langage de programmation pris en charge.

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

Étape 6 : Nettoyez la session.

La dernière étape détruit la session, y compris les références au CMM et le porte-clés.

Si vous préférez, au lieu de détruire la session, vous pouvez la réutiliser avec le même porte-clés et la même clé CMM pour déchiffrer la chaîne, ou pour chiffrer ou pour chiffrer ou déchiffrer d'autres messages. Pour utiliser la session pour le déchiffrement, utilisez la méthode aws_cryptosdk_session_reset pour modifier le mode vers AWS_CRYPTOSDK_DECRYPT.

Déchiffrement d'une chaîne

La deuxième partie de cet exemple consiste à déchiffrer un message chiffré qui contient le texte chiffré de la chaîne d'origine.

Étape 1 : Chargez des chaînes d'erreur.

Appelez leaws_cryptosdk_load_error_strings()dans votre code C ou C++. Il charge des informations d'erreur très utiles pour le débogage.

Vous n'avez besoin de l'appeler qu'une seule fois, par exemple dans votremainméthode.

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

Étape 2 : Construction du porte-clés.

Lorsque vous déchiffrer des données dans AWS KMS, vous transmettez message chiffré renvoyé par l'API de chiffrement. LeAPI de déchiffrementne prend pas deAWS KMS keyen entrée. En revanche, AWS KMS utilise la même AWS KMS key afin de déchiffrer le texte chiffré utilisé pour le chiffrement. Cependant, leAWS Encryption SDKvous permet de spécifier unAWS KMSporte-clés avecAWS KMS keyslors du chiffrement et du déchiffrement.

Lors du déchiffrement, vous pouvez configurer un porte-clés avec uniquement les AWS KMS keys que vous souhaitez utiliser pour déchiffrer le message chiffré. Par exemple, vous pouvez créer un porte-clés avec uniquement la AWS KMS key qui est utilisée par un rôle dans votre organisation. LeAWS Encryption SDKn'utilisera jamais unAWS KMS keysauf si elle s'affiche dans le porte-clés de déchiffrement. Si le kit SDK ne peut pas déchiffrer les clés de données chiffrées à l'aide de AWS KMS keys du porte-clés que vous fournissez, soit parce qu'aucune des AWS KMS keys du porte-clés n'a été utilisée pour chiffrer les clés de données, soit parce que le mandataire n'a pas l'autorisation d'utiliser les AWS KMS keys du porte-clés pour le déchiffrement, l'appel de déchiffrement échoue.

Lorsque vous spécifiez unAWS KMS keypour un porte-clés de déchiffrement, vous devez utiliser sonARN de clé. ARN d'aliassont autorisés uniquement dans les porte-clés de chiffrement. Pour obtenir de l'aide pour identifier leAWS KMS keysdans unAWS KMSporte-clés, voirIdentification de clés AWS KMS keys dans un porte-clés AWS KMS.

Dans cet exemple, nous spécifions un porte-clés configuré avec le mêmeAWS KMS keyutilisée pour chiffrer la chaîne. Avant d'exécuter ce code, remplacez l'exemple d'ARN de clé par un ARN valide.

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

Étape 3 : Créez une session.

Créez une session à l'aide de l'allocateur et du porte-clés. Pour configurer la session pour le déchiffrement, configurez la session avec le mode AWS_CRYPTOSDK_DECRYPT.

Après avoir créé une session avec un porte-clés, vous pouvez libérer votre référence au porte-clés à l'aide de la méthode fournie par le kit SDK. La session conserve une référence à l'objet de porte-clés pendant sa durée de vie, et la session et le porte-clés sont tous les deux libérés lorsque vous détruisez la session. Cette technique de comptage de référence permet d'éviter les fuites de mémoire et d'empêcher la libération des objets pendant leur utilisation.

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

Étape 4 : Déchiffrement de la chaîne.

Pour déchiffrer la chaîne, utilisez la méthode aws_cryptosdk_session_process_full avec la session qui est configurée pour le déchiffrement. Cette méthode, introduite dansAWS Encryption SDKversions 1.9.h/24, j/7et 2.2.h/24, j/7, est conçu pour le chiffrement et le déchiffrement sans streaming. Pour gérer les données en streaming, appelez leaws_cryptosdk_session_processen boucle.

Lors du déchiffrement, les champs de texte chiffré sont des champs d'entrée et les champs de texte brut sont des champs de sortie. Le champ ciphertext_input contient le message chiffré renvoyé par la méthode de chiffrement. Une fois le traitement terminé, le champ plaintext_output contient la chaîne en texte brut (déchiffrée).

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

Étape 5 : Vérifiez le contexte de chiffrement.

Assurez-vous que le contexte de chiffrement réel, celui qui a été utilisé pour déchiffrer le message, contient le contexte de chiffrement que vous avez fourni lors du chiffrement du message. Le contexte de chiffrement réel peut inclure des paires supplémentaires. En effet, le gestionnaire de matériaux cryptographiques (CMM) peut ajouter des paires au contexte de chiffrement fourni avant de chiffrer le message.

Dans le kit Kit SDK de chiffrement AWS pour C, vous n'êtes pas tenu de fournir un contexte de chiffrement lors du déchiffrement dans la mesure où le contexte de chiffrement est inclus dans le message chiffré renvoyé par le kit SDK. Toutefois, avant qu'elle ne renvoie le message en texte brut, votre fonction de déchiffrement doit vérifier que toutes les paires du contexte de chiffrement fourni apparaissent dans le contexte de chiffrement qui a été utilisé pour déchiffrer le message.

Tout d'abord, obtenez un pointeur en lecture seule à la table de hachage de la session. Cette table de hachage contient le contexte de chiffrement qui a été utilisé pour déchiffrer le message.

const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);

Ensuite, parcourez le contexte de chiffrement dans la table de hachage my_enc_ctx que vous avez copiée lors du chiffrement. Vérifiez que chaque paire de la table de hachage my_enc_ctx qui a été utilisée pour chiffrer s'affiche dans la table de hachage session_enc_ctx qui a été utilisée pour déchiffrer. Si une clé est manquante ou si cette clé a une valeur différente, arrêtez le traitement et écrivez un message d'erreur.

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

Étape 6 : Nettoyez la session.

Après avoir vérifié le contexte de chiffrement, vous pouvez détruire la session ou la réutiliser. Si vous devez reconfigurer la session, utilisez laaws_cryptosdk_session_resetméthode.

aws_cryptosdk_session_destroy(session);