Utilisation des Kit SDK de chiffrement AWS pour C - AWS Encryption SDK
Modèles de chiffrement et de déchiffrement des donnéesComptage des références

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation des Kit SDK de chiffrement AWS pour C

Cette rubrique explique certaines fonctions du kit Kit SDK de chiffrement AWS pour C qui ne sont pas prises en charge par d'autres implémentations de langage de programmation.

Les exemples de cette section montrent comment utiliserversion 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 deréférentiel aws-cryption-sdk-csur GitHub.

Pour plus de détails sur la programmation avec le kit Kit SDK de chiffrement AWS pour C, consultez les exemples C, les exemples du référentiel aws-encryption-sdk-c sur GitHub et la documentation de l'API Kit SDK de chiffrement AWS pour C.

Voir aussi : Utilisation des porte-clés

Modèles de chiffrement et de déchiffrement des données

Lorsque vous utilisez le kit Kit SDK de chiffrement AWS pour C, vous suivez un modèle similaire à ceci : créez un porte-clés, créez un CMM qui utilise le porte-clés, créez une session qui utilise le CMM (et le porte-clés), puis traitez la session.

1. Chargez les 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();
2. Créez un porte-clés.

Configurez votre porte-clés avec les clés d'encapsulage que vous souhaitez utiliser pour chiffrer vos clés de données. Cet exemple utilise unAWS KMSPorte-clésavec uneAWS KMS key, mais vous pouvez utiliser n'importe quel type de porte-clés à sa place.

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 AWS KMS keys dans un AWS KMS porte-clés.

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. Créez une session.

Dans le kit Kit SDK de chiffrement AWS pour C, vous utilisez une session pour chiffrer un seul message en texte brut ou déchiffrer un seul message en texte chiffré, quelle que soit sa taille. La session conserve l'état du message tout au long de son traitement.

Configurez votre session avec un allocateur, un porte-clés et un mode : AWS_CRYPTOSDK_ENCRYPT ou AWS_CRYPTOSDK_DECRYPT. Si vous devez modifier le mode de la session, utilisez la méthode aws_cryptosdk_session_reset.

Lorsque vous créez une session avec un porte-clés, leKit SDK de chiffrement AWS pour Ccrée automatiquement un gestionnaire de matériaux de chiffrement (CMM) par défaut pour vous. Vous n'avez pas besoin de créer, de maintenir ou de détruire cet objet.

Par exemple, la session suivante utilise l'allocateur et le porte-clés qui a été défini à l'étape 1. Lorsque vous chiffrez des données, le mode est AWS_CRYPTOSDK_ENCRYPT.

struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
4. Chiffrez ou déchiffrez les données.

Pour traiter les données de la session, utilisez la méthode aws_cryptosdk_session_process. Si le tampon d'entrée est suffisamment grand pour contenir tout le texte brut et que le tampon de sortie est suffisamment grand pour contenir le texte chiffré entier, vous pouvez appeleraws_cryptosdk_session_process_full. Toutefois, si vous avez besoin de gérer les données de streaming, vous pouvez appeleraws_cryptosdk_session_processen boucle. Pour de plus amples informations, vous pouvez consulter l'exemple file_streaming.cpp. Leaws_cryptosdk_session_process_fullest introduit dansAWS Encryption SDKversions 1.9.h/24, j/7et 2.2.h/24, j/7.

Lorsque la session est configurée pour chiffrer des données, les champs de texte brut décrivent les champs d'entrée et les champs du texte chiffré décrivent la sortie. Le champ plaintext contient le message que vous souhaitez chiffrer et le champ ciphertext obtient le message chiffré renvoyé par la méthode de chiffrement 

/* Encrypting data */
aws_cryptosdk_session_process_full(session,
                                   ciphertext,
                                   ciphertext_buffer_size,
                                   &ciphertext_length,
                                   plaintext,
                                   plaintext_length)

Lorsque la session est configurée pour déchiffrer des données, les champs de texte chiffré décrivent les champs d'entrée et les champs du texte brut décrivent la sortie. Le champ ciphertext contient le message chiffré renvoyé par la méthode de chiffrement, et le champ plaintext obtient le message en texte brut renvoyé par la méthode de déchiffrement.

Pour déchiffrer les données, appelez la méthode aws_cryptosdk_session_process_full.

/* Decrypting data */
aws_cryptosdk_session_process_full(session,
                                   plaintext,
                                   plaintext_buffer_size,
                                   &plaintext_length,
                                   ciphertext,
                                   ciphertext_length)

Comptage des références

Pour éviter les fuites de mémoire, assurez-vous de libérer vos références à tous les objets que vous créez lorsque vous en avez terminé avec eux. Dans le cas contraire, des fuites de mémoire se produisent. Le kit SDK fournit des méthodes pour faciliter cette tâche.

Chaque fois que vous créez un objet parent avec l'un des objets enfants suivants, l'objet parent obtient et conserve une référence à l'objet enfant, comme suit :

Sauf si vous avez besoin d'une référence indépendante à l'objet enfant, vous pouvez libérer votre référence à l'objet enfant dès que vous créez l'objet parent. La référence restante à l'objet enfant est libérée lorsque l'objet parent est détruit. Ce modèle garantit que vous conservez la référence à chaque objet uniquement pendant le délai nécessaire et empêche les fuites de mémoire en raison de références non libérées.

Vous êtes uniquement responsable de la libération des références aux objets enfants que vous créez explicitement. Vous n'êtes pas responsable de la gestion des références aux objets créés par le SDK pour vous. Si le SDK crée un objet, tel que le CMM par défaut que leaws_cryptosdk_caching_cmm_new_from_keyringajoute à une session, le SDK gère la création et la destruction de l'objet et de ses références.

Dans l'exemple suivant, lorsque vous créez une session avec un porte-clés, la session obtient une référence au porte-clés et conserve cette référence jusqu'à ce que la session soit détruite. Si vous n'avez pas besoin de conserver une référence supplémentaire au porte-clés, vous pouvez utiliser la méthode aws_cryptosdk_keyring_release pour libérer l'objet de porte-clés dès que la session est créée. Cette méthode diminue le nombre de références pour le porte-clés. La référence de la session au porte-clés est libérée lorsque vous appelez aws_cryptosdk_session_destroy pour détruire la session. 

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

Pour des tâches plus complexes, telles que la réutilisation d'un porte-clés pour plusieurs sessions ou la spécification d'une suite d'algorithmes dans un CMM, vous devrez peut-être conserver une référence indépendante à l'objet. Si c'est le cas, n'appelez pas les méthodes de publication immédiatement. Au lieu de cela, libérez vos références lorsque vous n'utilisez plus les objets, en plus de détruire la session.

Cette technique de comptage des références fonctionne également lorsque vous utilisez d'autres CMM, comme le CMM de mise en cache pourMise en cache des clés de données. Lorsque vous créez une CMM de mise en cache à partir d'un cache et d'un porte-clés, le CMM de mise en cache obtient une référence aux deux objets. Sauf si vous en avez besoin pour une autre tâche, vous pouvez libérer vos références indépendantes au cache et au porte-clés dès que le CMM de mise en cache est créé. Ensuite, lorsque vous créez une session avec le CMM de mise en cache, vous pouvez libérer votre référence au CMM de mise en cache.

Notez que vous êtes uniquement responsable de la publication des références aux objets que vous créez explicitement. Les objets que les méthodes créent pour vous, tels que le CMM par défaut qui sous-tend le CMM de mise en cache, sont gérés par la méthode.

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