Seald: documentation

English

Français

English

Français

First steps ​

Before starting, you need a Seald account. You can create a trial account on our staging environment here: https://www.seald.io/fr/create-sdk.

Once your trial account is created, you can access the administration panel and retrieve the necessary information.

WARNING

This allows you to create an account on our test environment only. This environment cannot be migrated to a production environment. There is no SLA, and data may be deleted.

To create a production account, contact us.

Prerequisites ​

From your developer account, get the following elements:

  • appId: Unique UUID for your application;
  • apiURL: URL of the API server to use. Required only for test environments; for production environment, you can omit the variable;
  • keyStorageURL: URL of the identity storage server to use. Required only for test environments; for production environment, you can omit the variable;
Dashboard mode SDK
Administration dashboard

Using the SDK requires JSON Web Tokens (JWT). Generating JWTs requires a JWT Secret.

When creating your administration account, a JWT Secret including all permissions is automatically generated. This is displayed on the dashboard homepage.

WARNING

The JWTSecret is a secret, it should be managed securely. The appId and the JWTSecretId can be public.

You can create other JWT Secrets on the dashboard. To do this, go to the settings, JWT Secrets tab. Click on Create secret. Select the permissions you want, then confirm the creation of the secret. Once the secret is created, get its ID, noted JWTSecretId hereafter, and its value, JWTSecret.

Installation ​

To use the Seald SDK in your app, you must install the NPM package @seald-io/sdk:

bash
npm i -S @seald-io/sdk

React-Native application ​

For the react-native SDK, in addition to the Seald-SDK itself, you will need to install react-native-modpow, react-native-async-storage , @seald-io/react-native-scrypt, react-native-rsa-native, and react-native-get-random-values:

bash
npm i -S react-native-modpow @react-native-community/async-storage @seald-io/react-native-scrypt react-native-rsa-native react-native-get-random-values

For iOS, you may need to run cd ios && pod install.

Moreover, if react-native <0.59 is used, it will be necessary to execute an npm link for each of these libraries.

Generation of the signupJWT ​

The signupJWT are generated from the shared secret JWTSecret retrieved above.

Since this is a secret not to be disclosed to the client side, it should be stored on the application server side and used to derive a signupJWT per user on the server side on demand, with a specific API point to be developed in the application server. A dedicated guide is available for this.

You can directly use one of our examples of signup JWT generation.

Storing User identities ​

To store the user's identity on the local device, you can use a persistent local database.

Additionally, to protect user identities on a server, two modes are available:

These modes are available as separately installable plugins for the Seald SDK:

bash
# For password protection @seald-io/sdk-plugin-ssks-password :
npm i -S @seald-io/sdk-plugin-ssks-password

# For a 2-man rule protection @seald-io/sdk-plugin-ssks-2mr :
npm i -S @seald-io/sdk-plugin-ssks-2mr

For more details, see here.

WARNING

If no identity protection plugin and no persistant database is used, the user's identity will not be stored anywhere, and the data encrypted with it would be unrecoverable as soon as the browser tab or application is closed.

Start encrypting ​

Once all these elements are taken care of, all that's left to do is to start encrypting 😊.

Import ​

First, you need to import the SDK, and the desired plugins:

js
import SealdSDK from '@seald-io/sdk'

import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password'

For specific cases (especially in non-standard build processes), see details of import modes.

Instanciation ​

This step allows to instantiate the SDK.

js
const seald = SealdSDK({ appId, apiURL })
await seald.initialize()

If you use plugins, you must pass them to the instantiation:

js
const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()

Initialization & recovery of a Seald identity ​

In this example, the password protection mode is used, and the identity encrypted by a derivation of this password is sent to the SaaS instance of SSKS.

js
// If you are creating an account for the first time
const password = 'SuperSecretPassword' // The user's password. Will be used to encrypt their identity keys
const signupJWT = 'XXXXXXXXXXXXXX' // Calculated by your server
const { sealdId: mySealdId } = await seald.initiateIdentity({ signupJWT }) // Create your Seald identity
await seald.ssksPassword.saveIdentity({ userId: myUserId, password }) // Save the password-encrypted Seald identity on the SSKS server
js
// If you are retrieving a previously created account
const password = 'SuperSecretPassword' // The user's password. Will be used to decrypt their identity keys
const { sealdId: mySealdId } = await seald.ssksPassword.retrieveIdentity({ userId: myUserId, password })

Encrypt and decrypt ​

Two possibilities are provided to encrypt and decrypt:

js
// Encrypt / decrypt files
const encryptedFile = await seald.encryptFile('Secret file content', 'SecretFile.txt', { sealdIds: [mySealdId, otherUserSealdId] })
const decryptedFile = await seald.decryptFile(encryptedFile)
js
// Use sessions
const session = await seald.createEncryptionSession({ sealdIds: [mySealdId, otherUserSealdId] })
const encryptedMessage = await session.encryptMessage('SecretMessage')
const decryptedMessage = await session.decryptMessage(encryptedMessage)
await session.addRecipients({ sealdIds: [anotherUserSealdId] })
await session.revokeRecipients({ sealdIds: [otherUserSealdId] })

const sessionBis = await seald.retrieveEncryptionSession({ encryptedMessage })
const decryptedMessageBis = await sessionBis.decryptMessage(encryptedMessage)