Seald: documentation

# Sessions de chiffrement

Lorsque vous comptez chiffrer de nombreux messages à la suite, par exemple dans un cas de discussion instantanée, vous pouvez utiliser une session de chiffrement. Une session de chiffrement utilise une même clé pour chiffrer tous les messages de la session.

Les avantages sont que votre code d'intégration peut être plus simple, que cela diminue le nombre de requêtes réseau liées à la récupération de clés de déchiffrement, et que vous diminuez le nombre de clés utilisées (opens new window).

L'inconvénient est que vous perdez la granularité offerte par le fait de chiffrer chaque message indépendamment : vous ne pouvez pas ajouter / révoquer un destinataire sur un seul message de la session, mais seulement sur la session toute entière.

# Créer une session de chiffrement

Vous pouvez créer une session avec la fonction sealdSDK.createEncryptionSession.

Lors de la création, deux éléments sont à définir :

  • userIds : un tableau des identifiants utilisateur dans votre application qui seront autorisés pour cette session de chiffrement ;
  • metadata : argument optionnel déclarant une métadonnée non chiffrée à l'API Seald. Elle peut servir dans l'administration d'un compte Seald.

La session ainsi créée est de type EncryptionSession. Elle possède un attribut sessionId, et plusieurs méthodes.

La personne qui crée une session en est alors l'administrateur : seul cet utilisateur sera en mesure de révoquer la session entière.

TIP

Si vous créez une session pour un groupe dont l'utilisateur fait partie, vous pouvez utiliser l'argument optionnel encryptForSelf: false afin de ne pas chiffrer directement pour ses propres identités. L'utilisateur pourra toujours déchiffrer les données grâce à son appartenance au groupe. Ceci peut vous permettre d'améliorer la performance du chiffrement, et d'économiser des clés de votre quota.

# Chiffrer des messages

Avec l'objet EncryptionSession, on peut dès lors chiffrer des messages, qui seront lisibles par tous les destinataires de la session.

Cela va donner un string de la forme :

'{"sessionId":"0000000000000000000000","data":"8RwaOppCD3uIJVFv2LoP3XGXpomj0xsMv4qmMVy30Vdqor2w0+DVCXu3j13PEyN2KfJm6SiSrWDRMDziiiOUjQ=="}'

Celui-ci contient le sessionId qui correspond à l'identifiant de la session de chiffrement et data qui correspond à la donnée chiffrée.

# Récupération d'une session

Une fois une session créée et un message chiffré, il faut être en mesure de récupérer la session a posteriori, y compris par l'émetteur lui-même.

Pour cela, il y a deux possibilités :

  • à partir du sessionId, mais cela nécessite de le stocker dans l'application dans un champ à part ;
  • à partir d'un message chiffré avec cette session directement, ce qui a le mérite d'être plus simple.

Dans les deux cas, on utilise la méthode sealdSDK.retrieveEncryptionSession, soit avec l'argument nommé sessionId si on le connait, soit avec l'argument nommé encryptedMessage :

# Déchiffrement

Une fois la session récupérée, on peut l'utiliser pour déchiffrer un message :

# Ajouter / révoquer des destinataires de la session

Tout destinataire de la session peut y ajouter d'autres destinataires, grâce à la méthode session.addRecipients.

Au contraire, pour révoquer un destinataire de la session avec la méthode session.revokeRecipients, seule la personne ayant ajouté ce destinataire (directement ou indirectement), ou le créateur de la session, peuvent le faire.

Ainsi, imaginons un scénario où user1 a ajouté user2 dans la session, et user2 a rajouté user3.

  • user3 ne peut révoquer personne
  • user2 peut révoquer user3 (car c'est lui qui l'a ajouté) mais ne peut pas révoquer user1
  • user1 peut révoquer user2 (car c'est lui qui l'a ajouté) et user3 (car c'est quelqu'un que lui a ajouté qui l'a ajouté)

Le créateur de la session peut également utiliser la methode session.revoke pour révoquer entièrement la session et tout son contenu.

# Chiffrer & déchiffrer des fichiers

Une EncryptionSession expose également deux méthodes encryptFile et decryptFile permettant d'utiliser cette session de chiffrement pour chiffrer des fichiers.

Comme expliqué dans le guide dédié au chiffrement des fichiers, ces méthodes supportent différents types (string, Buffer, Blob dans le navigateur uniquement, ReadableStream des Web Streams (opens new window), Readable des Streams Node.JS (opens new window)).

# Différence avec SDK#encryptFile et SDK#decryptFile

En utilisant une EncryptionSession pour chiffrer / déchiffrer des fichiers, on peut réutiliser la clé de chiffrement de la session sur différents fichiers / messages, et on gère les destinataires au niveau de la session de chiffrement.

Ainsi la méthode encryptFile d'une EncryptionSession ne prend pas l'argument recipients, et a seulement les arguments suivants :

  • clearFile : même chose que SDK#encryptFile ;
  • filename : dans ce cas, il n'est pas utilisé comme metadata, mais seulement comme nom de fichier dans le tar chiffré (voir le format d'un fichier chiffré) ;
  • options : l'objet options dont seule la propriété fileSize est utilisée, et qui n'est nécessaire que lorsque clearFile est de type Readable ou ReadableStream.

# Chiffrement

Voici un exemple de chiffrement (avec le type Buffer) :

# Déchiffrement

Pour déchiffrer un fichier chiffré avec une session, on doit utiliser la même EncryptionSession (préalablement récupérée avec SDK#retrieveEncryptionSession):

On peut également directement utiliser SDK#decryptFile qui récupèrera automatiquement l'EncryptionSession associée (l'ID de l'EncryptionSession est toujours inclus dans le résultat d'un chiffrement de fichiers) :

WARNING

Utiliser la méthode decryptFile d'une EncryptionSession sur un fichier chiffré pour une autre session ne fonctionnera pas.

TIP

Pour avoir des exemples avec d'autres types, référez-vous à la section d'exemples du guide sur le chiffrement de fichiers. Vous devrez simplement prendre en compte les différences sus-mentionnés.

← Chiffrement des fichiers →