Seald: documentation

Français

English

Français

English

Chiffrement anonyme ​

En plus du SDK complet, Seald propose également un SDK de chiffrement anonyme. Celui-ci permet à votre application de fournir un moyen à des utilisateurs sans identité Seald (non-inscrits, ou non-connectés) de chiffrer des données pour un utilisateur avec une identité Seald. Vous pouvez également l'utiliser pour que votre serveur chiffre des données pour vos utilisateurs.

Par mesure de sécurité, votre serveur doit autoriser ces chiffrements anonymes à l'aide de JSON Web tokens.

Import et instanciation ​

Le SDK de chiffrement anonyme de Seald s'importe de façon séparée du SDK complet.

Il y a trois manières d'utiliser le SDK Anonyme dans votre navigateur, selon vos besoins et l'architecture de votre application web.

Bibliothèque polyfillée ​

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous' // si votre bundler supporte les entry-points personnalisés (supportés par Webpack 5)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-browser' // si votre bundler supporte les entry-points personnalisés (supportés par Webpack 5) et que vous voulez explicitement importer la version pour navigateur

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/browser/anonymous-sdk.polyfilled.js' // import explicite

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Cette version est déjà empaquetée, transpilée et minifiée pour l'utilisation dans un navigateur web. Elle inclut toutes les bibliothèques, dépendances et polyfills nécessaires à son fonctionnement.

Utilisez cette méthode si vous utilisez un bundler comme webpack, mais que vous ne voulez pas configurer ce bundler pour inclure les polyfills nécessaires.

Bibliothèque ​

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-browser-library' // si votre bundler supporte les entry-points personnalisés (supportés par Webpack 5)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/browser/anonymous-sdk.js' // import explicite

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Ceci importe @seald-io/sdk/browser/anonymous-sdk.js, qui est la version pour le navigateur.

Utilisez cette méthode si vous utilisez un bundler comme Webpack. Pour cela, referez-vous à la section Empaquetage personnalisé et transpilation du guide sur les imports.

Cette méthode est recommandée, puisqu'elle permet de diminuer la duplication des dépendances et polyfills, et donc minimiser la taille finale de votre application.

Bundle ​

Copiez le fichier @seald-io/sdk/browser/anonymous-sdk.browser.js, puis importez-le via une balise <script> :

html
<html>
<head>
...
<script src="/libraries/anonymous-sdk.browser.js"></script>
<script>
var anonymousSDK = window.AnonymousSDK({ apiURL })
</script>
...
</head>
</html>

Cette version est déjà empaquetée, transpilée et minifiée pour l'utilisation dans un navigateur web. Elle inclut toutes les bibliothèques, dépendances et polyfills nécessaires à son fonctionnement.

Elle expose le constructeur du SDK Anonyme dans la variable globale window.AnonymousSDK.

Node.js / Electron ​

javascript
import { AnonymousSDKBuilder } from '@seald-io/sdk'

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Cela importe la version empaquetée pour les projets Node.js.

Elle peut être utilisée pour un serveur NodeJS, une application de bureau en Electron, des tests unitaires, etc.

React-Native ​

Installation ​

Le SDK Anonyme pour react-native a des "peer dependencies" qui doivent être installées séparément :

  • react-native-modpow
  • react-native-get-random-values

Vous pouvez les installer avec la commande :

sh
npm i -S react-native-modpow react-native-get-random-values

Bundle ​

Si vous ne configurez pas vous-même la transpilation de votre application, vous pouvez utiliser la version empaquetée, transpilée et minifiée du SDK Anonyme. Elle est utilisable telle quelle.

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-react-native' // si votre bundler supporte les entry-points personnalisés (non supporté par Metro)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/react-native/anonymous-sdk-react-native.bundle.js' // import explicite

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Bibliothèque ​

Si votre application est elle-même transpilée, vous pouvez importer la librairie source. Cela vous permettra alors d'optimiser la taille de votre application.

javascript
import AnonymousSDKBuilder from '@seald-io/sdk/anonymous-react-native-library' // si votre bundler supporte les entry-points personnalisés (non supporté par Metro)

const anonymousSDK = AnonymousSDKBuilder({ apiURL })
javascript
import AnonymousSDKBuilder from '@seald-io/sdk/react-native/anonymous-sdk-react-native.js' // import explicite

