Seald: documentation

# Chiffrement des fichiers

Pour chiffrer & déchiffrer des fichiers, on peut utiliser :

Pour l'utilisation des méthodes EncryptionSession#encryptFile et EncryptionSession#decryptFile, il faut se référer à la section dédiée du guide sur les EncryptionSession.

# Format d'un fichier chiffré

Un fichier chiffré avec Seald est constitué de deux parties :

  • un en-tête contenant l'identifiant de l'EncryptionSession ;
  • le résultat du chiffrement avec la clé de l'EncryptionSession d'un tar (opens new window) contenant le fichier à chiffrer.

Ainsi le fichier chiffré est légèrement plus volumineux que le fichier original, d'environ 2 kB.

# Description des fonctions

# encryptFile

La méthode encryptFile a 4 arguments : clearFile, filename, recipients et opts.

Elle retourne un Promise qui se résout en le même type qu'utilisé pour clearFile.

# clearFile: le fichier à chiffrer

encryptFile supporte plusieurs types pour clearFile et retourne le résultat avec le même type :

Des exemples d'utilisation avec ces différents types sont disponibles à la fin de cette page.

# filename: le nom du fichier

Il s'agit d'un String qui est utilisé pour :

  1. être la metadata par défaut de l'EncryptionSession qui sera créée ;
  2. être enregistré comme nom du fichier à chiffrer dans le tar décrit ci-dessus.

TIP

Le filename n'est pas disponible lors du déchiffrement, cela fera l'objet d'une mise à jour.

# recipients: les utilisateurs autorisés à déchiffrer

Il s'agit d'un objet avec deux propriétés décrivant les utilisateurs autorisés à déchiffrer :

  • userIds : un tableau contenant des identifiants utilisateurs dans votre application tels que déclarés lors de la génération des identités ;
  • sealdIds : un tableau contenant des identifiants internes de Seald, cela est notamment utile pour chiffrer pour un groupId.

TIP

Il est possible de chiffrer pour un userId qui n'a pas encore créé une identité Seald si opts.allowUnregisteredUsers est à true.

Dans ce cas, il ne s'agit pas de chiffrement de bout-en-bout : la clé de chiffrement en clair est mise en séquestre sur les serveurs de Seald le temps qu'une identité Seald soit créée et associée à ce userId.

# opts: options

Il s'agit d'un objet avec plusieurs propriétés optionnelles. Trois d'entre elles sont particulièrement intéressantes (pour avoir la liste complète, consultez la référence) :

  • fileSize : taille du fichier à chiffrer, nécessaire pour une utilisation avec les types ReadableStream and Readable.
  • metadata : metadata de l'EncryptionSession qui sera créée (la valeur de filename par défaut).
  • encryptForSelf : si vous chiffrez pour un groupe dont l'utilisateur fait partie, vous pouvez mettre cette option à false afin de ne pas chiffrer directement pour ses propres identités. L'utilisateur pourra toujours déchiffrer la donnée grâce à son appartenance au groupe. Ceci peut vous permettre d'améliorer la performance du chiffrement.

# decryptFile

La méthode decryptFile a un seul argument : encryptedFile, le fichier à déchiffrer.

decryptFile supporte les mêmes types pour encryptedFile qu'encryptFile pour clearFile.

Elle retourne une Promise qui se résout en un Object qui a les propriétés suivantes :

  • data: le fichier déchiffré, est du même type que celui utilisé pour encryptedFile ;
  • type: un des types suivants 'string', 'buffer', 'node-stream', 'blob', 'readable-stream' ;
  • filename: le nom du fichier original ;
  • size: la taille du fichier en octets ;
  • sessionId: l'identifiant de l'EncryptionSession.

# Exemples

# Avec des String

La signature la plus simple pour chiffrer un fichier est un String:

Dans ce cas, le type de sortie sera un String encodé en base64 du fichier chiffré. Il sera alors possible de le déchiffrer de la façon suivante :

info

Le contenu de clearFile est interprété comme étant de l'UTF-8.

TIP

S'il ne s'agit que de textes à chiffrer, il est recommandé d'utiliser l'autre format de chiffrement : encryptMessage / decryptMessage qui est beaucoup plus léger.

WARNING

La sortie de encryptFile utilisée avec un String est environ 33% plus lourde que le fichier original à cause de l'encodage base64.

# Avec des Buffer

Le SDK peut utiliser des Buffer au sens de Node.js (qui sont polyfillés hors environnement Node.js (opens new window)) :

Dans ce cas, le type de sortie sera un Buffer. Il sera alors possible de le déchiffrer de la façon suivante :

# Avec des Blob

Dans un navigateur, le SDK peut utiliser des Blob :

Dans ce cas, le type de sortie sera un Blob. Il sera alors possible de le déchiffrer de la façon suivante :

TIP

Les fichiers obtenus au travers de champs <input type="file"> sont de type File qui hérite de Blob. Il sont donc traités de la même façon par le SDK.

Le Blob déchiffré n'a pas de Blob#type défini, mais il peut être déduit de l'extension du fichier (en utilisant le paquet mime-types par exemple (opens new window)).

Vous pouvez également recréer une instance de File en utilisant son constructeur (opens new window) à partir du Blob déchiffré et du filename (et éventuellement du type mime déduit).

WARNING

React-Native n'implémentant pas les méthodes Blob#arrayBuffer ou Blob#stream pourtant standards, il n'est pas possible d'utiliser le type Blob dans un environnement React-Native. Il faut utiliser un autre type (comme les Buffer en utilisant un polyfill ou les String).

# Avec des ReadableStream

Dans un navigateur, le SDK peut utiliser des ReadableStream. Par exemple, avec la méthode Blob#stream (opens new window) :

WARNING

Dans ce mode, il faut passer à la fonction encryptFile la taille du fichier en clair via le paramètre options.fileSize.

Dans ce cas, le type de sortie sera un ReadableStream. Il sera alors possible de le déchiffrer de la façon suivante :

# Streamer un envoi de fichier

Hormis sur Chrome depuis la version 95 (opens new window), il n'est pas possible d'utiliser fetch avec un ReadableStream comme corps de requête.

Pour contourner, une solution consiste à découper côté client le fichier chiffré en chunks de 5Mo par exemple, de les envoyer individuellement au serveur, et le serveur aura la charge de reconstituer les différents chunks dans l'ordre.

# Avec des streams Readable de Node.js

Le SDK peut utiliser des streams Readable de Node.js. Dans un navigateur, cela fonctionne également en utilisant un polyfill (opens new window). Par exemple, pour lire & chiffrer un fichier puis l'écrire :

WARNING

Dans ce mode, il faut passer à la fonction encryptFile la taille du fichier en clair via le paramètre options.fileSize.

Il sera alors possible de le déchiffrer de la façon suivante :

← Intégrer le 2-man-rule sur votre backend →