# 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 personneuser2
peut révoqueruser3
(car c'est lui qui l'a ajouté) mais ne peut pas révoqueruser1
user1
peut révoqueruser2
(car c'est lui qui l'a ajouté) etuser3
(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 queSDK#encryptFile
;filename
: dans ce cas, il n'est pas utilisé commemetadata
, 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 lorsqueclearFile
est de typeReadable
ouReadableStream
.
# 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.