const anonymousSDK = AnonymousSDKBuilder({ apiURL })

Cette bibliothèque devra être transpilée pour être utilisée. Pour cela, referez-vous à la section Empaquetage personnalisé et transpilation du guide sur les imports.

JSON Web Tokens ​

Par mesure de sécurité, votre serveur doit autoriser ces chiffrements anonymes à l'aide de JSON Web tokens.

Le chiffrement anonyme s'effectue en deux étapes

  • récupération des clés de chiffrement des destinataires
  • création de la session pour ces destinataires

Chacune de ces deux étapes doit être autorisée par un JSON Web Token. Vous trouverez des exemples détaillés de génération de ces JWTs dans différents languages de programmation au paragraphe JWTs de chiffrement anonyme de notre page de documentation concernant les JWTs.

TIP

La récupération de clés de destinataires peut nécessiter plusieurs requêtes. Il est donc fortement déconseillé de définir un jti sur le JWT en question, sinon les requêtes après la première pourraient échouer.

Au contraire, la création de session se fait en une seule requête. Il est donc recommandé de définir un jti, pour éviter que le même JWT soit utilisé plusieurs fois pendant l'intervalle de temps autorisé.

TIP

Même si techniquement rien n'empêche d'utiliser un seul JWT pour les deux opérations, il est recommandé de créer deux JWT différents pour la récupération de clés et pour la création de session, afin de pouvoir définir un jti sur le JWT de création de session, pour que celui-ci ne puisse être utilisé qu'une seule fois.

Pour plus d'informations concernant la génération des_JSON Web Tokens_, référez-vous à cette documentation

Utilisation ​

Vous avez maintenant tout le nécessaire pour faire un chiffrement anonyme. Cela peut se faire avec l'une de ces deux fonctions :

anonymousSDK.encrypt ​

Cette fonction vous permet de chiffrer directement un fichier.

Les arguments à noter de cette fonction sont :

  • clearFile : Obligatoire. Le fichier à chiffrer. Peut être un string, un Buffer, un Blob, un WebStream ReadableStream, ou un stream Node Readable. Si vous utilisez un ReadableStream ou un Readable, vous devrez également donner l'argument fileSize.
  • getKeysToken : Facultatif. Le JWT utilisé pour la récupération de clé. S'il n'est pas fourni, la récupération de clé utilisera encryptionToken.
  • encryptionToken : Obligatoire. Le JWT utilisé pour la création de session.
  • sealdIds : Obligatoire. Tableau des Seald IDs des destinataires de la session à créer.

Le retour de cette fonction est une Promise, contenant :

  • id : un string, ID de la session pour le fichier chiffré.
  • encryptedFile : fichier nouvellement chiffré, au même format que le format du clearFile donné.

Exemple d'utilisation :

javascript
const { id, encryptedFile } = await anonymousSDK.encrypt({
  getKeysToken,
  encryptionToken,
  sealdIds: [user1SealdId, user2SealdId],
  clearFile: clearFileBuffer,
  filename: 'test.txt'
})

anonymousSDK.createEncryptionSession ​

Cette fonction vous permet de créer une AnonymousEncryptionSession, que vous pouvez utiliser ensuite pour chiffrer et déchiffrer des fichiers et messages.

Les arguments à noter de cette fonction sont :

  • getKeysToken : Facultatif. Le JWT utilisé pour la récupération de clé. S'il n'est pas fourni, la récupération de clé utilisera encryptionToken.
  • encryptionToken : Obligatoire. Le JWT utilisé pour la création de session.
  • sealdIds : Obligatoire. Tableau des Seald IDs des destinataires de la session à créer.

Le retour de cette fonction est une Promise, contenant une AnonymousEncryptionSession, que vous pouvez utiliser pour chiffrer et déchiffrer des fichiers et messages.

Exemple d'utilisation :

javascript
// Créer la `AnonymousEncryptionSession`
const session = await anonymousSDK.createEncryptionSession({
  getKeysToken,
  encryptionToken,
  sealdIds: [user1SealdId, user2SealdId]
})
// Chiffrer un fichier
const encryptedFile = await session.encryptFile({
  clearFile: clearFileBuffer,
  filename: 'test.txt'
})
// Chiffrer un message
const encryptedMessage = await session.encryptMessage('Secret Message')